synth-ai 0.2.9.dev2__py3-none-any.whl → 0.2.9.dev4__py3-none-any.whl

examples/warming_up_to_rl/run_fft_and_save.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Tuple, List
+
+import tomllib
+import re
+import requests
+
+
+def mask(val: str) -> str:
+    if not isinstance(val, str) or not val:
+        return "<unset>"
+    return f"{val[:6]}…{val[-4:]}" if len(val) >= 10 else "****"
+
+
+def post_multipart(base: str, api_key: str, path: str, file_field: str, filepath: Path) -> Dict[str, Any]:
+    """Upload a file, trying backend-specific endpoints with fallbacks.
+
+    Priority:
+    - {BASE}/learning/files (Modal Learning v2 style)
+    - {BASE}/files (OpenAI-style)
+    """
+    headers = {"Authorization": f"Bearer {api_key}"}
+    files = {file_field: (filepath.name, filepath.read_bytes(), "application/jsonl")}
+    data = {"purpose": "fine-tune"}
+
+    endpoints = [
+        f"{base.rstrip('/')}/{path.lstrip('/')}",  # e.g., /learning/files
+        f"{base.rstrip('/')}/files",               # OpenAI-style
+    ]
+    last_err: Dict[str, Any] | None = None
+    for ep in endpoints:
+        try:
+            r = requests.post(ep, headers=headers, files=files, data=data, timeout=300)
+            # Success fast-path
+            try:
+                js = r.json()
+            except Exception:
+                js = {"status": r.status_code, "text": r.text[:800]}
+
+            if r.status_code < 400 and (js.get("id") or js.get("object") in ("file",)):
+                return js
+
+            # 404/405 -> try next endpoint
+            if r.status_code in (404, 405):
+                last_err = {"status": r.status_code, "body": (r.text or "")[:800], "endpoint": ep}
+                continue
+
+            # Other errors: return rich error
+            return {
+                "error": True,
+                "status": r.status_code,
+                "endpoint": ep,
+                "body": (r.text or "")[:1200],
+            }
+        except requests.RequestException as e:
+            last_err = {"error": True, "exception": str(e), "endpoint": ep}
+            continue
+
+    return last_err or {"error": True, "detail": "upload_failed_all_endpoints"}
+
+
+def post_json(base: str, api_key: str, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+    url = f"{base.rstrip('/')}/{path.lstrip('/')}"
+    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+    r = requests.post(url, headers=headers, data=json.dumps(body), timeout=120)
+    try:
+        return r.json()
+    except Exception:
+        return {"status": r.status_code, "text": r.text[:400]}
+
+
+def get_json(base: str, api_key: str, path: str) -> Dict[str, Any]:
+    url = f"{base.rstrip('/')}/{path.lstrip('/')}"
+    headers = {"Authorization": f"Bearer {api_key}"}
+    r = requests.get(url, headers=headers, timeout=30)
+    try:
+        return r.json()
+    except Exception:
+        return {"status": r.status_code, "text": r.text[:400]}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Submit FFT job and save resulting model id")
+    parser.add_argument("--backend", default=os.getenv("BACKEND_BASE_URL", "http://localhost:8000/api"))
+    parser.add_argument("--toml", required=True, help="Path to FFT TOML config")
+    parser.add_argument("--data", default="", help="Override dataset JSONL path")
+    parser.add_argument("--poll-seconds", type=int, default=1800)
+    parser.add_argument("--env-file", default="", help="Optional path to .env file with SYNTH_API_KEY")
+    args = parser.parse_args()
+
+    config_path = Path(args.toml).expanduser().resolve()
+    if not config_path.exists():
+        print(f"Config not found: {config_path}", file=sys.stderr)
+        sys.exit(2)
+    with config_path.open("rb") as fh:
+        cfg = tomllib.load(fh)
+
+    job_cfg = cfg.get("job", {}) if isinstance(cfg.get("job"), dict) else {}
+    compute_cfg = cfg.get("compute", {}) if isinstance(cfg.get("compute"), dict) else {}
+    data_cfg_full = cfg.get("data", {}) if isinstance(cfg.get("data"), dict) else {}
+    topo_cfg = (data_cfg_full or {}).get("topology", {}) if isinstance(data_cfg_full, dict) else {}
+    validation_local_path = (data_cfg_full or {}).get("validation_path") if isinstance(data_cfg_full, dict) else None
+    train_cfg = cfg.get("training", {}) if isinstance(cfg.get("training"), dict) else {}
+    hp_cfg = cfg.get("hyperparameters", {}) if isinstance(cfg.get("hyperparameters"), dict) else {}
+
+    model = str(job_cfg.get("model") or os.getenv("SFT_MODEL") or "Qwen/Qwen3-4B")
+
+    # Resolve dataset path
+    data_path = args.data or job_cfg.get("data") or job_cfg.get("data_path")
+    data_file: Path | None = None
+    if isinstance(data_path, str) and data_path.strip():
+        p = Path(data_path).expanduser()
+        if not p.is_absolute():
+            p = (config_path.parent / p).resolve()
+        data_file = p
+    if data_file is None:
+        print("Missing dataset path in --data or [job].data", file=sys.stderr)
+        sys.exit(2)
+    if not data_file.exists():
+        print(f"Dataset not found: {data_file}", file=sys.stderr)
+        sys.exit(2)
+
+    synth_key = (os.getenv("SYNTH_API_KEY") or "").strip()
+    # Fallback: try to load from .env if not present in environment
+    if not synth_key:
+        candidate_env: Path | None = None
+        if isinstance(args.env_file, str) and args.env_file.strip():
+            candidate_env = Path(args.env_file).expanduser().resolve()
+        else:
+            # Prefer .env next to the TOML config
+            candidate_env = (config_path.parent / ".env").resolve()
+        if candidate_env and candidate_env.exists():
+            try:
+                env_text = candidate_env.read_text(encoding="utf-8", errors="ignore")
+                # Match lines like: SYNTH_API_KEY=..., or export SYNTH_API_KEY=...
+                key_val: str | None = None
+                for line in env_text.splitlines():
+                    m = re.match(r"^\s*(?:export\s+)?SYNTH_API_KEY\s*=\s*(.*)$", line)
+                    if m:
+                        raw = m.group(1).strip()
+                        # Trim surrounding quotes if present
+                        if (raw.startswith('"') and raw.endswith('"')) or (raw.startswith("'") and raw.endswith("'")):
+                            raw = raw[1:-1]
+                        key_val = raw.strip()
+                        break
+                if key_val:
+                    synth_key = key_val
+                    os.environ["SYNTH_API_KEY"] = synth_key
+                    print(f"[INFO] Loaded SYNTH_API_KEY from {candidate_env}")
+            except Exception as _e:
+                # Ignore and fall through to error below
+                pass
+    if not synth_key:
+        print("Missing SYNTH_API_KEY (set in env or provide --env-file pointing to .env)", file=sys.stderr)
+        sys.exit(2)
+
+    backend = args.backend.rstrip("/")
+    print(f"[INFO] Using backend={backend} key_fp={mask(synth_key)} data={data_file}")
+    if isinstance(validation_local_path, str) and validation_local_path.strip():
+        print(f"[INFO] Using validation path={validation_local_path}")
+
+    # 1) Upload training file
+    print("[INFO] Uploading training file…")
+    upf = post_multipart(backend, synth_key, "/learning/files", "file", data_file)
+    try:
+        print(f"[INFO] Upload response: {json.dumps(upf, indent=2)[:400]}")
+    except Exception:
+        print(f"[INFO] Upload response (raw): {str(upf)[:400]}")
+    file_id = str((upf or {}).get("id") or "").strip()
+    if not file_id:
+        # Rich diagnostics
+        err_status = (upf or {}).get("status")
+        err_body = (upf or {}).get("body") or (upf or {}).get("text")
+        err_ep = (upf or {}).get("endpoint")
+        print(f"Upload failed (status={err_status} endpoint={err_ep}) body={str(err_body)[:200]}", file=sys.stderr)
+        sys.exit(4)
+
+    # Optionally upload validation file
+    val_file_id: str | None = None
+    if isinstance(validation_local_path, str) and validation_local_path.strip():
+        vpath = Path(validation_local_path).expanduser()
+        if not vpath.is_absolute():
+            vpath = (config_path.parent / vpath).resolve()
+        if not vpath.exists():
+            print(f"[WARN] Validation file not found: {vpath} (skipping validation)")
+        else:
+            print("[INFO] Uploading validation file…")
+            upv = post_multipart(backend, synth_key, "/learning/files", "file", vpath)
+            try:
+                print(f"[INFO] Validation upload response: {json.dumps(upv, indent=2)[:300]}")
+            except Exception:
+                print(f"[INFO] Validation upload response (raw): {str(upv)[:300]}")
+            val_file_id = str((upv or {}).get("id") or "").strip() or None
+            if not val_file_id:
+                err_status = (upv or {}).get("status")
+                err_body = (upv or {}).get("body") or (upv or {}).get("text")
+                err_ep = (upv or {}).get("endpoint")
+                print(f"[WARN] Validation upload failed (status={err_status} endpoint={err_ep}) body={str(err_body)[:180]} — continuing without validation")
+
+    # 2) Build job payload
+    hp_block: Dict[str, Any] = {
+        "n_epochs": int(hp_cfg.get("n_epochs") or 1),
+    }
+    # Optional extras if present
+    for k in (
+        "batch_size",
+        "global_batch",
+        "per_device_batch",
+        "gradient_accumulation_steps",
+        "sequence_length",
+        "learning_rate",
+        "warmup_ratio",
+        "train_kind",
+    ):
+        if k in hp_cfg:
+            hp_block[k] = hp_cfg[k]
+
+    parallel = hp_cfg.get("parallelism") if isinstance(hp_cfg.get("parallelism"), dict) else None
+    if parallel:
+        hp_block["parallelism"] = parallel
+
+    compute_block: Dict[str, Any] = {}
+    for k in ("gpu_type", "gpu_count", "nodes"):
+        if k in compute_cfg:
+            compute_block[k] = compute_cfg[k]
+
+    effective = {
+        "compute": compute_block,
+        "data": {"topology": topo_cfg or {}},
+        "training": {k: v for k, v in train_cfg.items() if k in ("mode", "use_qlora")},
+    }
+    # If TOML includes a [training.validation] block, forward relevant knobs into hyperparameters
+    validation_cfg = train_cfg.get("validation") if isinstance(train_cfg.get("validation"), dict) else None
+    if isinstance(validation_cfg, dict):
+        # Enable evaluation and map keys as-is; backend trainer maps metric_for_best_model 'val.loss'→'eval_loss'
+        hp_block.update({
+            "evaluation_strategy": validation_cfg.get("evaluation_strategy", "steps"),
+            "eval_steps": int(validation_cfg.get("eval_steps", 0) or 0),
+            "save_best_model_at_end": bool(validation_cfg.get("save_best_model_at_end", True)),
+            "metric_for_best_model": validation_cfg.get("metric_for_best_model", "val.loss"),
+            "greater_is_better": bool(validation_cfg.get("greater_is_better", False)),
+        })
+        # Also surface validation enable flag into effective_config for visibility (optional)
+        effective.setdefault("training", {})["validation"] = {"enabled": bool(validation_cfg.get("enabled", True))}
+
+    body = {
+        "model": model,
+        "training_file_id": file_id,
+        "training_type": "sft_offline",
+        "hyperparameters": hp_block,
+        "metadata": {"effective_config": effective},
+    }
+    if val_file_id:
+        # Shared API expects top-level validation_file? Tests mention legacy; prefer placing into metadata.effective_config.data
+        # Put into effective_config.data so downstream loader can read it; keep top-level off unless required.
+        effective.setdefault("data", {})["validation_files"] = [val_file_id]
+
+    # 3) Create and start job
+    print("[INFO] Creating FFT job…")
+    cj = post_json(backend, synth_key, "/learning/jobs", body)
+    print(f"[INFO] Create response: {json.dumps(cj, indent=2)[:200]}")
+    job_id = str(cj.get("job_id") or cj.get("id") or "").strip()
+    if not job_id:
+        print("Create job failed", file=sys.stderr)
+        sys.exit(5)
+
+    print(f"[INFO] Starting job {job_id}…")
+    _ = post_json(backend, synth_key, f"/learning/jobs/{job_id}/start", {})
+
+    # 4) Poll until terminal
+    deadline = time.time() + max(30, int(job_cfg.get("poll_seconds") or args.poll_seconds))
+    status = "queued"
+    ft_model = None
+    queued_since = time.time()
+    while time.time() < deadline:
+        info = get_json(backend, synth_key, f"/learning/jobs/{job_id}")
+        status = (info.get("status") or "").lower()
+        ft_model = info.get("fine_tuned_model")
+        print(f"[INFO] poll status={status} ft_model={ft_model}")
+        if status in ("succeeded", "failed", "canceled", "cancelled"):
+            break
+        # Warn if stuck queued for >10 minutes
+        if status == "queued" and (time.time() - queued_since) > 600:
+            print("[WARN] Job has remained queued for >10 minutes. Backend may be capacity constrained.")
+            queued_since = time.time()
+        time.sleep(5)
+
+    # 5) Save model id
+    out_file = Path(__file__).parent / "ft_model_id.txt"
+    if ft_model:
+        with out_file.open("a") as fh:
+            fh.write(str(ft_model) + "\n")
+        print(f"[INFO] Saved model id to {out_file}: {ft_model}")
+        sys.exit(0 if status == "succeeded" else 1)
+    else:
+        print(f"[WARN] No fine_tuned_model found; final status={status}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

examples/warming_up_to_rl/run_local_rollout.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Hit a locally running Crafter task app and request a rollout."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import sys
+
+import httpx
+from dotenv import load_dotenv
+
+from synth_ai.task import (
+    RolloutEnvSpec,
+    RolloutPolicySpec,
+    RolloutRecordConfig,
+    RolloutRequest,
+    RolloutSafetyConfig,
+    TaskAppClient,
+)
+
+
+def build_rollout_request(
+    seed: int,
+    run_id: str,
+    *,
+    model: str,
+    inference_url: str,
+    ops: list[str],
+    extra_headers: dict[str, str] | None = None,
+    trace_format: str = "compact",
+    return_trace: bool = False,
+) -> RolloutRequest:
+    policy_config = {"model": model, "inference_url": inference_url}
+    if extra_headers:
+        policy_config["extra_headers"] = extra_headers
+    record_cfg = RolloutRecordConfig(
+        trajectories=True,
+        trace_format=trace_format,
+        return_trace=return_trace,
+    )
+    return RolloutRequest(
+        run_id=run_id,
+        env=RolloutEnvSpec(env_name='crafter', seed=seed, config={}),
+        policy=RolloutPolicySpec(policy_name='crafter-react', config=policy_config),
+        ops=ops,
+        record=record_cfg,
+        on_done='reset',
+        safety=RolloutSafetyConfig(),
+    )
+
+
+def summarise_response(data: Any) -> dict[str, Any]:
+    metrics = data.metrics.model_dump() if hasattr(data.metrics, "model_dump") else data.get("metrics", {})
+    error = None
+    rollout_status = None
+    try:
+        trajectories = getattr(data, "trajectories", None) or data.get("trajectories")
+        if isinstance(trajectories, list) and trajectories:
+            final = getattr(trajectories[0], "final", None)
+            if not final and isinstance(trajectories[0], dict):
+                final = trajectories[0].get("final")
+            if isinstance(final, dict):
+                error = final.get("error")
+                rollout_status = final.get("rollout_status")
+    except Exception:
+        pass
+    return {
+        "run_id": getattr(data, "run_id", None) or data.get("run_id"),
+        "num_episodes": metrics.get("num_episodes"),
+        "num_steps": metrics.get("num_steps"),
+        "episode_returns": metrics.get("episode_returns"),
+        "outcome_score": metrics.get("outcome_score"),
+        "events_score": metrics.get("events_score"),
+        "rollout_status": rollout_status,
+        "error": error,
+    }
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://localhost:8001", help="Task app base URL")
+    parser.add_argument("--api-key", help="Environment API key (or set via --env-file)")
+    parser.add_argument('--seed', type=int, default=42, help='Env seed to rollout')
+    parser.add_argument('--run-id', default='local-demo', help='Run identifier')
+    parser.add_argument('--model', default='gpt-4o-mini', help='Model identifier for the Crafter policy (OpenAI-compatible)')
+    parser.add_argument('--inference-url', default='https://api.openai.com', help='Inference base URL used by the policy (e.g., https://api.openai.com)')
+    parser.add_argument('--env-file', type=str, default=None, help='Path to .env file with API keys')
+    parser.add_argument('--ops', default=None, help='Comma-separated rollout ops (advanced override)')
+    parser.add_argument('--max-llm-calls', type=int, default=1, help='Number of policy inference calls when --ops not provided')
+    parser.add_argument('--max-policy-tokens', type=int, default=None, help='Optional per-call token limit forwarded to the policy config')
+    parser.add_argument('--timeout', type=float, default=600.0, help='HTTP timeout (seconds) for task app requests')
+    parser.add_argument('--verbose', action='store_true', help='Print resolved configuration and headers')
+    args = parser.parse_args()
+
+    if args.env_file:
+        env_path = Path(args.env_file).expanduser()
+        if not env_path.exists():
+            print(f"[WARN] Env file not found: {env_path}")
+        else:
+            load_dotenv(env_path, override=False)
+
+    api_key = args.api_key or os.getenv("ENVIRONMENT_API_KEY")
+    if not api_key:
+        parser.error("Missing --api-key (or ENVIRONMENT_API_KEY not set)")
+
+    extra_headers: dict[str, str] | None = None
+    synth_key = os.getenv("SYNTH_API_KEY")
+    if synth_key:
+        extra_headers = {"Authorization": f"Bearer {synth_key}"}
+        if "openai.com" not in args.inference_url.lower():
+            os.environ["OPENAI_API_KEY"] = synth_key
+
+    if args.verbose:
+        def _mask(val: str | None) -> str:
+            if not val:
+                return '<unset>'
+            return f"{val[:6]}…{val[-4:]} (len={len(val)})"
+
+        print('Resolved configuration:')
+        print(f"  Task app base URL  : {args.base_url}")
+        print(f"  Inference base URL : {args.inference_url}")
+        print(f"  Task app API key   : {_mask(api_key)}")
+        print(f"  Synth API key      : {_mask(synth_key)}")
+        print(f"  HTTP timeout       : {args.timeout:.1f}s")
+
+    if args.ops:
+        ops = [op.strip() for op in args.ops.split(',') if op.strip()]
+        if not ops:
+            raise ValueError('Ops must contain at least one entry')
+    else:
+        llm_calls = max(args.max_llm_calls, 1)
+        if llm_calls > 20:
+            print('[WARN] --max-llm-calls capped at 20 to avoid excessive episodes; use --ops for manual control.')
+            llm_calls = 20
+        ops = []
+        for _ in range(llm_calls):
+            ops.extend(['agent', 'env'])
+
+    async with TaskAppClient(args.base_url, api_key=api_key, timeout=args.timeout) as client:
+        try:
+            print(f'Fetching task_info for seed {args.seed}…')
+            task_info = await client.task_info(seeds=[args.seed])
+            info_payload = task_info[0] if isinstance(task_info, list) else task_info
+            print(json.dumps(info_payload.model_dump(), indent=2)[:600])
+
+            request = build_rollout_request(
+                args.seed,
+                args.run_id,
+                model=args.model,
+                inference_url=args.inference_url,
+                ops=ops,
+                extra_headers=extra_headers,
+            )
+            if args.max_policy_tokens is not None:
+                request.policy.config.update({
+                    'max_completion_tokens': args.max_policy_tokens,
+                    'max_tokens': args.max_policy_tokens,
+                })
+            if args.verbose:
+                print(f'Ops: {ops}')
+                print(f'Request headers: {request.policy.config.get("extra_headers", {})}')
+            print('Requesting rollout…')
+            response = await client.rollout(request)
+            summary = summarise_response(response)
+            print(json.dumps(summary, indent=2))
+            print(f'Ops executed: {ops}')
+            print('Tip: use --max-llm-calls N for agent/env pairs or --ops for manual control.')
+        except httpx.HTTPStatusError as exc:
+            detail = exc.response.json() if exc.response.headers.get('content-type', '').startswith('application/json') else exc.response.text
+            print(f'HTTP error {exc.response.status_code}: {detail}', file=sys.stderr)
+            if exc.response.status_code in (401, 503):
+                print('Hint: ensure the task app was started with ENVIRONMENT_API_KEY set and pass the same key via --api-key.', file=sys.stderr)
+            if exc.response.status_code == 500 and args.model in str(detail):
+                print('Hint: supply --model/--inference-url (and set OPENAI_API_KEY or GROQ_API_KEY) so the policy can route inference.', file=sys.stderr)
+                print('Hint: the inference URL should be the base (e.g., https://api.openai.com); the task app appends /v1/chat/completions.', file=sys.stderr)
+                if args.max_policy_tokens is not None:
+                    print(f'Hint: --max-policy-tokens={args.max_policy_tokens} is forwarded to the policy config as max_completion_tokens.', file=sys.stderr)
+            raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/warming_up_to_rl/run_local_rollout_modal.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Rollout a Crafter task app using the Modal backend proxy."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import sys
+
+import httpx
+from dotenv import load_dotenv
+
+from synth_ai.task import (
+    RolloutEnvSpec,
+    RolloutPolicySpec,
+    RolloutRecordConfig,
+    RolloutRequest,
+    RolloutSafetyConfig,
+    TaskAppClient,
+)
+
+
+def build_rollout_request(seed: int, run_id: str, *, model: str, inference_url: str, ops: list[str], api_key: str) -> RolloutRequest:
+    policy_config = {
+        "model": model,
+        "inference_url": inference_url,
+        "extra_headers": {
+            "Authorization": f"Bearer {api_key}",
+        },
+    }
+    return RolloutRequest(
+        run_id=run_id,
+        env=RolloutEnvSpec(env_name="crafter", seed=seed, config={}),
+        policy=RolloutPolicySpec(policy_name="crafter-react", config=policy_config),
+        ops=ops,
+        record=RolloutRecordConfig(trajectories=True),
+        on_done="reset",
+        safety=RolloutSafetyConfig(),
+    )
+
+
+def summarise_response(data: Any) -> dict[str, Any]:
+    metrics = data.metrics.model_dump() if hasattr(data.metrics, "model_dump") else data.get("metrics", {})
+    return {
+        "run_id": getattr(data, "run_id", None) or data.get("run_id"),
+        "num_episodes": metrics.get("num_episodes"),
+        "num_steps": metrics.get("num_steps"),
+        "episode_returns": metrics.get("episode_returns"),
+        "outcome_score": metrics.get("outcome_score"),
+        "events_score": metrics.get("events_score"),
+    }
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://localhost:8010", help="Task app base URL")
+    parser.add_argument("--env-file", type=str, default=None, help="Path to .env file with keys")
+    parser.add_argument("--seed", type=int, default=42, help="Env seed to rollout")
+    parser.add_argument("--run-id", default="modal-eval", help="Run identifier")
+    parser.add_argument("--model", required=True, help="Model identifier for the Crafter policy")
+    parser.add_argument("--inference-url", required=True, help="Modal backend inference base URL (e.g., http://localhost:8000/api)")
+    parser.add_argument("--task-app-key", default=None, help="Environment API key for the task app (fallback ENVIRONMENT_API_KEY)")
+    parser.add_argument("--modal-key", default=None, help="Synth/Modal API key for inference (fallback SYNTH_API_KEY)")
+    parser.add_argument("--max-llm-calls", type=int, default=20, help="Number of policy inference calls")
+    parser.add_argument("--ops", default=None, help="Comma-separated rollout ops (advanced override)")
+    parser.add_argument("--max-policy-tokens", type=int, default=None, help="Optional per-call token limit forwarded to the policy config")
+    parser.add_argument("--verbose", action="store_true", help="Print resolved configuration and headers")
+    args = parser.parse_args()
+
+    if args.env_file:
+        env_path = Path(args.env_file).expanduser()
+        if not env_path.exists():
+            print(f"[WARN] Env file not found: {env_path}")
+        else:
+            load_dotenv(env_path, override=False)
+
+    task_app_key = args.task_app_key or os.getenv("ENVIRONMENT_API_KEY")
+    if not task_app_key:
+        parser.error("Missing task app API key (set ENVIRONMENT_API_KEY or pass --task-app-key)")
+
+    modal_key = args.modal_key or os.getenv("SYNTH_API_KEY")
+    if not modal_key:
+        parser.error("Missing Synth/Modal API key (set SYNTH_API_KEY or pass --modal-key)")
+
+    if synth_key and "openai.com" not in args.inference_url.lower():
+        os.environ["OPENAI_API_KEY"] = synth_key
+
+    if args.ops:
+        ops = [op.strip() for op in args.ops.split(",") if op.strip()]
+        if not ops:
+            raise ValueError("Ops must contain at least one entry")
+    else:
+        llm_calls = max(args.max_llm_calls, 1)
+        if llm_calls > 20:
+            llm_calls = 20
+        ops = []
+        for _ in range(llm_calls):
+            ops.extend(["agent", "env"])
+
+    if args.verbose:
+        def _mask(val: str | None) -> str:
+            if not val:
+                return "<unset>"
+            return f"{val[:6]}…{val[-4:]} (len={len(val)})"
+
+        print("Resolved configuration:")
+        print(f"  Task app base URL  : {args.base_url}")
+        print(f"  Inference base URL : {args.inference_url}")
+        print(f"  Task app API key   : {_mask(task_app_key)}")
+        print(f"  Modal API key      : {_mask(modal_key)}")
+        print(f"  Ops (count={len(ops)}) : {ops}")
+
+    inf_url_norm = args.inference_url.rstrip('/')
+    if '/api' not in inf_url_norm:
+        print('[WARN] Inference URL is missing /api prefix; proxy endpoints usually live at /api/inference/v1/chat/completions.')
+    elif not inf_url_norm.lower().endswith('/api'):
+        print('[INFO] Using inference base URL; policy will append /v1/chat/completions automatically.')
+
+    async with TaskAppClient(args.base_url, api_key=task_app_key) as client:
+        try:
+            print(f"Fetching task_info for seed {args.seed}…")
+            task_info = await client.task_info(seeds=[args.seed])
+            info_payload = task_info[0] if isinstance(task_info, list) else task_info
+            print(json.dumps(info_payload.model_dump(), indent=2)[:600])
+
+            request = build_rollout_request(
+                args.seed,
+                args.run_id,
+                model=args.model,
+                inference_url=args.inference_url,
+                ops=ops,
+                api_key=modal_key,
+            )
+            if args.verbose:
+                print(f"Request headers: {request.policy.config.get('extra_headers', {})}")
+            if args.max_policy_tokens is not None:
+                request.policy.config.update({
+                    "max_completion_tokens": args.max_policy_tokens,
+                    "max_tokens": args.max_policy_tokens,
+                })
+            print("Requesting rollout…")
+            response = await client.rollout(request)
+            summary = summarise_response(response)
+            print(json.dumps(summary, indent=2))
+            print(f"Ops executed: {ops}")
+        except httpx.HTTPStatusError as exc:
+            detail = exc.response.json() if exc.response.headers.get("content-type", "").startswith("application/json") else exc.response.text
+            print(f"HTTP error {exc.response.status_code}: {detail}", file=sys.stderr)
+            if exc.response.status_code in (401, 503):
+                print("Hint: ensure ENVIRONMENT_API_KEY and SYNTH_API_KEY are correctly set.", file=sys.stderr)
+            raise
+
+
+if __name__ == "__main__":
+    asyncio.run(main())