@modellahja/vivo

Professional browser-first SDK for realtime AI voice and video conversations.

Current package version: 1.6.0

Vivo combines realtime media, streaming transcripts/audio, resumable conversation history, semantic interaction routing, turn-taking control, session recovery, a provider adapter layer, and a built-in conversation/interview UI.

Install

npm install @modellahja/[email protected]

Documentation

Start here:

• Documentation Home — complete documentation map.
• General Usage Guide — full end-to-end usage in one file.
• Quick Start — shortest working path.
• Configuration Reference — every top-level SDK option.
• Arabic Guide / الدليل العربي — شرح عربي مختصر لأهم الاستخدامات.

Core conversation features:

• Conversation Lifecycle
• Streaming Text & Audio
• Chat History & Resume
• KeyPass Semantic Events
• Turn-Taking & Interruption Priority
• Session Recovery & Reconnect
• Events Reference

UI and application integration:

• VivoComponent & showVivo
• Interview Mode
• Media & Devices
• Browser Custom Events
• Provider Adapters

Engineering references:

• Public API Reference
• Architecture
• Errors & Troubleshooting
• Security & Persistence
• Production Best Practices
• Examples Index
• Full End-to-End Example

Minimal example

import {
  createVivoConversation,
  GoogleGenAIAdapter
} from '@modellahja/vivo';

const vivo = createVivoConversation({
  mode: 'video',
  adapter: new GoogleGenAIAdapter({ client: googleClient }),

  context: {
    language: 'ar-SA',
    dialect: 'najdi',
    speaker: {
      role: 'assistant',
      voice: 'Aoede'
    }
  },

  turnTaking: {
    priority: 'balanced'
  },

  sessionPersistence: {
    enabled: true,
    storage: 'localStorage'
  }
});

vivo.on('assistant.text.final', ({ text }) => {
  console.log('Assistant:', text);
});

vivo.on('history.changed', ({ chatHistory }) => {
  console.log('History:', chatHistory);
});

if (vivo.session.hasRecovery()) {
  await vivo.session.restore();
} else {
  await vivo.session.start();
}

Built-in UI

<div id="vivo"></div>

await vivo.showVivo({
  container: '#vivo',
  variant: 'conversation',
  title: 'Vivo',
  showTranscript: true,
  showLevels: true,
  showTimer: true
});

For interviews:

await vivo.showVivo({
  container: '#vivo',
  variant: 'interview',
  interview: {
    position: 'Senior Backend Engineer',
    language: 'ar-SA',
    dialect: 'najdi',
    durationMinutes: 30,
    keywords: ['.NET', 'APIs', 'architecture']
  }
});

Core concepts

| Concept | Purpose | |---|---| | context | Prompt, language, dialect, keywords, speaker, interview metadata | | chatHistory | Ordered conversation interactions used for resume/continuation | | keyPass | Semantic { key, prompt } rules that emit application events | | turnTaking | Controls who owns the speaking floor and interruption behavior | | sessionPersistence | Saves a recovery pointer in a cookie and the full checkpoint in Web Storage | | reconnect | Reconnects transient provider/network failures without ending the logical conversation | | streaming | Emits partial/final text and audio events | | adapter | Connects Vivo to a realtime AI provider |

Important recovery design

Vivo does not store the full conversation in a cookie. Cookies are intentionally small. The SDK stores only a compact recovery pointer in the cookie and stores the full recovery checkpoint in localStorage or sessionStorage.

The checkpoint includes session/conversation identifiers, chatHistory, current partial text, KeyPass configuration, turn-taking state, floor ownership, and stream sequence. Raw long-form audio is not persisted in cookies or Web Storage.

See Session Recovery.

Package layout

@modellahja/vivo
├─ src/                 SDK source
├─ dist/                compiled package
├─ docs/                feature documentation
├─ examples/            usage examples
├─ scripts/             verification/regression scripts
├─ README.md            main entry point
└─ package.json

Development verification

npm install
npm run typecheck
npm run build
npm run test:regression
npm run verify:publish
npm pack

License

MIT