Metadata-Version: 2.4
Name: zooid
Version: 0.1.0
Summary: Zero-code OpenTelemetry auto-instrumentation for Voice AI pipelines & Telemetry Trust Center
Project-URL: Homepage, https://github.com/Priyank911/zooid
Project-URL: Repository, https://github.com/Priyank911/zooid
Author-email: Zooid Team <zooid@signoz.io>
License-File: LICENSE
Keywords: llm,opentelemetry,signoz,speech-to-text,text-to-speech,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: wrapt>=1.14.0
Provides-Extra: all
Requires-Dist: deepgram-sdk>=3.0.0; extra == 'all'
Requires-Dist: elevenlabs>=0.2.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: deepgram
Requires-Dist: deepgram-sdk>=3.0.0; extra == 'deepgram'
Provides-Extra: dev
Requires-Dist: mcp>=1.0.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Provides-Extra: elevenlabs
Requires-Dist: elevenlabs>=0.2.0; extra == 'elevenlabs'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# 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

```bash
pip install zooid
```

For local development within this workspace:
```bash
pip install -e .
```

---

## Quick Start

### 1. Initialize Instrumentation

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

```python
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:

```python
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.

```python
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

| Metric Name | Type | Unit | Description |
|---|---|---|---|
| `voice.time_to_first_audio_ms` | Histogram | ms | Time from user turn start to first synthesized audio |
| `voice.stt_duration_ms` | Histogram | ms | Speech-To-Text processing duration |
| `voice.llm_first_token_ms` | Histogram | ms | LLM Time-To-First-Token latency |
| `voice.turns_total` | Counter | 1 | Total number of conversational turns processed |
| `voice.interruptions_total` | Counter | 1 | Total number of user interruptions recorded |
| `instrumentation.score` | Gauge | 1 | Telemetry quality score (0-100) evaluated by Trust Center |

---

## License

Apache License 2.0
