voice-runtime 1.0.1 → 1.2.0

package/README.md

@@ -8,23 +8,29 @@
 [TVIC](https://github.com/Kkartik14/TVIC), a provider-neutral runtime for realtime
 voice agents with bring-your-own telephony, speech, model, and synthesis providers.
 
+New to the package? Start with the [beginner's guide](https://github.com/Kkartik14/TVIC/blob/main/docs/getting-started.md).
+Use the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)
+for application design, [providers](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md)
+for model setup, and [transports](https://github.com/Kkartik14/TVIC/blob/main/docs/transports.md)
+for browser and phone connections.
+
 ## Status
 
-`voice-runtime@1.0.0` is the public Node.js entry point for the TVIC runtime. It
-declares Node.js 20 or newer, ships both ESM and CommonJS entry points, and is
-server-side only. The main CI compatibility matrix exercises Node 22, 24, and 26;
-Node 20 remains the package engine floor.
+`voice-runtime@1.1.0` is the public Node.js entry point for the TVIC runtime. It
+supports Node.js 22, 24, and 26, ships both ESM and CommonJS entry points, and is
+server-side only. The main CI compatibility matrix exercises all three supported
+lines.
 
 Browser audio connects to a Node server through the browser-audio transport
 adapter. Browser code does not import this package directly.
 
-The stable managed API assembles the STT → LLM → TTS pipeline from a prompt and
+The stable managed API assembles the STT -> LLM -> TTS pipeline from a prompt and
 provider configuration. The host application still owns its HTTP server,
 webhook authentication, browser-session authentication, and domain tools.
 
-If you are new to voice systems, read the [beginner guide on GitHub](https://github.com/Kkartik14/TVIC/blob/main/docs/start-here.md)
-before using the lower-level examples. The [provider guide](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md)
-explains credentials, model selection, and maturity labels.
+For a system overview, read [How it works](https://github.com/Kkartik14/TVIC/blob/main/docs/how-it-works.md).
+For testing and deployment, read the [testing guide](https://github.com/Kkartik14/TVIC/blob/main/docs/testing.md)
+and [deployment guide](https://github.com/Kkartik14/TVIC/blob/main/docs/deploying.md).
 
 ## Install
 
@@ -48,12 +54,13 @@ The command asks for `y` before writing `.claude/skills/tvic/SKILL.md` for Claud
 Code and `.agents/skills/tvic/SKILL.md` for Codex and OpenRouter-compatible
 agents. It does not run automatically during `npm install`, write to a home
 directory, or overwrite an existing skill without `--force`. Use
-`npx voice-runtime skills install --yes` in automation. See the [AI agent skills
-guide](https://github.com/Kkartik14/TVIC/blob/main/docs/agent-skills.md).
+`npx voice-runtime skills install --yes` in automation. See the [AI coding-agent
+guide](https://github.com/Kkartik14/TVIC/blob/main/docs/ai-coding-agents.md) and
+[skills reference](https://github.com/Kkartik14/TVIC/blob/main/docs/agent-skills.md).
 
 ## Prompt-first agent
 
-The prompt-first API assembles the STT → LLM → TTS pipeline. It still needs an
+The prompt-first API assembles the STT -> LLM -> TTS pipeline. It still needs an
 authenticated transport `CallHandle`; `npm install` does not create a public
 audio endpoint or a phone call for your application.
 
@@ -61,14 +68,14 @@ audio endpoint or a phone call for your application.
 import { createVoiceAgent } from "voice-runtime";
 
 const agent = createVoiceAgent({
-  prompt: "You schedule appointments for Dr. Kartik. Be concise and confirm the time.",
+  prompt: "You schedule appointments for a doctor Be concise and confirm the time.",
   providers: {
     telephony: { provider: "web-client-audio" },
     stt: { provider: "deepgram", apiKey: process.env.DEEPGRAM_API_KEY },
     llm: {
-      provider: "openai",
-      apiKey: process.env.OPENAI_API_KEY,
-      model: "gpt-4.1-mini",
+      provider: "groq",
+      apiKey: process.env.GROQ_API_KEY,
+      model: "openai/gpt-oss-20b",
     },
     tts: {
       provider: "cartesia",
@@ -153,17 +160,23 @@ outside the realtime critical path.
 
 Each stage is configured independently. Built-in options currently include:
 
+The complete matrix, catalog dates, official provider links, and live-test
+guidance are in the [provider guide](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md).
+
 - STT: Deepgram, Sarvam, ElevenLabs Scribe, AssemblyAI, and Soniox.
-- LLM: OpenAI Responses.
-- TTS: Cartesia and ElevenLabs.
+- LLM: Groq Chat Completions (the reference path) and an optional OpenAI Responses adapter.
+- TTS: Cartesia, ElevenLabs (WebSocket, REST, and HTTP stream), and Sarvam Bulbul v3.
 - Transport: browser audio and inbound Twilio Media Streams.
 
 Maturity is intentionally explicit: Web Client Audio and inbound Twilio Media
-Streams are the stable transport paths in `1.0.0`. The paid STT, LLM,
-and TTS adapters are currently `experimental`. Their deterministic protocol
-coverage passes, but each still needs a credential-gated live-service check
-before release notes can call it stable. The root export `PROVIDER_STABILITY`
-contains the machine-readable labels.
+Streams are the stable transport paths in `1.1.0`. The paid STT, LLM, and TTS
+adapters are currently `experimental`. `validated` is the intermediate label
+for an exact adapter/model/configuration that has passed the small-scale live
+evidence profile and is reasonable for low-volume use; `stable` additionally
+requires a support matrix, release evidence, ownership, and an upgrade policy.
+The root exports `PROVIDER_STABILITY` and `PROVIDER_STABILITY_LEVELS` contain
+the machine-readable labels. See the provider guide for the complete evidence
+and promotion rules.
 
 Pass an explicit `apiKey` or use the documented environment variable. Explicit
 credentials take precedence; missing credentials fail before a live session is
@@ -176,14 +189,19 @@ created.
 | ElevenLabs | `ELEVENLABS_API_KEY` |
 | AssemblyAI | `ASSEMBLYAI_API_KEY` |
 | Soniox     | `SONIOX_API_KEY`     |
+| Groq       | `GROQ_API_KEY`       |
 | OpenAI     | `OPENAI_API_KEY`     |
 | Cartesia   | `CARTESIA_API_KEY`   |
+| Sarvam TTS | `SARVAM_API_KEY`     |
 
 STT, LLM, and TTS models are independent settings. TTS voice selection is also
 independent. Built-in TTS can read `CARTESIA_VOICE_ID` or
 `ELEVENLABS_VOICE_ID` for its voice. For complete provider-specific control,
 pass a constructed provider instance instead of a built-in configuration object.
-Built-in STT and OpenAI-compatible LLM configurations reject models outside the
+Sarvam's managed configuration defaults to its WebSocket adapter; set
+`transport: "rest"` or `transport: "http-stream"` on the Sarvam TTS config when
+the downstream use case needs one-shot HTTP delivery.
+Built-in STT and LLM configurations reject models outside the
 dated TVIC catalog unless `allowUnknownModel: true` is explicitly set.
 
 Tools are application-owned functions. Define their schema and executor once,
@@ -207,7 +225,7 @@ const bookAppointment = defineTool<{ date: string }, { booked: boolean }>({
 const providers = {
   telephony: { provider: "web-client-audio" as const },
   stt: { provider: "deepgram" as const, apiKey: process.env.DEEPGRAM_API_KEY },
-  llm: { provider: "openai" as const, apiKey: process.env.OPENAI_API_KEY },
+  llm: { provider: "groq" as const, apiKey: process.env.GROQ_API_KEY },
   tts: {
     provider: "cartesia" as const,
     apiKey: process.env.CARTESIA_API_KEY,
@@ -230,9 +248,13 @@ application's responsibility.
 
 Advanced runtime, media, provider, normalized-error, and durable-adapter APIs
 are exported from the package root. There are no advanced subpath imports in
-1.0.0. This lets a developer start with `createVoiceAgent` and later own
+1.1.0. This lets a developer start with `createVoiceAgent` and later own
 the runtime/session/pipeline boundaries without changing package names.
 
+Read the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)
+for the managed to composable migration path and the [API reference](https://github.com/Kkartik14/TVIC/blob/main/docs/api-reference.md)
+for the root exports.
+
 The host remains responsible for creating authenticated transport connections,
 owning HTTP/webhook lifecycle, and implementing application-domain tools. TVIC
 does not automatically create public unauthenticated endpoints or choose a
@@ -244,6 +266,9 @@ The root also exposes the PostgreSQL and Redis durability building blocks. The
 database drivers are intentionally injected, so install and configure `pg` and
 `redis` in your application:
 
+The [persistence guide](https://github.com/Kkartik14/TVIC/blob/main/docs/persistence.md)
+covers migrations, memory scopes, Docker, ownership, and production retention.
+
 ```ts
 import {
   createPostgresMemory,