synth-ai 0.2.14__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/tracing_v3/abstractions.py

@@ -1,302 +0,0 @@
-"""Core data structures for tracing v3.
-
-This module defines the fundamental data structures used throughout the tracing system.
-All structures are implemented as frozen dataclasses for immutability and type safety.
-
-The hierarchy is designed to support different types of events while maintaining
-a consistent interface for storage and processing.
-
-Event Type Hierarchy:
--------------------
-- BaseEvent: Common fields for all events
-  - RuntimeEvent: Events from the runtime system (e.g., actions taken)
-  - EnvironmentEvent: Events from the environment (e.g., rewards, termination)
-  - LMCAISEvent: Language model events with token/cost tracking
-
-Session Structure:
------------------
-- SessionTrace: Top-level container for a complete session
-  - SessionTimeStep: Logical steps within a session (e.g., conversation turns)
-    - Events: Individual events that occurred during the timestep
-    - Messages: Information passed between subsystems (user, agent, runtime, environments)
-
-Concepts:
----------
-- Events capture something that happened inside a subsystem. They may or may not be externally
-  visible. Examples include an LLM API call (LMCAISEvent), a tool selection (RuntimeEvent), or
-  a tool execution outcome (EnvironmentEvent).
-
-- Messages represent information transmitted between subsystems within the session.
-  Messages are used to record communications like: a user sending input to the agent,
-  the agent/runtime sending a tool invocation to an environment, the environment sending a
-  tool result back, and the agent sending a reply to the user. Do not confuse these with
-  provider-specific LLM API "messages" (prompt formatting) — those belong inside an LMCAISEvent
-  as part of its input/output content, not as SessionEventMessages.
-"""
-
-from __future__ import annotations
-
-from dataclasses import asdict, dataclass, field
-from datetime import datetime, timezone
-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.
-        message_time: Optional integer timestamp for message-specific timing.
-                     Can be used for external message IDs or sequence numbers.
-    """
-
-    event_time: float
-    message_time: int | None = None
-
-
-@dataclass(frozen=True)
-class SessionMessageContent:
-    """Normalized payload stored alongside session messages."""
-
-    text: str | None = None
-    json_payload: str | None = None
-
-    def as_text(self) -> str:
-        return self.text or (self.json_payload or "")
-
-    def has_json(self) -> bool:
-        return self.json_payload is not None
-
-    def __str__(self) -> str:  # pragma: no cover - convenience for logging
-        return self.as_text()
-
-
-@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)
-    - Agent -> Runtime (agent deciding on an action)
-    - Runtime -> Environment (executing a tool/action)
-    - 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')
-        time_record: Timing information for the boundary crossing
-        metadata: Boundary crossing metadata. Recommended keys:
-                  - 'step_id': Timestep identifier
-                  - 'from_system_instance_id': UUID of the sending system
-                  - 'to_system_instance_id': UUID of the receiving system
-                  - 'from_system_role': Role of sender (e.g., 'human', 'agent', 'runtime', 'environment')
-                  - 'to_system_role': Role of receiver
-                  - 'boundary_type': Type of Markov blanket boundary being crossed
-                  - 'call_id': Correlate request/response pairs across boundaries
-                  - 'causal_influence': Direction of causal flow
-    """
-
-    content: SessionMessageContent
-    message_type: str
-    time_record: TimeRecord
-    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')
-        time_record: Timing information for the event
-        metadata: Flexible dictionary for event-specific data. Common keys include:
-                 - 'step_id': Associated timestep identifier
-                 - 'error': Error information if event failed
-                 - 'duration_ms': Event duration in milliseconds
-        event_metadata: Optional list for structured metadata that doesn't fit
-                       in the dictionary format (e.g., tensor data, embeddings)
-    """
-
-    system_instance_id: str
-    time_record: TimeRecord
-    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)
-
-
-@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
-        truncated: Whether the episode ended due to a time/step limit
-        system_state_before: System state before the action (for debugging)
-        system_state_after: System state after the action (observations)
-    """
-
-    reward: float = 0.0
-    terminated: bool = False
-    truncated: bool = False
-    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')
-        input_tokens: Number of tokens in the prompt/input
-        output_tokens: Number of tokens in the completion/output
-        total_tokens: Total tokens used (input + output)
-        cost_usd: Estimated cost in US dollars for this call
-        latency_ms: End-to-end latency in milliseconds
-        span_id: OpenTelemetry compatible span identifier
-        trace_id: OpenTelemetry compatible trace identifier
-        system_state_before: State snapshot before the LLM call
-        system_state_after: State snapshot after the LLM call
-        call_records: List of normalized LLM call records capturing request/response
-                      details (messages, tool calls/results, usage, params, etc.).
-    """
-
-    model_name: str = ""
-    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
-        timestamp: When this timestep started (UTC)
-        turn_number: Optional turn number for conversational contexts
-        events: All events that occurred during this timestep
-        step_messages: Messages exchanged during this timestep
-        step_metadata: Additional metadata specific to this step (e.g.,
-                      'user_feedback', 'context_switches', 'tool_calls')
-        completed_at: When this timestep was completed (None if still active)
-    """
-
-    step_id: str = ""
-    step_index: int = 0
-    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    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)
-        session_time_steps: Ordered list of timesteps in this session
-        event_history: Complete chronological list of all events
-        message_history: Complete chronological list of all messages
-        metadata: Session-level metadata (e.g., 'user_id', 'experiment_id',
-                 '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.
-        This redundancy enables both efficient queries and complete reconstruction.
-    """
-
-    session_id: str = ""
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    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.
-        """
-        return asdict(self)

synth_ai/tracing_v3/config.py

@@ -1,84 +0,0 @@
-"""Configuration for tracing v3 with Turso/sqld."""
-
-import os
-from dataclasses import dataclass
-
-
-@dataclass
-class TursoConfig:
-    """Configuration for Turso/sqld connection."""
-
-    # Default values matching serve.sh
-    DEFAULT_DB_FILE = "traces/v3/synth_ai.db"
-    DEFAULT_HTTP_PORT = 8080
-
-    # Local embedded database for async SQLAlchemy
-    # Resolve to the actual SQLite file used by sqld if the base path is a directory
-    def _resolve_sqlite_db_url() -> str:  # type: ignore[no-redef]
-        base_path = os.path.abspath(os.getenv("SQLD_DB_PATH", "traces/v3/synth_ai.db"))
-        # If sqld is managing this DB, the real SQLite file lives under dbs/default/data
-        candidate = os.path.join(base_path, "dbs", "default", "data")
-        if os.path.isdir(base_path) and os.path.exists(candidate):
-            return f"sqlite+aiosqlite:///{candidate}"
-        return f"sqlite+aiosqlite:///{base_path}"
-
-    # Use env override if provided; otherwise resolve based on SQLD layout
-    db_url: str = os.getenv("TURSO_LOCAL_DB_URL", _resolve_sqlite_db_url())
-
-    # 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
-
-    # Connection pool settings
-    pool_size: int = int(os.getenv("TURSO_POOL_SIZE", "8"))
-    max_overflow: int = int(os.getenv("TURSO_MAX_OVERFLOW", "16"))
-    pool_timeout: float = float(os.getenv("TURSO_POOL_TIMEOUT", "30.0"))
-    pool_recycle: int = int(os.getenv("TURSO_POOL_RECYCLE", "3600"))
-
-    # SQLite settings
-    foreign_keys: bool = os.getenv("TURSO_FOREIGN_KEYS", "true").lower() == "true"
-    journal_mode: str = os.getenv("TURSO_JOURNAL_MODE", "WAL")
-
-    # Performance settings
-    echo_sql: bool = os.getenv("TURSO_ECHO_SQL", "false").lower() == "true"
-    batch_size: int = int(os.getenv("TURSO_BATCH_SIZE", "1000"))
-
-    # Daemon settings (for local sqld) - match serve.sh defaults
-    sqld_binary: str = os.getenv("SQLD_BINARY", "sqld")
-    sqld_db_path: str = os.getenv("SQLD_DB_PATH", "traces/v3/synth_ai.db")
-    sqld_http_port: int = int(os.getenv("SQLD_HTTP_PORT", "8080"))
-    sqld_idle_shutdown: int = int(os.getenv("SQLD_IDLE_SHUTDOWN", "0"))  # 0 = no idle shutdown
-
-    def get_connect_args(self) -> dict:
-        """Get SQLAlchemy connection arguments."""
-        args = {}
-        if self.auth_token:
-            args["auth_token"] = self.auth_token
-        return args
-
-    def get_engine_kwargs(self) -> dict:
-        """Get SQLAlchemy engine creation kwargs."""
-        kwargs = {
-            "echo": self.echo_sql,
-            "future": True,
-        }
-
-        # Only add pool settings for non-SQLite URLs
-        if not (self.db_url.startswith("sqlite") or ":memory:" in self.db_url):
-            kwargs.update(
-                {
-                    "pool_size": self.pool_size,
-                    "max_overflow": self.max_overflow,
-                    "pool_timeout": self.pool_timeout,
-                    "pool_recycle": self.pool_recycle,
-                }
-            )
-
-        return kwargs
-
-
-# Global config instance
-CONFIG = TursoConfig()

synth_ai/tracing_v3/db_config.py

@@ -1,194 +0,0 @@
-"""
-Centralized database configuration for v3 tracing.
-"""
-
-import logging
-import os
-import shutil
-from typing import TYPE_CHECKING, Optional
-
-if TYPE_CHECKING:
-    from .turso.daemon import SqldDaemon
-
-logger = logging.getLogger(__name__)
-
-
-class DatabaseConfig:
-    """Centralized database configuration management."""
-
-    # Default values from serve.sh
-    DEFAULT_DB_FILE = "traces/v3/synth_ai.db"
-    DEFAULT_HTTP_PORT = 8080
-
-    def __init__(
-        self, db_path: str | None = None, http_port: int | None = None, use_sqld: bool = True
-    ):
-        """
-        Initialize database configuration.
-
-        Args:
-            db_path: Path to database file. If None, uses DEFAULT_DB_FILE from serve.sh.
-            http_port: HTTP port for sqld daemon. If None, uses DEFAULT_HTTP_PORT from serve.sh.
-            use_sqld: Whether to use sqld daemon or direct SQLite.
-        """
-        self.use_sqld = use_sqld and self._sqld_binary_available()
-        self.http_port = http_port or int(os.getenv("SQLD_HTTP_PORT", self.DEFAULT_HTTP_PORT))
-        self._daemon: SqldDaemon | None = None
-
-        # Set up database path to match serve.sh configuration
-        if db_path is None:
-            # Use the same database file as serve.sh
-            self.db_file = os.getenv("SQLD_DB_PATH", self.DEFAULT_DB_FILE)
-            # For sqld, db_base_path is just the filename without directory
-            self.db_base_path = self.db_file
-        else:
-            self.db_file = db_path
-            self.db_base_path = db_path
-
-    @property
-    def database_url(self) -> str:
-        """Get the SQLAlchemy database URL."""
-        # Always use direct file access with aiosqlite
-        # (sqld HTTP interface is not compatible with SQLAlchemy)
-
-        # Check if sqld is running - it creates a directory structure
-        abs_path = os.path.abspath(self.db_file)
-        sqld_data_path = os.path.join(abs_path, "dbs", "default", "data")
-
-        if os.path.exists(sqld_data_path):
-            # sqld is managing the database
-            logger.debug(f"✅ Using sqld-managed database at: {sqld_data_path}")
-            actual_db_path = sqld_data_path
-        else:
-            # Direct SQLite file
-            if not os.path.exists(abs_path):
-                logger.debug(f"⚠️  Database file not found at: {abs_path}")
-                logger.debug("🔧 Make sure to run './serve.sh' to start the turso/sqld service")
-            else:
-                logger.debug(f"📁 Using direct SQLite file at: {abs_path}")
-            actual_db_path = abs_path
-
-        # SQLite URLs need 3 slashes for absolute paths
-        return f"sqlite+aiosqlite:///{actual_db_path}"
-
-    def _sqld_binary_available(self) -> bool:
-        """Check if the sqld (Turso) binary is available on PATH."""
-        # Respect explicit SQLD_BINARY override when present
-        binary_override = os.getenv("SQLD_BINARY")
-        candidates = [binary_override, "sqld", "libsql-server"]
-
-        for candidate in candidates:
-            if candidate and shutil.which(candidate):
-                return True
-
-        if binary_override:
-            logger.warning(
-                "Configured SQLD_BINARY='%s' but the executable was not found on PATH. "
-                "Falling back to direct SQLite.",
-                binary_override,
-            )
-        else:
-            logger.warning(
-                "sqld binary not detected; falling back to SQLite-only mode. "
-                "Install Turso's sqld or set SQLD_BINARY to enable the Turso daemon."
-            )
-
-        return False
-
-    def start_daemon(self, wait_time: float = 2.0):
-        """
-        Start the sqld daemon if configured.
-
-        Args:
-            wait_time: Time to wait for daemon startup.
-
-        Returns:
-            The daemon instance.
-        """
-        if not self.use_sqld:
-            raise RuntimeError("Database not configured to use sqld daemon")
-
-        if self._daemon is None:
-            # Import here to avoid circular dependency
-            from .turso.daemon import SqldDaemon
-
-            self._daemon = SqldDaemon(db_path=self.db_base_path, http_port=self.http_port)
-
-        self._daemon.start()
-
-        # Wait for daemon to be ready
-        import time
-
-        time.sleep(wait_time)
-
-        return self._daemon
-
-    def stop_daemon(self):
-        """Stop the sqld daemon if running."""
-        if self._daemon:
-            self._daemon.stop()
-            self._daemon = None
-
-    def get_daemon_and_url(self, wait_time: float = 2.0) -> tuple[Optional["SqldDaemon"], str]:
-        """
-        Get daemon (starting if needed) and database URL.
-
-        Returns:
-            Tuple of (daemon or None, database_url)
-        """
-        daemon = None
-        if self.use_sqld:
-            daemon = self.start_daemon(wait_time)
-
-        return daemon, self.database_url
-
-
-# Global default configuration
-_default_config: DatabaseConfig | None = None
-
-
-def get_default_db_config() -> DatabaseConfig:
-    """Get the default database configuration."""
-    global _default_config
-    if _default_config is None:
-        # Check environment variable for database path
-        db_path = os.environ.get("SYNTH_AI_V3_DB_PATH")
-        use_sqld = os.environ.get("SYNTH_AI_V3_USE_SQLD", "true").lower() == "true"
-
-        # Check if sqld is already running (started by serve.sh)
-        import subprocess
-
-        sqld_port = int(os.getenv("SQLD_HTTP_PORT", DatabaseConfig.DEFAULT_HTTP_PORT))
-        sqld_running = False
-        try:
-            result = subprocess.run(
-                ["pgrep", "-f", f"sqld.*--http-listen-addr.*:{sqld_port}"],
-                capture_output=True,
-                text=True,
-            )
-            if result.returncode == 0:
-                # sqld is already running, don't start a new one
-                sqld_running = True
-                use_sqld = False
-                logger.debug(f"✅ Detected sqld already running on port {sqld_port}")
-        except Exception as e:
-            logger.debug(f"Could not check for sqld process: {e}")
-
-        if not sqld_running and use_sqld:
-            logger.warning("⚠️  sqld service not detected!")
-            logger.warning("🔧 Please start the turso/sqld service by running:")
-            logger.warning("   ./serve.sh")
-            logger.warning("")
-            logger.warning("This will start:")
-            logger.warning("  - sqld daemon (SQLite server) on port 8080")
-            logger.warning("  - Environment service on port 8901")
-
-        _default_config = DatabaseConfig(db_path=db_path, use_sqld=use_sqld)
-
-    return _default_config
-
-
-def set_default_db_config(config: DatabaseConfig):
-    """Set the default database configuration."""
-    global _default_config
-    _default_config = config