zooid 0.1.0__tar.gz

zooid-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+htmlcov/
+.venv
+venv/
+ENV/
+env/
+
+# Node / Web
+node_modules/
+web/node_modules/
+web/dist/
+web/.vite/
+.npm
+*.log
+
+# Web source dir — not the Python "lib/" build artifact excluded above
+!web/src/lib/
+!web/src/lib/**
+
+# IDE & OS
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+
+# Docker / Local logs
+*.log
+docker/*.log
+docker/.bin/
+docker/pours/
+docker/casting.yaml.lock
+
+# Secrets — never commit real API keys
+.env
+server/.env
+!server/.env.example

zooid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zooid-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+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

zooid-0.1.0/README.md

@@ -0,0 +1,123 @@
+# 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

zooid-0.1.0/dashboards/trust_center_dashboard.json

@@ -0,0 +1,102 @@
+{
+  "title": "Zooid Trust Center",
+  "description": "Dashboard for voice agent instrumentation scoring and health",
+  "widgets": [
+    {
+      "id": "w1",
+      "title": "Instrumentation Score",
+      "description": "Average instrumentation score across services",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_score",
+            "aggregate": "avg",
+            "groupBy": ["service_name"]
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 0, "y": 0 }
+    },
+    {
+      "id": "w2",
+      "title": "Score by Service",
+      "description": "Detailed scores per service",
+      "panelType": "table",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_score",
+            "aggregate": "avg",
+            "groupBy": ["service_name"]
+          }
+        ]
+      },
+      "layout": { "w": 8, "h": 4, "x": 4, "y": 0 }
+    },
+    {
+      "id": "w3",
+      "title": "Score Trend",
+      "description": "Score over time",
+      "panelType": "graph",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_score",
+            "aggregate": "avg",
+            "groupBy": ["service_name"]
+          }
+        ]
+      },
+      "layout": { "w": 6, "h": 4, "x": 0, "y": 2 }
+    },
+    {
+      "id": "w4",
+      "title": "Top Violations",
+      "description": "Most frequent instrumentation violations",
+      "panelType": "bar",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_violations_total",
+            "aggregate": "sum",
+            "groupBy": ["rule_id"]
+          }
+        ]
+      },
+      "layout": { "w": 6, "h": 4, "x": 6, "y": 4 }
+    },
+    {
+      "id": "w5",
+      "title": "Unscorable Spans",
+      "description": "Total unscorable spans",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_unscorable_total",
+            "aggregate": "sum"
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 0, "y": 6 }
+    },
+    {
+      "id": "w6",
+      "title": "Category Distribution",
+      "description": "Distribution of violation categories",
+      "panelType": "pie",
+      "query": {
+        "metrics": [
+          {
+            "name": "instrumentation_violations_total",
+            "aggregate": "sum",
+            "groupBy": ["category"]
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 4, "x": 4, "y": 6 }
+    }
+  ],
+  "layout": []
+}

zooid-0.1.0/dashboards/voice_agent_dashboard.json

@@ -0,0 +1,114 @@
+{
+  "title": "Voice Agent Dashboard",
+  "description": "Performance and health metrics for voice agents",
+  "widgets": [
+    {
+      "id": "w1",
+      "title": "TTFA (p50)",
+      "description": "Time to First Audio (50th percentile)",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_time_to_first_audio_ms",
+            "aggregate": "p50"
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 0, "y": 0 }
+    },
+    {
+      "id": "w2",
+      "title": "TTFA Distribution",
+      "description": "Histogram of Time to First Audio",
+      "panelType": "graph",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_ttfa_distribution",
+            "aggregate": "sum"
+          }
+        ]
+      },
+      "layout": { "w": 8, "h": 4, "x": 4, "y": 0 }
+    },
+    {
+      "id": "w3",
+      "title": "TTFA by Architecture",
+      "description": "Time to First Audio categorized by voice architecture",
+      "panelType": "bar",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_time_to_first_audio_ms",
+            "aggregate": "avg",
+            "groupBy": ["voice_architecture"]
+          }
+        ]
+      },
+      "layout": { "w": 6, "h": 4, "x": 0, "y": 2 }
+    },
+    {
+      "id": "w4",
+      "title": "Stage Latency",
+      "description": "Latency for STT, LLM, TTS stages",
+      "panelType": "table",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_stage_latency_ms",
+            "aggregate": "avg",
+            "groupBy": ["stage_name"]
+          }
+        ]
+      },
+      "layout": { "w": 6, "h": 4, "x": 6, "y": 4 }
+    },
+    {
+      "id": "w5",
+      "title": "Total Turns",
+      "description": "Total number of conversational turns",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_turns_total",
+            "aggregate": "sum"
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 0, "y": 6 }
+    },
+    {
+      "id": "w6",
+      "title": "Error Rate",
+      "description": "Percentage of turns with errors",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_errors_total",
+            "aggregate": "sum"
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 4, "y": 6 }
+    },
+    {
+      "id": "w7",
+      "title": "Interruptions",
+      "description": "User interruptions during generation",
+      "panelType": "value",
+      "query": {
+        "metrics": [
+          {
+            "name": "voice_interruptions_total",
+            "aggregate": "sum"
+          }
+        ]
+      },
+      "layout": { "w": 4, "h": 2, "x": 8, "y": 6 }
+    }
+  ],
+  "layout": []
+}

zooid-0.1.0/examples/basic_voice_agent.py

@@ -0,0 +1,64 @@
+import asyncio
+import random
+import time
+from zooid import instrument_voice_app, voice_turn, VoiceTurnContext
+
+from opentelemetry import trace
+
+# Initialize instrumentation for the demo
+instrument_voice_app(service_name='demo-voice-agent', signoz_endpoint='localhost:4317')
+
+@voice_turn()
+async def process_turn(turn_idx: int):
+    print(f"--- Starting Turn {turn_idx} ---")
+    context = VoiceTurnContext.get_current()
+    
+    # 1. STT Phase
+    with context.tracer.start_as_current_span("stt.transcribe") as span:
+        print("Listening...")
+        # Intentional "bad" instrumentation for turn 3
+        if turn_idx != 3:
+            span.set_attribute("gen_ai.system", "deepgram")
+        await asyncio.sleep(random.uniform(0.15, 0.25))
+        transcript = "Hello, how are you?"
+        span.set_attribute("stt.transcript", transcript)
+        
+    # 2. LLM Phase
+    with context.tracer.start_as_current_span("llm.generate") as span:
+        print("Thinking...")
+        span.set_attribute("gen_ai.system", "openai")
+        span.set_attribute("llm.model", "gpt-4o-mini")
+        
+        # Simulate LLM streaming and latency
+        await asyncio.sleep(random.uniform(0.2, 0.4))
+        
+        if turn_idx == 7: # Simulate an error
+            span.record_exception(Exception("LLM API Timeout"))
+            span.set_status(2, "Error occurred") # Status.ERROR = 2
+            print("LLM Error!")
+            return
+            
+        response_text = "I am doing great, thank you!"
+        
+    # 3. TTS Phase
+    with context.tracer.start_as_current_span("tts.synthesize") as span:
+        print("Speaking...")
+        span.set_attribute("gen_ai.system", "elevenlabs")
+        
+        await asyncio.sleep(random.uniform(0.05, 0.15))
+        
+        # Mark time to first audio
+        context.record_ttfa()
+        
+        await asyncio.sleep(0.5) # Simulate audio playing out
+        print("Finished speaking.")
+
+async def main():
+    print("Starting simulated voice agent...")
+    for i in range(1, 11):
+        await process_turn(i)
+        await asyncio.sleep(1)
+    print("Simulation complete.")
+
+if __name__ == "__main__":
+    asyncio.run(main())

zooid-0.1.0/examples/docker-compose.yml

@@ -0,0 +1,14 @@
+version: "3"
+services:
+  # This is a reference docker-compose for running examples.
+  # It assumes you have the main SigNoz stack running in the zooid-net network.
+  example-agent:
+    build: .
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-otel-collector:4317
+    networks:
+      - zooid-net
+
+networks:
+  zooid-net:
+    external: true

zooid-0.1.0/examples/pipecat_agent.py

@@ -0,0 +1,28 @@
+import asyncio
+from zooid import instrument_voice_app, voice_turn
+
+# NOTE: This is a structural example showing how you might integrate with Pipecat.
+# It assumes a typical Pipecat pipeline setup.
+
+# instrument_voice_app(service_name='pipecat-voice-agent')
+
+@voice_turn
+async def handle_user_input(pipeline, user_audio):
+    """
+    In a real Pipecat app, you might wrap your main event handlers
+    or pipeline execution points with the @voice_turn decorator.
+    """
+    print("Processing user audio through Pipecat pipeline...")
+    # await pipeline.process(user_audio)
+    await asyncio.sleep(0.5)
+    print("Response generated.")
+
+async def main():
+    print("Pipecat integration example (mocked)")
+    # pipeline = build_pipeline()
+    # while True:
+    #     audio = get_audio()
+    #     await handle_user_input(pipeline, audio)
+
+if __name__ == "__main__":
+    asyncio.run(main())