synth-ai 0.2.8.dev4__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/utils/apps.py

@@ -0,0 +1,152 @@
+import ast
+import importlib.util as importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Set, cast
+
+from uvicorn._types import ASGIApplication
+
+from synth_ai.utils.paths import is_py_file
+
+
+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 get_asgi_app(module: ModuleType) -> ASGIApplication:
+    def _coerce_app(candidate: Any) -> ASGIApplication | None:
+        if candidate is None:
+            return None
+        if callable(candidate):
+            return cast(ASGIApplication, 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 load_file_to_module(
+    path: Path,
+    module_name: str | None = None
+) -> ModuleType:
+    if not is_py_file(path):
+        raise ValueError(f"{path} is not a .py file")
+    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_task_app(path: Path | None) -> Path:
+    assert path is not None
+    path = path.resolve()
+    module = load_file_to_module(path)
+    app = get_asgi_app(module)
+    if app is None:
+        raise ValueError(f"Failed to extract app attribute from module for {path}")
+    routes = set(extract_routes_from_app(app))
+    required_endpoints: Set[str] = {
+        '/',
+        "/health",
+        "/info",
+        "/task_info",
+        "/rollout"
+    }
+    missing = required_endpoints - routes
+    if missing:
+        raise ValueError(f"{path} is missing required FastAPI endpoints: {', '.join(sorted(missing))}")
+    return path
+
+
+def validate_modal_app(path: Path | None) -> Path:
+    assert path is not None
+    if not is_py_file(path):
+        raise ValueError(f"{path} must be a .py file containing a Modal app definition.")
+    try:
+        source = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"Unable to read modal app file {path}: {exc}") from exc
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        raise ValueError(f"{path} contains invalid Python syntax: {exc}") from exc
+
+    app_aliases: set[str] = set()
+    modal_aliases: set[str] = set()
+
+    def literal_name(call: ast.Call) -> str | None:
+        for kw in call.keywords:
+            if (
+                kw.arg in {"name", "app_name"}
+                and isinstance(kw.value, ast.Constant)
+                and isinstance(kw.value.value, str)
+            ):
+                return kw.value.value
+        if call.args:
+            first = call.args[0]
+            if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                return first.value
+        return None
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "modal":
+            for alias in node.names:
+                if alias.name == "App":
+                    app_aliases.add(alias.asname or alias.name)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "modal":
+                    modal_aliases.add(alias.asname or alias.name)
+        elif isinstance(node, ast.Call):
+            func = node.func
+            if isinstance(func, ast.Name) and func.id in app_aliases:
+                if literal_name(node):
+                    return path
+            elif (
+                isinstance(func, ast.Attribute)
+                and func.attr == "App"
+                and isinstance(func.value, ast.Name)
+                and func.value.id in modal_aliases
+                and literal_name(node)
+            ):
+                return path
+    raise ValueError(f"{path} must declare `app = modal.App(...)` (or import `App` directly) with a literal name.")

synth_ai/utils/base_url.py

@@ -0,0 +1,94 @@
+"""
+Base URL resolution for learning-v2 and related backend APIs.
+
+Default to production, allow overrides via environment variables:
+- LEARNING_V2_BASE_URL (highest precedence)
+- SYNTH_BASE_URL (legacy)
+- SYNTH_LOCAL_BASE_URL
+- SYNTH_DEV_BASE_URL
+- SYNTH_PROD_BASE_URL (fallback if none provided)
+
+Normalization: ensure the returned URL ends with "/api".
+"""
+
+import os
+from typing import Literal
+
+PROD_BASE_URL_DEFAULT = "https://agent-learning.onrender.com"
+
+
+def _normalize_base(url: str) -> str:
+    url = url.strip()
+    if url.endswith("/v1"):
+        url = url[:-3]
+    url = url.rstrip("/")
+    if not url.endswith("/api"):
+        url = f"{url}/api"
+    return url
+
+
+def get_learning_v2_base_url(mode: Literal["dev", "prod"] = "prod") -> str:
+    if mode == "prod":
+        prod = os.getenv("SYNTH_PROD_BASE_URL") or PROD_BASE_URL_DEFAULT
+        return _normalize_base(prod)
+    env_url = os.getenv("LEARNING_V2_BASE_URL")
+    if env_url:
+        return _normalize_base(env_url)
+
+    legacy = os.getenv("SYNTH_BASE_URL")
+    if legacy:
+        return _normalize_base(legacy)
+
+    local = os.getenv("SYNTH_LOCAL_BASE_URL")
+    if local:
+        return _normalize_base(local)
+
+    dev = os.getenv("SYNTH_DEV_BASE_URL")
+    if dev:
+        return _normalize_base(dev)
+
+    raise ValueError("No base URL configured. Set one of: LEARNING_V2_BASE_URL, SYNTH_BASE_URL, SYNTH_LOCAL_BASE_URL, SYNTH_DEV_BASE_URL")
+
+
+def _resolve_override_mode() -> str:
+    ov = (os.getenv("SYNTH_BACKEND_URL_OVERRIDE", "") or "").strip().lower()
+    if ov in {"local", "dev", "prod"}:
+        return ov
+    return "prod"
+
+
+def get_backend_from_env() -> tuple[str, str]:
+    direct_override = (os.getenv("BACKEND_OVERRIDE") or "").strip()
+    if direct_override:
+        base = direct_override.rstrip("/")
+        if base.endswith("/api"):
+            base = base[: -len("/api")]
+        api_key = os.getenv("SYNTH_API_KEY", "").strip()
+        return base, api_key
+
+    mode = _resolve_override_mode()
+    if mode == "local":
+        base = os.getenv("LOCAL_BACKEND_URL", "http://localhost:8000")
+        key = os.getenv("TESTING_LOCAL_SYNTH_API_KEY", "")
+        return base.rstrip("/"), key
+    if mode == "dev":
+        base = os.getenv("DEV_BACKEND_URL", "") or "http://localhost:8000"
+        key = os.getenv("DEV_SYNTH_API_KEY", "")
+        return base.rstrip("/"), key
+    base = os.getenv("PROD_BACKEND_URL", f"{PROD_BASE_URL_DEFAULT}")
+    base = base.rstrip("/")
+    if base.endswith("/api"):
+        base = base[: -len("/api")]
+    key = (
+        os.getenv("PROD_SYNTH_API_KEY", "")
+        or os.getenv("TESTING_PROD_SYNTH_API_KEY", "")
+        or os.getenv("SYNTH_API_KEY", "")
+    )
+    return base, key
+
+
+__all__ = [
+    "PROD_BASE_URL_DEFAULT",
+    "get_backend_from_env",
+    "get_learning_v2_base_url",
+]

synth_ai/utils/bin.py

@@ -0,0 +1,39 @@
+import shlex
+import subprocess
+from pathlib import Path
+
+from .cli import prompt_choice
+
+
+def install_bin(name: str, install_options: list[str]) -> bool:
+    cmd = prompt_choice(
+        f"How would you like to install {name}?",
+        install_options
+    )
+    div_start = f"{'-' * 29} INSTALL START {'-' * 29}"
+    div_end = f"{'-' * 30} INSTALL END {'-' * 30}"
+    try:
+        print(f"Installing {name} via `{cmd}`")
+        print('\n' + div_start)
+        subprocess.run(shlex.split(cmd), check=True)
+        print(div_end + '\n')
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"Failed to install {name}: {e}")
+        print(div_end + '\n')
+        return False
+    
+
+def verify_bin(bin_path: Path) -> bool:
+    try:
+        result = subprocess.run(
+            [str(bin_path), "--version"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            check=False
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.SubprocessError) as e:
+        print(e)
+        return False

synth_ai/utils/claude.py

@@ -0,0 +1,36 @@
+import platform
+from dataclasses import dataclass
+from pathlib import Path
+
+from .json import create_and_write_json, load_json_to_dict
+
+
+@dataclass
+class ClaudeConfig:
+    config_path: Path
+    server_name: str = "synth-ai"
+    cmd: str = "python"
+    args: tuple[str, ...] = ("-m", "synth_ai.mcp")
+    
+    @staticmethod
+    def get_default_config_path() -> Path:
+        system = platform.system()
+        if system == "Darwin":
+            return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
+        return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+    
+    def update_mcp_config(self) -> None:
+        print("Adding Synth AI to your Claude MCP config")
+        config = load_json_to_dict(self.config_path)
+        if not isinstance(config, dict):
+            config = {}
+        servers = config.setdefault("mcpServers", {})
+        if not isinstance(servers, dict):
+            servers = {}
+            config["mcpServers"] = servers
+        servers[self.server_name] = {
+            "command": self.cmd,
+            "args": list(self.args)
+        }
+        create_and_write_json(self.config_path, config)
+        print("Adding Synth AI to your Claude MCP config at", self.config_path)

synth_ai/utils/cli.py

@@ -0,0 +1,284 @@
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Callable, cast
+
+import click
+
+
+def prompt_choice(msg: str, choices: list[str]) -> str:
+    print(msg)
+    for i, label in enumerate(choices, start=1):
+        print(f" [{i}] {label}")
+    while True:
+        try:
+            choice = click.prompt(
+                "Select an option",
+                default=1,
+                type=int,
+                show_choices=False
+            )
+        except click.Abort:
+            raise
+        if 1 <= choice <= len(choices):
+            return choices[choice - 1]
+        print(f"Invalid selection. Enter a number between 1 and {len(choices)}")
+
+
+class PromptedChoiceType(click.Choice):
+    """`click.Choice` variant that reprompts with an interactive menu on failure.
+
+    Example
+    -------
+    ```python
+    import click
+
+    from synth_ai.utils.cli import PromptedChoiceType, PromptedChoiceOption
+
+
+    @click.command()
+    @click.option(
+        "--mode",
+        cls=PromptedChoiceOption,
+        type=PromptedChoiceType(["sft", "rl"]),
+        required=True,
+    )
+    def train(mode: str) -> None:
+        click.echo(f"Selected mode: {mode}")
+    ```
+    """
+
+    def convert(
+        self,
+        value: Any,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> str:
+        """Validate *value*; prompt for a replacement when it is missing or invalid."""
+        if param is None:
+            raise RuntimeError("Invalid parameter")
+        if ctx is None:
+            raise RuntimeError("Invalid context")
+        if value in (None, ""):
+            return self._prompt_user(param, ctx)
+        try:
+            return super().convert(value, param, ctx)
+        except click.BadParameter:
+            cmd_name = self._get_cmd_name(ctx)
+            if getattr(param, "opts", None):
+                click.echo(f'\n[{cmd_name}] Invalid value "{value}" for {self._get_arg_name(param)}')
+            else:
+                click.echo(f'\n[{cmd_name}] Invalid value "{value}"')
+            return self._prompt_user(param, ctx)
+
+    def _prompt_user(
+        self,
+        param: click.Parameter,
+        ctx: click.Context | None,
+    ) -> str:
+        """Render a numbered picker and return the user’s selection."""
+        arg_name = self._get_arg_name(param)
+        click.echo(f"\n[{self._get_cmd_name(ctx)}] Please choose a value for {arg_name}")
+        for index, choice in enumerate(self.choices, 1):
+            click.echo(f" [{index}] {choice}")
+        while True:
+            choice = click.prompt(
+                "Select an option",
+                default=1,
+                type=int,
+                show_choices=False
+            )
+            if 1 <= choice <= len(self.choices):
+                print('')
+                return cast(str, self.choices[choice - 1])
+            click.echo(f"Invalid selection for {arg_name}, please try again")
+
+    def _get_cmd_name(self, ctx: click.Context | None) -> str:
+        """Safely extract the current command name for diagnostic output."""
+        cmd = getattr(ctx, "command", None) if ctx is not None else None
+        if cmd is None:
+            return "?"
+        name = getattr(cmd, "name", None)
+        return name or "?"
+
+    def _get_arg_name(self, param: click.Parameter) -> str:
+        """Return the most human-friendly identifier for the parameter."""
+        opts = getattr(param, "opts", None)
+        if opts:
+            return opts[-1]
+        name = getattr(param, "name", None)
+        if name:
+            return name
+        human_name = getattr(param, "human_readable_name", None)
+        if human_name:
+            return human_name
+        return "?"
+
+
+class PromptedChoiceOption(click.Option):
+    """`click.Option` subclass that triggers the interactive picker when missing.
+
+    Example
+    -------
+    ```python
+    import click
+
+    from synth_ai.utils.cli import PromptedChoiceType, PromptedChoiceOption
+
+
+    @click.command()
+    @click.option(
+        "--mode",
+        cls=PromptedChoiceOption,
+        type=PromptedChoiceType(["sft", "rl"]),
+        required=True,
+    )
+    def train(mode: str) -> None:
+        click.echo(f"Selected mode: {mode}")
+    ```
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("prompt", True)
+        kwargs.setdefault("prompt_required", True)
+        super().__init__(*args, **kwargs)
+
+    def prompt_for_value(self, ctx: click.Context) -> Any:
+        """Invoke the choice picker when the option was omitted."""
+        option_type = getattr(self, "type", None)
+        if isinstance(option_type, PromptedChoiceType):
+            return option_type._prompt_user(self, ctx)
+        return super().prompt_for_value(ctx)
+
+
+def prompt_for_path(
+    label: str,
+    *,
+    available_paths: Sequence[str | Path] | None = None,
+    file_type: str | None = None,
+    path_type: click.Path | None = None,
+) -> Path:
+    """Prompt for a filesystem path, optionally offering curated choices."""
+
+    def _normalize_suffix(ext: str | None) -> str | None:
+        if not ext:
+            return None
+        stripped = ext.strip()
+        if not stripped:
+            return None
+        if not stripped.startswith("."):
+            stripped = f".{stripped}"
+        return stripped.lower()
+
+    def _format_label(text: str) -> str:
+        return text.strip() or "path"
+
+    expected_suffix = _normalize_suffix(file_type)
+    prompt_label = _format_label(label)
+
+    path_type = path_type or click.Path(
+        exists=True,
+        dir_okay=False,
+        file_okay=True,
+        path_type=Path,
+    )
+
+    candidates: list[str] = []
+    if available_paths:
+        seen: set[str] = set()
+        for entry in available_paths:
+            candidate = str(Path(entry))
+            suffix = Path(candidate).suffix.lower()
+            if candidate in seen:
+                continue
+            if expected_suffix and suffix != expected_suffix:
+                continue
+            seen.add(candidate)
+            candidates.append(candidate)
+
+    ctx = click.get_current_context(silent=True)
+
+    while True:
+        if candidates:
+            click.echo(f"\nPlease choose a {prompt_label}:")
+            for index, option in enumerate(candidates, 1):
+                click.echo(f" [{index}] {option}")
+            custom_index = len(candidates) + 1
+            click.echo(f" [{custom_index}] Enter a custom path")
+
+            selection = click.prompt("> ", type=int)
+            if 1 <= selection <= len(candidates):
+                raw_value = candidates[selection - 1]
+            elif selection == custom_index:
+                raw_value = click.prompt(prompt_label, type=path_type)
+            else:
+                click.echo("Invalid selection, please try again")
+                continue
+        else:
+            raw_value = click.prompt(prompt_label, type=path_type)
+
+        try:
+            converted = path_type.convert(str(raw_value), None, ctx)
+        except click.BadParameter as exc:
+            click.echo(str(exc))
+            continue
+
+        result = converted if isinstance(converted, Path) else Path(converted)
+        if expected_suffix and result.suffix.lower() != expected_suffix:
+            click.echo(f"Expected a {expected_suffix} file. Received: {result}")
+            continue
+        
+        return result
+
+
+class PromptedPathOption(click.Option):
+    """Option that prompts for a filesystem path when omitted."""
+
+    def __init__(
+        self,
+        *args: Any,
+        available_paths: Sequence[str | Path] | Callable[[], Sequence[str | Path]] | None = None,
+        file_type: str | None = None,
+        path_type: click.Path | None = None,
+        prompt_guard: Callable[[click.Context], bool] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._available_paths = available_paths
+        self._file_type = file_type
+        self._path_type = path_type
+        self._prompt_guard = prompt_guard
+        kwargs.setdefault("prompt", True)
+        kwargs.setdefault("prompt_required", True)
+        super().__init__(*args, **kwargs)
+
+    def _resolve_available_paths(self) -> Sequence[str | Path] | None:
+        if callable(self._available_paths):
+            try:
+                return self._available_paths()
+            except Exception:
+                return None
+        return self._available_paths
+
+    def prompt_for_value(self, ctx: click.Context) -> Any:
+        if not ctx:
+            return super().prompt_for_value(ctx)
+        if self._prompt_guard is not None:
+            try:
+                if not self._prompt_guard(ctx):
+                    return None
+            except Exception:
+                return None
+        label = self.help or self.name or "path"
+        available_paths = self._resolve_available_paths()
+        return prompt_for_path(
+            label,
+            available_paths=available_paths,
+            file_type=self._file_type,
+            path_type=self._path_type or getattr(self, "type", None),
+        )
+
+
+def print_next_step(message: str, lines: Sequence[str]) -> None:
+    print(f"\n➡️  Next, {message}:")
+    for line in lines:
+        print(f"   {line}")
+    print("")

synth_ai/utils/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Optional, overload
+
+import click
+
+from .errors import get_required_value
+
+
+class ConfigResolver:
+    """Resolve configuration values with consistent precedence and messaging."""
+
+    @overload
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = False,
+        docs_url: Optional[str] = None,
+    ) -> Optional[str]: ...
+
+    @overload
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = True,
+        docs_url: Optional[str] = None,
+    ) -> str: ...
+
+    @staticmethod
+    def resolve(
+        name: str,
+        *,
+        cli_value: Optional[str] = None,
+        env_value: Optional[str] = None,
+        config_value: Optional[str] = None,
+        default: Optional[str] = None,
+        required: bool = False,
+        docs_url: Optional[str] = None,
+    ) -> Optional[str]:
+        """Resolve value with CLI > ENV > CONFIG > DEFAULT precedence."""
+
+        def _clean(value: Optional[str]) -> Optional[str]:
+            if value is None:
+                return None
+            stripped = value.strip()
+            return stripped if stripped else None
+
+        cli_clean = _clean(cli_value)
+        env_clean = _clean(env_value)
+        config_clean = _clean(config_value)
+        default_clean = _clean(default)
+
+        if cli_clean and config_clean and cli_clean != config_clean:
+            click.secho(
+                f"⚠️  {name}: CLI flag overrides config file "
+                f"(using {cli_clean}, ignoring {config_clean})",
+                err=True,
+                fg="yellow",
+            )
+
+        resolved = cli_clean or env_clean or config_clean or default_clean
+        if required:
+            return get_required_value(
+                name,
+                cli_value=cli_clean,
+                env_value=env_clean,
+                config_value=config_clean,
+                default=default_clean,
+                docs_url=docs_url,
+            )
+        return resolved