Documentation / Reference / Public API
Public root API¶
Import provider-neutral types from vaani. Provider, recording, transport, and
publisher integrations use their documented submodules.
Begin with Assistant¶
| API | Purpose |
|---|---|
Assistant |
name, preset, prompt, preparation, named prompts, tools, optional deployment-owned Callable[[Call, str], object | Awaitable[object]] transfer operation, approved recording Adapter, and exact production lock |
Call |
immutable normalized incoming identity, approved metadata, and prepared state |
CallResult |
the one immutable terminal result after Closure |
BASIC_MONOLINGUAL |
convenient bundled development preset |
BIRLA_PROD_V42 |
alias for the source-default exact birla-prod-v42@14 preset |
The source-default @14 preset is published in rc43. Historical rc42 installs
remain paired with birla-prod-v42@13.
Use the Assistant guide. The construction
types below remain compatible for advanced consumers and are also grouped
under vaani.advanced.
The groups below are an orientation map, not a replacement for the frozen
contract. The installed package's vaani.__all__ defines the root exports.
Exact signatures, fields, enums, and invariants are frozen under
contracts/public/v1 in the matching source release.
Run a LiveKit worker¶
The worker boundary is available from vaani.assistant.worker:
| API | Purpose |
|---|---|
run_livekit_worker |
register one Assistant with LiveKit Agents and run its worker process |
OnRequestHandler |
callback type for a deployment-owned JobRequest accept/reject decision |
Pass on_request when a deployment needs admission before a call reaches
Assistant.run(). The callback must explicitly call the provider request's
accept() or reject(terminate=...). None preserves LiveKit's automatic
acceptance. See job admission and SIP canaries
for reassignment semantics and the distinction between shared-name admission
and upstream create_dispatch routing.
Select a startup environment¶
| API | Purpose |
|---|---|
bootstrap_environment |
select and freeze exactly one development or production document |
EnvironmentConfiguration, EnvironmentDocuments, ResolvedPreset |
resolved startup state and injectable document locations; environment.profile is the exact immutable ResolvedPreset and exposes its typed, read-only recording_requirement |
DevelopmentEvaluationCatalog, EvaluationSession |
expose one backend-owned development allow-list and bind one exact profile |
ProductionDeploymentProfile |
immutable production routes, fallbacks, failure domains, and resilience policy |
ProviderFailureDomain, ResiliencePolicy, RouteTarget |
public deployment values that configure bounded failover, Route Health, and recovery probes |
create_production_deployment_lock |
create secret-free review bytes for one production profile |
load_production_deployment |
load and validate one complete deployment document |
verify_production_deployment_lock |
reject environment, target, ordering, policy, or digest drift |
Route Health is worker-scoped runtime behavior configured through the deployment values above; there is no mutable global health object for an application to edit. The source distribution also carries the environment-bound reference console template and its exact compatibility assets.
Advanced: construct a call runtime¶
| API | Purpose |
|---|---|
VoiceRuntime |
immutable assembly of adapters and PriceBook; run() or start() |
ActiveCall |
call_id, revision, update(), end(), wait() |
CallSetup |
complete consumer setup |
CallInvocationContext |
telephony, opaque transport, consumer state |
CallResult |
one immutable terminal record |
Compose behavior¶
| API family | Main types |
|---|---|
| Cascade | CascadeMode, ExplicitFallback, OperationDeadlinePolicy |
| Languages | LanguagePolicy, LanguageBinding, LanguageProfile |
| Profiles | SpeechRecognitionProfile, ReasoningProfile, SpeechGenerationProfile |
| Conversation | GreetingPolicy, ConversationPolicy, EndingPolicy |
| Tools | RuntimeTool, ToolExecutionPolicy, ToolEffect, ToolRetryPolicy, ToolAuditPolicy, VoiceToolContext |
| Telephony features | RecordingPolicy, TransferPolicy, TransferRequest |
| Measurement | MeasurementPolicy, TranscriptCapturePolicy, PriceBook |
| Evaluation | JudgeSetup, JudgeRubric, JudgeEvidencePolicy |
Change or end a call¶
| API | Purpose |
|---|---|
CallUpdate |
atomic prompt, language, tools, STT, reasoning, and TTS replacement |
UpdateBoundary |
commit after current reply or interrupt now |
InterruptedReplyHandling |
regenerate latest turn or wait |
UpdateReceipt |
committed revision and selected routes |
UNCHANGED |
explicit unchanged sentinel/default |
EndRequest, EndRequestSource, EndReceipt |
graceful-ending coordination |
Inspect terminal evidence¶
The result types are grouped by:
- lifecycle and ending;
- transcript and timing;
- usage and cost;
- provider, language, update, and tool history;
- Judge, failures, telephony, recording, transfer, and provenance.
Start with the results concept. In the matching source
release, src/vaani/_model.py and
contracts/public/v1/schemas/call-result.schema.json define the exact fields.
Handle errors¶
VoiceRuntimeError is the immutable normalized base error.
InvalidCallSetup, CallStartFailed, UnsupportedUpdate, and
InvalidCallState identify common control-flow boundaries. See the
error taxonomy.
Build adapters and publishers¶
The root exports provider-neutral protocols and values:
RuntimeAdapter,TransportAdapter,RecordingAdapter,TransferAdapter;AdapterManifest;CredentialSource,CredentialScope;ResultPublisher,ResultPublicationRecord,DeliveryPolicy,DeliveryReport.
Concrete integrations are documented in Providers and credentials.
Advanced test primitives¶
RuntimeTestKit, ScriptedAdapter, FakeMonotonicClock, and
DeterministicIds remain public APIs for runtime maintainers. Application
acceptance should follow the live voice test.
Next: configuration reference or provider modules.