zooid 0.1.0__py3-none-any.whl

zooid/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ._version import __version__
+from .instrumentor import instrument_voice_app
+from .context import (
+    voice_turn,
+    VoiceTurnContext,
+    create_traced_task,
+    traced_callback,
+    get_current_turn,
+)
+from .metrics import VoiceMetrics
+from .wrappers.base_wrapper import unpatch_all
+
+__all__ = [
+    "__version__",
+    "instrument_voice_app",
+    "voice_turn",
+    "VoiceTurnContext",
+    "create_traced_task",
+    "traced_callback",
+    "VoiceMetrics",
+    "get_current_turn",
+    "unpatch_all",
+]

zooid/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

zooid/context.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import inspect
+import time
+from typing import Any, AsyncGenerator, Awaitable, Callable, Coroutine, Dict, Optional, TypeVar, cast
+import functools
+
+from opentelemetry import trace, context as otel_context
+from opentelemetry.trace.status import Status, StatusCode
+
+tracer = trace.get_tracer(__name__)
+
+_voice_turn_var: contextvars.ContextVar[Optional["VoiceTurnContext"]] = contextvars.ContextVar(
+    "_voice_turn_var", default=None
+)
+
+def get_current_turn() -> Optional[VoiceTurnContext]:
+    """Get the current voice turn context if one exists."""
+    return _voice_turn_var.get()
+
+class VoiceTurnContext:
+    """Context manager for tracking voice turn timing and metrics."""
+    
+    def __init__(
+        self, 
+        architecture_mode: str = "sequential",
+        attributes: Optional[Dict[str, Any]] = None
+    ):
+        self.architecture_mode = architecture_mode
+        self.attributes = attributes or {}
+        self.start_time: float = 0.0
+        self.ttfa_ms: Optional[float] = None
+        self.stt_duration_ms: Optional[float] = None
+        self.llm_first_token_ms: Optional[float] = None
+        self.span: Optional[trace.Span] = None
+        self._token: Optional[contextvars.Token] = None
+        self._span_token: Optional[object] = None
+
+    @classmethod
+    def get_current(cls) -> Optional["VoiceTurnContext"]:
+        """Class method alias to get current voice turn context."""
+        return get_current_turn()
+
+    @property
+    def tracer(self) -> trace.Tracer:
+        """Expose tracer instance."""
+        return tracer
+
+    def record_stt_complete(self) -> None:
+        if self.start_time:
+            self.stt_duration_ms = (time.monotonic() - self.start_time) * 1000.0
+
+    def mark_stt_complete(self) -> None:
+        self.record_stt_complete()
+
+    def record_llm_first_token(self) -> None:
+        if self.start_time and self.llm_first_token_ms is None:
+            self.llm_first_token_ms = (time.monotonic() - self.start_time) * 1000.0
+
+    def mark_llm_first_token(self) -> None:
+        self.record_llm_first_token()
+
+    def record_ttfa(self) -> None:
+        if self.start_time and self.ttfa_ms is None:
+            self.ttfa_ms = (time.monotonic() - self.start_time) * 1000.0
+            if self.span:
+                self.span.set_attribute("voice.time_to_first_audio_ms", self.ttfa_ms)
+
+    def mark_first_audio(self) -> None:
+        self.record_ttfa()
+
+    async def __aenter__(self) -> "VoiceTurnContext":
+        self.start_time = time.monotonic()
+        
+        attrs = {
+            "voice.architecture_mode": self.architecture_mode,
+            **self.attributes
+        }
+        
+        self.span = tracer.start_span("voice.turn", attributes=attrs)
+        self._span_token = otel_context.attach(trace.set_span_in_context(self.span))
+        self._token = _voice_turn_var.set(self)
+        
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        try:
+            if exc_type is not None:
+                if self.span:
+                    self.span.set_status(Status(StatusCode.ERROR, str(exc_val)))
+                    if issubclass(exc_type, asyncio.CancelledError):
+                        self.span.set_attribute("voice.interrupted", True)
+            
+            if self.span:
+                if self.ttfa_ms is not None:
+                    self.span.set_attribute("voice.time_to_first_audio_ms", self.ttfa_ms)
+                if self.stt_duration_ms is not None:
+                    self.span.set_attribute("voice.stt_duration_ms", self.stt_duration_ms)
+                if self.llm_first_token_ms is not None:
+                    self.span.set_attribute("voice.llm_first_token_ms", self.llm_first_token_ms)
+                self.span.end()
+        finally:
+            if self._span_token is not None:
+                otel_context.detach(self._span_token)
+            if self._token is not None:
+                _voice_turn_var.reset(self._token)
+
+def voice_turn(architecture_mode: str = "sequential") -> Callable:
+    """Decorator to wrap a function in a VoiceTurnContext."""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            async with VoiceTurnContext(architecture_mode=architecture_mode):
+                return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+T = TypeVar("T")
+
+def create_traced_task(coro: Coroutine[Any, Any, T], name: Optional[str] = None) -> asyncio.Task[T]:
+    """Create an asyncio task that inherits the current OpenTelemetry and Voice turn context."""
+    current_otel_context = otel_context.get_current()
+    current_voice_turn = _voice_turn_var.get()
+    
+    async def wrapped_coro() -> T:
+        token = otel_context.attach(current_otel_context)
+        vt_token = _voice_turn_var.set(current_voice_turn)
+        try:
+            return await coro
+        finally:
+            otel_context.detach(token)
+            _voice_turn_var.reset(vt_token)
+            
+    return asyncio.create_task(wrapped_coro(), name=name)
+
+def traced_callback(func: Callable) -> Callable:
+    """Decorator for preserving context in callbacks (sync or async)."""
+    current_otel_context = otel_context.get_current()
+    current_voice_turn = _voice_turn_var.get()
+
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            token = otel_context.attach(current_otel_context)
+            vt_token = _voice_turn_var.set(current_voice_turn)
+            try:
+                return await func(*args, **kwargs)
+            finally:
+                otel_context.detach(token)
+                _voice_turn_var.reset(vt_token)
+        return async_wrapper
+    else:
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            token = otel_context.attach(current_otel_context)
+            vt_token = _voice_turn_var.set(current_voice_turn)
+            try:
+                return func(*args, **kwargs)
+            finally:
+                otel_context.detach(token)
+                _voice_turn_var.reset(vt_token)
+        return sync_wrapper
+
+async def traced_async_generator(
+    original: AsyncGenerator[T, None], 
+    span: trace.Span, 
+    on_first_item: Optional[Callable[[], None]] = None
+) -> AsyncGenerator[T, None]:
+    """Wrap an async generator to maintain context and track chunks."""
+    current_otel_context = otel_context.get_current()
+    current_voice_turn = _voice_turn_var.get()
+    
+    chunk_count = 0
+    
+    try:
+        token = otel_context.attach(current_otel_context)
+        vt_token = _voice_turn_var.set(current_voice_turn)
+        
+        try:
+            async for item in original:
+                if chunk_count == 0 and on_first_item:
+                    on_first_item()
+                chunk_count += 1
+                
+                # Detach before yielding to avoid leaking context to consumer
+                otel_context.detach(token)
+                _voice_turn_var.reset(vt_token)
+                
+                yield item
+                
+                # Re-attach after consumer returns control
+                token = otel_context.attach(current_otel_context)
+                vt_token = _voice_turn_var.set(current_voice_turn)
+                
+        finally:
+            # Final detach in case we broke out of the loop
+            # Or if it completed normally, we still need to detach the re-attached context
+            try:
+                otel_context.detach(token)
+            except Exception:
+                pass
+            try:
+                _voice_turn_var.reset(vt_token)
+            except Exception:
+                pass
+            
+            span.set_attribute("gen.chunk_count", chunk_count)
+            span.end()
+    except asyncio.CancelledError:
+        span.set_status(Status(StatusCode.ERROR, "Cancelled"))
+        span.end()
+        raise
+    except Exception as e:
+        span.set_status(Status(StatusCode.ERROR, str(e)))
+        span.end()
+        raise

zooid/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/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/exporters/__init__.py

@@ -0,0 +1 @@
+

zooid/exporters/signoz.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+
+
+@dataclass
+class SigNozConfig:
+    endpoint: str = "localhost:4317"
+    insecure: bool = True
+    headers: Dict[str, str] = field(default_factory=dict)
+    
+    @property
+    def formatted_endpoint(self) -> str:
+        if "://" in self.endpoint:
+            return self.endpoint
+        return f"http://{self.endpoint}" if self.insecure else f"https://{self.endpoint}"
+
+
+def create_signoz_exporter(
+    endpoint: str = "localhost:4317",
+    insecure: bool = True,
+    headers: Optional[Dict[str, str]] = None
+) -> OTLPSpanExporter:
+    """Helper function to create a SigNoz specific OTLP Span Exporter."""
+    config = SigNozConfig(endpoint=endpoint, insecure=insecure, headers=headers or {})
+    
+    return OTLPSpanExporter(
+        endpoint=config.formatted_endpoint,
+        insecure=config.insecure,
+        headers=config.headers
+    )
+    
+def create_signoz_metric_exporter(
+    endpoint: str = "localhost:4317",
+    insecure: bool = True,
+    headers: Optional[Dict[str, str]] = None
+) -> OTLPMetricExporter:
+    """Helper function to create a SigNoz specific OTLP Metric Exporter."""
+    config = SigNozConfig(endpoint=endpoint, insecure=insecure, headers=headers or {})
+    
+    return OTLPMetricExporter(
+        endpoint=config.formatted_endpoint,
+        insecure=config.insecure,
+        headers=config.headers
+    )

zooid/instrumentor.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional, Any
+
+from opentelemetry import trace
+from opentelemetry import metrics
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION, DEPLOYMENT_ENVIRONMENT
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+
+from .metrics import VoiceMetrics
+from ._version import __version__
+
+logger = logging.getLogger(__name__)
+
+class InstrumentationHandle:
+    def __init__(
+        self,
+        tracer_provider: TracerProvider,
+        meter_provider: MeterProvider,
+        voice_metrics: VoiceMetrics,
+        trust_processor: Optional[Any] = None,
+        context_writer: Optional[Any] = None
+    ):
+        self.tracer_provider = tracer_provider
+        self.meter_provider = meter_provider
+        self.voice_metrics = voice_metrics
+        self.trust_processor = trust_processor
+        self.context_writer = context_writer
+
+    def shutdown(self) -> None:
+        """Shutdown the providers and the background context writer."""
+        if self.context_writer is not None:
+            try:
+                self.context_writer.stop()
+            except Exception as e:
+                logger.error("Failed to stop context writer: %s", e)
+        try:
+            self.tracer_provider.shutdown()
+            self.meter_provider.shutdown()
+        except Exception as e:
+            logger.error("Failed to shutdown OpenTelemetry providers: %s", e)
+
+    def __enter__(self) -> "InstrumentationHandle":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.shutdown()
+
+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,
+    context_path: Optional[str] = None
+) -> InstrumentationHandle:
+    """Instrument a voice application with OpenTelemetry for SigNoz."""
+    
+    resource = Resource.create({
+        SERVICE_NAME: service_name,
+        SERVICE_VERSION: __version__,
+        DEPLOYMENT_ENVIRONMENT: "production",
+        "telemetry.sdk.name": "zooid",
+        "telemetry.sdk.language": "python",
+        "telemetry.sdk.version": __version__,
+    })
+
+    endpoint_url = signoz_endpoint if "://" in signoz_endpoint else f"http://{signoz_endpoint}"
+    
+    # Trace setup
+    tracer_provider = TracerProvider(resource=resource)
+    span_exporter = OTLPSpanExporter(endpoint=endpoint_url, insecure=insecure)
+    span_processor = BatchSpanProcessor(span_exporter)
+    tracer_provider.add_span_processor(span_processor)
+
+    trust_processor = None
+    context_writer = None
+    if enable_trust_center:
+        try:
+            from .trust import InstrumentationScoreProcessor
+            trust_processor = InstrumentationScoreProcessor(
+                mode=trust_center_mode,
+                llm_endpoint=llm_endpoint,
+            )
+            tracer_provider.add_span_processor(trust_processor)
+
+            # Mirror the live score to .zooid/context.json for coding agents / MCP.
+            from .trust.context_writer import ContextSyncWriter, DEFAULT_PATH
+            path = context_path or os.environ.get("ZOOID_CONTEXT_PATH", DEFAULT_PATH)
+            context_writer = ContextSyncWriter(
+                trust_processor.aggregator, service_name, path=path
+            ).start()
+        except ImportError:
+            logger.warning("Could not import InstrumentationScoreProcessor. Ensure it exists in .trust module.")
+        except Exception as e:
+            logger.warning("Failed to start Trust Center / context writer: %s", e)
+
+    trace.set_tracer_provider(tracer_provider)
+
+    # Metrics setup
+    metric_exporter = OTLPMetricExporter(endpoint=endpoint_url, insecure=insecure)
+    metric_reader = PeriodicExportingMetricReader(
+        metric_exporter, export_interval_millis=export_interval_ms
+    )
+    meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+    metrics.set_meter_provider(meter_provider)
+
+    voice_metrics = VoiceMetrics(meter_provider)
+
+    # Patch libraries (ignoring ImportError for optional dependencies)
+    try:
+        from .wrappers.openai_wrapper import patch_openai
+        patch_openai()
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.warning("Failed to patch OpenAI: %s", e)
+
+    try:
+        from .wrappers.elevenlabs_wrapper import patch_elevenlabs
+        patch_elevenlabs()
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.warning("Failed to patch ElevenLabs: %s", e)
+
+    try:
+        from .wrappers.deepgram_wrapper import patch_deepgram
+        patch_deepgram()
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.warning("Failed to patch Deepgram: %s", e)
+
+    return InstrumentationHandle(
+        tracer_provider=tracer_provider,
+        meter_provider=meter_provider,
+        voice_metrics=voice_metrics,
+        trust_processor=trust_processor,
+        context_writer=context_writer
+    )