Documentation / Guides / Providers

Provider setup, extras, and credentials¶

Provider selection is consumer policy. VAANI exposes typed profiles and, where the public contract includes one, a factory that creates a capability-declaring adapter.

Support matrix¶

“Profile” means the public module can represent the route. “Factory” means a consumer can construct the packaged adapter without using a private underscore-prefixed API.

Integration	Extra	Role	Public construction
Deepgram	`deepgram`	STT	profile + `create_deepgram_adapter`
Google / Vertex	`google`	STT, reasoning, TTS	profiles + `create_google_adapter`
Sarvam	`sarvam`	STT, TTS, language detection	profiles + `create_sarvam_adapter`
SmallestAI	`smallestai`	TTS	profile + `create_smallestai_adapter`
ElevenLabs	`elevenlabs`	TTS	profile only in current public module
Cartesia	`cartesia`	TTS	profile + `create_cartesia_adapter`
OpenAI	`openai`	reasoning	profile + `create_openai_adapter`
OpenRouter	`openrouter`	reasoning	profile + `create_openrouter_adapter`
Groq	`groq`	reasoning	profile only in current public module
Silero	`silero`	VAD	profile only in current public module
LiveKit turn detector	`turn-detector`	endpointing	profile only in current public module
LiveKit noise cancellation	`noise-cancellation`	audio processing	profile only in current public module
GCS recording	`recording-gcs`	recording	config + adapter class
PostgreSQL	`postgres`	result publication	config + publisher class

All rows are in supported-adapters@1; that promise does not imply identical public factory coverage. Never call private _runtime_adapter helpers from a consumer. Groq is a supported optional route, but live Groq validation is deferred and outside the currently documented tested path.

Install a minimal set¶

python -m pip install "vaani[deepgram,google,cartesia]"

Keep LiveKit provider plugins on the same patch line during first migration (1.5.17). The contract supports >=1.5.17,<1.6.0 and requires patch alignment. There is no all extra.

Credentials are explicit¶

Factories accept both a CredentialSource and the exact CredentialScope it must expose. VAANI does not read ambient environment variables.

import os
from vaani import CredentialScope

class EnvironmentCredential:
    def __init__(self, name: str, scope: CredentialScope) -> None:
        self._name = name
        self._scope = scope

    @property
    def scope(self) -> CredentialScope:
        return self._scope

    async def resolve(self) -> object:
        value = os.getenv(self._name)
        if not value:
            raise RuntimeError(f"required credential {self._name} is absent")
        return value

Keep the environment name and scope in consumer deployment code. Do not put a secret in a profile, CallSetup, adapter ID, route ID, result, or log.

Factory example¶

This credential-required construction snippet creates an AI Studio reasoning adapter; it does not make a network call:

from vaani import CredentialScope
from vaani.providers.google import (
    GoogleAuthMode,
    GoogleProviderRole,
    GoogleReasoningOptions,
    create_google_adapter,
)

scope = CredentialScope("google", "api-key", "ai-studio-prod", None)
credential = EnvironmentCredential("GOOGLE_GEMINI_API_KEY", scope)
adapter = create_google_adapter(
    adapter_id="google-ai-studio",
    credential_source=credential,
    credential_scope=scope,
    roles=(GoogleProviderRole.REASONING,),
    auth_mode=GoogleAuthMode.API_KEY,
    routes=("google-ai-studio",),
    models=("approved-model-id",),
    voices=(),
    languages=("en-IN", "hi-IN"),
    reasoning=GoogleReasoningOptions(
        temperature=0.4,
        max_output_tokens=512,
    ),
)

For Vertex reasoning use VERTEX_SERVICE_ACCOUNT, a service-account JSON credential source, and explicit project and location. For Google speech roles use SERVICE_ACCOUNT_JSON; API-key mode is reasoning-only.

Repository smoke environment names¶

These names belong to the repository's optional live smoke runners, not the core runtime:

Runner	Names
Deepgram → Google → Cartesia	`DEEPGRAM_API_KEY`, `GOOGLE_API_KEY`, `CARTESIA_API_KEY`, `VAANI_CARTESIA_VOICE_ID`
OpenAI / Groq reasoning	`OPENAI_API_KEY` or `GROQ_API_KEY`
Sarvam	`SARVAM_API_KEY`
ElevenLabs / SmallestAI	`ELEVENLABS_API_KEY`, `SMALLEST_API_KEY`

Missing credentials are expected to block a live smoke; that is not a live success. Current documentation verification makes no network calls.

LiveKit transport¶

LiveKitTransportAdapter accepts a LiveKitCallHandoff containing:

a validated TelephonyIdentity;
an async iterable of normalized events;
a callable audio sink;
a callable close operation.

The deployment still owns SIP provisioning and turns its already-routed LiveKit job/room callbacks into that handoff.

VAANI currently provides the handoff adapter, not a turnkey LiveKit worker bridge. A consumer must still wire job acceptance, room events, audio sinks, and shutdown into these normalized operations. The privately published create-vaani-app==0.1.2 companion Starter CLI generates that bridge as consumer/deployment scaffolding; it is not part of the current public runtime. Version 0.1.3 is in progress, and its credentialed live path is unverified.

Next: exact provider exports or production readiness.