synth-ai 0.2.10__py3-none-any.whl → 0.2.13.dev1__py3-none-any.whl

synth_ai/tracing_v3/llm_call_record_helpers.py

@@ -4,11 +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 dataclasses import dataclass, field
 from datetime import UTC, datetime
-from typing import Any
+from typing import Any, TypedDict, cast
 
-from synth_ai.tracing_v3.lm_call_record_abstractions import (
+from .lm_call_record_abstractions import (
     LLMCallRecord,
     LLMChunk,
     LLMContentPart,
@@ -17,7 +20,21 @@ from synth_ai.tracing_v3.lm_call_record_abstractions import (
     LLMUsage,
     ToolCallSpec,
 )
-from synth_ai.v0.lm.vendors.base import BaseLMResponse
+
+BaseLMResponse = Any
+
+
+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(
@@ -110,9 +127,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 +143,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
@@ -188,7 +207,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 +254,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(

synth_ai/tracing_v3/replica_sync.py

@@ -26,6 +26,7 @@ application to continue without blocking on sync operations.
 
 import asyncio
 import logging
+from typing import Any
 
 import libsql
 
@@ -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

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)
+
+

synth_ai/tracing_v3/storage/utils.py

@@ -3,8 +3,8 @@
 import asyncio
 import functools
 import time
-from collections.abc import Callable
-from typing import Any, TypeVar
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar, cast
 
 T = TypeVar("T")
 
@@ -18,9 +18,9 @@ def retry_async(max_attempts: int = 3, delay: float = 1.0, backoff: float = 2.0)
         backoff: Backoff multiplier for each retry
     """
 
-    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
         @functools.wraps(func)
-        async def wrapper(*args, **kwargs):
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
             last_exception: Exception | None = None
             current_delay = delay
 
@@ -171,13 +171,14 @@ STORAGE_METRICS = StorageMetrics()
 def track_metrics(operation: str):
     """Decorator to track storage operation metrics."""
 
-    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+    def decorator(func: Callable[..., Awaitable[T]] | Callable[..., T]) -> Callable[..., Awaitable[T]] | Callable[..., T]:
         @functools.wraps(func)
-        async def async_wrapper(*args, **kwargs):
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
             start_time = time.time()
             success = False
             try:
-                result = await func(*args, **kwargs)
+                async_func = cast(Callable[..., Awaitable[T]], func)
+                result = await async_func(*args, **kwargs)
                 success = True
                 return result
             finally:
@@ -185,11 +186,12 @@ def track_metrics(operation: str):
                 STORAGE_METRICS.record_operation(operation, duration, success)
 
         @functools.wraps(func)
-        def sync_wrapper(*args, **kwargs):
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
             start_time = time.time()
             success = False
             try:
-                result = func(*args, **kwargs)
+                sync_func = cast(Callable[..., T], func)
+                result = sync_func(*args, **kwargs)
                 success = True
                 return result
             finally:

synth_ai/tracing_v3/turso/__init__.py

@@ -0,0 +1,12 @@
+"""Turso integration package for tracing v3."""
+
+from .daemon import SqldDaemon, get_daemon, start_sqld, stop_sqld
+from .native_manager import NativeLibsqlTraceManager
+
+__all__ = [
+    "SqldDaemon",
+    "NativeLibsqlTraceManager",
+    "get_daemon",
+    "start_sqld",
+    "stop_sqld",
+]

synth_ai/tracing_v3/turso/daemon.py

@@ -6,6 +6,7 @@ import subprocess
 import time
 
 import requests
+from requests import RequestException
 
 from ..config import CONFIG
 
@@ -79,7 +80,7 @@ class SqldDaemon:
                 response = requests.get(health_url, timeout=1)
                 if response.status_code == 200:
                     return
-            except requests.exceptions.RequestException:
+            except RequestException:
                 pass
 
             # Check if process crashed

synth_ai/tracing_v3/turso/native_manager.py

@@ -11,18 +11,14 @@ import asyncio
 import json
 import logging
 import re
+from collections.abc import Callable
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 import libsql
 from sqlalchemy.engine import make_url
 
-try:  # pragma: no cover - exercised only when pandas present
-    import pandas as pd  # type: ignore
-except Exception:  # pragma: no cover
-    pd = None  # type: ignore[assignment]
-
 from ..abstractions import (
     EnvironmentEvent,
     LMCAISEvent,
@@ -34,6 +30,24 @@ from ..config import CONFIG
 from ..storage.base import TraceStorage
 from .models import analytics_views
 
+if TYPE_CHECKING:
+    from sqlite3 import Connection as LibsqlConnection
+else:  # pragma: no cover - runtime fallback for typing only
+    LibsqlConnection = Any  # type: ignore[assignment]
+
+_LIBSQL_CONNECT_ATTR = getattr(libsql, "connect", None)
+if _LIBSQL_CONNECT_ATTR is None:  # pragma: no cover - defensive guard
+    raise RuntimeError("libsql.connect is required for NativeLibsqlTraceManager")
+_libsql_connect: Callable[..., LibsqlConnection] = cast(
+    Callable[..., LibsqlConnection],
+    _LIBSQL_CONNECT_ATTR,
+)
+
+try:  # pragma: no cover - exercised only when pandas present
+    import pandas as pd  # type: ignore
+except Exception:  # pragma: no cover
+    pd = None  # type: ignore[assignment]
+
 logger = logging.getLogger(__name__)
 
 
@@ -66,9 +80,8 @@ def _resolve_connection_target(db_url: str | None, auth_token: str | None) -> _C
     # Fallback to SQLAlchemy URL parsing for anything else we missed.
     try:
         parsed = make_url(url)
-        if parsed.drivername.startswith("sqlite"):
-            if parsed.database:
-                return _ConnectionTarget(database=parsed.database, auth_token=auth_token)
+        if parsed.drivername.startswith("sqlite") and parsed.database:
+            return _ConnectionTarget(database=parsed.database, auth_token=auth_token)
         if parsed.drivername.startswith("libsql"):
             database = parsed.render_as_string(hide_password=False)
             return _ConnectionTarget(database=database, sync_url=database, auth_token=auth_token)
@@ -314,12 +327,12 @@ class NativeLibsqlTraceManager(TraceStorage):
     ):
         self._config_auth_token = auth_token
         self._target = _resolve_connection_target(db_url, auth_token)
-        self._conn: libsql.Connection | None = None
+        self._conn: LibsqlConnection | None = None
         self._conn_lock = asyncio.Lock()
         self._op_lock = asyncio.Lock()
         self._initialized = False
 
-    def _open_connection(self) -> libsql.Connection:
+    def _open_connection(self) -> LibsqlConnection:
         """Open a libsql connection for the resolved target."""
         kwargs: dict[str, Any] = {}
         if self._target.sync_url and self._target.sync_url.startswith("libsql://"):
@@ -329,7 +342,7 @@ class NativeLibsqlTraceManager(TraceStorage):
         # Disable automatic background sync; ReplicaSync drives this explicitly.
         kwargs.setdefault("sync_interval", 0)
         logger.debug("Opening libsql connection to %s", self._target.database)
-        return libsql.connect(self._target.database, **kwargs)
+        return _libsql_connect(self._target.database, **kwargs)
 
     async def initialize(self):
         """Initialise the backend."""
@@ -493,7 +506,7 @@ class NativeLibsqlTraceManager(TraceStorage):
                 return None
 
             session_columns = ["session_id", "created_at", "num_timesteps", "num_events", "num_messages", "metadata"]
-            session_data = dict(zip(session_columns, session_row))
+            session_data = dict(zip(session_columns, session_row, strict=True))
 
             timestep_cursor = conn.execute(
                 """
@@ -608,10 +621,10 @@ class NativeLibsqlTraceManager(TraceStorage):
 
         if not rows:
             if pd is not None:
-                return pd.DataFrame(columns=[col for col in columns])
+                return pd.DataFrame(columns=list(columns))
             return []
 
-        records = [dict(zip(columns, row)) for row in rows]
+        records = [dict(zip(columns, row, strict=True)) for row in rows]
         if pd is not None:
             return pd.DataFrame(records)
         return records

{synth_ai-0.2.10.dist-info → synth_ai-0.2.13.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.2.10
+Version: 0.2.13.dev1
 Summary: RL as a service SDK - Core AI functionality and tracing
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -79,7 +79,7 @@ Dynamic: license-file
 
 [![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![PyPI](https://img.shields.io/badge/PyPI-0.2.4.dev9-orange)](https://pypi.org/project/synth-ai/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.2.10-orange)](https://pypi.org/project/synth-ai/)
 ![Coverage](https://img.shields.io/badge/coverage-9.09%25-red)
 ![Tests](https://img.shields.io/badge/tests-37%2F38%20passing-brightgreen)
 ![Blacksmith CI](https://img.shields.io/badge/CI-Blacksmith%20Worker-blue)
@@ -88,6 +88,8 @@ Docs: [Synth‑AI Documentation](https://docs.usesynth.ai/welcome/introduction)
 
 Fast and effective reinforcement learning for agents, via an API
 
+> Latest: 0.2.10 published to PyPI (uv publish)
+
 ## Highlights
 
 - Easily scale gpu topologies - train on 3 a10gs or 8 H100s (multi-node available upon request)