Skip to content

Documentation / Core concepts / Configuration model

CallSetup, bindings, profiles, and adapters

CallSetup is the consumer's immutable description of one call. It contains no provider clients or secrets.

The public values are frozen dataclasses. Build them directly and use dataclasses.replace() for copy-on-change composition; do not assign to fields. See the verified replacement pattern.

Build from the inside out

  1. A speech-recognition, reasoning, or speech-generation profile selects a route and reviewed behavior identity.
  2. LanguageProfile groups one compatible STT → LLM → TTS path.
  3. LanguageBinding attaches consumer instructions and tools to one language.
  4. LanguagePolicy declares enabled bindings and optional switching behavior.
  5. CascadeMode selects the initial routes, operation deadlines, required update capabilities, and explicit fallbacks.
  6. CallSetup combines those values with greeting, conversation, ending, measurement, recording, transfer, and optional Judge policy.
recognition = SpeechRecognitionProfile("nova-3", "1", "deepgram", "hi-IN")
reasoning = ReasoningProfile("gemini", "1", "vertex", "hi-IN")
generation = SpeechGenerationProfile(
    "chirp-3", "1", "google-speech", "hi-IN", "approved-voice-id"
)
profile = LanguageProfile(
    "product-hi-IN", "1", recognition, reasoning, generation
)
binding = LanguageBinding(
    "hi-IN",
    profile,
    product_prompt,
    (lookup_product_catalog,),
)

This is a construction snippet: the IDs are consumer configuration, not VAANI defaults.

Profiles describe; adapters execute

A profile's route_id must match an adapter's adapter_id. The profile selects a declared model/voice/language. The adapter holds the provider capability and resolves credentials at the operation boundary.

SpeechGenerationProfile(route_id="google-speech", voice_id="...")
                                  │
                                  ▼
adapter_id="google-speech" with cascade.tts capability

Use a distinct adapter ID when the same vendor has materially different authentication or roles—for example vertex, google-ai-studio, and google-speech.

Complete language bindings

Every enabled language must have:

  • consumer-written instructions;
  • one compatible speech-recognition profile;
  • one compatible reasoning profile;
  • one compatible speech-generation profile and voice;
  • the correct tools for that language.

VAANI never translates or fills in a missing prompt. One deliberately multilingual instruction can be assigned to multiple bindings, but the consumer must make that choice explicitly.

Preflight before ownership

VoiceRuntime.start() validates setup before publishing an ActiveCall. Invalid route references, unsafe tool schemas, missing language coverage, incompatible recording/transfer adapters, and unsupported required update capabilities raise InvalidCallSetup. Because lifecycle ownership has not begun, there is no CallResult for a startup failure.

Where to find exact fields

These docs teach the shape without duplicating every field:

Next: the call lifecycle or provider composition.