synth-ai 0.2.13.dev2__py3-none-any.whl → 0.2.16__py3-none-any.whl

synth_ai/cli/train.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+from synth_ai.api.train.cli import register as _register
+from synth_ai.api.train.cli import train_command as _train_command
+
+__all__ = ["register", "train_command"]
+
+
+def register(cli: Any) -> None:
+    """Compatibility wrapper for the legacy train CLI location."""
+
+    _register(cli)
+
+
+def train_command(*args: Any, **kwargs: Any) -> Any:
+    return _train_command(*args, **kwargs)

synth_ai/cli/tui.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""
+CLI: Interactive TUI dashboard for Synth AI.
+"""
+
+import importlib
+import os
+
+import click
+from rich.console import Console
+
+
+def register(cli):
+    @cli.command()
+    @click.option(
+        "--url",
+        "db_url",
+        default="sqlite+libsql://http://127.0.0.1:8080",
+        help="Database URL (default: sqlite+libsql://http://127.0.0.1:8080)",
+    )
+    @click.option("--debug", is_flag=True, help="Enable debug logging")
+    def tui(db_url: str, debug: bool):
+        """Launch interactive TUI dashboard showing experiments, balance, and active runs."""
+        console = Console()
+
+        # Import here to avoid circular imports and handle optional dependencies
+        try:
+            module = importlib.import_module("synth_ai.tui.dashboard")
+        except (ImportError, ModuleNotFoundError) as e:
+            console.print("[red]Error:[/red] TUI dashboard not available.")
+            console.print(f"Missing dependencies: {e}")
+            console.print("Install with: pip install textual")
+            return
+        except Exception:
+            # Handle other import errors (like missing libsql, type annotation issues, etc.)
+            console.print("[red]Error:[/red] TUI dashboard not available.")
+            console.print("This may be due to missing dependencies or Python version compatibility.")
+            console.print("Try: pip install textual libsql")
+            console.print("If using Python < 3.10, you may need to update Python or install eval_type_backport.")
+            return
+        tui_main = getattr(module, "main", None)
+        if not callable(tui_main):
+            console.print("[red]Error:[/red] TUI dashboard entrypoint not available.")
+            return
+
+        # Set environment variables for the TUI to use
+        os.environ.setdefault("TUI_DB_URL", db_url)
+        if debug:
+            os.environ["TUI_DEBUG"] = "1"
+
+        # Run the TUI by calling the module directly with sanitized argv
+        try:
+            tui_args = ["--url", db_url]
+            if debug:
+                tui_args.append("--debug")
+            tui_main(tui_args)
+        except KeyboardInterrupt:
+            console.print("\n[blue]TUI closed.[/blue]")
+        except Exception as e:
+            console.print(f"\n[red]Error running TUI:[/red] {e}")
+            if debug:
+                raise

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 serve 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

@@ -57,7 +57,7 @@ def _load_build_config():
 build_config = _load_build_config()
 
 
-APP_ID = "grpo-crafter"
+APP_ID = "grpo-crafter-task-app"
 
 
 def _build_base_config() -> TaskAppConfig:

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

synth_ai/demos/math/app.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+# Reuse the examples/rl task_app routes if available
+try:
+    from synth_ai.examples.rl.task_app import make_app as make_rl_app  # type: ignore
+except Exception:  # fallback path when imported from repo root
+    try:
+        from examples.rl.task_app import make_app as make_rl_app  # type: ignore
+    except Exception as e:  # pragma: no cover
+        raise ImportError(f"Unable to import RL task app: {e}") from e
+
+
+def create_app() -> FastAPI:
+    # Configure math defaults via env (consumed by RL task_app helpers)
+    os.environ.setdefault("DEMO_ENV_NAME", "math")
+    os.environ.setdefault("DEMO_POLICY_NAME", "math-react")
+    # Build base app
+    app = make_rl_app()
+    # CORS for local demo
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    return app
+
+
+def run(host: str = "127.0.0.1", port: int = 8080):
+    import uvicorn
+
+    uvicorn.run(create_app(), host=host, port=int(os.getenv("PORT", port)))