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

synth_ai/cli/traces.py

@@ -11,7 +11,7 @@ from rich import box
 from rich.console import Console
 from rich.table import Table
 
-from synth_ai.cli._storage import load_storage
+from ._storage import load_storage
 
 
 def register(cli):

synth_ai/cli/train/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .core import register, train_command
+from .errors import TrainCliError
+from .validation import validate_train_environment
+
+__all__ = [
+    "register",
+    "train_command",
+    "TrainCliError",
+    "validate_train_environment",
+]

synth_ai/cli/train/core.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import click
+from synth_ai.api.train.cli import (
+    register as _register_with_cli,
+)
+from synth_ai.api.train.cli import (
+    train_command as _train_command,
+)
+
+__all__ = ["register", "train_command"]
+
+
+def register(cli: click.Group) -> None:
+    """Attach the train command to the root CLI."""
+    _register_with_cli(cli)
+
+
+def train_command(*args, **kwargs):
+    """Entrypoint used by the train CLI command."""
+    return _train_command(*args, **kwargs)

synth_ai/cli/train/errors.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+
+class TrainCliError(RuntimeError):
+    """Base exception for train CLI failures."""
+
+
+__all__ = ["TrainCliError"]

synth_ai/cli/train/validation.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Dict, Tuple
+
+from synth_ai.api.train.env_resolver import KeySpec, resolve_env
+
+__all__ = ["validate_train_environment"]
+
+
+def validate_train_environment(
+    *,
+    config_path: Path | None,
+    explicit_env_paths: Iterable[str],
+    required_keys: list[KeySpec],
+) -> Tuple[Path, Dict[str, str]]:
+    """Validate and resolve environment secrets used by the train command."""
+    resolved_path, resolved_keys = resolve_env(
+        config_path=config_path,
+        explicit_env_paths=explicit_env_paths,
+        required_keys=required_keys,
+    )
+    return resolved_path, resolved_keys

synth_ai/cli/train.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from synth_ai.cli.commands.train.core import register, train_command
+
+__all__ = ["register", "train_command"]

synth_ai/cli/turso.py

@@ -6,7 +6,7 @@ import subprocess
 
 import click
 
-from synth_ai.cli.root import SQLD_VERSION, find_sqld_binary, install_sqld
+from .root import SQLD_VERSION, find_sqld_binary, install_sqld
 
 
 def register(cli: click.Group) -> None:

synth_ai/cli/watch.py

@@ -16,7 +16,7 @@ from rich.console import Console, Group
 from rich.panel import Panel
 from rich.table import Table
 
-from synth_ai.cli._storage import load_storage
+from ._storage import load_storage
 
 
 def _open_db(db_url: str):

synth_ai/demos/__init__.py

@@ -0,0 +1,10 @@
+"""Namespace for demo task apps (math, crafter, etc.)."""
+
+import contextlib
+
+# Ensure registry entries are loaded for CLI discovery.
+with contextlib.suppress(Exception):  # pragma: no cover - optional on downstream installs
+    from synth_ai.demos.math import task_app_entry  # noqa: F401
+
+with contextlib.suppress(Exception):  # pragma: no cover - optional on downstream installs
+    from synth_ai.demos.crafter import grpo_crafter_task_app  # noqa: F401

synth_ai/demos/core/__init__.py

@@ -1 +1,28 @@
-# Core demo CLI and helpers package
+"""
+Compatibility layer exposing the legacy demo helpers.
+
+Historically these utilities lived in ``synth_ai.demos.core`` as a module.
+Upstream refactors moved the implementation under
+``synth_ai.demos.demo_task_apps.core``.  Several call sites (including the new
+vision tests) still import the older path, so we re-export everything here.
+"""
+
+from __future__ import annotations
+
+from synth_ai.demos.demo_task_apps import core as _demo_core
+
+__all__ = [
+    name
+    for name in dir(_demo_core)
+    if not name.startswith("_")
+]
+
+globals().update({name: getattr(_demo_core, name) for name in __all__})
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        value = getattr(_demo_core, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(name)

synth_ai/demos/crafter/__init__.py

@@ -0,0 +1 @@
+# Crafter demo task app

synth_ai/demos/crafter/crafter_fft_4b.toml

@@ -0,0 +1,55 @@
+# FFT job config for Qwen/Qwen3-4B on Crafter SFT dataset
+
+type = "sft"
+
+[algorithm]
+type = "offline"
+method = "supervised_finetune"
+variety = "fft"
+
+
+[job]
+model = "Qwen/Qwen3-4B"
+data = "ft_data/crafter_sft.jsonl"
+
+[compute]
+# Adjust as needed for your quota
+gpu_type = "H100"
+gpu_count = 1
+nodes = 1
+
+[data]
+# Optional topology metadata (left empty for now)
+topology = {}
+
+# Optional local validation dataset path (JSONL). If set, the client will upload
+# this file and wire up validation so the frontend can display val.loss.
+# validation_path = "../ft_data/crafter_validation.jsonl"
+
+[training]
+mode = "sft_offline"
+use_qlora = false
+
+# Validation settings to emit val.loss on the frontend
+[training.validation]
+enabled = true
+evaluation_strategy = "steps"
+eval_steps = 20
+save_best_model_at_end = true
+metric_for_best_model = "val.loss"
+greater_is_better = false
+
+[hyperparameters]
+# Minimal safe defaults; backend can override
+n_epochs = 1
+batch_size = 1
+gradient_accumulation_steps = 64
+sequence_length = 4096
+learning_rate = 5e-6
+warmup_ratio = 0.03
+train_kind = "fft"
+
+# Optional parallelism block example
+#[hyperparameters.parallelism]
+# tensor_parallel_size = 1
+# pipeline_parallel_size = 1

synth_ai/demos/crafter/grpo_crafter_task_app.py

@@ -0,0 +1,185 @@
+"""Compatibility wrapper for the GRPO Crafter task app.
+
+This module now delegates to the TaskAppConfig defined in the local example at
+`examples/warming_up_to_rl/task_app/grpo_crafter.py`. It is kept for legacy usage
+(running the file directly or targeting `fastapi_app` from external tooling).
+Prefer using `uvx synth-ai deploy --runtime uvicorn grpo-crafter` for local development and testing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+from contextlib import suppress
+from pathlib import Path
+
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.requests import Request
+from synth_ai.task.apps import ModalDeploymentConfig, TaskAppEntry, registry
+from synth_ai.task.auth import is_api_key_header_authorized, normalize_environment_api_key
+from synth_ai.task.server import TaskAppConfig, create_task_app, run_task_app
+
+
+def _load_build_config():
+    import synth_ai
+
+    synth_ai_path = Path(synth_ai.__file__).resolve().parent.parent
+    module_path = synth_ai_path / "examples" / "warming_up_to_rl" / "task_app" / "grpo_crafter.py"
+
+    if not module_path.exists():
+        raise ImportError(
+            f"Could not find task app module at {module_path}. Make sure you're running from the synth-ai repository."
+        )
+
+    spec = importlib.util.spec_from_file_location(
+        "warming_up_to_rl.task_app.grpo_crafter", module_path
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load task app module at {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    import sys
+
+    sys.modules.setdefault(spec.name, module)
+
+    from synth_ai.task import apps as task_apps
+
+    original_register = task_apps.registry.register
+
+    def _safe_register(entry):
+        with suppress(ValueError):
+            original_register(entry)
+
+    task_apps.registry.register = _safe_register
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        task_apps.registry.register = original_register
+    return module.build_config
+
+
+build_config = _load_build_config()
+
+
+APP_ID = "grpo-crafter"
+
+
+def _build_base_config() -> TaskAppConfig:
+    return build_config()
+
+
+try:
+    _REGISTERED_ENTRY = registry.get(APP_ID)
+except Exception:  # pragma: no cover - registry unavailable in some contexts
+    MODAL_DEPLOYMENT: ModalDeploymentConfig | None = None
+else:
+    MODAL_DEPLOYMENT = _REGISTERED_ENTRY.modal
+
+
+def build_task_app_config() -> TaskAppConfig:
+    base = _build_base_config()
+    return base.clone()
+
+
+def fastapi_app():
+    app = create_task_app(build_task_app_config())
+
+    filtered_routes = []
+    for route in app.router.routes:
+        path = getattr(route, "path", None)
+        methods = getattr(route, "methods", set()) or set()
+        if path in {"/health", "/health/rollout"} and "GET" in methods:
+            continue
+        filtered_routes.append(route)
+    app.router.routes = filtered_routes
+
+    def _log_env_key_prefix(source: str, env_key: str | None) -> str | None:
+        if not env_key:
+            return None
+        prefix = env_key[: max(1, len(env_key) // 2)]
+        print(f"[{source}] expected ENVIRONMENT_API_KEY prefix: {prefix}")
+        return prefix
+
+    @app.get("/health")
+    async def health(request: Request):
+        env_key = normalize_environment_api_key()
+        if not env_key:
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "detail": "Missing ENVIRONMENT_API_KEY"},
+            )
+        if not is_api_key_header_authorized(request):
+            prefix = _log_env_key_prefix("health", env_key)
+            content = {"status": "healthy", "authorized": False}
+            if prefix:
+                content["expected_api_key_prefix"] = prefix
+            return JSONResponse(status_code=200, content=content)
+        return {"status": "healthy", "authorized": True}
+
+    @app.get("/health/rollout")
+    async def health_rollout(request: Request):
+        env_key = normalize_environment_api_key()
+        if not env_key:
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "detail": "Missing ENVIRONMENT_API_KEY"},
+            )
+        if not is_api_key_header_authorized(request):
+            prefix = _log_env_key_prefix("health/rollout", env_key)
+            content = {"status": "healthy", "authorized": False}
+            if prefix:
+                content["expected_api_key_prefix"] = prefix
+            return JSONResponse(status_code=200, content=content)
+        return {"ok": True, "authorized": True}
+
+    @app.exception_handler(RequestValidationError)
+    async def _on_validation_error(request: Request, exc: RequestValidationError):
+        try:
+            hdr = request.headers
+            snapshot = {
+                "path": str(request.url.path),
+                "have_x_api_key": bool(hdr.get("x-api-key")),
+                "have_x_api_keys": bool(hdr.get("x-api-keys")),
+                "have_authorization": bool(hdr.get("authorization")),
+                "errors": exc.errors()[:5],
+            }
+            print("[422] validation", snapshot, flush=True)
+        except Exception:
+            pass
+        return JSONResponse(
+            status_code=422,
+            content={"status": "invalid", "detail": exc.errors()[:5]},
+        )
+
+    return app
+
+
+def register_demo_entry() -> None:
+    description = "Crafter demo task app"
+    entry = TaskAppEntry(
+        app_id="crafter-demo",
+        description=description,
+        config_factory=build_task_app_config,
+        aliases=("crafter",),
+        modal=MODAL_DEPLOYMENT,
+    )
+    with suppress(ValueError):
+        registry.register(entry)
+
+
+register_demo_entry()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run the Crafter task app locally")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8001)
+    parser.add_argument("--reload", action="store_true", help="Enable uvicorn autoreload")
+    args = parser.parse_args()
+
+    run_task_app(
+        build_task_app_config,
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )

synth_ai/demos/crafter/rl_from_base_qwen4b.toml

@@ -0,0 +1,74 @@
+# RL training starting from base Qwen/Qwen3-4B (TOML-only model selection)
+
+type = "rl"
+
+[algorithm]
+type = "online"
+method = "policy_gradient"
+variety = "gspo"
+
+[services]
+task_url = "https://synth-laboratories--grpo-crafter-task-app-final-warming--ceb5b2.modal.run"
+
+[compute]
+# Cluster shape for RL pipeline
+gpu_type = "H100"
+gpu_count = 8
+
+[topology]
+# Split GPUs across vLLM, training, and reference
+# Must sum to compute.gpu_count
+type = "single_node_split"
+gpus_for_vllm = 4
+gpus_for_training = 3
+gpus_for_ref = 1
+tensor_parallel = 4
+
+[vllm]
+# Serving tensor parallel size
+tensor_parallel_size = 4
+max_model_len = 8192
+
+[reference]
+# Required by trainer/runtime; ensures dedicated/scoped scoring server config exists
+placement = "dedicated"
+port = 8002
+tp = 1
+health_max_wait_s = 180
+health_interval_ms = 300
+
+[model]
+# Base model start
+base = "Qwen/Qwen3-4B"
+label = "crafter-rl-from-base"
+
+[rollout]
+max_turns = 10
+episodes_per_batch = 64
+policy_name = "crafter"
+
+[evaluation]
+# Run baseline evaluation over the first 100 seeds every 20 training iterations
+instances = 10
+every_n_iters = 10
+seeds = [
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+]
+
+[training]
+log_interval = 1
+weight_sync_interval = 1
+# Additional RL hyperparameters can go here
+
+# Stepwise rewards (Crafter decision-level)
+step_rewards_enabled = true
+step_rewards_mode = "decision_stepwise"  # "off" | "decision_stepwise" | "env_sparse"
+step_rewards_beta = 0.0
+step_rewards_indicator_lambda = 1.0
+# Optional selector for decision scalar: "unique" | "absolute" (default unique)
+event_rewards_kind = "unique"
+
+[training.weight_sync]
+enable  = true
+targets = ["policy"]
+weight_sync_interval = 1

synth_ai/demos/demo_registry.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+@dataclass(slots=True)
+class CopySpec:
+    source: str
+    destination: str
+    make_executable: bool = False
+
+    def absolute_source(self) -> Path:
+        return (REPO_ROOT / self.source).resolve()
+
+
+@dataclass(slots=True)
+class DemoTemplate:
+    template_id: str
+    name: str
+    description: str
+    copy_specs: tuple[CopySpec, ...]
+    default_subdir: str | None = None
+    env_lines: tuple[str, ...] = ()
+    config_source: str | None = None
+    config_destination: str = "demo_config.toml"
+    requires_modal: bool = False
+    post_copy: Callable[[Path], None] | None = None
+    default_secret_name: str | None = None
+
+    def iter_copy_specs(self) -> Iterator[CopySpec]:
+        yield from self.copy_specs
+
+    def config_source_path(self) -> Path | None:
+        if not self.config_source:
+            return None
+        return (REPO_ROOT / self.config_source).resolve()
+
+
+def _postprocess_math_modal(root: Path) -> None:
+    task_path = (root / "task_app.py").resolve()
+    if not task_path.exists():
+        return
+    text = task_path.read_text(encoding="utf-8")
+    text = text.replace('App("hendrycks-math-task-app")', 'App("hendrycks-math-task-app-demo")')
+    text = text.replace(
+        'DEFAULT_TASK_APP_SECRET_NAME = "hendrycks-math-task-app-secret"',
+        'DEFAULT_TASK_APP_SECRET_NAME = "hendrycks-math-task-app-demo-secret"',
+    )
+    task_path.write_text(text, encoding="utf-8")
+
+    deploy_script = root / "deploy_task_app.sh"
+    if deploy_script.exists():
+        import stat
+
+        mode = deploy_script.stat().st_mode
+        deploy_script.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+DEMO_TEMPLATES: dict[str, DemoTemplate] = {
+    "math-modal": DemoTemplate(
+        template_id="math-modal",
+        name="Math Single-Step (Modal deployment)",
+        description="Packaged modal task app matching examples/rl math environment.",
+        copy_specs=(
+            CopySpec(
+                "synth_ai/demos/math/modal_task_app.py",
+                "task_app.py",
+            ),
+            CopySpec(
+                "synth_ai/demos/math/README.md",
+                "README.md",
+            ),
+            CopySpec(
+                "synth_ai/demos/math/deploy_task_app.sh",
+                "deploy_task_app.sh",
+                make_executable=True,
+            ),
+            CopySpec(
+                "synth_ai/demos/math/config.toml",
+                "configs/rl_from_base_qwen17.toml",
+            ),
+        ),
+        default_subdir="math_demo",
+        env_lines=(
+            "# Required for task app auth to environment service",
+            "ENVIRONMENT_API_KEY=",
+            "",
+            "# Optional: for CLI job submission and proxying OpenAI models",
+            "SYNTH_API_KEY=",
+            "OPENAI_API_KEY=",
+            "",
+            "# Optional: set to 'prod' to use production names",
+            "ENVIRONMENT=",
+        ),
+        config_source="synth_ai/demos/math/config.toml",
+        requires_modal=True,
+        post_copy=lambda root: _postprocess_math_modal(root),
+        default_secret_name="hendrycks-math-task-app-demo-secret",
+    ),
+    "crafter-local": DemoTemplate(
+        template_id="crafter-local",
+        name="Crafter GRPO (local FastAPI)",
+        description="Lightweight wrapper around examples/warming_up_to_rl/task_app/grpo_crafter for local experimentation.",
+        copy_specs=(
+            CopySpec(
+                "synth_ai/demos/crafter/grpo_crafter_task_app.py",
+                "task_app.py",
+            ),
+            CopySpec(
+                "synth_ai/demos/crafter/README.md",
+                "README.md",
+            ),
+            CopySpec(
+                "synth_ai/demos/crafter/configs/rl_from_base_qwen4b.toml",
+                "configs/rl_from_base_qwen4b.toml",
+            ),
+            CopySpec(
+                "synth_ai/demos/crafter/configs/crafter_fft_4b.toml",
+                "configs/crafter_fft_4b.toml",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/task_app/grpo_crafter.py",
+                "grpo_crafter.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/task_app/synth_envs_hosted",
+                "synth_envs_hosted",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/run_local_rollout.py",
+                "run_local_rollout.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/run_local_rollout_traced.py",
+                "run_local_rollout_traced.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/shared.py",
+                "shared.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/export_trace_sft.py",
+                "export_trace_sft.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/run_fft_and_save.py",
+                "run_fft_and_save.py",
+            ),
+            CopySpec(
+                "examples/warming_up_to_rl/run_local_rollout_modal.py",
+                "run_local_rollout_modal.py",
+            ),
+        ),
+        default_subdir="crafter_demo",
+        env_lines=(
+            "ENVIRONMENT_API_KEY=",
+            "SYNTH_API_KEY=",
+            "",
+            "# Optional: URL for existing Crafter task app",
+            "TASK_APP_BASE_URL=",
+        ),
+        default_secret_name="grpo-crafter-demo-secret",
+    ),
+}
+
+
+def list_demo_templates() -> tuple[DemoTemplate, ...]:
+    return tuple(DEMO_TEMPLATES.values())
+
+
+def get_demo_template(template_id: str) -> DemoTemplate | None:
+    return DEMO_TEMPLATES.get(template_id)

synth_ai/demos/demo_task_apps/crafter/grpo_crafter_task_app.py

@@ -3,7 +3,7 @@
 This module now delegates to the TaskAppConfig defined in the local example at
 `examples/task_apps/crafter/task_app/grpo_crafter.py`. It is kept for legacy usage
 (running the file directly or targeting `fastapi_app` from external tooling).
-Prefer using `uvx synth-ai serve grpo-crafter` for local development and testing.
+Prefer using `uvx synth-ai deploy --runtime uvicorn grpo-crafter` for local development and testing.
 """
 
 from __future__ import annotations

synth_ai/demos/math/__init__.py

@@ -0,0 +1 @@
+# Package namespace for Math demo task app

synth_ai/demos/math/_common.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+"""Minimal helpers for the math task app.
+
+This module provides a local fallback for install_problem_bank_into_shared so
+the modal task app can import it without requiring an external math_rl package.
+"""
+
+
+def install_problem_bank_into_shared() -> None:
+    """No-op placeholder for installing the Hendrycks MATH problem bank.
+
+    In production deployments, this can download or unpack the problem bank
+    into a shared directory. For the demo scaffold, it is a no-op.
+    """
+    return None