synth-ai 0.2.8.dev2__py3-none-any.whl → 0.4.3__py3-none-any.whl

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()
+    }

synth_ai/core/cfgs.py

@@ -0,0 +1,240 @@
+import os
+from pathlib import Path
+from typing import Any, Literal, Optional, cast
+
+from pydantic import BaseModel
+
+from synth_ai.core.paths import get_bin_path
+from synth_ai.core.telemetry import log_error, log_info
+
+
+class LocalDeployCfg(BaseModel):
+    task_app_path: Path
+    env_api_key: str
+    trace: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        env_api_key: str,
+        trace: bool = True,
+        host: str = "127.0.0.1",
+        port: int = 8000
+    ) -> "LocalDeployCfg":
+        ctx: dict[str, Any] = {
+            "task_app_path": str(task_app_path),
+            "trace": trace,
+            "host": host,
+            "port": port,
+        }
+        log_info("creating LocalDeployCfg", ctx=ctx)
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                env_api_key=env_api_key,
+                trace=trace,
+                host=host,
+                port=port,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("LocalDeployCfg creation failed", ctx=ctx)
+            raise
+
+    @classmethod
+    def create_from_dict(
+        cls,
+        data: dict[str, Any]
+    ) -> "LocalDeployCfg":
+        path = Path(data["task_app_path"])
+        trace = bool(data.get("trace", True))
+        host = str(data.get("host", "127.0.0.1"))
+        port = int(data.get("port", 8000))
+        ctx: dict[str, Any] = {
+            "task_app_path": str(path),
+            "trace": trace,
+            "host": host,
+            "port": port,
+        }
+        log_info("creating LocalDeployCfg from dict", ctx=ctx)
+        env_api_key = data.get("env_api_key")
+        if not env_api_key or not isinstance(env_api_key, str):
+            raise ValueError("env_api_key is required in local deploy configuration")
+
+        try:
+            cfg = cls(
+                task_app_path=path,
+                env_api_key=env_api_key,
+                trace=trace,
+                host=host,
+                port=port,
+            )
+            return cfg
+        except (KeyError, TypeError, ValueError) as err:
+            ctx["error"] = type(err).__name__
+            log_error("LocalDeployCfg from dict failed", ctx=ctx)
+            raise ValueError(f"Invalid local deploy configuration: {err}") from err
+        
+
+class ModalDeployCfg(BaseModel):
+    task_app_path: Path
+    modal_app_path: Path
+    modal_bin_path: Path
+    synth_api_key: str
+    env_api_key: str
+    cmd_arg: Literal["deploy", "serve"] = "deploy"
+    modal_app_name: Optional[str] = None
+    dry_run: bool = False
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        modal_app_path: Path,
+        synth_api_key: str,
+        env_api_key: str,
+        modal_bin_path: Path | None = None,
+        cmd_arg: Literal["deploy", "serve"] = "deploy",
+        modal_app_name: Optional[str] = None,
+        dry_run: bool = False,
+    ) -> "ModalDeployCfg":
+        ctx: dict[str, Any] = {
+            "task_app_path": str(task_app_path),
+            "modal_app_path": str(modal_app_path),
+            "cmd_arg": cmd_arg,
+            "dry_run": dry_run,
+            "modal_app_name": modal_app_name,
+            "modal_bin_path": str(modal_bin_path) if modal_bin_path else None,
+        }
+        log_info("creating ModalDeployCfg", ctx=ctx)
+        modal_bin_path = modal_bin_path or get_bin_path("modal")
+        if modal_bin_path is None:
+            ctx["error"] = "ModalCLINotFound"
+            log_error("ModalDeployCfg creation failed", ctx=ctx)
+            raise ValueError("Modal CLI not found; install `modal` or pass --modal-cli with its path.")
+        ctx["modal_bin_path"] = str(modal_bin_path)
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                modal_app_path=modal_app_path,
+                modal_bin_path=modal_bin_path,
+                synth_api_key=synth_api_key,
+                env_api_key=env_api_key,
+                cmd_arg=cmd_arg,
+                modal_app_name=modal_app_name,
+                dry_run=dry_run,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("ModalDeployCfg creation failed", ctx=ctx)
+            raise
+
+    @classmethod
+    def create_from_kwargs(cls, **kwargs: Any) -> "ModalDeployCfg":
+        ctx: dict[str, Any] = {**kwargs}
+        log_info("creating ModalDeployCfg from kwargs", ctx=ctx)
+
+        synth_api_key = kwargs.get("synth_api_key")
+        if not synth_api_key or not isinstance(synth_api_key, str):
+            raise ValueError("synth_api_key must be provided as a string")
+        env_api_key = kwargs.get("env_api_key")
+        if not env_api_key or not isinstance(env_api_key, str):
+            raise ValueError("env_api_key must be provided as a string")
+
+        cmd_arg = str(kwargs.get("modal_mode", "deploy")).strip().lower()
+        if cmd_arg not in {"deploy", "serve"}:
+            raise ValueError("`--modal-mode` must be either 'deploy' or 'serve'.")
+
+        dry_run = bool(kwargs.get("dry_run", False))
+        if dry_run and os.getenv("CTX") == "mcp":
+            ctx["error"] = "dry_run_mcp"
+            log_error("ModalDeployCfg create_from_kwargs blocked", ctx=ctx)
+            raise ValueError("`synth-ai deploy --runtime modal --dry-run` cannot be used by MCP")
+        if dry_run and cmd_arg == "serve":
+            ctx["error"] = "dry_run_serve"
+            log_error("ModalDeployCfg create_from_kwargs blocked", ctx=ctx)
+            raise ValueError("`synth-ai deploy --runtime modal --modal-mode serve` cannot be used with `--dry-run`")
+
+        modal_bin_path_arg = kwargs.get("modal_cli")
+        modal_bin_path = Path(str(modal_bin_path_arg)).expanduser() if modal_bin_path_arg else get_bin_path("modal")
+        if modal_bin_path is None or not modal_bin_path.exists():
+            ctx["error"] = "ModalCLINotFound"
+            log_error("ModalDeployCfg create_from_kwargs failed", ctx=ctx)
+            raise ValueError('Modal binary not found via shutil.which("modal"). Install `modal` or pass --modal-cli with its path.')
+        modal_bin_path = modal_bin_path.resolve()
+
+        modal_app_name = kwargs.get("name")
+        if modal_app_name is not None:
+            modal_app_name = str(modal_app_name).strip() or None
+
+        literal_cmd = cast(Literal["deploy", "serve"], cmd_arg)
+
+        task_app_path = kwargs.get("task_app_path")
+        modal_app_path = kwargs.get("modal_app")
+
+        if not task_app_path:
+            raise ValueError("task_app_path is required")
+        if not modal_app_path:
+            raise ValueError("modal_app is required")
+
+        if not isinstance(task_app_path, Path):
+            task_app_path = Path(task_app_path)
+        if not isinstance(modal_app_path, Path):
+            modal_app_path = Path(modal_app_path)
+
+        try:
+            cfg = cls(
+                task_app_path=task_app_path,
+                modal_app_path=modal_app_path,
+                modal_bin_path=modal_bin_path,
+                synth_api_key=synth_api_key,
+                env_api_key=env_api_key,
+                cmd_arg=literal_cmd,
+                modal_app_name=modal_app_name,
+                dry_run=dry_run,
+            )
+            return cfg
+        except Exception as exc:
+            ctx["error"] = type(exc).__name__
+            log_error("ModalDeployCfg from kwargs failed", ctx=ctx)
+            raise
+
+
+class CFDeployCfg(BaseModel):
+    task_app_path: Path
+    env_api_key: str
+    host: str = "127.0.0.1"
+    port: int = 8000
+    mode: Literal["quick", "managed"] = "quick"
+    tunnel_token: Optional[str] = None
+    subdomain: Optional[str] = None
+    trace: bool = True
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_app_path: Path,
+        env_api_key: str,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        mode: Literal["quick", "managed"] = "quick",
+        subdomain: Optional[str] = None,
+        trace: bool = True,
+    ) -> "CFDeployCfg":
+        return cls(
+            task_app_path=task_app_path,
+            env_api_key=env_api_key,
+            host=host,
+            port=port,
+            mode=mode,
+            subdomain=subdomain,
+            trace=trace,
+        )

synth_ai/core/config/__init__.py

@@ -0,0 +1,16 @@
+"""Configuration base classes and utilities.
+
+This module provides base classes for job configs and common
+configuration patterns used across the SDK.
+"""
+
+from __future__ import annotations
+
+from .base import BaseJobConfig, ConfigValidator
+
+__all__ = [
+    "BaseJobConfig",
+    "ConfigValidator",
+]
+
+