synth-ai 0.2.8.dev4__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/tracing_v3/examples/basic_usage.py

@@ -2,13 +2,14 @@
 
 import asyncio
 import time
+from typing import Any
 
-from synth_ai.tracing_v3 import SessionTracer
-from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, RuntimeEvent, TimeRecord
-from synth_ai.tracing_v3.turso.daemon import SqldDaemon
+from .. import SessionTracer
+from ..abstractions import EnvironmentEvent, LMCAISEvent, RuntimeEvent, TimeRecord
+from ..turso.daemon import SqldDaemon
 
 
-async def simulate_llm_call(model: str, prompt: str) -> dict:
+async def simulate_llm_call(model: str, prompt: str) -> dict[str, Any]:
     """Simulate an LLM API call."""
     await asyncio.sleep(0.1)  # Simulate network latency
 
@@ -133,6 +134,9 @@ async def main():
         print("\n--- Example 3: Querying Data ---")
 
         # Get model usage statistics
+        if tracer.db is None:
+            raise RuntimeError("Tracer database backend is not initialized")
+
         model_usage = await tracer.db.get_model_usage()
         print("\nModel Usage:")
         print(model_usage)
@@ -150,9 +154,10 @@ async def main():
         # Get specific session details
         if recent_sessions:
             session_detail = await tracer.db.get_session_trace(recent_sessions[0]["session_id"])
-            print(f"\nSession Detail for {session_detail['session_id']}:")
-            print(f"  Created: {session_detail['created_at']}")
-            print(f"  Timesteps: {len(session_detail['timesteps'])}")
+            if session_detail:
+                print(f"\nSession Detail for {session_detail['session_id']}:")
+                print(f"  Created: {session_detail['created_at']}")
+                print(f"  Timesteps: {len(session_detail['timesteps'])}")
 
         # Example 4: Using hooks
         print("\n--- Example 4: Hooks ---")
@@ -166,8 +171,9 @@ async def main():
 
         tracer.hooks.register("event_recorded", count_events, name="event_counter")
 
-        async with tracer.session(metadata={"example": "hooks"}) as session_id, tracer.timestep(
-            "hook_test"
+        async with (
+            tracer.session(metadata={"example": "hooks"}) as session_id,
+            tracer.timestep("hook_test"),
         ):
             for i in range(3):
                 event = RuntimeEvent(

synth_ai/tracing_v3/hooks.py

@@ -1,4 +1,3 @@
-from __future__ import annotations
 """Hook system for extending tracing functionality.
 
 The hook system provides a flexible way to extend the tracing system without
@@ -33,6 +32,8 @@ Common Use Cases:
 - Custom filtering and sampling
 """
 
+from __future__ import annotations
+
 import asyncio
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -88,9 +89,9 @@ class HookManager:
         self,
         event: str,
         callback: Callable,
-        name: str = None,
+        name: str | None = None,
         priority: int = 0,
-        event_types: list[str] = None,
+        event_types: list[str] | None = None,
     ) -> Hook:
         """Register a new hook.
 
@@ -114,7 +115,7 @@ class HookManager:
             raise ValueError(f"Unknown hook event: {event}")
 
         hook = Hook(
-            name=name or callback.__name__,
+            name=name or getattr(callback, "__name__", "unknown"),
             callback=callback,
             event_types=event_types,
             priority=priority,
@@ -202,6 +203,7 @@ def create_default_hooks() -> HookManager:
     # Example: Log session starts - useful for debugging and monitoring
     async def log_session_start(session_id: str, metadata: dict[str, Any]):
         import os
+
         if os.getenv("SYNTH_TRACE_VERBOSE", "0") in ("1", "true", "True"):
             print(f"Session started: {session_id}")
 

synth_ai/tracing_v3/llm_call_record_helpers.py

@@ -4,12 +4,14 @@ This module provides utilities to convert vendor responses to LLMCallRecord
 format and compute aggregates from call records.
 """
 
+from __future__ import annotations
+
 import uuid
-from datetime import datetime
-from typing import Any
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, TypedDict, cast
 
-from synth_ai.lm.vendors.base import BaseLMResponse
-from synth_ai.tracing_v3.lm_call_record_abstractions import (
+from .lm_call_record_abstractions import (
     LLMCallRecord,
     LLMChunk,
     LLMContentPart,
@@ -20,6 +22,63 @@ from synth_ai.tracing_v3.lm_call_record_abstractions import (
 )
 
 
+class BaseLMResponse:
+    """
+    Standard response format from language model API calls.
+    
+    This is a simple dataclass-like object for compatibility with tracing helpers.
+    Can be used as a dict-like object or with attributes.
+    
+    Attributes:
+        raw_response: The raw text response from the model
+        structured_output: Optional parsed Pydantic model if structured output was requested
+        tool_calls: Optional list of tool calls if tools were provided
+        response_id: Optional response ID for thread management (Responses API)
+        reasoning: Optional reasoning trace from the model (o1 models)
+        api_type: Optional API type used ("chat", "responses", or "harmony")
+        usage: Optional usage dictionary with token counts and costs
+    """
+    
+    def __init__(
+        self,
+        raw_response: str,
+        structured_output: Any | None = None,
+        tool_calls: list[dict] | None = None,
+        response_id: str | None = None,
+        reasoning: str | None = None,
+        api_type: str | None = None,
+        usage: dict[str, Any] | None = None,
+    ):
+        self.raw_response = raw_response
+        self.structured_output = structured_output
+        self.tool_calls = tool_calls
+        self.response_id = response_id
+        self.reasoning = reasoning
+        self.api_type = api_type
+        self.usage = usage
+    
+    def __getitem__(self, key: str) -> Any:
+        """Allow dict-like access for backward compatibility."""
+        return getattr(self, key)
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Allow dict-like .get() for backward compatibility."""
+        return getattr(self, key, default)
+
+
+class _UsageDict(TypedDict, total=False):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+    reasoning_tokens: int
+    cost_usd: float
+    duration_ms: int
+    reasoning_input_tokens: int
+    reasoning_output_tokens: int
+    cache_write_tokens: int
+    cache_read_tokens: int
+
+
 def create_llm_call_record_from_response(
     response: BaseLMResponse,
     model_name: str,
@@ -110,9 +169,10 @@ def create_llm_call_record_from_response(
         )
 
     # Extract tool calls if present
-    output_tool_calls = []
-    if hasattr(response, "tool_calls") and response.tool_calls:
-        for idx, tool_call in enumerate(response.tool_calls):
+    output_tool_calls: list[ToolCallSpec] = []
+    tool_calls_data = cast(list[dict[str, Any]] | None, getattr(response, "tool_calls", None))
+    if tool_calls_data:
+        for idx, tool_call in enumerate(tool_calls_data):
             if isinstance(tool_call, dict):
                 output_tool_calls.append(
                     ToolCallSpec(
@@ -125,18 +185,19 @@ def create_llm_call_record_from_response(
 
     # Extract usage information
     usage = None
-    if hasattr(response, "usage") and response.usage:
+    usage_data = cast(_UsageDict | None, getattr(response, "usage", None))
+    if usage_data:
         usage = LLMUsage(
-            input_tokens=response.usage.get("input_tokens"),
-            output_tokens=response.usage.get("output_tokens"),
-            total_tokens=response.usage.get("total_tokens"),
-            cost_usd=response.usage.get("cost_usd"),
+            input_tokens=usage_data.get("input_tokens"),
+            output_tokens=usage_data.get("output_tokens"),
+            total_tokens=usage_data.get("total_tokens"),
+            cost_usd=usage_data.get("cost_usd"),
             # Additional token accounting if available
-            reasoning_tokens=response.usage.get("reasoning_tokens"),
-            reasoning_input_tokens=response.usage.get("reasoning_input_tokens"),
-            reasoning_output_tokens=response.usage.get("reasoning_output_tokens"),
-            cache_write_tokens=response.usage.get("cache_write_tokens"),
-            cache_read_tokens=response.usage.get("cache_read_tokens"),
+            reasoning_tokens=usage_data.get("reasoning_tokens"),
+            reasoning_input_tokens=usage_data.get("reasoning_input_tokens"),
+            reasoning_output_tokens=usage_data.get("reasoning_output_tokens"),
+            cache_write_tokens=usage_data.get("cache_write_tokens"),
+            cache_read_tokens=usage_data.get("cache_read_tokens"),
         )
 
     # Build request parameters
@@ -149,11 +210,15 @@ def create_llm_call_record_from_response(
     )
 
     # Handle response-specific fields
-    finish_reason = None
+    finish_reason: str | None = None
     if hasattr(response, "finish_reason"):
-        finish_reason = response.finish_reason
+        finish_reason = getattr(response, "finish_reason", None)
+        if finish_reason is not None:
+            finish_reason = str(finish_reason)
     elif hasattr(response, "stop_reason"):
-        finish_reason = response.stop_reason
+        stop_reason = getattr(response, "stop_reason", None)
+        if stop_reason is not None:
+            finish_reason = str(stop_reason)
 
     # Create the call record
     record = LLMCallRecord(
@@ -161,8 +226,8 @@ def create_llm_call_record_from_response(
         api_type=api_type,
         provider=provider,
         model_name=model_name,
-        started_at=started_at or datetime.utcnow(),
-        completed_at=completed_at or datetime.utcnow(),
+        started_at=started_at or datetime.now(UTC),
+        completed_at=completed_at or datetime.now(UTC),
         latency_ms=latency_ms,
         request_params=params,
         input_messages=input_messages,
@@ -188,7 +253,45 @@ def create_llm_call_record_from_response(
     return record
 
 
-def compute_aggregates_from_call_records(call_records: list[LLMCallRecord]) -> dict[str, Any]:
+@dataclass
+class _AggregateAccumulator:
+    """Mutable accumulator for call record aggregates."""
+
+    call_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    reasoning_tokens: int = 0
+    cost_usd: float = 0.0
+    latency_ms: int = 0
+    models_used: set[str] = field(default_factory=set)
+    providers_used: set[str] = field(default_factory=set)
+    tool_calls_count: int = 0
+    error_count: int = 0
+    success_count: int = 0
+
+
+class AggregateSummary(TypedDict, total=False):
+    """Aggregate metrics derived from call records."""
+
+    call_count: int
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    reasoning_tokens: int
+    cost_usd: float
+    latency_ms: int
+    models_used: list[str]
+    providers_used: list[str]
+    tool_calls_count: int
+    error_count: int
+    success_count: int
+    avg_latency_ms: float
+    avg_input_tokens: float
+    avg_output_tokens: float
+
+
+def compute_aggregates_from_call_records(call_records: list[LLMCallRecord]) -> AggregateSummary:
     """Compute aggregate statistics from a list of LLMCallRecord instances.
 
     Args:
@@ -197,65 +300,62 @@ def compute_aggregates_from_call_records(call_records: list[LLMCallRecord]) -> d
     Returns:
         Dictionary containing aggregated statistics
     """
-    aggregates = {
-        "input_tokens": 0,
-        "output_tokens": 0,
-        "total_tokens": 0,
-        "reasoning_tokens": 0,
-        "cost_usd": 0.0,
-        "latency_ms": 0,
-        "models_used": set(),
-        "providers_used": set(),
-        "tool_calls_count": 0,
-        "error_count": 0,
-        "success_count": 0,
-        "call_count": len(call_records),
-    }
+    aggregates = _AggregateAccumulator(call_count=len(call_records))
 
     for record in call_records:
         # Token aggregation
         if record.usage:
             if record.usage.input_tokens:
-                aggregates["input_tokens"] += record.usage.input_tokens
+                aggregates.input_tokens += record.usage.input_tokens
             if record.usage.output_tokens:
-                aggregates["output_tokens"] += record.usage.output_tokens
+                aggregates.output_tokens += record.usage.output_tokens
             if record.usage.total_tokens:
-                aggregates["total_tokens"] += record.usage.total_tokens
+                aggregates.total_tokens += record.usage.total_tokens
             if record.usage.reasoning_tokens:
-                aggregates["reasoning_tokens"] += record.usage.reasoning_tokens
+                aggregates.reasoning_tokens += record.usage.reasoning_tokens
             if record.usage.cost_usd:
-                aggregates["cost_usd"] += record.usage.cost_usd
+                aggregates.cost_usd += record.usage.cost_usd
 
         # Latency aggregation
-        if record.latency_ms:
-            aggregates["latency_ms"] += record.latency_ms
+        if record.latency_ms is not None:
+            aggregates.latency_ms += record.latency_ms
 
         # Model and provider tracking
         if record.model_name:
-            aggregates["models_used"].add(record.model_name)
+            aggregates.models_used.add(record.model_name)
         if record.provider:
-            aggregates["providers_used"].add(record.provider)
+            aggregates.providers_used.add(record.provider)
 
         # Tool calls
-        aggregates["tool_calls_count"] += len(record.output_tool_calls)
+        aggregates.tool_calls_count += len(record.output_tool_calls)
 
         # Success/error tracking
         if record.outcome == "error":
-            aggregates["error_count"] += 1
+            aggregates.error_count += 1
         elif record.outcome == "success":
-            aggregates["success_count"] += 1
-
-    # Convert sets to lists for JSON serialization
-    aggregates["models_used"] = list(aggregates["models_used"])
-    aggregates["providers_used"] = list(aggregates["providers_used"])
+            aggregates.success_count += 1
+
+    summary: AggregateSummary = {
+        "call_count": aggregates.call_count,
+        "input_tokens": aggregates.input_tokens,
+        "output_tokens": aggregates.output_tokens,
+        "total_tokens": aggregates.total_tokens,
+        "reasoning_tokens": aggregates.reasoning_tokens,
+        "cost_usd": aggregates.cost_usd,
+        "latency_ms": aggregates.latency_ms,
+        "models_used": list(aggregates.models_used),
+        "providers_used": list(aggregates.providers_used),
+        "tool_calls_count": aggregates.tool_calls_count,
+        "error_count": aggregates.error_count,
+        "success_count": aggregates.success_count,
+    }
 
-    # Compute averages
-    if aggregates["call_count"] > 0:
-        aggregates["avg_latency_ms"] = aggregates["latency_ms"] / aggregates["call_count"]
-        aggregates["avg_input_tokens"] = aggregates["input_tokens"] / aggregates["call_count"]
-        aggregates["avg_output_tokens"] = aggregates["output_tokens"] / aggregates["call_count"]
+    if aggregates.call_count > 0:
+        summary["avg_latency_ms"] = aggregates.latency_ms / aggregates.call_count
+        summary["avg_input_tokens"] = aggregates.input_tokens / aggregates.call_count
+        summary["avg_output_tokens"] = aggregates.output_tokens / aggregates.call_count
 
-    return aggregates
+    return summary
 
 
 def create_llm_call_record_from_streaming(
@@ -322,8 +422,8 @@ def create_llm_call_record_from_streaming(
         api_type="responses",  # Streaming typically from Responses API
         provider=provider,
         model_name=model_name,
-        started_at=started_at or datetime.utcnow(),
-        completed_at=completed_at or datetime.utcnow(),
+        started_at=started_at or datetime.now(UTC),
+        completed_at=completed_at or datetime.now(UTC),
         latency_ms=latency_ms,
         request_params=params,
         input_messages=input_messages,

synth_ai/tracing_v3/migration_helper.py

@@ -68,7 +68,7 @@ def categorize_files(v2_files: list[tuple[str, list[str]]]) -> dict:
             categories["examples"].append((file_path, imports))
         elif any(
             core in file_path
-            for core in ["synth_ai/lm/", "synth_ai/tui/", "synth_ai/environments/"]
+            for core in ["synth_ai/lm/", "synth_ai/environments/"]
         ):
             categories["core_library"].append((file_path, imports))
         else:
@@ -104,7 +104,6 @@ def print_migration_report():
     print("2. Debug scripts: Can be deleted or archived")
     print("3. Core library files: Need careful migration to v3")
     print("   - synth_ai/lm/core/main_v2.py")
-    print("   - synth_ai/tui/cli/query_experiments.py")
     print("   - synth_ai/environments/service/core_routes.py")
     print("4. Examples: Should be updated to demonstrate v3 usage")
 

synth_ai/tracing_v3/replica_sync.py

@@ -25,14 +25,15 @@ application to continue without blocking on sync operations.
 """
 
 import asyncio
+import importlib
 import logging
-
-import libsql
+from typing import Any, cast
 
 from .config import CONFIG
 
 logger = logging.getLogger(__name__)
 
+libsql = cast(Any, importlib.import_module("libsql"))
 
 class ReplicaSync:
     """Manages synchronization of embedded SQLite replica with remote Turso database.
@@ -52,7 +53,7 @@ class ReplicaSync:
         db_path: str = "embedded.db",
         sync_url: str | None = None,
         auth_token: str | None = None,
-        sync_interval: int | None = None,
+        sync_interval: float | None = None,
     ):
         """Initialize replica sync manager.
 
@@ -66,8 +67,8 @@ class ReplicaSync:
         self.sync_url = sync_url or CONFIG.sync_url
         self.auth_token = auth_token or CONFIG.auth_token
         self.sync_interval = sync_interval or CONFIG.sync_interval
-        self._sync_task: asyncio.Task | None = None
-        self._conn: libsql.Connection | None = None
+        self._sync_task: asyncio.Task[Any] | None = None
+        self._conn: Any | None = None
 
     def _ensure_connection(self):
         """Ensure libsql connection is established.
@@ -113,8 +114,11 @@ class ReplicaSync:
         """
         try:
             self._ensure_connection()
+            conn = self._conn
+            if conn is None:
+                raise RuntimeError("Replica sync connection is not available after initialization")
             # Run sync in thread pool since libsql sync is blocking
-            await asyncio.to_thread(self._conn.sync)
+            await asyncio.to_thread(conn.sync)
             logger.info("Successfully synced with remote Turso database")
             return True
         except Exception as e:
@@ -146,7 +150,7 @@ class ReplicaSync:
             # Sleep until next sync interval
             await asyncio.sleep(self.sync_interval)
 
-    def start_background_sync(self) -> asyncio.Task:
+    def start_background_sync(self) -> asyncio.Task[Any]:
         """Start the background sync task.
 
         Creates an asyncio task that runs the sync loop. The task is stored
@@ -180,6 +184,7 @@ class ReplicaSync:
             # Request cancellation
             self._sync_task.cancel()
             import contextlib
+
             with contextlib.suppress(asyncio.CancelledError):
                 # Wait for the task to finish
                 await self._sync_task

synth_ai/tracing_v3/serialization.py

@@ -0,0 +1,130 @@
+"""HTTP-safe serialization helpers for tracing v3.
+
+These utilities normalize tracing structures (including dataclasses) into
+JSON-serializable forms and provide a compact JSON encoder suitable for
+HTTP transmission to backend services.
+
+Design goals:
+- Preserve structure while ensuring standard-compliant JSON (no NaN/Infinity)
+- Handle common non-JSON types: datetime, Decimal, bytes, set/tuple, numpy scalars
+- Keep output compact (no unnecessary whitespace) while readable if needed
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+
+try:
+    import numpy as _np  # type: ignore
+except Exception:  # pragma: no cover - numpy optional at runtime
+    _np = None  # type: ignore
+
+
+def normalize_for_json(value: Any) -> Any:
+    """Return a JSON-serializable version of ``value``.
+
+    Rules:
+    - dataclass → dict (recursively normalized)
+    - datetime/date → ISO-8601 string (UTC-aware datetimes preserve tzinfo)
+    - Decimal → float (fallback to string if not finite)
+    - bytes/bytearray → base64 string (RFC 4648)
+    - set/tuple → list
+    - Enum → enum.value (normalized)
+    - numpy scalar → corresponding Python scalar
+    - float NaN/Inf/−Inf → None (to keep JSON standard compliant)
+    - dict / list → recursively normalized
+    - other primitives (str, int, bool, None, float) passed through
+    """
+
+    # Dataclasses
+    if is_dataclass(value) and not isinstance(value, type):
+        try:
+            return normalize_for_json(asdict(value))
+        except Exception:
+            # Fallback: best-effort conversion via __dict__
+            return normalize_for_json(getattr(value, "__dict__", {}))
+
+    # Mapping
+    if isinstance(value, dict):
+        return {str(k): normalize_for_json(v) for k, v in value.items()}
+
+    # Sequences
+    if isinstance(value, list | tuple | set):
+        return [normalize_for_json(v) for v in value]
+
+    # Datetime / Date
+    if isinstance(value, datetime | date):
+        return value.isoformat()
+
+    # Decimal
+    if isinstance(value, Decimal):
+        try:
+            f = float(value)
+            if f != f or f in (float("inf"), float("-inf")):
+                return str(value)
+            return f
+        except Exception:
+            return str(value)
+
+    # Bytes-like
+    if isinstance(value, bytes | bytearray):
+        return base64.b64encode(bytes(value)).decode("ascii")
+
+    # Enum
+    if isinstance(value, Enum):
+        return normalize_for_json(value.value)
+
+    # Numpy scalars / arrays
+    if _np is not None:
+        if isinstance(value, _np.generic):  # type: ignore[attr-defined]
+            return normalize_for_json(value.item())
+        if isinstance(value, _np.ndarray):
+            return normalize_for_json(value.tolist())
+
+    # Floats: sanitize NaN / Infinity to None
+    if isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            return None
+        return value
+
+    return value
+
+
+def dumps_http_json(payload: Any) -> str:
+    """Dump ``payload`` into a compact, HTTP-safe JSON string.
+
+    - Recursively normalizes non-JSON types (see ``normalize_for_json``)
+    - Disallows NaN/Infinity per RFC 8259 (allow_nan=False)
+    - Uses compact separators and preserves Unicode (ensure_ascii=False)
+    """
+
+    normalized = normalize_for_json(payload)
+    return json.dumps(
+        normalized,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+    )
+
+
+def serialize_trace_for_http(trace: Any) -> str:
+    """Serialize a tracing v3 session (or dict-like) to HTTP-safe JSON.
+
+    Accepts either a dataclass (e.g., SessionTrace) or a dict/list and
+    applies normalization and compact JSON encoding.
+    """
+
+    if is_dataclass(trace) and not isinstance(trace, type):
+        try:
+            return dumps_http_json(asdict(trace))
+        except Exception:
+            return dumps_http_json(getattr(trace, "__dict__", {}))
+    return dumps_http_json(trace)
+
+