synth-ai 0.2.4.dev6__py3-none-any.whl → 0.2.4.dev8__py3-none-any.whl

synth_ai/tracing_v3/abstractions.py

@@ -35,19 +35,21 @@ Concepts:
 """
 
 from __future__ import annotations
-from dataclasses import dataclass, field, asdict
+
+from dataclasses import asdict, dataclass, field
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any
+
 from .lm_call_record_abstractions import LLMCallRecord
 
 
 @dataclass
 class TimeRecord:
     """Time information for events and messages.
-    
+
     This class captures timing information with microsecond precision for event
     correlation and performance analysis.
-    
+
     Attributes:
         event_time: Unix timestamp (float) when the event occurred. This is the
                    primary timestamp used for ordering and correlation.
@@ -56,17 +58,17 @@ class TimeRecord:
     """
 
     event_time: float
-    message_time: Optional[int] = None
+    message_time: int | None = None
 
 
 @dataclass
 class SessionEventMarkovBlanketMessage:
     """Message crossing Markov blanket boundaries between systems in a session.
-    
+
     IMPORTANT: This represents information transfer BETWEEN distinct systems/subsystems,
     where each system is conceptualized as having a Markov blanket that separates its
     internal states from the external environment. These messages cross those boundaries.
-    
+
     This is NOT for chat messages within an LLM conversation (those belong in LLMCallRecord).
     Instead, this captures inter-system communication such as:
     - Human -> Agent system (user providing instructions)
@@ -75,11 +77,11 @@ class SessionEventMarkovBlanketMessage:
     - Environment -> Runtime (returning results)
     - Runtime -> Agent (passing back results)
     - Agent -> Human (final response)
-    
+
     Each system maintains its own internal state and processing, but can only influence
     other systems through these explicit boundary-crossing messages. This follows the
     Free Energy Principle where systems minimize surprise by maintaining boundaries.
-    
+
     Attributes:
         content: The actual message content crossing the boundary (text, JSON, etc.)
         message_type: Type of boundary crossing (e.g., 'observation', 'action', 'result')
@@ -98,17 +100,17 @@ class SessionEventMarkovBlanketMessage:
     content: str
     message_type: str
     time_record: TimeRecord
-    metadata: Dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass
 class BaseEvent:
     """Base class for all event types.
-    
+
     This is the foundation for all events in the tracing system. Every event must
     have a system identifier and timing information. Events are intra-system facts
     (they occur within a subsystem) and are not necessarily direct communications.
-    
+
     Attributes:
         system_instance_id: Identifier for the system/component that generated
                            this event (e.g., 'llm', 'environment', 'tool_executor')
@@ -123,37 +125,37 @@ class BaseEvent:
 
     system_instance_id: str
     time_record: TimeRecord
-    metadata: Dict[str, Any] = field(default_factory=dict)
-    event_metadata: Optional[List[Any]] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    event_metadata: list[Any] | None = None
 
 
 @dataclass
 class RuntimeEvent(BaseEvent):
     """Event from runtime system.
-    
+
     Captures events from the AI system's runtime, typically representing decisions
     or actions taken by the system (e.g., selecting a tool with arguments).
     Use paired SessionEventMessages to record the communication of this choice to
     the environment.
-    
+
     Attributes:
         actions: List of action identifiers or indices. The interpretation
                 depends on the system (e.g., discrete action indices for RL,
                 tool selection IDs for agents, etc.)
     """
 
-    actions: List[int] = field(default_factory=list)
+    actions: list[int] = field(default_factory=list)
 
 
 @dataclass
 class EnvironmentEvent(BaseEvent):
     """Event from environment.
-    
+
     Captures feedback from the environment in response to system actions (e.g.,
     command output, exit codes, observations). Use a paired SessionEventMessage
     to record the environment-to-agent communication of the result.
     Follows the Gymnasium/OpenAI Gym convention for compatibility.
-    
+
     Attributes:
         reward: Scalar reward signal from the environment
         terminated: Whether the episode ended due to reaching a terminal state
@@ -165,19 +167,19 @@ class EnvironmentEvent(BaseEvent):
     reward: float = 0.0
     terminated: bool = False
     truncated: bool = False
-    system_state_before: Optional[Dict[str, Any]] = None
-    system_state_after: Optional[Dict[str, Any]] = None
+    system_state_before: dict[str, Any] | None = None
+    system_state_after: dict[str, Any] | None = None
 
 
 @dataclass
 class LMCAISEvent(BaseEvent):
     """Extended CAIS event for language model interactions.
-    
+
     CAIS (Claude AI System) events capture detailed information about LLM calls,
     including performance metrics, cost tracking, and distributed tracing support.
     Treat provider-specific prompt/completion structures as part of this event's
     data. Do not emit them as SessionEventMessages.
-    
+
     Attributes:
         model_name: The specific model used (e.g., 'gpt-4', 'claude-3-opus')
         provider: LLM provider (e.g., 'openai', 'anthropic', 'local')
@@ -195,27 +197,27 @@ class LMCAISEvent(BaseEvent):
     """
 
     model_name: str = ""
-    provider: Optional[str] = None
-    input_tokens: Optional[int] = None
-    output_tokens: Optional[int] = None
-    total_tokens: Optional[int] = None
-    cost_usd: Optional[float] = None
-    latency_ms: Optional[int] = None
-    span_id: Optional[str] = None
-    trace_id: Optional[str] = None
-    system_state_before: Optional[Dict[str, Any]] = None
-    system_state_after: Optional[Dict[str, Any]] = None
-    call_records: List[LLMCallRecord] = field(default_factory=list)
+    provider: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    cost_usd: float | None = None
+    latency_ms: int | None = None
+    span_id: str | None = None
+    trace_id: str | None = None
+    system_state_before: dict[str, Any] | None = None
+    system_state_after: dict[str, Any] | None = None
+    call_records: list[LLMCallRecord] = field(default_factory=list)
 
 
 @dataclass
 class SessionTimeStep:
     """A logical timestep within a session.
-    
+
     Represents a discrete step in the session timeline. In conversational AI,
     this often corresponds to a single turn of dialogue. In RL systems, it
     might represent a single environment step.
-    
+
     Attributes:
         step_id: Unique identifier for this step (e.g., 'turn_1', 'step_42')
         step_index: Sequential index of this step within the session
@@ -231,21 +233,21 @@ class SessionTimeStep:
     step_id: str = ""
     step_index: int = 0
     timestamp: datetime = field(default_factory=datetime.utcnow)
-    turn_number: Optional[int] = None
-    events: List[BaseEvent] = field(default_factory=list)
-    markov_blanket_messages: List[SessionEventMarkovBlanketMessage] = field(default_factory=list)
-    step_metadata: Dict[str, Any] = field(default_factory=dict)
-    completed_at: Optional[datetime] = None
+    turn_number: int | None = None
+    events: list[BaseEvent] = field(default_factory=list)
+    markov_blanket_messages: list[SessionEventMarkovBlanketMessage] = field(default_factory=list)
+    step_metadata: dict[str, Any] = field(default_factory=dict)
+    completed_at: datetime | None = None
 
 
 @dataclass
 class SessionTrace:
     """Complete trace of a session.
-    
+
     The top-level container that holds all data for a single execution session.
     This could represent a complete conversation, an RL episode, or any other
     bounded interaction sequence.
-    
+
     Attributes:
         session_id: Unique identifier for this session
         created_at: When the session started (UTC)
@@ -256,7 +258,7 @@ class SessionTrace:
                  'model_config', 'environment_name')
         session_metadata: Optional list of structured metadata entries that
                          don't fit the dictionary format
-    
+
     Note:
         Both event_history and message_history contain the complete record,
         while individual timesteps also reference their specific events/messages.
@@ -265,15 +267,17 @@ class SessionTrace:
 
     session_id: str = ""
     created_at: datetime = field(default_factory=datetime.utcnow)
-    session_time_steps: List[SessionTimeStep] = field(default_factory=list)
-    event_history: List[BaseEvent] = field(default_factory=list)
-    markov_blanket_message_history: List[SessionEventMarkovBlanketMessage] = field(default_factory=list)
-    metadata: Dict[str, Any] = field(default_factory=dict)
-    session_metadata: Optional[List[Dict[str, Any]]] = None
-
-    def to_dict(self) -> Dict[str, Any]:
+    session_time_steps: list[SessionTimeStep] = field(default_factory=list)
+    event_history: list[BaseEvent] = field(default_factory=list)
+    markov_blanket_message_history: list[SessionEventMarkovBlanketMessage] = field(
+        default_factory=list
+    )
+    metadata: dict[str, Any] = field(default_factory=dict)
+    session_metadata: list[dict[str, Any]] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary representation.
-        
+
         Returns:
             A dictionary containing all session data, suitable for
             JSON serialization or database storage.

synth_ai/tracing_v3/config.py

@@ -1,7 +1,7 @@
 """Configuration for tracing v3 with Turso/sqld."""
 
-from dataclasses import dataclass
 import os
+from dataclasses import dataclass
 
 
 @dataclass
@@ -28,7 +28,9 @@ class TursoConfig:
     # Remote database sync configuration
     sync_url: str = os.getenv("TURSO_DATABASE_URL", "")
     auth_token: str = os.getenv("TURSO_AUTH_TOKEN", "")
-    sync_interval: int = int(os.getenv("TURSO_SYNC_SECONDS", "2"))  # 2 seconds for responsive local development
+    sync_interval: int = int(
+        os.getenv("TURSO_SYNC_SECONDS", "2")
+    )  # 2 seconds for responsive local development
 
     # Connection pool settings
     pool_size: int = int(os.getenv("TURSO_POOL_SIZE", "8"))

synth_ai/tracing_v3/db_config.py

@@ -2,11 +2,9 @@
 Centralized database configuration for v3 tracing.
 """
 
-import os
-import tempfile
-from pathlib import Path
-from typing import Optional, Tuple, TYPE_CHECKING
 import logging
+import os
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from .turso.daemon import SqldDaemon
@@ -22,7 +20,7 @@ class DatabaseConfig:
     DEFAULT_HTTP_PORT = 8080
 
     def __init__(
-        self, db_path: Optional[str] = None, http_port: Optional[int] = None, use_sqld: bool = True
+        self, db_path: str | None = None, http_port: int | None = None, use_sqld: bool = True
     ):
         """
         Initialize database configuration.
@@ -34,7 +32,7 @@ class DatabaseConfig:
         """
         self.use_sqld = use_sqld
         self.http_port = http_port or int(os.getenv("SQLD_HTTP_PORT", self.DEFAULT_HTTP_PORT))
-        self._daemon: Optional["SqldDaemon"] = None
+        self._daemon: SqldDaemon | None = None
 
         # Set up database path to match serve.sh configuration
         if db_path is None:
@@ -106,7 +104,7 @@ class DatabaseConfig:
             self._daemon.stop()
             self._daemon = None
 
-    def get_daemon_and_url(self, wait_time: float = 2.0) -> Tuple[Optional["SqldDaemon"], str]:
+    def get_daemon_and_url(self, wait_time: float = 2.0) -> tuple[Optional["SqldDaemon"], str]:
         """
         Get daemon (starting if needed) and database URL.
 
@@ -121,7 +119,7 @@ class DatabaseConfig:
 
 
 # Global default configuration
-_default_config: Optional[DatabaseConfig] = None
+_default_config: DatabaseConfig | None = None
 
 
 def get_default_db_config() -> DatabaseConfig:

synth_ai/tracing_v3/decorators.py

@@ -22,58 +22,57 @@ The decorators support both sync and async functions where appropriate,
 though async is preferred for consistency with the rest of the system.
 """
 
+import asyncio
 import contextvars
 import functools
 import time
-from typing import Callable, Any, Optional, TypeVar, Union
-import asyncio
-import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar
 
 from .abstractions import LMCAISEvent, TimeRecord
-from .utils import detect_provider, calculate_cost
-
+from .utils import calculate_cost, detect_provider
 
 # Context variables for session and turn tracking
 # These variables automatically propagate across async call boundaries,
 # allowing deeply nested code to access tracing context without explicit passing
-_session_id_ctx: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+_session_id_ctx: contextvars.ContextVar[str | None] = contextvars.ContextVar(
     "session_id", default=None
 )
-_turn_number_ctx: contextvars.ContextVar[Optional[int]] = contextvars.ContextVar(
+_turn_number_ctx: contextvars.ContextVar[int | None] = contextvars.ContextVar(
     "turn_number", default=None
 )
-_session_tracer_ctx: contextvars.ContextVar[Optional[Any]] = contextvars.ContextVar(
+_session_tracer_ctx: contextvars.ContextVar[Any | None] = contextvars.ContextVar(
     "session_tracer", default=None
 )
 
 
-def set_session_id(session_id: Optional[str]) -> None:
+def set_session_id(session_id: str | None) -> None:
     """Set the current session ID in context.
-    
+
     This ID will be available to all async tasks spawned from the current context.
     Setting to None clears the session context.
-    
+
     Args:
         session_id: The session ID to set, or None to clear
     """
     _session_id_ctx.set(session_id)
 
 
-def get_session_id() -> Optional[str]:
+def get_session_id() -> str | None:
     """Get the current session ID from context.
-    
+
     Returns:
         The current session ID if one is set, None otherwise
     """
     return _session_id_ctx.get()
 
 
-def set_turn_number(turn: Optional[int]) -> None:
+def set_turn_number(turn: int | None) -> None:
     """Set the current turn number in context."""
     _turn_number_ctx.set(turn)
 
 
-def get_turn_number() -> Optional[int]:
+def get_turn_number() -> int | None:
     """Get the current turn number from context."""
     return _turn_number_ctx.get()
 
@@ -93,15 +92,15 @@ T = TypeVar("T")
 
 def with_session(require: bool = True):
     """Decorator that ensures a session is active.
-    
+
     This decorator checks if a session is active before allowing the decorated
     function to execute. It supports both sync and async functions.
-    
+
     Args:
         require: If True, raises RuntimeError when no session is active.
                 If False, allows execution without a session (useful for
                 optional tracing).
-    
+
     Example:
         ```python
         @with_session()
@@ -144,21 +143,21 @@ def trace_llm_call(
     extract_cost: bool = True,
 ):
     """Decorator to trace LLM API calls.
-    
+
     Automatically records LLM API calls as LMCAISEvent instances. Extracts token
     counts, calculates costs, and measures latency. Only works with async functions.
-    
+
     Args:
         model_name: Model name to record (can be overridden by actual response)
         system_id: System identifier for the event (default: "llm")
         extract_tokens: Whether to extract token counts from response
         extract_cost: Whether to calculate USD cost from token counts
-    
+
     Expected Response Format:
         The decorated function should return a dict with:
         - 'usage': dict with 'prompt_tokens', 'completion_tokens', 'total_tokens'
         - 'model': actual model name (optional, falls back to model_name param)
-    
+
     Example:
         ```python
         @trace_llm_call(model_name="gpt-4")
@@ -251,14 +250,14 @@ def trace_llm_call(
 
 def trace_method(event_type: str = "runtime", system_id: str = None):
     """Generic method tracing decorator.
-    
+
     Traces any method call by recording it as a RuntimeEvent. Supports both
     sync and async methods, though async is preferred.
-    
+
     Args:
         event_type: Type of event to create (default: "runtime")
         system_id: System identifier (defaults to class name)
-    
+
     Example:
         ```python
         class Agent:
@@ -278,7 +277,7 @@ def trace_method(event_type: str = "runtime", system_id: str = None):
                 if not tracer:
                     return await fn(self, *args, **kwargs)
 
-                from .abstractions import BaseEvent, RuntimeEvent
+                from .abstractions import RuntimeEvent
 
                 # Use class name as system_id if not provided
                 actual_system_id = system_id or self.__class__.__name__
@@ -314,20 +313,20 @@ def trace_method(event_type: str = "runtime", system_id: str = None):
 
 class SessionContext:
     """Context manager for session tracking.
-    
+
     Provides a way to temporarily set session context, useful for testing
     or when you need to manually manage context outside of SessionTracer.
-    
+
     This context manager properly handles both sync and async contexts,
     and ensures the previous context is restored on exit.
-    
+
     Example:
         ```python
         # Sync usage
         with SessionContext("test_session_123", tracer):
             # Code here sees the test session
             process_data()
-        
+
         # Async usage
         async with SessionContext("test_session_123", tracer):
             # Async code here sees the test session

synth_ai/tracing_v3/examples/basic_usage.py

@@ -2,10 +2,9 @@
 
 import asyncio
 import time
-from datetime import datetime
 
 from synth_ai.tracing_v3 import SessionTracer
-from synth_ai.tracing_v3.abstractions import LMCAISEvent, EnvironmentEvent, RuntimeEvent, TimeRecord
+from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, RuntimeEvent, TimeRecord
 from synth_ai.tracing_v3.turso.daemon import SqldDaemon
 
 
@@ -31,7 +30,7 @@ async def main():
     print("Starting tracing v3 example...")
 
     # Option 1: Start sqld daemon programmatically
-    with SqldDaemon() as daemon:
+    with SqldDaemon():
         print("✓ Started sqld daemon")
 
         # Wait for daemon to be ready
@@ -167,15 +166,16 @@ async def main():
 
         tracer.hooks.register("event_recorded", count_events, name="event_counter")
 
-        async with tracer.session(metadata={"example": "hooks"}) as session_id:
-            async with tracer.timestep("hook_test"):
-                for i in range(3):
-                    event = RuntimeEvent(
-                        system_instance_id="hook_test",
-                        time_record=TimeRecord(event_time=time.time()),
-                        actions=[i],
-                    )
-                    await tracer.record_event(event)
+        async with tracer.session(metadata={"example": "hooks"}) as session_id, tracer.timestep(
+            "hook_test"
+        ):
+            for i in range(3):
+                event = RuntimeEvent(
+                    system_instance_id="hook_test",
+                    time_record=TimeRecord(event_time=time.time()),
+                    actions=[i],
+                )
+                await tracer.record_event(event)
 
         print(f"✓ Hook called {call_count['count']} times")
 

synth_ai/tracing_v3/hooks.py

@@ -32,18 +32,18 @@ Common Use Cases:
 - Custom filtering and sampling
 """
 
-from typing import Any, Callable, Dict, List, Optional
-from dataclasses import dataclass
 import asyncio
-import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
 
-from .abstractions import SessionTrace, SessionTimeStep, BaseEvent, SessionEventMarkovBlanketMessage
+from .abstractions import BaseEvent
 
 
 @dataclass
 class Hook:
     """A hook that can be registered with the tracer.
-    
+
     Attributes:
         name: Unique identifier for the hook
         callback: Function to call when hook is triggered. Can be sync or async.
@@ -54,25 +54,25 @@ class Hook:
 
     name: str
     callback: Callable
-    event_types: Optional[List[str]] = None
+    event_types: list[str] | None = None
     priority: int = 0
     enabled: bool = True
 
 
 class HookManager:
     """Manages hooks for session tracing.
-    
+
     The HookManager maintains collections of hooks for each hook point and
     handles their execution. It ensures hooks are called in priority order
     and handles both sync and async callbacks appropriately.
-    
+
     Thread Safety:
         The HookManager is designed to be thread-safe for registration and
         execution. Multiple async tasks can trigger hooks concurrently.
     """
 
     def __init__(self):
-        self.hooks: Dict[str, List[Hook]] = {
+        self.hooks: dict[str, list[Hook]] = {
             "session_start": [],
             "session_end": [],
             "timestep_start": [],
@@ -89,10 +89,10 @@ class HookManager:
         callback: Callable,
         name: str = None,
         priority: int = 0,
-        event_types: List[str] = None,
+        event_types: list[str] = None,
     ) -> Hook:
         """Register a new hook.
-        
+
         Args:
             event: Hook point name (e.g., 'session_start', 'event_recorded')
             callback: Function to call. Signature depends on hook point:
@@ -102,10 +102,10 @@ class HookManager:
             name: Optional name for the hook (defaults to callback.__name__)
             priority: Execution priority (higher = earlier execution)
             event_types: For 'event_recorded' hook, filter to specific event types
-        
+
         Returns:
             The created Hook instance
-            
+
         Raises:
             ValueError: If the event name is not a valid hook point
         """
@@ -126,7 +126,7 @@ class HookManager:
 
     def unregister(self, event: str, name: str):
         """Unregister a hook by name.
-        
+
         Args:
             event: Hook point name
             name: Name of the hook to remove
@@ -136,18 +136,18 @@ class HookManager:
 
         self.hooks[event] = [h for h in self.hooks[event] if h.name != name]
 
-    async def trigger(self, event: str, *args, **kwargs) -> List[Any]:
+    async def trigger(self, event: str, *args, **kwargs) -> list[Any]:
         """Trigger all hooks for an event.
-        
+
         Executes all registered hooks for the given event in priority order.
         Handles both sync and async callbacks appropriately. Exceptions in
         hooks are caught and logged but don't stop execution of other hooks.
-        
+
         Args:
             event: Hook point name
             *args: Positional arguments passed to hook callbacks
             **kwargs: Keyword arguments passed to hook callbacks
-            
+
         Returns:
             List of return values from all executed hooks
         """
@@ -187,20 +187,22 @@ class HookManager:
 # Default hooks for common use cases
 def create_default_hooks() -> HookManager:
     """Create hook manager with default hooks.
-    
+
     Sets up a basic set of hooks that provide common functionality:
     - Session start logging
     - Event validation
     - Automatic event enrichment
-    
+
     Returns:
         HookManager with default hooks registered
     """
     manager = HookManager()
 
     # Example: Log session starts - useful for debugging and monitoring
-    async def log_session_start(session_id: str, metadata: Dict[str, Any]):
-        print(f"Session started: {session_id}")
+    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}")
 
     # Example: Validate events before recording - ensures data quality
     def validate_event(event_obj: BaseEvent) -> bool: