synth-ai 0.2.9.dev11__py3-none-any.whl → 0.4.1__py3-none-any.whl

examples/rl/task_app/math_task_app.py

@@ -1,115 +0,0 @@
-"""Legacy entrypoint for the math single-step task app."""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from fastapi.exceptions import RequestValidationError
-from fastapi.responses import JSONResponse
-from starlette.requests import Request
-from synth_ai.task.auth import is_api_key_header_authorized, normalize_environment_api_key
-from synth_ai.task.server import create_task_app, run_task_app
-
-from .math_single_step import build_config
-
-
-def fastapi_app():
-    """Return a FastAPI application for hosting the math task app."""
-
-    app = create_task_app(build_config())
-
-    # Replace default health endpoints with auth-tolerant handlers.
-    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
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Run the math single-step task app locally")
-    parser.add_argument("--host", default="0.0.0.0")
-    parser.add_argument("--port", type=int, default=8101)
-    parser.add_argument("--reload", action="store_true", help="Enable uvicorn autoreload")
-    parser.add_argument(
-        "--env-file",
-        action="append",
-        default=[],
-        help="Additional .env files to load before startup",
-    )
-    args = parser.parse_args()
-
-    default_env = Path(__file__).resolve().parents[2] / ".env"
-    env_files = [str(default_env)] if default_env.exists() else []
-    env_files.extend(args.env_file or [])
-
-    run_task_app(
-        build_config,
-        host=args.host,
-        port=args.port,
-        reload=args.reload,
-        env_files=env_files,
-    )

examples/run_crafter_demo.sh

@@ -1,10 +0,0 @@
-#!/bin/bash
-
-# Run a Crafter agent demo with Gemini
-# This script demonstrates a reactive agent in the Crafter environment
-
-echo "🚀 Starting Crafter agent demo with Gemini 1.5 Flash..."
-echo "Make sure the synth-ai service is running: uvx synth-ai serve"
-echo ""
-
-uv run python -m synth_ai.environments.examples.crafter_classic.agent_demos.test_crafter_react_agent --model gemini-1.5-flash

examples/sft/README.md

@@ -1,139 +0,0 @@
-### Supervised Fine-Tuning for Crafter
-
-This folder provides a minimal, reusable SFT workflow that pulls out the SFT step from `examples/warming_up_to_rl/` and focuses it on LoRA/QLoRA. We've also added guidance for running full finetuning (FFT) so you can compare adapters against end-to-end weight updates.
-
-It supports distilling Groq (or other vendor) rollouts into JSONL using tracing and then training a small base model like `Qwen/Qwen3-0.6B`.
-
----
-
-### 0) Load environment from .env.dev (recommended)
-
-Use your dev env file so keys/URLs are sourced consistently:
-
-```bash
-# Example path; update to your actual dev env
-set -a && source /Users/joshpurtell/Documents/GitHub/monorepo/backend/.env.dev && set +a
-```
-
-This ensures `ENVIRONMENT_API_KEY`, `GROQ_API_KEY`, and (optionally) `BACKEND_BASE_URL` are available to the steps below.
-
----
-
-### 1) Collect traces and export SFT JSONL
-
-You can generate traces with the Crafter task app and then export them to SFT JSONL using the existing exporter:
-
-```bash
-# Serve the task app locally with tracing enabled (example)
-uvx synth-ai serve grpo-crafter \
-  --trace traces/v3 \
-  --trace-db traces/v3/synth_ai.db \
-  --port 8001
-
-# Or run traced local rollouts to accumulate data
-uv run python examples/warming_up_to_rl/run_local_rollout_traced.py \
-  --episodes 50 --max-turns 10
-
-# Export SFT dataset from the trace DB
-uv run python examples/warming_up_to_rl/export_trace_sft.py \
-  --db traces/v3/synth_ai.db \
-  --min-unique 0 \
-  --output examples/sft/ft_data/crafter_traces.jsonl
-```
-
-Notes:
-- The exporter uses achievements and event rewards to filter high-signal steps. Combine `--min-unique`, `--min-outcome-reward`, `--event-reward`, and `--require-achievement` to control data quality.
-- You can restrict to sessions from certain providers/models with `--provider`/`--model`.
-- Use `--limit` while debugging to reduce dataset size quickly.
-
----
-
-### 2a) Train LoRA (QLoRA) on Qwen/Qwen3-0.6B
-
-Use the standard CLI. Do not use a custom Python finetuning script. Point the CLI at your `.env.dev` so it picks up keys automatically:
-
-```bash
-uvx synth-ai train \
-  --type sft \
-  --config examples/sft/configs/crafter_lora_qwen0p6b.toml \
-  --dataset examples/sft/ft_data/crafter_traces.jsonl \
-  --env-file /Users/joshpurtell/Documents/GitHub/monorepo/backend/.env.dev
-```
-
-The config sets `training.use_qlora = true` and `hyperparameters.train_kind = "peft"` to request LoRA adapters.
-
-Experiment tips:
-- The backend currently defaults to a LoRA rank of 16. If you need other ranks, generate the payload with `--dry-run`, add `"lora_rank": <value>` (and optional `"lora_alpha"`, `"lora_dropout"`) under `hyperparameters`, and submit it via the API until the CLI exposes these knobs directly.
-- Duplicate the TOML and adjust `hyperparameters.warmup_ratio`, `learning_rate`, or `gradient_accumulation_steps` to keep the global batch size comparable across datasets.
-
----
-
-### 2b) Train Full Finetune (FFT) on Qwen/Qwen3-0.6B
-
-Full finetuning updates all weights and uses a near-identical CLI flow with the LoRA toggle disabled. The helper config lives alongside the LoRA sample:
-
-```bash
-uvx synth-ai train \
-  --type sft \
-  --config examples/sft/configs/crafter_fft_qwen0p6b.toml \
-  --dataset examples/sft/ft_data/crafter_traces.jsonl \
-  --env-file /Users/joshpurtell/Documents/GitHub/monorepo/backend/.env.dev
-```
-
-Key differences vs LoRA:
-- `training.use_qlora = false` and `hyperparameters.train_kind = "fft"` request a full-weight update.
-- `per_device_batch` defaults to 1 to keep memory use comfortable on a single H100; raise gradually as you confirm headroom.
-- FFT runs slower per step. Consider trimming the dataset with `--examples` or the exporter filters for quick baselines.
-
-If you want the 4B Crafter FFT baseline from the RL examples, reuse `examples/warming_up_to_rl/configs/crafter_fft_4b.toml` with the same CLI command.
-
----
-
-### 3) Evaluate the fine-tuned models
-
-After the job completes, list your fine-tuned models and evaluate them in the Crafter loop:
-
-```bash
-# List models
-uv run python - <<'PY'
-import asyncio
-import os
-from synth_ai.learning.client import LearningClient
-
-backend = os.getenv("BACKEND_BASE_URL", "https://agent-learning.onrender.com/api")
-api_key = os.getenv("SYNTH_API_KEY", "")
-async def main():
-    client = LearningClient(backend, api_key)
-    models = await client.list_fine_tuned_models()
-    for m in models:
-        print(m)
-asyncio.run(main())
-PY
-
-# Evaluate in the Crafter eval loop (example via warming_up_to_rl)
-TASK_APP_URL=http://localhost:8001 \
-uv run python examples/warming_up_to_rl/run_eval.py \
-  --toml examples/warming_up_to_rl/configs/eval_local_vllm.toml \
-  --model ft:YOUR_FT_MODEL_ID \
-  --use-rollout
-```
-
----
-
-### 4) Plan comparison runs
-
-Keep runs comparable by adjusting one axis at a time and logging the settings in your experiment tracker (spreadsheet, weights & biases, etc.).
-
-- **LoRA rank sweeps:** start from `crafter_lora_qwen0p6b.toml`, clone it per rank (e.g., `r=4,8,16,64`). For now add the desired `lora_rank` in the job payload manually (see note above) and include it in the run name.
-- **Dataset size:** duplicate the exported JSONL and slice with `head -n`, or pass `--examples N` to the CLI for quick subsamples. Track the effective token count using the exporter logs.
-- **Data quality:** increase `--min-unique`, require specific achievements, or exclude low-reward sessions with `export_trace_sft.py`. Capture the filter tuple in your run metadata so evaluations stay reproducible.
-- **FFT vs LoRA:** run both configs on the same dataset/cardinality so differences reflect the training method rather than the data.
-
-For each sweep, use consistent evaluation seeds and write down throughput (tokens/sec) so you can weigh quality vs cost.
-
----
-
-### Files
-- `configs/crafter_lora_qwen0p6b.toml`: LoRA/QLoRA SFT config for `Qwen/Qwen3-0.6B`.
-- `configs/crafter_fft_qwen0p6b.toml`: Full-finetune SFT config for `Qwen/Qwen3-0.6B`.
-- `ft_data/`: place your exported JSONL here (ignored by VCS).

examples/sft/configs/crafter_fft_qwen0p6b.toml

@@ -1,44 +0,0 @@
-[job]
-model = "Qwen/Qwen3-0.6B"
-# Prefer passing --dataset at runtime for repeatability
-# data = "examples/sft/ft_data/crafter_traces.jsonl"
-
-[compute]
-gpu_type = "H100"
-gpu_count = 1
-nodes = 1
-
-[data]
-topology = {}
-# Optional validation set if you have one locally
-# validation_path = "examples/sft/ft_data/crafter_traces.val.jsonl"
-
-[training]
-mode = "sft_offline"
-use_qlora = false
-
-[training.validation]
-enabled = true
-evaluation_strategy = "steps"
-eval_steps = 50
-save_best_model_at_end = true
-metric_for_best_model = "val.loss"
-greater_is_better = false
-
-[hyperparameters]
-n_epochs = 1
-train_kind = "fft"
-per_device_batch = 1
-gradient_accumulation_steps = 32
-sequence_length = 4096
-learning_rate = 1e-5
-warmup_ratio = 0.03
-weight_decay = 0.01
-
-[hyperparameters.parallelism]
-use_deepspeed = true
-deepspeed_stage = 2
-fsdp = false
-bf16 = true
-fp16 = false
-activation_checkpointing = true

examples/sft/configs/crafter_lora_qwen0p6b.toml

@@ -1,45 +0,0 @@
-[job]
-model = "Qwen/Qwen3-0.6B"
-# Optionally set here, but prefer passing --dataset at runtime
-# data = "examples/sft/ft_data/crafter_traces.jsonl"
-
-[compute]
-gpu_type = "H100"
-gpu_count = 1
-nodes = 1
-
-[data]
-# Forwarded into metadata.effective_config
-topology = {}
-# Optional validation set if you have one locally
-# validation_path = "examples/sft/ft_data/crafter_traces.val.jsonl"
-
-[training]
-mode = "lora"
-use_qlora = true
-
-[training.validation]
-enabled = true
-evaluation_strategy = "steps"
-eval_steps = 50
-save_best_model_at_end = true
-metric_for_best_model = "val.loss"
-greater_is_better = false
-
-[hyperparameters]
-n_epochs = 1
-train_kind = "peft"
-per_device_batch = 2
-gradient_accumulation_steps = 32
-sequence_length = 4096
-learning_rate = 5e-6
-warmup_ratio = 0.03
-
-[hyperparameters.parallelism]
-use_deepspeed = true
-deepspeed_stage = 2
-fsdp = false
-bf16 = true
-fp16 = false
-activation_checkpointing = true
-

examples/sft/evaluate.py

@@ -1,117 +0,0 @@
-#!/usr/bin/env python3
-"""Evaluate a base or fine-tuned model on Crafter via the Task App rollout.
-
-This mirrors the minimal evaluation loop: call `/rollout` for a set of seeds
-and report outcome/step metrics. If tracing is enabled server-side, you can
-use the exported sqlite DB for further analysis.
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import os
-from dataclasses import dataclass
-from typing import Any
-
-from synth_ai.task import (
-    RolloutEnvSpec,
-    RolloutPolicySpec,
-    RolloutRecordConfig,
-    RolloutRequest,
-    TaskAppClient,
-)
-
-
-@dataclass(slots=True)
-class EvalArgs:
-    base_url: str
-    api_key: str
-    model: str
-    inference_url: str
-    inference_api_key: str
-    seeds: list[int]
-    max_llm_calls: int
-    timeout: float
-
-
-def _ops(n: int) -> list[str]:
-    n = max(1, n)
-    ops: list[str] = []
-    for _ in range(n):
-        ops.extend(["agent", "env"])  # one LLM step followed by one env step
-    return ops
-
-
-def _request(seed: int, a: EvalArgs) -> RolloutRequest:
-    return RolloutRequest(
-        run_id=f"eval-{seed}",
-        env=RolloutEnvSpec(env_name="crafter", seed=seed, config={}),
-        policy=RolloutPolicySpec(
-            policy_name="crafter-react",
-            config={"model": a.model, "inference_url": a.inference_url, "api_key": a.inference_api_key},
-        ),
-        ops=_ops(a.max_llm_calls),
-        record=RolloutRecordConfig(trajectories=True, return_trace=False, trace_format="compact"),
-    )
-
-
-async def _eval_seed(client: TaskAppClient, seed: int, a: EvalArgs) -> dict[str, Any]:
-    resp = await client.rollout(_request(seed, a))
-    m = resp.metrics
-    return {"seed": seed, "num_steps": m.num_steps, "episode_returns": m.episode_returns, "outcome_score": m.outcome_score}
-
-
-async def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__)
-    p.add_argument("--base-url", default=os.getenv("TASK_APP_URL", "http://localhost:8001"))
-    p.add_argument("--api-key", default=os.getenv("ENVIRONMENT_API_KEY"))
-    p.add_argument("--model", required=True, help="Base or ft:<id> to evaluate")
-    p.add_argument("--inference-url", default=os.getenv("INFERENCE_URL", "https://api.groq.com/openai"))
-    p.add_argument("--inference-api-key", default=os.getenv("GROQ_API_KEY"))
-    p.add_argument("--seeds", default="0,1,2,3,4,5,6,7,8,9")
-    p.add_argument("--max-llm-calls", type=int, default=10)
-    p.add_argument("--timeout", type=float, default=60.0)
-    args = p.parse_args()
-
-    seeds = [int(s) for s in str(args.seeds).split(",") if s.strip()]
-    a = EvalArgs(
-        base_url=str(args.base_url).strip(),
-        api_key=str(args.api_key or "").strip(),
-        model=str(args.model).strip(),
-        inference_url=str(args.inference_url).strip(),
-        inference_api_key=str(args.inference_api_key or "").strip(),
-        seeds=seeds,
-        max_llm_calls=int(args.max_llm_calls),
-        timeout=float(args.timeout),
-    )
-    if not a.api_key:
-        raise SystemExit("ENVIRONMENT_API_KEY is required")
-    if not a.inference_api_key:
-        raise SystemExit("Inference API key (e.g., GROQ_API_KEY) is required")
-
-    results: list[dict[str, Any]] = []
-    async with TaskAppClient(a.base_url, api_key=a.api_key, timeout=a.timeout) as client:
-        for seed in a.seeds:
-            r = await _eval_seed(client, seed, a)
-            results.append(r)
-            print(f"seed={seed} return={r.get('episode_returns')}")
-
-    # Simple aggregate
-    flat_returns: list[float] = []
-    for r in results:
-        ers = r.get("episode_returns") or []
-        if isinstance(ers, list) and ers:
-            try:
-                flat_returns.append(float(ers[0]))
-            except Exception:
-                pass
-    if flat_returns:
-        mean_ret = sum(flat_returns) / len(flat_returns)
-        print(f"mean_return={mean_ret:.3f} over {len(flat_returns)} episodes")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-
-

examples/sft/export_dataset.py

@@ -1,117 +0,0 @@
-#!/usr/bin/env python3
-"""Export SFT JSONL from tracing_v3 sqlite using the shared exporter utilities.
-
-Thin wrapper over `examples/warming_up_to_rl/export_trace_sft.py` to keep the
-SFT workflow self-contained in this folder while reusing tested logic.
-"""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from examples.warming_up_to_rl.export_trace_sft import (
-    build_sft_dataset,
-    connect,
-    fetch_achievement_data,
-    fetch_event_reward_totals,
-    fetch_outcome_rewards,
-    fetch_session_models,
-    parse_event_filters,
-    write_jsonl,
-)
-
-
-def main() -> None:
-    p = argparse.ArgumentParser(description=__doc__)
-    p.add_argument("--db", type=Path, default=Path("traces/v3/synth_ai.db"))
-    p.add_argument("--output", type=Path, default=Path("examples/sft/ft_data/crafter_traces.jsonl"))
-    p.add_argument("--model", action="append", dest="models")
-    p.add_argument("--provider", action="append", dest="providers")
-    p.add_argument("--min-unique", type=int, default=0)
-    p.add_argument("--max-unique", type=int, default=None)
-    p.add_argument("--exclude-achievement", action="append", dest="exclude_achievements")
-    p.add_argument("--require-achievement", action="append", dest="required_achievements")
-    p.add_argument("--min-outcome-reward", type=float, default=None)
-    p.add_argument("--max-outcome-reward", type=float, default=None)
-    p.add_argument("--event-reward", action="append", dest="event_reward_filters")
-    p.add_argument("--limit", type=int, default=None)
-    args = p.parse_args()
-
-    conn = connect(args.db)
-    try:
-        achievements_map, unique_counts, name_counts, size_counts, session_uniques, session_final = (
-            fetch_achievement_data(conn)
-        )
-        session_models = fetch_session_models(conn)
-        outcome_data = fetch_outcome_rewards(conn)
-        event_totals = fetch_event_reward_totals(conn)
-        event_filters = parse_event_filters(args.event_reward_filters)
-
-        allowed_models = set(args.models) if args.models else None
-        allowed_providers = set(args.providers) if args.providers else None
-        required_achievements = set(args.required_achievements or [])
-        excluded_achievements = set(args.exclude_achievements or [])
-
-        eligible: set[str] = set()
-        for session_id, (model_name, provider, _calls) in session_models.items():
-            if allowed_models and model_name not in allowed_models:
-                continue
-            if allowed_providers and (provider or "unknown") not in allowed_providers:
-                continue
-
-            session_unique = session_uniques.get(session_id, set())
-            adjusted_uniques = {a for a in session_unique if a not in excluded_achievements}
-            unique_count = len(adjusted_uniques)
-            if args.min_unique is not None and unique_count < args.min_unique:
-                continue
-            if args.max_unique is not None and unique_count > args.max_unique:
-                continue
-
-            outcome = outcome_data.get(session_id)
-            total_reward = outcome["total_reward"] if outcome else 0.0
-            final_achievements = (
-                outcome["achievements"] if outcome else session_final.get(session_id, set())
-            )
-            if args.min_outcome_reward is not None and total_reward < args.min_outcome_reward:
-                continue
-            if args.max_outcome_reward is not None and total_reward > args.max_outcome_reward:
-                continue
-            if required_achievements and not required_achievements.issubset(final_achievements):
-                continue
-
-            totals = event_totals.get(session_id, {})
-            meets_filters = True
-            for reward_type, min_total in event_filters:
-                total = totals.get(reward_type, {}).get("total", 0.0)
-                if total < min_total:
-                    meets_filters = False
-                    break
-            if not meets_filters:
-                continue
-            eligible.add(session_id)
-
-        if not eligible:
-            raise SystemExit("No sessions matched the provided filters.")
-
-        dataset = build_sft_dataset(
-            conn,
-            achievements_map,
-            eligible,
-            allowed_models=allowed_models,
-            limit=args.limit,
-        )
-        if not dataset:
-            raise SystemExit("No rollout steps matched the filters (after session selection).")
-
-        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
-        write_jsonl(args.output, dataset)
-        print(f"Wrote {len(dataset)} examples -> {args.output}")
-    finally:
-        conn.close()
-
-
-if __name__ == "__main__":
-    main()
-
-