Documentation / Reference / Public API
Public root API¶
Import provider-neutral types from vaani. Provider, recording, transport, and
publisher integrations use their documented submodules.
The groups below are an orientation map, not a replacement for the frozen
contract. Exact signatures, field order, defaults, enums, and method invariants
are authoritative in vaani.__all__ (src/vaani/__init__.py) and
contracts/public/v1 in the source repository.
Run a call¶
| 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/profile 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, then use the
CallResult source in src/vaani/_model.py and the call-result.v1 schema in
contracts/public/v1/schemas/call-result.schema.json for 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 provider reference.
Test¶
RuntimeTestKit, ScriptedAdapter, FakeMonotonicClock, and
DeterministicIds are public deterministic test APIs. See the
testing guide.
Next: configuration reference or provider modules.