zooid

zooid provides OpenTelemetry auto-instrumentation and SDK helpers specifically engineered for conversational Voice AI applications (such as speech-to-speech agents, streaming LLM cascades, and voice bots) along with Telemetry Trust Center scoring for SigNoz.

It helps you track critical voice metrics like Time-To-First-Audio (TTFA), token stream latencies, interruptions, and multi-stage (STT -> LLM -> TTS) timing boundaries.

Installation

pip install zooid

For local development within this workspace:

pip install -e .

Quick Start

1. Initialize Instrumentation

Initialize OpenTelemetry providers and the Telemetry Trust Center at your application entry point:

from zooid import instrument_voice_app

handle = instrument_voice_app(
    service_name="voice-assistant-service",
    signoz_endpoint="localhost:4317",
    insecure=True,
    enable_trust_center=True
)

2. Trace Voice Turns

Wrap your conversational turns using the async context manager or decorator:

import asyncio
from zooid import VoiceTurnContext, voice_turn

# Option A: Async Context Manager (Recommended)
async def process_turn(audio_stream):
    async with VoiceTurnContext(architecture_mode="cascade") as turn:
        # 1. Speech-to-Text
        text = await process_stt(audio_stream)
        turn.mark_stt_complete()

        # 2. LLM Streaming
        async for chunk in stream_llm(text):
            if turn.llm_first_token_ms is None:
                turn.mark_llm_first_token()

        # 3. Text-to-Speech Output
        audio_out = await generate_tts(chunk)
        turn.mark_first_audio()  # Captures TTFA metric

# Option B: Decorator
@voice_turn(architecture_mode="hybrid")
async def handle_turn(input_data):
    current_turn = VoiceTurnContext.get_current()
    # Execute turn logic...

Core Features

• Automatic TTFA Tracking: Dedicated timing hooks to accurately record Time-To-First-Audio.
• Stage Latency Isolation: Measure STT duration, LLM Time-To-First-Token (TTFT), and TTS generation independently.
• Telemetry Trust Center: Live span quality evaluation calculating a score (0-100) with critical violation detection.
• Asyncio Context Propagation: Preserves OpenTelemetry trace context across asyncio.create_task() background loops.

API Reference

instrument_voice_app(...)

Initializes OpenTelemetry Tracer and Meter Providers configured for SigNoz OTLP gRPC export.

def instrument_voice_app(
    service_name: str = 'voice-agent',
    signoz_endpoint: str = 'localhost:4317',
    insecure: bool = True,
    enable_trust_center: bool = True,
    trust_center_mode: str = 'template',
    llm_endpoint: Optional[str] = None,
    export_interval_ms: int = 5000
) -> InstrumentationHandle

VoiceTurnContext

Context manager for tracking voice turn timing and metrics.

• VoiceTurnContext.get_current(): Returns the active VoiceTurnContext instance for the current asyncio context.
• turn.mark_stt_complete(): Marks STT processing completion and records STT duration.
• turn.mark_llm_first_token(): Marks the arrival of the first LLM token stream chunk.
• turn.mark_first_audio(): Marks the output of the first synthesized audio chunk and exports the TTFA metric.

Metrics Reference

License

Apache License 2.0