synth-ai 0.2.16__py3-none-any.whl → 0.2.19__py3-none-any.whl

synth_ai/tracing_v3/config.py

@@ -1,19 +1,162 @@
-"""Configuration for tracing v3 with Turso/sqld."""
+"""Configuration helpers for tracing v3.
 
-import os
-from dataclasses import dataclass
+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 synth_ai.tracing_v3.constants import canonical_trace_db_path
+from __future__ import annotations
 
-DEFAULT_DB_FILE = str(canonical_trace_db_path())
+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.tracing_v3.constants import canonical_trace_db_path
 
-def _default_sqlite_url() -> str:
-    base_path = os.path.abspath(os.getenv("SQLD_DB_PATH", DEFAULT_DB_FILE))
-    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}"
+# 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
@@ -24,12 +167,12 @@ class TursoConfig:
     DEFAULT_DB_FILE = DEFAULT_DB_FILE
     DEFAULT_HTTP_PORT = 8080
 
-    # Use env override if provided; otherwise resolve based on SQLD layout
-    db_url: str = os.getenv("TURSO_LOCAL_DB_URL", _default_sqlite_url())
+    # 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("TURSO_DATABASE_URL", "")
-    auth_token: str = os.getenv("TURSO_AUTH_TOKEN", "")
+    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
@@ -54,16 +197,16 @@ class TursoConfig:
     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:
+    def get_connect_args(self) -> dict[str, str]:
         """Get SQLAlchemy connection arguments."""
-        args = {}
+        args: dict[str, str] = {}
         if self.auth_token:
             args["auth_token"] = self.auth_token
         return args
 
-    def get_engine_kwargs(self) -> dict:
+    def get_engine_kwargs(self) -> dict[str, Any]:
         """Get SQLAlchemy engine creation kwargs."""
-        kwargs = {
+        kwargs: dict[str, Any] = {
             "echo": self.echo_sql,
             "future": True,
         }

synth_ai/tracing_v3/constants.py

@@ -4,7 +4,7 @@ from datetime import datetime
 from pathlib import Path
 
 TRACE_DB_DIR = Path("traces")
-TRACE_DB_BASENAME = "task_app_traces"
+TRACE_DB_BASENAME = "turso_task_app_traces"
 
 
 def canonical_trace_db_name(*, timestamp: datetime | None = None) -> str:

synth_ai/tracing_v3/db_config.py

@@ -30,11 +30,12 @@ class DatabaseConfig:
 
         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.
+            http_port: Hrana WebSocket port for sqld daemon (env: SQLD_HTTP_PORT). If None, uses DEFAULT_HTTP_PORT.
             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))
+        # Note: SQLD_HTTP_PORT is actually the hrana port (8080), not the HTTP API port
+        self.hrana_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
@@ -57,21 +58,16 @@ class DatabaseConfig:
         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
+        if not os.path.exists(sqld_data_path) and not os.path.exists(abs_path):
+            raise RuntimeError(
+                "sqld data directory not found. Run `sqld --db-path <path>` before using the tracing database."
+            )
 
-        # SQLite URLs need 3 slashes for absolute paths
-        return f"sqlite+aiosqlite:///{actual_db_path}"
+        # Use http:// for local sqld HTTP API port
+        # sqld has two ports: hrana_port (Hrana WebSocket) and hrana_port+1 (HTTP API)
+        # Python libsql client uses HTTP API with http:// URLs
+        http_api_port = self.hrana_port + 1
+        return f"http://127.0.0.1:{http_api_port}"
 
     def _sqld_binary_available(self) -> bool:
         """Check if the sqld (Turso) binary is available on PATH."""
@@ -84,18 +80,12 @@ class DatabaseConfig:
                 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,
+            raise RuntimeError(
+                f"Configured SQLD_BINARY='{binary_override}' but the executable was not found on PATH."
             )
-        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
+        raise RuntimeError(
+            "sqld binary not detected; install Turso's sqld or set SQLD_BINARY so that libSQL can be used."
+        )
 
     def start_daemon(self, wait_time: float = 2.0):
         """
@@ -114,7 +104,7 @@ class DatabaseConfig:
             # 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 = SqldDaemon(db_path=self.db_base_path, hrana_port=self.hrana_port)
 
         self._daemon.start()
 
@@ -160,11 +150,13 @@ def get_default_db_config() -> DatabaseConfig:
         # 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_hrana_port = int(os.getenv("SQLD_HTTP_PORT", DatabaseConfig.DEFAULT_HTTP_PORT))
+        sqld_http_port = sqld_hrana_port + 1
         sqld_running = False
         try:
+            # Check for either hrana or http port in the process command line
             result = subprocess.run(
-                ["pgrep", "-f", f"sqld.*--http-listen-addr.*:{sqld_port}"],
+                ["pgrep", "-f", f"sqld.*(--hrana-listen-addr.*:{sqld_hrana_port}|--http-listen-addr.*:{sqld_http_port})"],
                 capture_output=True,
                 text=True,
             )
@@ -172,18 +164,12 @@ def get_default_db_config() -> DatabaseConfig:
                 # 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}")
+                logger.debug(f"✅ Detected sqld already running on ports {sqld_hrana_port} (hrana) and {sqld_http_port} (http)")
         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")
+            logger.warning("sqld service not detected. Start the Turso daemon (./serve.sh) before running tracing workloads.")
 
         _default_config = DatabaseConfig(db_path=db_path, use_sqld=use_sqld)
 

synth_ai/tracing_v3/migration_helper.py

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

synth_ai/tracing_v3/storage/config.py

@@ -1,10 +1,12 @@
 """Storage configuration for tracing v3."""
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
 
+from ..config import resolve_trace_db_auth_token, resolve_trace_db_settings
+
 
 class StorageBackend(str, Enum):
     """Supported storage backends."""
@@ -24,12 +26,9 @@ def _is_enabled(value: str | None) -> bool:
 class StorageConfig:
     """Configuration for storage backend."""
 
-    backend: StorageBackend = StorageBackend.TURSO_NATIVE
     connection_string: str | None = None
-
-    # Turso-specific settings
-    turso_url: str = os.getenv("TURSO_DATABASE_URL", "sqlite+libsql://http://127.0.0.1:8080")
-    turso_auth_token: str = os.getenv("TURSO_AUTH_TOKEN", "")
+    backend: StorageBackend | None = None
+    turso_auth_token: str | None = field(default=None)
 
     # Common settings
     pool_size: int = int(os.getenv("STORAGE_POOL_SIZE", "8"))
@@ -44,9 +43,48 @@ class StorageConfig:
         # Allow legacy override while keeping compatibility with existing TURSO_NATIVE env flag
         native_env = os.getenv("TURSO_NATIVE")
         native_flag = _is_enabled(native_env) if native_env is not None else None
+        resolved_url: str | None = self.connection_string
+        resolved_token: str | None = self.turso_auth_token
+
+        if resolved_url is None:
+            resolved_url, inferred_token = resolve_trace_db_settings()
+            self.connection_string = resolved_url
+            resolved_token = inferred_token
+
+        if resolved_token is None:
+            resolved_token = resolve_trace_db_auth_token()
+
+        self.turso_auth_token = resolved_token or ""
+
+        if self.backend is None:
+            self.backend = self._infer_backend(self.connection_string or "")
 
         if native_flag is False:
-            self.backend = StorageBackend.SQLITE
+            raise RuntimeError("TURSO_NATIVE=false is no longer supported; only Turso/libSQL backend is available.")
+
+        # Allow both TURSO_NATIVE and SQLITE backends (both use libsql.connect)
+        if self.backend not in (StorageBackend.TURSO_NATIVE, StorageBackend.SQLITE):
+            raise RuntimeError(f"Unsupported backend: {self.backend}. Only Turso/libSQL and SQLite are supported.")
+
+    @staticmethod
+    def _infer_backend(connection_string: str) -> StorageBackend:
+        """Infer backend type from the connection string."""
+        scheme = connection_string.split(":", 1)[0].lower()
+        
+        # Plain SQLite files: file://, /absolute/path, or no scheme
+        if (
+            scheme == "file"
+            or scheme.startswith("sqlite")
+            or connection_string.startswith("/")
+            or "://" not in connection_string
+        ):
+            return StorageBackend.SQLITE
+        
+        # Turso/sqld: libsql://, http://, https://
+        if scheme.startswith("libsql") or "libsql" in scheme or scheme in ("http", "https"):
+            return StorageBackend.TURSO_NATIVE
+        
+        raise RuntimeError(f"Unsupported tracing backend scheme: {scheme}")
 
     def get_connection_string(self) -> str:
         """Get the appropriate connection string for the backend."""
@@ -54,12 +92,8 @@ class StorageConfig:
             return self.connection_string
 
         if self.backend == StorageBackend.TURSO_NATIVE:
-            return self.turso_url
-        if self.backend == StorageBackend.SQLITE:
-            return "sqlite+aiosqlite:///traces.db"
-        if self.backend == StorageBackend.POSTGRES:
-            return os.getenv("POSTGRES_URL", "postgresql+asyncpg://localhost/traces")
-        raise ValueError(f"Unknown backend: {self.backend}")
+            return self.connection_string or ""
+        raise ValueError(f"Unsupported backend: {self.backend}")
 
     def get_backend_config(self) -> dict[str, Any]:
         """Get backend-specific configuration."""

synth_ai/tracing_v3/storage/factory.py

@@ -24,14 +24,14 @@ def create_storage(config: StorageConfig | None = None) -> TraceStorage:
 
     connection_string = config.get_connection_string()
 
-    if config.backend == StorageBackend.TURSO_NATIVE:
+    # Both TURSO_NATIVE and SQLITE use NativeLibsqlTraceManager
+    # because libsql.connect() handles both remote and local file databases
+    if config.backend in (StorageBackend.TURSO_NATIVE, StorageBackend.SQLITE):
         backend_config = config.get_backend_config()
         return NativeLibsqlTraceManager(
             db_url=connection_string,
             auth_token=backend_config.get("auth_token"),
         )
-    elif config.backend == StorageBackend.SQLITE:
-        return NativeLibsqlTraceManager(db_url=connection_string)
     elif config.backend == StorageBackend.POSTGRES:
         # Future: PostgreSQL implementation
         raise NotImplementedError("PostgreSQL backend not yet implemented")

synth_ai/tracing_v3/turso/daemon.py

@@ -1,8 +1,11 @@
 """sqld daemon management utilities."""
 
+import logging
+import os
 import pathlib
 import shutil
 import subprocess
+import sys
 import time
 
 import requests
@@ -10,6 +13,8 @@ from requests import RequestException
 
 from ..config import CONFIG
 
+logger = logging.getLogger(__name__)
+
 
 class SqldDaemon:
     """Manages local sqld daemon lifecycle."""
@@ -18,28 +23,101 @@ class SqldDaemon:
         self,
         db_path: str | None = None,
         http_port: int | None = None,
+        hrana_port: int | None = None,
         binary_path: str | None = None,
     ):
         """Initialize sqld daemon manager.
 
         Args:
             db_path: Path to database file (uses config default if not provided)
-            http_port: HTTP port for daemon (uses config default if not provided)
+            http_port: HTTP port for health/API (uses config default + 1 if not provided)
+            hrana_port: Hrana WebSocket port for libsql connections (uses config default if not provided)
             binary_path: Path to sqld binary (auto-detected if not provided)
         """
         self.db_path = db_path or CONFIG.sqld_db_path
-        self.http_port = http_port or CONFIG.sqld_http_port
+        self.hrana_port = hrana_port or CONFIG.sqld_http_port  # Main port for libsql://
+        self.http_port = http_port or (self.hrana_port + 1)  # HTTP API on next port
         self.binary_path = binary_path or self._find_binary()
         self.process: subprocess.Popen[str] | None = None
 
     def _find_binary(self) -> str:
-        """Find sqld binary in PATH."""
+        """Find sqld binary in PATH, auto-installing if needed.
+        
+        Search order:
+        1. CONFIG.sqld_binary in PATH
+        2. libsql-server in PATH
+        3. Common install locations (~/.turso/bin, /usr/local/bin, etc.)
+        4. Auto-install via synth_ai.utils.sqld (if interactive terminal)
+        
+        Returns:
+            Path to sqld binary
+            
+        Raises:
+            RuntimeError: If binary not found and auto-install fails/disabled
+        """
+        # Check PATH first
         binary = shutil.which(CONFIG.sqld_binary) or shutil.which("libsql-server")
-        if not binary:
-            raise RuntimeError(
-                "sqld binary not found in PATH. Install with: brew install turso-tech/tools/sqld"
-            )
-        return binary
+        if binary:
+            logger.debug(f"Found sqld binary in PATH: {binary}")
+            return binary
+        
+        # Check common install locations
+        try:
+            from synth_ai.utils.sqld import find_sqld_binary
+            binary = find_sqld_binary()
+            if binary:
+                logger.debug(f"Found sqld binary in common location: {binary}")
+                return binary
+        except ImportError:
+            logger.debug("synth_ai.utils.sqld not available, skipping common location check")
+        
+        # Try auto-install if enabled and interactive
+        auto_install_enabled = os.getenv("SYNTH_AI_AUTO_INSTALL_SQLD", "true").lower() == "true"
+        
+        if auto_install_enabled and sys.stdin.isatty():
+            try:
+                from synth_ai.utils.sqld import install_sqld
+                logger.info("sqld binary not found. Attempting automatic installation...")
+                
+                # Use click if available for better UX, otherwise proceed automatically
+                try:
+                    import click
+                    if not click.confirm(
+                        "sqld not found. Install automatically via Homebrew?",
+                        default=True
+                    ):
+                        raise RuntimeError("User declined automatic installation")
+                except ImportError:
+                    # click not available, auto-install without prompt
+                    logger.info("Installing sqld automatically (non-interactive mode)")
+                
+                binary = install_sqld()
+                logger.info(f"Successfully installed sqld to: {binary}")
+                return binary
+                
+            except Exception as exc:
+                logger.warning(f"Auto-install failed: {exc}")
+                # Fall through to error message below
+        elif not auto_install_enabled:
+            logger.debug("Auto-install disabled via SYNTH_AI_AUTO_INSTALL_SQLD=false")
+        elif not sys.stdin.isatty():
+            logger.debug("Non-interactive terminal, skipping auto-install prompt")
+        
+        # If we get here, all methods failed
+        raise RuntimeError(
+            "sqld binary not found. Install using one of these methods:\n"
+            "\n"
+            "Quick install (recommended):\n"
+            "  synth-ai turso\n"
+            "\n"
+            "Manual install:\n"
+            "  brew install turso-tech/tools/sqld\n"
+            "  # or\n"
+            "  curl -sSfL https://get.tur.so/install.sh | bash && turso dev\n"
+            "\n"
+            "For CI/CD environments:\n"
+            "  Set SYNTH_AI_AUTO_INSTALL_SQLD=false and pre-install sqld"
+        )
 
     def start(self, wait_for_ready: bool = True) -> subprocess.Popen:
         """Start the sqld daemon."""
@@ -53,6 +131,8 @@ class SqldDaemon:
             self.binary_path,
             "--db-path",
             str(db_file),
+            "--hrana-listen-addr",
+            f"127.0.0.1:{self.hrana_port}",
             "--http-listen-addr",
             f"127.0.0.1:{self.http_port}",
         ]
@@ -112,6 +192,14 @@ class SqldDaemon:
         """Check if daemon is running."""
         return self.process is not None and self.process.poll() is None
 
+    def get_hrana_port(self) -> int:
+        """Get the Hrana WebSocket port for libsql:// connections."""
+        return self.hrana_port
+
+    def get_http_port(self) -> int:
+        """Get the HTTP API port for health checks."""
+        return self.http_port
+
     def __enter__(self):
         """Context manager entry."""
         self.start()
@@ -126,13 +214,27 @@ class SqldDaemon:
 _daemon: SqldDaemon | None = None
 
 
-def start_sqld(db_path: str | None = None, port: int | None = None) -> SqldDaemon:
-    """Start a global sqld daemon instance."""
+def start_sqld(
+    db_path: str | None = None,
+    port: int | None = None,
+    hrana_port: int | None = None,
+    http_port: int | None = None,
+) -> SqldDaemon:
+    """Start a global sqld daemon instance.
+    
+    Args:
+        db_path: Path to database file
+        port: Legacy parameter - used as hrana_port if hrana_port not specified
+        hrana_port: Hrana WebSocket port for libsql:// connections
+        http_port: HTTP API port for health checks
+    """
     global _daemon
     if _daemon and _daemon.is_running():
         return _daemon
 
-    _daemon = SqldDaemon(db_path=db_path, http_port=port)
+    # Support legacy 'port' parameter by using it as hrana_port
+    final_hrana_port = hrana_port or port
+    _daemon = SqldDaemon(db_path=db_path, hrana_port=final_hrana_port, http_port=http_port)
     _daemon.start()
     return _daemon