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

synth_ai/core/tracing_v3/__init__.py

@@ -0,0 +1,99 @@
+"""Tracing v3 - Turso/sqld based tracing implementation.
+
+This module provides a modern, async-first tracing system for capturing and storing
+detailed execution traces from AI systems. It's designed to handle high-throughput
+scenarios with proper async/await patterns throughout.
+
+Architecture Overview:
+---------------------
+The v3 tracing system is built on several key components:
+
+1. **Data Abstractions** (`abstractions.py`):
+   - Dataclass-based models for traces, events, and messages
+   - Type-safe representations of session data
+   - Support for multiple event types (Runtime, Environment, LM/CAIS)
+
+2. **Session Tracer** (`session_tracer.py`):
+   - Main interface for creating and managing trace sessions
+   - Async context managers for session and timestep management
+   - Automatic event and message recording with proper ordering
+
+3. **Async Storage** (`turso/manager.py`):
+   - SQLAlchemy async engine with Turso/sqld backend
+   - Batch insert capabilities for high-throughput scenarios
+   - Analytics views for querying trace data
+
+4. **Decorators** (`decorators.py`):
+   - Context-aware decorators using asyncio's ContextVar
+   - Automatic LLM call tracing with token/cost tracking
+   - Session and turn number propagation across async boundaries
+
+5. **Hook System** (`hooks.py`):
+   - Extensible hook points throughout the tracing lifecycle
+   - Support for both sync and async hook callbacks
+   - Pre/post processing of events and messages
+
+6. **Replica Sync** (`replica_sync.py`):
+   - Optional background sync with remote Turso database
+   - Local embedded SQLite for low-latency writes
+   - Configurable sync intervals
+
+Key Features:
+------------
+- **Async-First**: All database operations are async, preventing blocking
+- **Context Propagation**: Session/turn info flows through async call chains
+- **Type Safety**: Full typing support with dataclasses and type hints
+- **Extensibility**: Hook system allows custom processing logic
+- **Performance**: Batch operations and connection pooling for efficiency
+
+Usage Example:
+-------------
+    from synth_ai.core.tracing_v3 import SessionTracer
+
+    tracer = SessionTracer()
+    await tracer.initialize()
+
+    async with tracer.session() as session_id:
+        async with tracer.timestep("step1", turn_number=1):
+            # Record events during execution
+            await tracer.record_event(RuntimeEvent(...))
+            await tracer.record_message("User input", "user")
+
+Configuration:
+-------------
+The system uses environment variables for configuration:
+- TURSO_LOCAL_DB_URL: Local SQLite database URL
+- TURSO_POOL_SIZE: Connection pool size (default: 8)
+- TURSO_ECHO_SQL: Enable SQL logging (default: false)
+- SQLD_DB_PATH: Path to SQLite database file
+
+See `config.py` for full configuration options.
+"""
+
+from .abstractions import (
+    BaseEvent,
+    EnvironmentEvent,
+    RuntimeEvent,
+    SessionEventMarkovBlanketMessage,
+    SessionMessageContent,
+    SessionTimeStep,
+    SessionTrace,
+    TimeRecord,
+)
+from .config import TursoConfig
+from .llm_call_record_helpers import BaseLMResponse
+from .session_tracer import SessionTracer
+
+__all__ = [
+    "SessionTracer",
+    "SessionTrace",
+    "SessionTimeStep",
+    "BaseEvent",
+    "RuntimeEvent",
+    "EnvironmentEvent",
+    "SessionEventMarkovBlanketMessage",
+    "SessionMessageContent",
+    "TimeRecord",
+    "TursoConfig",
+    "BaseLMResponse",
+]

synth_ai/core/tracing_v3/abstractions.py

@@ -0,0 +1,302 @@
+"""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 UTC, datetime
+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(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(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/core/tracing_v3/config.py

@@ -0,0 +1,229 @@
+"""Configuration helpers for tracing v3.
+
+This module centralises the logic for discovering which datastore the tracer
+should use. Historically the project defaulted to a local SQLite file which
+breaks under parallel load. The new resolver inspects environment variables
+and defaults to Turso/libSQL whenever credentials are supplied, while keeping a
+SQLite fallback for contributors without remote access.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+from synth_ai.core.tracing_v3.constants import canonical_trace_db_path
+
+# STARTUP DIAGNOSTIC - Commented out to reduce noise
+# print(f"[TRACING_V3_CONFIG_LOADED] Python={sys.version_info.major}.{sys.version_info.minor} MODAL_IS_REMOTE={os.getenv('MODAL_IS_REMOTE')}", flush=True)
+
+# ---------------------------------------------------------------------------
+# DSN resolution helpers
+# ---------------------------------------------------------------------------
+
+_CANONICAL_DB_PATH = canonical_trace_db_path()
+_DEFAULT_TRACE_DIR = Path(os.getenv("SYNTH_TRACES_DIR", _CANONICAL_DB_PATH.parent))
+
+
+def _normalise_path(path: Path) -> Path:
+    """Resolve relative paths and expand user/home markers."""
+    path = path.expanduser()
+    if not path.is_absolute():
+        path = (Path.cwd() / path).resolve()
+    return path
+
+
+def _is_modal_environment() -> bool:
+    """Detect if running in Modal container.
+    
+    Modal automatically sets MODAL_IS_REMOTE=1 in all deployed containers.
+    We check this first, then fall back to other Modal env vars.
+    """
+    # Modal sets this in all deployed containers
+    if os.getenv("MODAL_IS_REMOTE") == "1":
+        return True
+    
+    # Additional Modal env vars as fallback
+    return bool(
+        os.getenv("MODAL_TASK_ID")
+        or os.getenv("MODAL_ENVIRONMENT")
+        or os.getenv("SERVICE", "").upper() == "MODAL"
+    )
+
+
+def _split_auth_from_url(url: str) -> tuple[str, str | None]:
+    """Strip any auth_token query parameter from a DSN."""
+    parsed = urlparse(url)
+    if not parsed.query:
+        return url, None
+
+    params = dict(parse_qsl(parsed.query, keep_blank_values=True))
+    token = params.pop("auth_token", None)
+    query = urlencode(params, doseq=True)
+    # urlunparse will omit the '?' automatically when query is empty
+    sanitised = urlunparse(parsed._replace(query=query))
+    return sanitised, token
+
+
+def _default_sqlite_url(*, ensure_dir: bool = True) -> tuple[str, str | None]:
+    """Generate a SQLite URL from SYNTH_TRACES_DIR if set, otherwise raise."""
+    traces_dir = os.getenv("SYNTH_TRACES_DIR")
+    if traces_dir:
+        dir_path = _normalise_path(Path(traces_dir))
+        if ensure_dir:
+            dir_path.mkdir(parents=True, exist_ok=True)
+        db_path = dir_path / "synth_traces.db"
+        sqlite_url = f"sqlite+aiosqlite:///{db_path}"
+        return sqlite_url, None
+    raise RuntimeError("SQLite fallback is disabled; configure LIBSQL_URL or run sqld locally.")
+
+
+def resolve_trace_db_settings(*, ensure_dir: bool = True) -> tuple[str, str | None]:
+    """Resolve the tracing database URL and optional auth token.
+
+    Resolution order:
+      1. `SYNTH_TRACES_DB` (explicit DSN override)
+      2. `LIBSQL_URL` / `TURSO_DATABASE_URL` (remote libSQL endpoints)
+      3. `TURSO_LOCAL_DB_URL` (legacy env for local sqld)
+      4. Modal environment: plain SQLite file (no sqld, no auth)
+      5. Local dev: sqld default
+    """
+    import logging
+    logger = logging.getLogger(__name__)
+
+    explicit = os.getenv("SYNTH_TRACES_DB")
+    if explicit:
+        logger.info(f"[TRACE_CONFIG] Using explicit SYNTH_TRACES_DB: {explicit}")
+        return _split_auth_from_url(explicit)
+
+    remote = os.getenv("LIBSQL_URL") or os.getenv("TURSO_DATABASE_URL")
+    if remote:
+        logger.info(f"[TRACE_CONFIG] Using remote Turso: {remote}")
+        url, token = _split_auth_from_url(remote)
+        if token:
+            return url, token
+        env_token = os.getenv("LIBSQL_AUTH_TOKEN") or os.getenv("TURSO_AUTH_TOKEN")
+        return url, env_token
+
+    local_override = os.getenv("TURSO_LOCAL_DB_URL")
+    if local_override:
+        logger.info(f"[TRACE_CONFIG] Using TURSO_LOCAL_DB_URL: {local_override}")
+        url, token = _split_auth_from_url(local_override)
+        if token:
+            return url, token
+        env_token = os.getenv("LIBSQL_AUTH_TOKEN") or os.getenv("TURSO_AUTH_TOKEN")
+        return url, env_token
+
+    # Check for SYNTH_TRACES_DIR to generate SQLite URL
+    traces_dir = os.getenv("SYNTH_TRACES_DIR")
+    if traces_dir:
+        try:
+            sqlite_url, _ = _default_sqlite_url(ensure_dir=ensure_dir)
+            logger.info(f"[TRACE_CONFIG] Using SQLite from SYNTH_TRACES_DIR: {sqlite_url}")
+            return sqlite_url, None
+        except RuntimeError:
+            pass  # Fall through to other options
+
+    # Modal environment: use plain SQLite file (no sqld daemon, no auth required)
+    is_modal = _is_modal_environment()
+    logger.info(f"[TRACE_CONFIG] Modal detection: {is_modal} (MODAL_IS_REMOTE={os.getenv('MODAL_IS_REMOTE')})")
+    if is_modal:
+        logger.info("[TRACE_CONFIG] Using Modal SQLite: file:/tmp/synth_traces.db")
+        return "file:/tmp/synth_traces.db", None
+
+    # Local dev: default to sqld HTTP API
+    default_url = os.getenv("LIBSQL_DEFAULT_URL", "http://127.0.0.1:8081")
+    logger.info(f"[TRACE_CONFIG] Using local sqld: {default_url}")
+    return default_url, None
+
+
+def resolve_trace_db_url(*, ensure_dir: bool = True) -> str:
+    """Return just the DSN, discarding any auth token."""
+    url, _ = resolve_trace_db_settings(ensure_dir=ensure_dir)
+    return url
+
+
+def resolve_trace_db_auth_token() -> str | None:
+    """Return the resolved auth token for the tracing datastore."""
+    _, token = resolve_trace_db_settings()
+    return token
+
+
+# ---------------------------------------------------------------------------
+# Config dataclasses
+# ---------------------------------------------------------------------------
+
+DEFAULT_DB_FILE = str(_normalise_path(_DEFAULT_TRACE_DIR) / _CANONICAL_DB_PATH.name)
+
+
+@dataclass
+class TursoConfig:
+    """Configuration for Turso/sqld connection."""
+
+    # Default values matching serve.sh
+    DEFAULT_DB_FILE = DEFAULT_DB_FILE
+    DEFAULT_HTTP_PORT = 8080
+
+    # Resolve DB URL and auth token from environment (libSQL preferred)
+    db_url: str = field(default_factory=resolve_trace_db_url)
+
+    # Remote database sync configuration
+    sync_url: str = os.getenv("LIBSQL_SYNC_URL") or os.getenv("TURSO_SYNC_URL", "")
+    auth_token: str = resolve_trace_db_auth_token() or ""
+    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", DEFAULT_DB_FILE)
+    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[str, str]:
+        """Get SQLAlchemy connection arguments."""
+        args: dict[str, str] = {}
+        if self.auth_token:
+            args["auth_token"] = self.auth_token
+        return args
+
+    def get_engine_kwargs(self) -> dict[str, Any]:
+        """Get SQLAlchemy engine creation kwargs."""
+        kwargs: dict[str, Any] = {
+            "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/core/tracing_v3/constants.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+TRACE_DB_DIR = Path("traces")
+TRACE_DB_BASENAME = "turso_task_app_traces"
+
+
+def canonical_trace_db_name(*, timestamp: datetime | None = None) -> str:
+    """Return the canonical trace database filename (with optional timestamp suffix)."""
+
+    if timestamp is None:
+        return f"{TRACE_DB_BASENAME}.db"
+    return f"{TRACE_DB_BASENAME}_{timestamp.strftime('%Y-%m-%d_%H-%M-%S')}.db"
+
+
+def canonical_trace_db_path(*, timestamp: datetime | None = None) -> Path:
+    """Return the canonical trace database path within the default trace directory."""
+
+    return TRACE_DB_DIR / canonical_trace_db_name(timestamp=timestamp)