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

synth_ai/cli/utils/traces.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+CLI: basic info about traces (runs).
+"""
+
+import asyncio
+import os
+
+import click
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from synth_ai.cli._internal.storage import load_storage
+
+
+def register(cli):
+    @cli.command()
+    @click.option(
+        "--url",
+        "db_url",
+        default="sqlite+aiosqlite:///./synth_ai.db/dbs/default/data",
+        help="Database URL",
+    )
+    @click.option("--limit", default=25, type=int, help="Max sessions to display")
+    def traces(db_url: str, limit: int):
+        """Show local trace DBs, traces per DB, and per-system counts."""
+        console = Console()
+
+        async def _run():
+            # Discover DBs under ./synth_ai.db/dbs (or override via env)
+            root = os.getenv("SYNTH_TRACES_ROOT", "./synth_ai.db/dbs")
+            if not os.path.isdir(root):
+                console.print(f"[red]No DB root found:[/red] {root}")
+                return
+
+            entries: list[tuple[str, str]] = []
+            for name in sorted(os.listdir(root)):
+                path = os.path.join(root, name)
+                data_path = os.path.join(path, "data")
+                if os.path.isdir(path) and os.path.isfile(data_path):
+                    entries.append((name, os.path.abspath(path)))
+
+            if not entries:
+                console.print("[dim]No trace databases found.[/dim]")
+                return
+
+            def _dir_size_bytes(dir_path: str) -> int:
+                total = 0
+                for dp, _, files in os.walk(dir_path):
+                    for fn in files:
+                        fp = os.path.join(dp, fn)
+                        import contextlib
+
+                        with contextlib.suppress(OSError):
+                            total += os.path.getsize(fp)
+                return total
+
+            async def db_counts(db_dir: str) -> tuple[int, dict[str, int], int, str | None, int]:
+                data_file = os.path.join(db_dir, "data")
+                create_storage, storage_config = load_storage()
+                mgr = create_storage(storage_config(connection_string=f"sqlite+aiosqlite:///{data_file}"))
+                await mgr.initialize()
+                try:
+                    traces_df = await mgr.query_traces("SELECT COUNT(*) AS c FROM session_traces")
+                    traces_count = (
+                        int(traces_df.iloc[0]["c"])
+                        if traces_df is not None and not traces_df.empty
+                        else 0
+                    )
+                    try:
+                        systems_df = await mgr.query_traces(
+                            "SELECT system_type, COUNT(*) AS c FROM systems GROUP BY system_type"
+                        )
+                        system_counts = (
+                            {
+                                str(r["system_type"] or "-"): int(r["c"] or 0)
+                                for _, r in systems_df.iterrows()
+                            }
+                            if systems_df is not None
+                            and hasattr(systems_df, "iterrows")
+                            and not systems_df.empty
+                            else {}
+                        )
+                    except Exception:
+                        system_counts = {}
+                    try:
+                        exps_df = await mgr.query_traces("SELECT COUNT(*) AS c FROM experiments")
+                        exps_count = (
+                            int(exps_df.iloc[0]["c"])
+                            if exps_df is not None and not exps_df.empty
+                            else 0
+                        )
+                    except Exception:
+                        exps_count = 0
+                    try:
+                        last_df = await mgr.query_traces(
+                            "SELECT MAX(created_at) AS last_created_at FROM session_traces"
+                        )
+                        last_created = (
+                            str(last_df.iloc[0]["last_created_at"])
+                            if last_df is not None and not last_df.empty
+                            else None
+                        )
+                    except Exception:
+                        last_created = None
+                    size_bytes = _dir_size_bytes(db_dir)
+                    return traces_count, system_counts, exps_count, last_created, size_bytes
+                finally:
+                    await mgr.close()
+
+            results = []
+            for name, db_dir in entries:
+                try:
+                    counts = await db_counts(db_dir)
+                except Exception:
+                    counts = (0, {}, 0, None, 0)
+                results.append((name, counts))
+
+            # DB summary table
+            summary = Table(title="Trace Databases", box=box.SIMPLE, header_style="bold")
+            for col in ["DB", "Traces", "Experiments", "Last Activity", "Size (GB)"]:
+                summary.add_column(
+                    col, justify="right" if col in {"Traces", "Experiments"} else "left"
+                )
+
+            aggregate_systems: dict[str, int] = {}
+            total_bytes = 0
+            for name, (
+                traces_count,
+                system_counts,
+                experiments_count,
+                last_created_at,
+                size_bytes,
+            ) in results:
+                total_bytes += int(size_bytes or 0)
+                gb = int(size_bytes or 0) / (1024**3)
+                summary.add_row(
+                    name,
+                    f"{traces_count:,}",
+                    f"{experiments_count:,}",
+                    str(last_created_at or "-"),
+                    f"{gb:.2f}",
+                )
+                for k, v in system_counts.items():
+                    aggregate_systems[k] = aggregate_systems.get(k, 0) + int(v)
+            console.print(summary)
+
+            # Total storage line
+            total_gb = total_bytes / (1024**3)
+            console.print(f"[dim]Total storage across DBs:[/dim] [bold]{total_gb:.2f} GB[/bold]")
+
+            # Per-system aggregate across DBs
+            if aggregate_systems:
+                st = Table(title="Per-System (all DBs)", box=box.SIMPLE, header_style="bold")
+                st.add_column("System")
+                st.add_column("Count", justify="right")
+                for sys_name, count in sorted(
+                    aggregate_systems.items(), key=lambda x: (-x[1], x[0])
+                ):
+                    st.add_row(sys_name or "-", f"{int(count):,}")
+                console.print(st)
+
+        asyncio.run(_run())

synth_ai/contracts/__init__.py

@@ -0,0 +1,67 @@
+"""
+Synth AI Contracts
+
+OpenAPI contracts for implementing Task Apps in any language.
+These contracts define the HTTP interface between Synth optimizers
+(MIPRO, GEPA) and your Task App service.
+
+Usage:
+    # Get the contract file path
+    from synth_ai.contracts import TASK_APP_CONTRACT_PATH
+
+    # Get the contract as a string
+    from synth_ai.contracts import get_task_app_contract
+    yaml_content = get_task_app_contract()
+
+    # Or access directly via CLI
+    # synth contracts show task-app
+"""
+
+from pathlib import Path
+
+CONTRACTS_DIR = Path(__file__).parent
+TASK_APP_CONTRACT_PATH = CONTRACTS_DIR / "task_app.yaml"
+
+
+def get_task_app_contract() -> str:
+    """Return the Task App contract as a YAML string.
+
+    This OpenAPI spec defines the HTTP interface that Task Apps must implement
+    to work with Synth's MIPRO and GEPA prompt optimizers.
+
+    Returns:
+        The full OpenAPI 3.1 specification as a YAML string.
+
+    Example:
+        >>> contract = get_task_app_contract()
+        >>> print(contract[:50])
+        openapi: 3.1.0
+        info:
+          title: Synth Task App
+    """
+    return TASK_APP_CONTRACT_PATH.read_text()
+
+
+def get_contract_path(contract_name: str = "task-app") -> Path:
+    """Get the filesystem path to a contract file.
+
+    Args:
+        contract_name: Name of the contract. Currently only "task-app" is supported.
+
+    Returns:
+        Path to the contract YAML file.
+
+    Raises:
+        ValueError: If the contract name is not recognized.
+    """
+    if contract_name in ("task-app", "task_app"):
+        return TASK_APP_CONTRACT_PATH
+    raise ValueError(f"Unknown contract: {contract_name}. Available: task-app")
+
+
+__all__ = [
+    "CONTRACTS_DIR",
+    "TASK_APP_CONTRACT_PATH",
+    "get_task_app_contract",
+    "get_contract_path",
+]

synth_ai/core/__init__.py

@@ -0,0 +1,100 @@
+"""Synth AI Core Layer.
+
+This module provides internal plumbing that SDK and CLI can share:
+- Environment resolution
+- HTTP client utilities
+- Error types
+- Logging
+- Pricing
+- Config base classes
+
+Dependency rules:
+- core/ can import data/
+- core/ should NOT import sdk/ or cli/
+- core/ should NOT import click (leave that to cli/)
+"""
+
+from __future__ import annotations
+
+# Config base classes
+from synth_ai.core.config import BaseJobConfig, ConfigValidator
+
+# Environment utilities
+from synth_ai.core.env import (
+    PROD_BASE_URL,
+    get_api_key,
+    get_backend_url,
+    load_env_file,
+    mask_value,
+    resolve_env_file,
+)
+
+# Error types
+from synth_ai.core.errors import (
+    AuthenticationError,
+    ConfigError,
+    HTTPError,
+    JobError,
+    ModelNotSupportedError,
+    StorageError,
+    SynthError,
+    TimeoutError,
+    ValidationError,
+)
+
+# HTTP utilities
+from synth_ai.core.http import AsyncHttpClient, sleep
+
+# Logging
+from synth_ai.core.logging import (
+    SDK_LOGGER_NAME,
+    configure_logging,
+    get_logger,
+    suppress_noisy_loggers,
+)
+
+# Pricing
+from synth_ai.core.pricing import (
+    MODEL_PRICES,
+    TokenRates,
+    estimate_cost,
+    get_token_rates,
+)
+
+__all__ = [
+    # Errors
+    "SynthError",
+    "ConfigError",
+    "AuthenticationError",
+    "ValidationError",
+    "HTTPError",
+    "JobError",
+    "TimeoutError",
+    "StorageError",
+    "ModelNotSupportedError",
+    # Environment
+    "get_api_key",
+    "get_backend_url",
+    "resolve_env_file",
+    "load_env_file",
+    "mask_value",
+    "PROD_BASE_URL",
+    # HTTP
+    "AsyncHttpClient",
+    "sleep",
+    # Logging
+    "get_logger",
+    "configure_logging",
+    "suppress_noisy_loggers",
+    "SDK_LOGGER_NAME",
+    # Pricing
+    "TokenRates",
+    "MODEL_PRICES",
+    "get_token_rates",
+    "estimate_cost",
+    # Config
+    "BaseJobConfig",
+    "ConfigValidator",
+]
+
+

synth_ai/core/_utils/__init__.py

@@ -0,0 +1,54 @@
+"""
+Compatibility shims for legacy `synth_ai.core._utils.*` imports.
+
+These modules re-export the public symbols so existing downstream code
+continues to work without modification.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+# Modules that can be eagerly loaded (no circular deps)
+_EAGER_MAPPING = {
+    "base_url": "synth_ai.core.env",
+    "http": "synth_ai.core.http",
+    "task_app_state": "synth_ai.core.task_app_state",
+    "user_config": "synth_ai.core.user_config",
+}
+
+# Modules that must be lazily loaded (have CLI deps)
+_LAZY_MAPPING = {
+    "prompts": "synth_ai.cli.lib.prompt_args",
+}
+
+__all__ = sorted(list(_EAGER_MAPPING.keys()) + list(_LAZY_MAPPING.keys()))
+
+
+def __getattr__(name: str) -> Any:
+    if name in _EAGER_MAPPING:
+        module = import_module(_EAGER_MAPPING[name])
+        globals()[name] = module
+        return module
+    if name in _LAZY_MAPPING:
+        module = import_module(_LAZY_MAPPING[name])
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module 'synth_ai.core._utils' has no attribute '{name}'")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+# Eagerly load non-circular modules
+for _name in _EAGER_MAPPING:
+    try:
+        _module = import_module(_EAGER_MAPPING[_name])
+        globals()[_name] = _module
+        if hasattr(_module, "__all__"):
+            for _attr in _module.__all__:
+                globals().setdefault(_attr, getattr(_module, _attr))
+    except ImportError:
+        pass

synth_ai/core/_utils/base_url.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.core.env import *  # noqa: F401,F403
+
+try:
+    from synth_ai.core.env import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/core/_utils/http.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.core.http import *  # noqa: F401,F403
+
+try:
+    from synth_ai.core.http import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/core/_utils/prompts.py

@@ -0,0 +1,14 @@
+"""Lazy re-export of prompt utilities to avoid circular imports."""
+from __future__ import annotations
+
+from typing import Any
+
+# Functions available via __getattr__:
+# - ensure_required_args
+
+
+def __getattr__(name: str) -> Any:
+    if name == "ensure_required_args":
+        from synth_ai.cli.lib import prompt_args
+        return getattr(prompt_args, name)
+    raise AttributeError(f"module 'synth_ai.core._utils.prompts' has no attribute '{name}'")

synth_ai/core/_utils/task_app_state.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from synth_ai.core.task_app_state import *  # noqa: F401,F403
+
+try:
+    from synth_ai.core.task_app_state import (
+        __all__ as __wrapped_all__,  # type: ignore[attr-defined]
+    )
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/core/_utils/user_config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.core.user_config import *  # noqa: F401,F403
+
+try:
+    from synth_ai.core.user_config import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/core/apps/common.py

@@ -0,0 +1,116 @@
+import ast
+import importlib.util as importlib
+import py_compile
+import subprocess
+import sys
+from ast import Module as AstModule
+from pathlib import Path
+from types import ModuleType
+from typing import Any, cast
+
+from fastapi.routing import APIRoute
+from starlette.types import ASGIApp
+
+
+def run_ruff_check(path: Path, fix: bool = False) -> int:
+    cmd = ["ruff", "check", "--extend-ignore", "I001,I002"]
+    if fix:
+        cmd.append("--fix")
+    cmd.append(str(path))
+    try:
+        return subprocess.run(cmd, check=False).returncode
+    except FileNotFoundError:
+        return 0
+
+
+def extract_routes_from_app(app: object) -> list[str]:
+    router = getattr(app, "router", None)
+    if router is None:
+        return []
+    routes = getattr(router, "routes", None)
+    if routes is None:
+        return []
+    return [getattr(route, "path", '') for route in routes]
+
+
+def build_fastapi_route_index(app: ASGIApp) -> dict[str, list[APIRoute]]:
+    router = getattr(app, "router", None)
+    if router is None:
+        raise ValueError("App does not expose a FastAPI router")
+    entries: dict[str, list[APIRoute]] = {}
+    for route in getattr(router, "routes", []):
+        if isinstance(route, APIRoute):
+            entries.setdefault(route.path, []).append(route)
+    return entries
+
+
+def get_asgi_app(module: ModuleType) -> ASGIApp:
+    def _coerce_app(candidate: Any) -> ASGIApp | None:
+        if candidate is None:
+            return None
+        if callable(candidate):
+            return cast(ASGIApp, candidate)
+        return None
+    
+    app = _coerce_app(getattr(module, "app", None))
+    if app:
+        return app
+    asgi_factory_names = (
+        "fastapi_app",
+        "create_app",
+        "build_app",
+        "configure_app",
+        "get_app",
+        "app_factory",
+    )
+    for name in asgi_factory_names:
+        factory = getattr(module, name, None)
+        if callable(factory):
+            produced = factory()
+            coerced = _coerce_app(produced)
+            if coerced is not None:
+                app = coerced
+                break
+    if app is None:
+        raise RuntimeError("Task app must expose an ASGI application via `app = FastAPI(...)` or a callable factory.")
+    return app
+
+
+def get_module(path: Path) -> AstModule:
+    try:
+        src = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"Unable to read file {path}: {exc}") from exc
+    try:
+        return ast.parse(src, filename=str(path))
+    except SyntaxError as exc:
+        raise ValueError(f"{path} contains invalid Python syntax: {exc}") from exc
+
+
+def load_module(
+    path: Path,
+    module_name: str | None = None
+) -> ModuleType:
+    name = module_name or path.stem
+    spec = importlib.spec_from_file_location(name, str(path))
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load module spec for {path}")
+    module = importlib.module_from_spec(spec)
+    if module_name:
+        sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        if module_name:
+            sys.modules.pop(module_name, None)
+        raise ImportError(f"Failed to import module: {exc}") from exc
+    return module
+
+
+def validate_py_file_compiles(path: Path) -> None:
+    path = path.resolve()
+    try:
+        py_compile.compile(str(path), doraise=True)
+    except py_compile.PyCompileError as exc:
+        raise ValueError(f"Failed to compile {path}: {exc.msg}") from exc
+    return None

synth_ai/core/auth.py

@@ -0,0 +1,95 @@
+import contextlib
+import time
+import webbrowser
+from dataclasses import dataclass
+
+import requests
+from requests import RequestException
+
+from synth_ai.core.urls import FRONTEND_URL_BASE
+
+INIT_URL = FRONTEND_URL_BASE + "/api/sdk/handshake/init"
+TOKEN_URL = FRONTEND_URL_BASE + "/api/sdk/handshake/token"
+POLL_INTERVAL = 3
+
+
+@dataclass
+class AuthSession:
+    device_code: str
+    verification_uri: str
+    expires_at: float
+
+
+def init_auth_session() -> AuthSession:    
+    try:
+        res = requests.post(INIT_URL, timeout=10)
+    except RequestException as exc:
+        raise RuntimeError(f"Failed to reach handshake init endpoint: {exc}") from exc
+    if res.status_code != 200:
+        body = res.text.strip()
+        raise RuntimeError(f"Handshake init failed ({res.status_code}): {body or 'no response body'}")
+
+    try:
+        data = res.json()
+    except ValueError as err:
+        raise RuntimeError("Handshake init returned malformed JSON.") from err
+
+    device_code = str(data.get("device_code") or "").strip()
+    verification_uri = str(data.get("verification_uri") or "").strip()
+    expires_in = int(data.get("expires_in") or 600)
+    if not device_code or not verification_uri or not expires_in:
+        raise RuntimeError("Handshake init response missing device_code or verification_uri or expires_in.")
+
+    return AuthSession(
+        device_code=device_code,
+        verification_uri=verification_uri,
+        expires_at=time.time() + expires_in
+    )
+
+
+def fetch_data(device_code: str) -> requests.Response | None:
+    try:
+        return requests.post(
+            TOKEN_URL,
+            json={"device_code": device_code},
+            timeout=10,
+        )
+    except RequestException:
+        return None
+
+
+def fetch_credentials_from_web_browser() -> dict:
+    print(f"Fetching your credentials from {FRONTEND_URL_BASE}")
+
+    auth_session = init_auth_session()
+
+    with contextlib.suppress(Exception):
+        webbrowser.open(auth_session.verification_uri)
+
+    data = None
+    while time.time() <= auth_session.expires_at:
+        res = fetch_data(auth_session.device_code)
+        if not res:
+            time.sleep(POLL_INTERVAL)
+            continue
+        if res.status_code == 200:
+            try:
+                data = res.json()
+            except ValueError as err:
+                raise RuntimeError("Handshake token returned malformed JSON.") from err
+            break
+        if res.status_code in (404, 410):
+            raise RuntimeError("Handshake failed: device code expired or was revoked.")
+        time.sleep(POLL_INTERVAL)
+    if data is None:
+        raise TimeoutError("Handshake timed out before credentials were returned.")
+
+    print(f"Connected to {FRONTEND_URL_BASE}")
+    credentials = data.get("keys")
+    if not isinstance(credentials, dict):
+        credentials = {}
+
+    return {
+        "SYNTH_API_KEY": str(credentials.get("synth") or "").strip(),
+        "ENVIRONMENT_API_KEY": str(credentials.get("rl_env") or "").strip()
+    }