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

examples/warming_up_to_rl/configs/eval_stepwise_simple.toml

@@ -4,9 +4,11 @@
 # task_app_url = "https://YOUR-TASK-APP.modal.run"
 
 model = "qwen/qwen3-32b"
-num_episodes = 50
+# Route inference to local task app Groq proxy
+inference_url = "http://localhost:8001/proxy/groq"
+num_episodes = 10
 max_turns = 10
-concurrency = 5
+concurrency = 10
 # difficulty = "easy"  # optional
 
 [rollout]

examples/warming_up_to_rl/run_eval.py

@@ -14,12 +14,14 @@ import contextlib
 import json
 import os
 import re
-import tomllib
-from copy import deepcopy
+import sys
 from collections import Counter
+from copy import deepcopy
 from pathlib import Path
 from typing import Any
 
+import tomllib
+
 import httpx
 
 
@@ -332,6 +334,12 @@ async def eval_episode(client: TaskAppClient, seed: int) -> dict[str, Any]:
     observation = created.get("observation") if isinstance(created, dict) else None
     if not isinstance(observation, dict):
         observation = {}
+    try:
+        ach_map_initial = observation.get("achievements_status")
+        if isinstance(ach_map_initial, dict):
+            achievements.update(k for k, v in ach_map_initial.items() if v)
+    except Exception:
+        pass
 
     try:
         while turns < MAX_TURNS and not done:
@@ -351,6 +359,12 @@ async def eval_episode(client: TaskAppClient, seed: int) -> dict[str, Any]:
                 nxt = step.get("observation")
                 if isinstance(nxt, dict):
                     observation = nxt
+                    try:
+                        ach_map = observation.get("achievements_status")
+                        if isinstance(ach_map, dict):
+                            achievements.update(k for k, v in ach_map.items() if v)
+                    except Exception:
+                        pass
     finally:
         with contextlib.suppress(Exception):
             await client.terminate(env_name, env_id)
@@ -358,21 +372,45 @@ async def eval_episode(client: TaskAppClient, seed: int) -> dict[str, Any]:
     return {"seed": seed, "turns": turns, "achievements": sorted(achievements)}
 
 
-async def main() -> None:
-    # Best-effort load local .env if present (ensures ENVIRONMENT_API_KEY for rollout)
+def _load_dotenv_defaults() -> None:
+    """Load .env-style key/value pairs without clobbering explicit exports."""
     try:
-        env_path = Path(__file__).resolve().parent / ".env"
-        if env_path.exists():
-            for line in env_path.read_text(encoding="utf-8").splitlines():
-                line = line.strip()
-                if not line or line.startswith("#") or "=" not in line:
-                    continue
-                k, v = line.split("=", 1)
-                k = k.strip()
-                v = v.strip().strip('"').strip("'")
-                os.environ.setdefault(k, v)
+        script_path = Path(__file__).resolve()
     except Exception:
-        pass
+        return
+    candidates: list[Path] = []
+    # Prefer the repo root .env, then allow per-directory overrides.
+    for base in [Path.cwd(), script_path.parent, *script_path.parents]:
+        env_path = base / ".env"
+        if env_path not in candidates and env_path.is_file():
+            candidates.append(env_path)
+    seen: set[str] = set()
+    try:
+        for env_path in candidates:
+            try:
+                for raw in env_path.read_text(encoding="utf-8").splitlines():
+                    line = raw.strip()
+                    if not line or line.startswith("#") or "=" not in line:
+                        continue
+                    key, value = line.split("=", 1)
+                    key = key.strip()
+                    if not key or key in seen:
+                        continue
+                    seen.add(key)
+                    val = value.strip().strip('"').strip("'")
+                    os.environ.setdefault(key, val)
+            except Exception:
+                continue
+    except Exception:
+        return
+
+
+async def main() -> None:
+    _load_dotenv_defaults()
+    if not (os.getenv("ENVIRONMENT_API_KEY") or os.getenv("DEV_ENVIRONMENT_API_KEY")):
+        raise RuntimeError(
+            "ENVIRONMENT_API_KEY is required. Export it or add it to your project .env."
+        )
 
     parser = argparse.ArgumentParser(
         description="Baseline eval against task app with optional TOML config"
@@ -497,7 +535,7 @@ async def main() -> None:
                                 if isinstance(step_block, dict):
                                     stepwise_details = step_block
                         # Extract achievements count if present
-                        ach = []
+                        achieved: set[str] = set()
                         try:
                             trajs = r.get("trajectories") or []
                             final_obs = (
@@ -511,9 +549,29 @@ async def main() -> None:
                                 else None
                             )
                             if isinstance(ach_map, dict):
-                                ach = sorted([k for k, v in ach_map.items() if v])
+                                achieved.update(k for k, v in ach_map.items() if v)
+                        except Exception:
+                            pass
+                        try:
+                            step_seen = stepwise_details.get("unique_achievements")
+                        except Exception:
+                            step_seen = None
+                        if isinstance(step_seen, (list, tuple, set)):
+                            achieved.update(str(a) for a in step_seen)
+                        else:
+                            try:
+                                alt_seen = stepwise_details.get("achievements_seen")
+                                if isinstance(alt_seen, (list, tuple, set)):
+                                    achieved.update(str(a) for a in alt_seen)
+                            except Exception:
+                                pass
+                        try:
+                            summary_final = stepwise_details.get("final_achievements")
+                            if isinstance(summary_final, (list, tuple, set)):
+                                achieved.update(str(a) for a in summary_final)
                         except Exception:
                             pass
+                        ach = sorted(achieved)
                         length = 0
                         try:
                             trajs = r.get("trajectories") or []
@@ -556,7 +614,10 @@ async def main() -> None:
             stepwise_reward_sums: list[float] = []
             stepwise_indicator_sums: list[float] = []
             stepwise_new_ach_totals: list[float] = []
+            stepwise_resource_rewards: list[float] = []
             strategies_seen = Counter()
+            unique_union: set[str] = set()
+            final_union: set[str] = set()
             for r in results:
                 if not isinstance(r, dict):
                     continue
@@ -577,6 +638,19 @@ async def main() -> None:
                             stepwise_new_ach_totals.append(
                                 float(stepwise_block.get("new_achievements_total"))
                             )
+                    with contextlib.suppress(Exception):
+                        if stepwise_block.get("resource_reward") is not None:
+                            stepwise_resource_rewards.append(
+                                float(stepwise_block.get("resource_reward"))
+                            )
+                    with contextlib.suppress(Exception):
+                        uniq = stepwise_block.get("unique_achievements") or []
+                        if isinstance(uniq, (list, tuple, set)):
+                            unique_union.update(str(v) for v in uniq)
+                    with contextlib.suppress(Exception):
+                        final = stepwise_block.get("final_achievements") or []
+                        if isinstance(final, (list, tuple, set)):
+                            final_union.update(str(v) for v in final)
                     strategy_name = stepwise_block.get("strategy")
                     if isinstance(strategy_name, str) and strategy_name:
                         strategies_seen[strategy_name] += 1
@@ -603,14 +677,49 @@ async def main() -> None:
                 aggregate["avg_stepwise_new_achievements"] = sum(stepwise_new_ach_totals) / len(
                     stepwise_new_ach_totals
                 )
+            if stepwise_resource_rewards:
+                aggregate["avg_stepwise_resource_reward"] = (
+                    sum(stepwise_resource_rewards) / len(stepwise_resource_rewards)
+                )
             if strategies_seen:
                 aggregate["stepwise_strategies"] = dict(strategies_seen)
-            aggregate["stepwise_samples"] = len(stepwise_reward_sums)
+            aggregate["stepwise_samples"] = max(
+                len(stepwise_reward_sums),
+                len(stepwise_indicator_sums),
+                len(stepwise_new_ach_totals),
+                len(stepwise_resource_rewards),
+            ) if any(
+                (
+                    stepwise_reward_sums,
+                    stepwise_indicator_sums,
+                    stepwise_new_ach_totals,
+                    stepwise_resource_rewards,
+                )
+            ) else 0
+            if not unique_union:
+                for r in results:
+                    try:
+                        for a in r.get("achievements") or []:
+                            unique_union.add(str(a))
+                    except Exception:
+                        continue
+            if not final_union:
+                final_union.update(unique_union)
+            if unique_union:
+                aggregate["unique_achievements_union"] = sorted(unique_union)
+            if final_union:
+                aggregate["final_achievements_union"] = sorted(final_union)
             summary = {
                 "episodes": results,
                 "aggregate": aggregate,
             }
             print(json.dumps(summary, indent=2))
+            # Failure guardrails: any error or zero-turn episodes across the board
+            any_errors = any(isinstance(r, dict) and r.get("error") for r in results)
+            all_zero_turns = all((int(r.get("turns") or 0) == 0) for r in results if isinstance(r, dict))
+            if any_errors or all_zero_turns:
+                # Exit non-zero so automation/CI treats this as a failure
+                sys.exit(2)
         else:
 
             async def _run(seed: int):

examples/workflows/math_rl/download_dataset.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Download subsets of the MATH dataset to local JSONL files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from datasets import load_dataset
+
+
+def extract_examples(dataset: Any, *, limit: int | None) -> list[dict[str, str]]:
+    if limit is not None:
+        dataset = dataset.select(range(min(limit, len(dataset))))
+    examples: list[dict[str, str]] = []
+    for item in dataset:
+        problem = (item.get("problem") or "").strip()
+        solution = item.get("solution") or ""
+        if isinstance(solution, list):
+            solution = "\n".join(str(part) for part in solution)
+        examples.append(
+            {
+                "problem": problem,
+                "solution": solution,
+            }
+        )
+    return examples
+
+
+def write_jsonl(path: Path, rows: list[dict[str, str]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as fh:
+        for row in rows:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Download MATH dataset splits to JSONL for offline use"
+    )
+    parser.add_argument(
+        "--output-dir", default="examples/rl/data", help="Directory to write <split>.jsonl files"
+    )
+    parser.add_argument(
+        "--dataset",
+        default="nlile/hendrycks-MATH-benchmark",
+        help="Hugging Face dataset identifier",
+    )
+    parser.add_argument(
+        "--config", default="algebra", help="Hugging Face dataset config (if required)"
+    )
+    parser.add_argument(
+        "--splits", nargs="*", default=["train", "validation", "test"], help="Splits to download"
+    )
+    parser.add_argument(
+        "--limit", type=int, default=None, help="Optional cap on examples per split"
+    )
+    args = parser.parse_args()
+
+    output_dir = Path(args.output_dir).expanduser()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    for split in args.splits:
+        print(f"[INFO] Downloading {args.dataset} ({args.config}) split={split}")
+        if args.config:
+            dataset = load_dataset(args.dataset, args.config, split=split)
+        else:
+            dataset = load_dataset(args.dataset, split=split)
+        rows = extract_examples(dataset, limit=args.limit)
+        out_path = output_dir / f"{split}.jsonl"
+        write_jsonl(out_path, rows)
+        print(f"[INFO] Wrote {len(rows)} examples to {out_path}")
+
+    print("Done. Set MATH_DATASET_LOCAL_DIR to the output directory when serving the task app.")
+
+
+if __name__ == "__main__":
+    main()

synth_ai/__init__.py

@@ -2,6 +2,28 @@
 Synth AI - Software for aiding the best and multiplying the will.
 """
 
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+from importlib.metadata import PackageNotFoundError
+from pathlib import Path
+
+try:  # Prefer the installed package metadata when available
+    __version__ = _metadata.version("synth-ai")
+except PackageNotFoundError:  # Fallback to pyproject version for editable installs
+    try:
+        import tomllib as _toml  # Python 3.11+
+    except ModuleNotFoundError:  # pragma: no cover - legacy interpreter guard
+        import tomli as _toml  # type: ignore[no-redef]
+
+    try:
+        pyproject_path = Path(__file__).resolve().parents[1] / "pyproject.toml"
+        with pyproject_path.open("rb") as fh:
+            _pyproject = _toml.load(fh)
+        __version__ = str(_pyproject["project"]["version"])
+    except Exception:
+        __version__ = "0.0.0.dev0"
+
 # Environment exports - moved from synth-env
 from synth_ai.environments import *  # noqa
 import synth_ai.environments as environments  # expose module name for __all__
@@ -21,12 +43,22 @@ try:
 except Exception:
     AsyncOpenAI = OpenAI = None  # type: ignore
 
+# Judge API contract schemas
+from synth_ai.judge_schemas import (
+    CriterionScorePayload,
+    JudgeOptions,
+    JudgeScoreRequest,
+    JudgeScoreResponse,
+    JudgeTaskApp,
+    JudgeTracePayload,
+    ReviewPayload,
+)
+
 # Legacy tracing v1 is not required for v3 usage and can be unavailable in minimal envs.
 tracing = None  # type: ignore
 EventPartitionElement = RewardSignal = SystemTrace = TrainingQuestion = None  # type: ignore
 trace_event_async = trace_event_sync = upload = None  # type: ignore
 
-__version__ = "0.2.6.dev4"
 __all__ = [
     "LM",
     "OpenAI",
@@ -34,4 +66,12 @@ __all__ = [
     "Anthropic",
     "AsyncAnthropic",
     "environments",
+    # Judge API contracts
+    "JudgeScoreRequest",
+    "JudgeScoreResponse",
+    "JudgeOptions",
+    "JudgeTaskApp",
+    "JudgeTracePayload",
+    "ReviewPayload",
+    "CriterionScorePayload",
 ]  # Explicitly define public API (v1 tracing omitted in minimal env)

synth_ai/api/train/builders.py

@@ -1,31 +1,45 @@
 from __future__ import annotations
 
 import importlib
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, cast
 
 import click
+from pydantic import ValidationError
 
 try:
-    _models_module = importlib.import_module("synth_ai.api.models.supported")
-    UnsupportedModelError = _models_module.UnsupportedModelError
-    ensure_allowed_model = _models_module.ensure_allowed_model
-    normalize_model_identifier = _models_module.normalize_model_identifier
+    _models_module = cast(
+        Any, importlib.import_module("synth_ai.api.models.supported")
+    )
+    UnsupportedModelError = cast(type[Exception], _models_module.UnsupportedModelError)
+    ensure_allowed_model = cast(
+        Callable[..., None], _models_module.ensure_allowed_model
+    )
+    normalize_model_identifier = cast(
+        Callable[[str], str], _models_module.normalize_model_identifier
+    )
 except Exception as exc:  # pragma: no cover - critical dependency
     raise RuntimeError("Unable to load supported model helpers") from exc
 
 try:
-    prepare_sft_job_payload = importlib.import_module("synth_ai.learning.sft.config").prepare_sft_job_payload
+    _sft_module = cast(
+        Any, importlib.import_module("synth_ai.learning.sft.config")
+    )
+    prepare_sft_job_payload = cast(
+        Callable[..., dict[str, Any]], _sft_module.prepare_sft_job_payload
+    )
 except Exception as exc:  # pragma: no cover - critical dependency
     raise RuntimeError("Unable to load SFT payload helpers") from exc
 
+from .configs import RLConfig, SFTConfig
 from .supported_algos import (
     AlgorithmValidationError,
     ensure_model_supported_for_algorithm,
     validate_algorithm_config,
 )
-from .utils import TrainError, ensure_api_base, load_toml
+from .utils import TrainError, ensure_api_base
 
 
 @dataclass(slots=True)
@@ -42,6 +56,16 @@ class SFTBuildResult:
     validation_file: Path | None
 
 
+def _format_validation_error(path: Path, exc: ValidationError) -> str:
+    lines: list[str] = []
+    for error in exc.errors():
+        loc = ".".join(str(part) for part in error.get("loc", ()))
+        msg = error.get("msg", "invalid value")
+        lines.append(f"{loc or '<root>'}: {msg}")
+    details = "\n".join(f"  - {line}" for line in lines) or "  - Invalid configuration"
+    return f"Config validation failed ({path}):\n{details}"
+
+
 def build_rl_payload(
     *,
     config_path: Path,
@@ -50,13 +74,30 @@ def build_rl_payload(
     idempotency: str | None,
     allow_experimental: bool | None = None,
 ) -> RLBuildResult:
-    data = load_toml(config_path)
     try:
-        spec = validate_algorithm_config(data.get("algorithm"), expected_family="rl")
+        rl_cfg = RLConfig.from_path(config_path)
+    except ValidationError as exc:
+        raise click.ClickException(_format_validation_error(config_path, exc)) from exc
+
+    data = rl_cfg.to_dict()
+    # Ensure required [reference] section for backend validators
+    try:
+        ref_cfg = data.get("reference") if isinstance(data, dict) else None
+        if not isinstance(ref_cfg, dict):
+            data["reference"] = {"placement": "none"}
+        else:
+            ref_cfg.setdefault("placement", "none")
+    except Exception:
+        # Defensive: never fail builder due to optional defaults
+        data["reference"] = {"placement": "none"}
+    try:
+        spec = validate_algorithm_config(
+            rl_cfg.algorithm.model_dump(), expected_family="rl"
+        )
     except AlgorithmValidationError as exc:
         raise click.ClickException(str(exc)) from exc
     services = data.get("services") if isinstance(data.get("services"), dict) else {}
-    model_cfg = data.get("model") if isinstance(data.get("model"), dict) else {}
+    model_cfg = rl_cfg.model
 
     final_task_url = (
         overrides.get("task_url")
@@ -69,10 +110,8 @@ def build_rl_payload(
             "Task app URL required (provide --task-url or set services.task_url in TOML)"
         )
 
-    raw_source = model_cfg.get("source") if isinstance(model_cfg, dict) else ""
-    model_source = str(raw_source or "").strip()
-    raw_base = model_cfg.get("base") if isinstance(model_cfg, dict) else ""
-    model_base = str(raw_base or "").strip()
+    model_source = (model_cfg.source or "").strip()
+    model_base = (model_cfg.base or "").strip()
     override_model = (overrides.get("model") or "").strip()
     if override_model:
         model_source = override_model
@@ -98,7 +137,7 @@ def build_rl_payload(
         if model_source:
             model_source = normalize_model_identifier(model_source)
         if model_base:
-            model_base = normalize_model_identifier(model_base, allow_finetuned_prefixes=False)
+            model_base = normalize_model_identifier(model_base)
     except UnsupportedModelError as exc:
         raise click.ClickException(str(exc)) from exc
 
@@ -160,22 +199,23 @@ def build_sft_payload(
     dataset_override: Path | None,
     allow_experimental: bool | None,
 ) -> SFTBuildResult:
-    data = load_toml(config_path)
     try:
-        spec = validate_algorithm_config(data.get("algorithm"), expected_family="sft")
+        sft_cfg = SFTConfig.from_path(config_path)
+    except ValidationError as exc:
+        raise TrainError(_format_validation_error(config_path, exc)) from exc
+
+    data = sft_cfg.to_dict()
+    try:
+        algo_mapping = sft_cfg.algorithm.model_dump() if sft_cfg.algorithm else None
+        spec = validate_algorithm_config(algo_mapping, expected_family="sft")
     except AlgorithmValidationError as exc:
         raise TrainError(str(exc)) from exc
-    job_cfg = data.get("job") if isinstance(data.get("job"), dict) else {}
     data_cfg = data.get("data") if isinstance(data.get("data"), dict) else {}
     hp_cfg = data.get("hyperparameters") if isinstance(data.get("hyperparameters"), dict) else {}
     train_cfg = data.get("training") if isinstance(data.get("training"), dict) else {}
     compute_cfg = data.get("compute") if isinstance(data.get("compute"), dict) else {}
 
-    raw_dataset = (
-        dataset_override
-        or (job_cfg.get("data") if isinstance(job_cfg, dict) else None)
-        or (job_cfg.get("data_path") if isinstance(job_cfg, dict) else None)
-    )
+    raw_dataset = dataset_override or sft_cfg.job.data or sft_cfg.job.data_path
     if not raw_dataset:
         raise TrainError("Dataset not specified; pass --dataset or set [job].data")
     dataset_path = Path(raw_dataset)
@@ -260,9 +300,11 @@ def build_sft_payload(
             "enabled": bool(validation_cfg.get("enabled", True))
         }
 
-    raw_model = str(
-        job_cfg.get("model") if isinstance(job_cfg, dict) else None or data.get("model") or ""
-    ).strip()
+    raw_model = (sft_cfg.job.model or "").strip()
+    if not raw_model:
+        model_block = data.get("model")
+        if isinstance(model_block, str):
+            raw_model = model_block.strip()
     if not raw_model:
         raise TrainError("Model not specified; set [job].model or [model].base in the config")
 
@@ -274,10 +316,12 @@ def build_sft_payload(
         )
     except UnsupportedModelError as exc:
         raise TrainError(str(exc)) from exc
-    try:
-        ensure_model_supported_for_algorithm(base_model, spec)
-    except AlgorithmValidationError as exc:
-        raise TrainError(str(exc)) from exc
+    
+    if base_model:
+        try:
+            ensure_model_supported_for_algorithm(base_model, spec)
+        except AlgorithmValidationError as exc:
+            raise TrainError(str(exc)) from exc
 
     try:
         payload = prepare_sft_job_payload(

synth_ai/api/train/cli.py

@@ -2,15 +2,17 @@ from __future__ import annotations
 
 import importlib
 import os
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 import click
 
 try:
-    _config_module = importlib.import_module("synth_ai.config.base_url")
-    get_backend_from_env = _config_module.get_backend_from_env
+    _config_module = cast(
+        Any, importlib.import_module("synth_ai.config.base_url")
+    )
+    get_backend_from_env = cast(Callable[[], str], _config_module.get_backend_from_env)
 except Exception as exc:  # pragma: no cover - critical dependency
     raise RuntimeError("Unable to load backend configuration helpers") from exc
 
@@ -238,8 +240,12 @@ def train_command(
     ]
     if missing_keys:
         try:
-            _task_apps_module = importlib.import_module("synth_ai.cli.task_apps")
-            _interactive_fill_env = _task_apps_module._interactive_fill_env
+            _task_apps_module = cast(
+                Any, importlib.import_module("synth_ai.cli.task_apps")
+            )
+            _interactive_fill_env = cast(
+                Callable[[Path], Path | None], _task_apps_module._interactive_fill_env
+            )
         except Exception as exc:  # pragma: no cover - protective fallback
             raise click.ClickException(f"Unable to prompt for env values: {exc}") from exc
 

synth_ai/api/train/configs/__init__.py

@@ -0,0 +1,44 @@
+"""Typed training config loaders for RL and SFT jobs."""
+
+from .rl import (
+    EvaluationConfig,
+    JudgeConfig,
+    JudgeOptionsConfig,
+    ModelConfig,
+    RLConfig,
+    RLServicesConfig,
+    RLTrainingConfig,
+    RolloutConfig,
+    WeightSyncConfig,
+)
+from .sft import (
+    HyperparametersConfig,
+    HyperparametersParallelism,
+    JobConfig,
+    SFTConfig,
+    SFTDataConfig,
+    TrainingConfig,
+    TrainingValidationConfig,
+)
+from .shared import AlgorithmConfig, ComputeConfig
+
+__all__ = [
+    "AlgorithmConfig",
+    "ComputeConfig",
+    "EvaluationConfig",
+    "HyperparametersConfig",
+    "HyperparametersParallelism",
+    "JobConfig",
+    "JudgeConfig",
+    "JudgeOptionsConfig",
+    "ModelConfig",
+    "RLConfig",
+    "RLServicesConfig",
+    "RLTrainingConfig",
+    "RolloutConfig",
+    "SFTConfig",
+    "SFTDataConfig",
+    "TrainingConfig",
+    "TrainingValidationConfig",
+    "WeightSyncConfig",
+]