agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/recipes/smartsearch_curriculum.py

@@ -0,0 +1,283 @@
+"""Pinned native SmartSearch curriculum preparation, separate from inference.
+
+These APIs do not train a model or manufacture process rewards. They consume
+recorded training-only rollouts and call the original redundancy/SFT/DPO/prefix
+converters. The complete SFT/DPO/GRPO training recipe remains a separate gate.
+"""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import importlib.util
+import io
+import json
+import math
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agentinputlab.contracts import ExternalDependencyError, ValidationError
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping, to_jsonable
+
+from .smartsearch import SMARTSEARCH_UPSTREAM_COMMIT
+
+_FILES = {
+    "redundancy": "scripts/data_construction/detect_redundancy.py",
+    "sft": "scripts/data_construction/transfer_sft.py",
+    "dpo": "scripts/data_construction/transfer_dpo.py",
+    "prefix": "scripts/data_construction/transfer_regenerate.py",
+    "reward": "scripts/data_construction/process_reward.py",
+    "refinement": "scripts/data_construction/query_refinement.py",
+}
+_PREPARATION_KEYS = ("redundancy", "sft", "dpo", "prefix")
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchTrainingCase:
+    case_id: str
+    question: str
+    split: str
+    source_reference: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.case_id, str) or not self.case_id.strip():
+            raise ValidationError("SmartSearch training case requires a non-empty ID")
+        if not isinstance(self.question, str) or not self.question.strip():
+            raise ValidationError("SmartSearch training case requires a non-empty question")
+        if self.split not in {"train", "validation", "test"}:
+            raise ValidationError("SmartSearch training case split is invalid")
+        try:
+            object.__setattr__(self, "source_reference", freeze_mapping(self.source_reference))
+        except (TypeError, ValueError) as exc:
+            raise ValidationError("SmartSearch case provenance is not canonical JSON") from exc
+
+
+def _question_hash(question: str) -> str:
+    # This additional overlap check is not a model-input transformation.
+    return content_hash(" ".join(question.split()).casefold())
+
+
+def validate_smartsearch_training_splits(
+    train: Sequence[SmartSearchTrainingCase],
+    validation: Sequence[SmartSearchTrainingCase],
+    test: Sequence[SmartSearchTrainingCase] = (),
+) -> Mapping[str, Any]:
+    if not train or not validation:
+        raise ValidationError("SmartSearch curriculum needs non-empty training and validation collections")
+    audit = {}
+    seen_ids: set[str] = set()
+    seen_questions: set[str] = set()
+    for name, cases in (("train", train), ("validation", validation), ("test", test)):
+        if any(not isinstance(case, SmartSearchTrainingCase) or case.split != name for case in cases):
+            raise ValidationError("SmartSearch curriculum case split label mismatch")
+        ids = tuple(case.case_id for case in cases)
+        hashes = tuple(_question_hash(case.question) for case in cases)
+        if len(ids) != len(set(ids)) or len(hashes) != len(set(hashes)):
+            raise ValidationError("SmartSearch curriculum split contains duplicate IDs/questions")
+        if set(ids) & seen_ids or set(hashes) & seen_questions:
+            raise ValidationError("SmartSearch fitting, validation and test collections overlap")
+        seen_ids.update(ids)
+        seen_questions.update(hashes)
+        audit[name] = {"case_ids": ids, "question_hashes": hashes,
+                       "case_hashes": tuple(content_hash(case) for case in cases)}
+    return freeze_mapping(audit)
+
+
+def verify_smartsearch_preparation_source(
+    checkout: str | Path, *, include_teacher: bool = False,
+) -> Mapping[str, Any]:
+    """Bind the exact upstream Git objects and their on-disk converter bytes."""
+    root = Path(checkout)
+    if root.is_symlink() or not root.is_dir():
+        raise ExternalDependencyError("SmartSearch preparation requires a regular pinned Git checkout")
+    root = root.resolve()
+
+    def git(*args: str) -> bytes:
+        try:
+            result = subprocess.run(
+                ["git", "-c", "core.fsmonitor=false", "-c", f"core.hooksPath={os.devnull}",
+                 "-C", str(root), *args], capture_output=True, check=True, timeout=30,
+                env={"PATH": os.defpath, "LANG": "C", "LC_ALL": "C",
+                     "GIT_CONFIG_NOSYSTEM": "1", "GIT_CONFIG_GLOBAL": os.devnull,
+                     "GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0"},
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise ExternalDependencyError("SmartSearch preparation source Git verification failed") from exc
+        return result.stdout
+
+    if git("rev-parse", "HEAD").decode().strip() != SMARTSEARCH_UPSTREAM_COMMIT:
+        raise ExternalDependencyError("SmartSearch preparation source revision changed")
+    if Path(git("rev-parse", "--show-toplevel").decode().strip()).resolve() != root:
+        raise ExternalDependencyError("SmartSearch preparation checkout is not the repository root")
+    if git("status", "--porcelain", "--untracked-files=all").strip():
+        raise ExternalDependencyError("SmartSearch preparation requires an unchanged source checkout")
+    files = {}
+    keys = tuple(_FILES) if include_teacher else _PREPARATION_KEYS
+    for relative in (_FILES[key] for key in keys):
+        path = root
+        for component in Path(relative).parts:
+            path = path / component
+            if path.is_symlink():
+                raise ExternalDependencyError("SmartSearch preparation source contains a symlink")
+        if not path.is_file():
+            raise ExternalDependencyError(f"SmartSearch native preparation file is missing: {relative}")
+        actual = path.read_bytes()
+        expected = git("show", f"{SMARTSEARCH_UPSTREAM_COMMIT}:{relative}")
+        if actual != expected:
+            raise ExternalDependencyError(f"SmartSearch native preparation file changed: {relative}")
+        files[relative] = hashlib.sha256(actual).hexdigest()
+    return freeze_mapping({"source_commit": SMARTSEARCH_UPSTREAM_COMMIT, "files": files,
+                           "root": str(root), "preparation_math_modified": False})
+
+
+def _native_converter(root: Path, key: str, source: Mapping[str, Any]) -> Any:
+    path = root / _FILES[key]
+    source_bytes = path.read_bytes()
+    if hashlib.sha256(source_bytes).hexdigest() != source["files"][_FILES[key]]:
+        raise ExternalDependencyError("SmartSearch preparation source changed before import")
+    name = f"_agentinputlab_smartsearch_{key}_{source['files'][_FILES[key]][:12]}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ExternalDependencyError("SmartSearch native converter could not be imported")
+    module = importlib.util.module_from_spec(spec)
+    try:
+        # Compile the verified bytes, never an unbound pre-existing .pyc cache.
+        exec(compile(source_bytes, str(path), "exec"), module.__dict__)
+    except ImportError as exc:
+        raise ExternalDependencyError("Install agentinputlab[smartsearch-prepare] in the preparation worker") from exc
+    class_name = {"redundancy": "Redundancy", "reward": "SearchEvaluation",
+                  "refinement": "Rewrite"}.get(key, "Transfer")
+    constructor = getattr(module, class_name, None)
+    if not callable(constructor):
+        raise ExternalDependencyError("SmartSearch native converter class signature changed")
+    return constructor("controlled-provider-no-network") if key in {"reward", "refinement"} else constructor()
+
+
+def _scored_rows(
+    value: Sequence[Mapping[str, Any]], allowed_questions: set[str], max_rows: int,
+) -> list[dict[str, Any]]:
+    if not isinstance(value, (tuple, list)) or len(value) > max_rows:
+        raise ValidationError("SmartSearch recorded rollout collection exceeds its explicit bound")
+    rows = []
+    for row in value:
+        if not isinstance(row, Mapping) or row.get("question") not in allowed_questions:
+            raise ValidationError("SmartSearch curriculum rollout is outside the allowed training questions")
+        if not isinstance(row.get("response"), str) or not isinstance(row.get("process_scores"), (list, tuple)):
+            raise ValidationError("SmartSearch curriculum requires recorded response and process scores")
+        metric = row.get("outcome_score")
+        score = metric.get("f1") if isinstance(metric, Mapping) else None
+        if isinstance(score, bool) or not isinstance(score, (float, int)) or not math.isfinite(score) or not 0 <= score <= 1:
+            raise ValidationError("SmartSearch curriculum requires a measured finite outcome F1")
+        for process in row["process_scores"]:
+            if not isinstance(process, Mapping) or not isinstance(process.get("score"), str) or process["score"] not in {"", "0", "1"}:
+                raise ValidationError("SmartSearch native process-score representation is invalid")
+        try:
+            rows.append(json.loads(json.dumps(to_jsonable(row), allow_nan=False)))
+        except (TypeError, ValueError) as exc:
+            raise ValidationError("SmartSearch scored rollout is not canonical JSON") from exc
+    return rows
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchCurriculumArtifact:
+    root: str
+    artifact_id: str
+    sft_count: int
+    dpo_count: int
+    prefix_count: int
+    source_fingerprint_sha256: str
+    split_audit_sha256: str
+    output_hashes: Mapping[str, str]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "output_hashes", freeze_mapping(self.output_hashes))
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchCurriculumPreparation:
+    max_rollout_rows: int = 1000
+    max_input_bytes: int = 16 * 1024 * 1024
+
+    def __post_init__(self) -> None:
+        if type(self.max_rollout_rows) is not int or self.max_rollout_rows < 1 or (
+            type(self.max_input_bytes) is not int or self.max_input_bytes < 1
+        ):
+            raise ValidationError("SmartSearch curriculum limits must be positive integers")
+
+    def prepare(
+        self, *, checkout: str | Path, output_root: str | Path,
+        train: Sequence[SmartSearchTrainingCase], validation: Sequence[SmartSearchTrainingCase],
+        initial_scored_rollouts: Sequence[Mapping[str, Any]],
+        regenerated_scored_rollouts: Sequence[Mapping[str, Any]],
+        test: Sequence[SmartSearchTrainingCase] = (),
+        rollout_provenance: Mapping[str, Any],
+    ) -> SmartSearchCurriculumArtifact:
+        audit = validate_smartsearch_training_splits(train, validation, test)
+        if not isinstance(rollout_provenance, Mapping) or not rollout_provenance:
+            raise ValidationError("SmartSearch recorded rollouts require explicit producer provenance")
+        allowed = {case.question for case in train}
+        initial = _scored_rows(initial_scored_rollouts, allowed, self.max_rollout_rows)
+        regenerated = _scored_rows(regenerated_scored_rollouts, allowed, self.max_rollout_rows)
+        if not initial:
+            raise ValidationError("SmartSearch curriculum needs initial recorded training rollouts")
+        raw_inputs = {"initial": initial, "regenerated": regenerated,
+                      "producer_provenance": to_jsonable(rollout_provenance)}
+        encoded = json.dumps(raw_inputs, ensure_ascii=False, allow_nan=False).encode()
+        if len(encoded) > self.max_input_bytes:
+            raise ValidationError("SmartSearch curriculum input exceeds its explicit byte bound")
+        source = verify_smartsearch_preparation_source(checkout)
+        source_root = Path(source["root"])
+        root = Path(output_root)
+        if root.is_symlink() or root.exists():
+            raise ValidationError("SmartSearch curriculum output must be a new directory")
+        root = root.resolve(strict=False)
+        if root.is_relative_to(source_root) or source_root.is_relative_to(root):
+            raise ValidationError("SmartSearch curriculum outputs must not overlap source checkout")
+        root.mkdir(parents=True, exist_ok=False)
+
+        def save(name: str, value: Any) -> None:
+            with (root / name).open("x", encoding="utf-8") as stream:
+                json.dump(to_jsonable(value), stream, ensure_ascii=False, sort_keys=True, allow_nan=False)
+
+        save("claim.json", {"source": source, "split_audit": audit, "input_hash": content_hash(raw_inputs),
+                            "rollout_provenance": rollout_provenance, "model_calls_performed": 0})
+        try:
+            with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+                redundancy = _native_converter(source_root, "redundancy", source)
+                initial_checked = redundancy.detect_redundancy(initial)
+                regenerated_checked = redundancy.detect_redundancy(regenerated)
+                sft = _native_converter(source_root, "sft", source).transfer(initial_checked)
+                dpo = _native_converter(source_root, "dpo", source).transfer(initial_checked, regenerated_checked)
+                prefix = _native_converter(source_root, "prefix", source).transfer(initial_checked)
+            for values in (sft, dpo, prefix):
+                if not isinstance(values, list):
+                    raise ExternalDependencyError("SmartSearch native converter returned a non-list")
+            for relative, digest in source["files"].items():
+                if hashlib.sha256((source_root / relative).read_bytes()).hexdigest() != digest:
+                    raise ExternalDependencyError("SmartSearch preparation source changed during execution")
+            outputs = {"native-initial-scored.json": initial_checked,
+                       "native-regenerated-scored.json": regenerated_checked,
+                       "sft.json": sft, "dpo.json": dpo, "prefix.json": prefix}
+            for name, value in outputs.items():
+                save(name, value)
+            hashes = {name: hashlib.sha256((root / name).read_bytes()).hexdigest() for name in outputs}
+            manifest = {"schema": "agentinputlab.smartsearch.native-curriculum-data.v1",
+                        "source": source, "split_audit": audit, "outputs": hashes,
+                        "sft_count": len(sft), "dpo_count": len(dpo), "prefix_count": len(prefix),
+                        "initial_rollout_count": len(initial), "regenerated_rollout_count": len(regenerated),
+                        "input_hash": content_hash(raw_inputs), "rollout_provenance": rollout_provenance,
+                        "model_calls_performed": 0, "neural_training_performed": False,
+                        "native_selection_thresholds_changed": False, "empty_selection_is_not_training_success": True}
+            artifact_id = content_hash(manifest)
+            save("manifest.json", {**manifest, "artifact_id": artifact_id})
+            return SmartSearchCurriculumArtifact(
+                str(root), artifact_id, len(sft), len(dpo), len(prefix), content_hash(source),
+                content_hash(audit), hashes,
+            )
+        except Exception as exc:
+            save("failed.json", {"error_type": type(exc).__name__, "error": str(exc),
+                                 "model_calls_performed": 0, "neural_training_performed": False})
+            raise

agentinputlab/recipes/smartsearch_grpo_contracts.py

@@ -0,0 +1,58 @@
+"""Execution contracts for the pinned native GRPO driver, not reward math.
+
+The native manager omits ``reward_extra_info`` while its PPO driver indexes
+that key and catches failures by invoking the manager again. Complete the
+dictionary without another scoring pass, and latch failures across the whole
+batch so a fallback cannot repeat already consumed helper calls.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from agentinputlab.contracts import ExternalDependencyError, ValidationError
+
+
+class NativeGRPORewardManagerContract:
+    """Keep native rewards unchanged and prohibit automatic batch retries.
+
+    This adapter does not itself load a model or certify a GRPO fit. The
+    execution worker must construct its manager from the verified native
+    source, bind the metered scorer, and retain original per-item costs.
+    """
+
+    def __init__(self, native_manager):
+        if not callable(native_manager):
+            raise ValidationError("SmartSearch GRPO requires a callable native reward manager")
+        self.native_manager = native_manager
+        self.native_calls = 0
+        self._failed = False
+
+    def __call__(self, data, return_dict=False, curr_save_path=None):
+        if self._failed:
+            raise ExternalDependencyError("SmartSearch native reward batch failed; no automatic scoring retry")
+        if type(return_dict) is not bool:
+            raise ValidationError("SmartSearch reward dictionary flag must be a boolean")
+        try:
+            self.native_calls += 1
+            result = self.native_manager(data, return_dict=return_dict, curr_save_path=curr_save_path)
+            if not return_dict:
+                return result
+            if not isinstance(result, Mapping):
+                # The native manager's explicit cached-rm branch returns the
+                # exact cached tensor, even when return_dict=True.
+                batch = getattr(data, "batch", None)
+                cached = batch.get("rm_scores") if hasattr(batch, "get") else None
+                if cached is None or result is not cached:
+                    raise ExternalDependencyError("SmartSearch native reward dictionary contract differs")
+                result = {"reward_tensor": result}
+            if "reward_tensor" not in result or result["reward_tensor"] is None:
+                raise ExternalDependencyError("SmartSearch native reward tensor is missing")
+            extras = result.get("reward_extra_info", {})
+            if not isinstance(extras, Mapping):
+                raise ExternalDependencyError("SmartSearch native reward extra-info mapping differs")
+            # Preserve the original tensor object and existing extra fields.
+            # No tensor arithmetic, rescaling, default positive or re-score.
+            return {**result, "reward_extra_info": extras}
+        except BaseException:
+            self._failed = True
+            raise

agentinputlab/recipes/smartsearch_grpo_data.py

@@ -0,0 +1,314 @@
+"""Pinned native SmartSearch GRPO data/configuration, with explicit split roles."""
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from agentinputlab.contracts import ExternalDependencyError, ValidationError
+from agentinputlab.contracts.serialization import content_hash, to_jsonable
+
+from .qrag import _file, _sha
+from .smartsearch import SMARTSEARCH_TOOL_SCHEMA
+from .smartsearch_curriculum import (
+    SmartSearchTrainingCase,
+    _question_hash,
+    validate_smartsearch_training_splits,
+)
+from .smartsearch_grpo_tools import SMARTSEARCH_GRPO_ENVIRONMENT
+from .smartsearch_sampling import verify_smartsearch_sampling_source
+
+GRPO_DATA_PROTOCOL = "agentinputlab.smartsearch.native_grpo_data.v1"
+_SOURCE = {
+    "data/prepare_dataset.py": "abf1dc41c410e8716c02b8651c9ef3fb3bbba6d52b50ae86db8325ecf5154554",
+    "scripts/train/train.sh": "07903f49e46bf18a0d764b6e92c1430d0a651523751fee653dec112379c66d72",
+    "src/verl/trainer/main_ppo.py": "6eace6c898923fe2e25081f473801c9439a709eb02d1968944f1f2cd2602f258",
+    "src/verl/trainer/config/ppo_trainer.yaml": "8a239cda92c40d520df0344857b5f51d6550254c449d28841e1de3f5b3feb1d7",
+    "src/verl/utils/dataset/rl_dataset.py": "06a599f81f7288fdd183111b15207c37e0c32e2d9399c8e9289edba637bf5f26",
+    "src/verl/workers/rollout/vllm_rollout/generate_new_prompts.py": "bc1f7d2a16d599e7f180406c9cd356034f1bb5ce0e97b5fb09d6264a11511615",
+    "src/verl/workers/rollout/vllm_rollout/vllm_rollout_spmd.py": "064aa3d6682149620c5b55239379199130941dc05d6fc5ed13026987b2867453",
+    "src/verl/workers/reward_manager/re_call.py": "0b239aaa9ee0c21b693359569e3f091bc650d537d7cf2a63e478c8fb4d976a7b",
+    "src/verl/trainer/ppo/ray_trainer.py": "465e1b53dfa9f0bfcdb597957cef64ea18941e5e75a2af17a48c0ecfd00ab3e2",
+    "src/verl/workers/actor/dp_actor.py": "09923f0891e2ca913e1eb860bfa7e62537b10b1f4527b9647784f7063ba86a8d",
+    "src/verl/workers/fsdp_workers.py": "65aa287db53a3308d5b579f47cf557ab8333231e26625ed62bbb65ca90153833",
+    "src/verl/utils/checkpoint/fsdp_checkpoint_manager.py": "640556d9c0801602818fcfd52aa6d2d066b49bf30f30eb0a81c08efde2495f4a",
+}
+
+
+def verify_smartsearch_grpo_source(checkout):
+    root, binding = verify_smartsearch_sampling_source(checkout)
+    for name, expected in _SOURCE.items():
+        path = _file(root / name, "SmartSearch native GRPO source")
+        if not path.is_relative_to(root) or _sha(path) != expected:
+            raise ExternalDependencyError("SmartSearch native GRPO source/configuration changed")
+    return root, {**binding, "grpo_source": dict(_SOURCE)}
+
+
+def _save(root, name, value):
+    encoded = json.dumps(to_jsonable(value), ensure_ascii=False, sort_keys=True, allow_nan=False)
+    with (root / name).open("x", encoding="utf-8") as stream:
+        stream.write(encoded)
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchGRPOExample:
+    case: SmartSearchTrainingCase
+    golden_answers: tuple[str, ...]
+
+    def __post_init__(self):
+        if not isinstance(self.case, SmartSearchTrainingCase) or self.case.split not in {"train", "validation"}:
+            raise ValidationError("SmartSearch GRPO examples must declare training/development case roles")
+        answers = self.golden_answers
+        if not isinstance(answers, (tuple, list)) or not answers or any(
+            not isinstance(value, str) or not value.strip() for value in answers
+        ):
+            raise ValidationError("SmartSearch GRPO examples require nonempty native reference answers")
+        object.__setattr__(self, "golden_answers", tuple(answers))
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchGRPODataArtifact:
+    root: Path
+    artifact_id: str
+    train_rows: int
+    validation_rows: int
+
+    @classmethod
+    def load(cls, root, *, max_rows=10000, max_file_bytes=64 * 1024 * 1024):
+        if any(type(n) is not int or n < 1 for n in (max_rows, max_file_bytes)):
+            raise ValidationError("SmartSearch GRPO artifact read limits must be positive integers")
+        folder = Path(root)
+        if folder.is_symlink() or not folder.is_dir():
+            raise ValidationError("SmartSearch GRPO data artifact must be a regular directory")
+        folder = folder.resolve()
+        record = json.loads(_file(folder / "manifest.json", "GRPO data manifest").read_text())
+        identity = record.pop("artifact_id", None)
+        if record.get("schema") != GRPO_DATA_PROTOCOL or identity != content_hash(record):
+            raise ValidationError("SmartSearch GRPO data artifact identity differs")
+        if set(record.get("outputs", {})) != {"train.parquet", "validation.parquet"}:
+            raise ValidationError("SmartSearch GRPO data artifact has an incomplete closure")
+        for name, digest in record["outputs"].items():
+            path = _file(folder / name, "GRPO native data")
+            if path.stat().st_size > max_file_bytes or _sha(path) != digest:
+                raise ValidationError("SmartSearch GRPO native data bytes changed")
+        for key in ("train_rows", "validation_rows"):
+            if type(record.get(key)) is not int or record[key] < 1:
+                raise ValidationError("SmartSearch GRPO data has an empty declared split")
+        try:
+            import pyarrow.parquet as pq
+        except ImportError as exc:
+            raise ExternalDependencyError("Install agentinputlab[benchmarks] to verify native GRPO data") from exc
+        for split in ("train", "validation"):
+            path = folder / f"{split}.parquet"
+            declared = record[split + "_rows"]
+            if pq.read_metadata(path).num_rows != declared or declared > max_rows:
+                raise ValidationError("SmartSearch GRPO parquet row count differs or exceeds its read limit")
+            rows = pq.read_table(path).to_pylist()
+            hashes = []
+            for row in rows:
+                if set(row) != {"data_source", "question", "ability", "reward_model", "extra_info"} or (
+                    row["data_source"] != "re_call" or row["ability"] != "re_call"
+                ) or not isinstance(row["question"], str) or not row["question"].strip():
+                    raise ValidationError("SmartSearch GRPO native logical fields differ")
+                reward, extra = row["reward_model"], row["extra_info"]
+                if not isinstance(reward, dict) or set(reward) != {"style", "ground_truth"} or (
+                    reward["style"] != "rule" or not isinstance(reward["ground_truth"], list)
+                    or not reward["ground_truth"] or any(not isinstance(v, str) or not v.strip() for v in reward["ground_truth"])
+                ) or not isinstance(extra, dict) or set(extra) != {"env", "func_schemas"} or (
+                    extra["env"] != SMARTSEARCH_GRPO_ENVIRONMENT
+                    or json.loads(extra["func_schemas"]) != to_jsonable(SMARTSEARCH_TOOL_SCHEMA)
+                ):
+                    raise ValidationError("SmartSearch GRPO reference/tool field contract differs")
+                hashes.append(_question_hash(row["question"]))
+            audit = record.get("split_audit", {}).get(split, {})
+            if hashes != audit.get("question_hashes") or len(set(hashes)) != declared:
+                raise ValidationError("SmartSearch GRPO native questions differ from their declared split")
+        if set(record["split_audit"]["train"]["question_hashes"]) & set(
+            record["split_audit"]["validation"]["question_hashes"]
+        ):
+            raise ValidationError("SmartSearch GRPO data artifact splits overlap")
+        return cls(folder, identity, record["train_rows"], record["validation_rows"])
+
+
+def prepare_smartsearch_grpo_data(
+    *, checkout, output_root, train: Sequence[SmartSearchGRPOExample],
+    validation: Sequence[SmartSearchGRPOExample], data_provenance: Mapping,
+    test: Sequence[SmartSearchTrainingCase] = (), max_rows: int = 10000,
+    max_input_bytes: int = 64 * 1024 * 1024,
+):
+    """Write exact native logical rows without upstream's test-to-dev sampling.
+
+    Corpus/retrieval is a separate frozen input. References remain in reward_model
+    and never enter the question field. The environment is replaced with the
+    fixed non-executable retrieval identifier. No model is loaded or fit here.
+    """
+    if any(type(n) is not int or n < 1 for n in (max_rows, max_input_bytes)) or (
+        not isinstance(data_provenance, Mapping) or not data_provenance
+    ):
+        raise ValidationError("SmartSearch GRPO preparation needs explicit limits and provenance")
+    for rows in (train, validation):
+        if not isinstance(rows, (tuple, list)) or not rows or len(rows) > max_rows or any(
+            not isinstance(row, SmartSearchGRPOExample) for row in rows
+        ):
+            raise ValidationError("SmartSearch GRPO preparation split exceeds its explicit row bound")
+    train, validation = tuple(train), tuple(validation)
+    data_provenance = to_jsonable(data_provenance)
+    audit = validate_smartsearch_training_splits([r.case for r in train], [r.case for r in validation], test)
+    encoded = json.dumps(to_jsonable({"train": train, "validation": validation,
+                                     "provenance": data_provenance}), allow_nan=False).encode()
+    if len(encoded) > max_input_bytes:
+        raise ValidationError("SmartSearch GRPO data inputs exceed the explicit byte bound")
+    source, binding = verify_smartsearch_grpo_source(checkout)
+    root = Path(output_root)
+    if root.is_symlink() or root.exists():
+        raise ValidationError("SmartSearch GRPO preparation must be create-only")
+    root = root.resolve(strict=False)
+    if root.is_relative_to(source) or source.is_relative_to(root):
+        raise ValidationError("SmartSearch GRPO preparation output must not overlap native source")
+    try:
+        import pyarrow as pa
+        import pyarrow.parquet as pq
+    except ImportError as exc:
+        raise ExternalDependencyError("Install agentinputlab[benchmarks] for native GRPO parquet data") from exc
+    root.mkdir(parents=True, exist_ok=False)
+    _save(root, "claim.json", {"source": binding, "split_audit": audit,
+          "inputs_sha256": content_hash({"train": train, "validation": validation}),
+          "data_provenance": data_provenance, "model_calls": 0, "optimizer_steps": 0})
+    try:
+        schema_text = json.dumps(to_jsonable(SMARTSEARCH_TOOL_SCHEMA), indent=4)
+        for name, rows in (("train", train), ("validation", validation)):
+            native_rows = [{"data_source": "re_call", "question": row.case.question,
+                 "ability": "re_call", "reward_model": {"style": "rule", "ground_truth": list(row.golden_answers)},
+                 "extra_info": {"env": SMARTSEARCH_GRPO_ENVIRONMENT, "func_schemas": schema_text}}
+                for row in rows]
+            pq.write_table(pa.Table.from_pylist(native_rows), root / f"{name}.parquet", compression="snappy")
+            if pq.read_table(root / f"{name}.parquet").to_pylist() != native_rows:
+                raise ExternalDependencyError("SmartSearch GRPO parquet roundtrip changed native rows")
+        manifest = {"schema": GRPO_DATA_PROTOCOL, "source": binding, "split_audit": audit,
+                    "train_rows": len(train), "validation_rows": len(validation),
+                    "outputs": {name: _sha(root / name) for name in ("train.parquet", "validation.parquet")},
+                    "data_provenance": data_provenance, "model_calls": 0, "optimizer_steps": 0,
+                    "native_logical_fields_unchanged": True, "fixed_environment_identifier_adapter": True,
+                    "no_native_test_to_dev_downsampling": True}
+        _save(root, "manifest.json", {**manifest, "artifact_id": content_hash(manifest)})
+        return SmartSearchGRPODataArtifact.load(root, max_rows=max_rows, max_file_bytes=max_input_bytes * 2 + 1024**2)
+    except Exception as exc:
+        _save(root, "failed.json", {"error_type": type(exc).__name__, "error": str(exc),
+                                    "model_calls": 0, "optimizer_steps": 0})
+        raise
+
+
+@dataclass(frozen=True, slots=True)
+class SmartSearchGRPOControls:
+    train_batch_size: int = 256
+    ppo_mini_batch_size: int = 64
+    rollout_samples: int = 8
+    total_epochs: int = 2
+    gpu_processes: int = 4
+    gpu_memory_utilization: float = .8
+    max_optimizer_steps: int = 10000
+    seed: int = 17
+    bounded_training_variant: bool = False
+
+    def __post_init__(self):
+        names = ("train_batch_size", "ppo_mini_batch_size", "rollout_samples", "total_epochs",
+                 "gpu_processes", "max_optimizer_steps")
+        if any(type(getattr(self, n)) is not int or getattr(self, n) < 1 for n in names) or (
+            type(self.seed) is not int or self.seed < 0 or type(self.bounded_training_variant) is not bool
+        ):
+            raise ValidationError("SmartSearch GRPO controls require explicit positive integer bounds")
+        if not 1 <= self.gpu_processes <= 4 or self.rollout_samples < 2 or (
+            self.ppo_mini_batch_size > self.train_batch_size or self.train_batch_size % self.ppo_mini_batch_size
+        ) or (self.train_batch_size * self.rollout_samples) % self.gpu_processes or (
+            (self.ppo_mini_batch_size * self.rollout_samples) % self.gpu_processes
+        ):
+            raise ValidationError("SmartSearch GRPO native batch/sample/GPU divisibility differs")
+        utilization = self.gpu_memory_utilization
+        if isinstance(utilization, bool) or not isinstance(utilization, (float, int)) or (
+            not math.isfinite(utilization) or not 0 < utilization <= .95
+        ):
+            raise ValidationError("SmartSearch GRPO GPU cache allowance is invalid")
+        if (self.train_batch_size, self.ppo_mini_batch_size, self.rollout_samples, self.total_epochs) != (
+            256, 64, 8, 2
+        ) and not self.bounded_training_variant:
+            raise ValidationError("Changing native GRPO batch/n/epochs requires an explicit labeled training variant")
+
+    def planned_steps(self, train_rows):
+        """Native dataloader/global steps, not the number of actor updates."""
+        if type(train_rows) is not int or train_rows < self.train_batch_size:
+            raise ValidationError("SmartSearch native drop_last would produce an empty GRPO training loader")
+        steps = train_rows // self.train_batch_size * self.total_epochs
+        if steps > self.max_optimizer_steps:
+            raise ValidationError("SmartSearch native optimizer plan exceeds the declared cap; it is not truncated")
+        return steps
+
+    def planned_actor_optimizer_steps(self, train_rows, *, ppo_epochs):
+        """Synchronized actor updates per rank, before any neural work.
+
+        Native FSDP normalizes the PPO minibatch by rollout_n/world_size;
+        those factors cancel when dividing each rank's local training batch.
+        Do not sum synchronized rank counters into extra distributed updates.
+        The executor must still meter actual optimizer calls on every rank.
+        """
+        if type(ppo_epochs) is not int or ppo_epochs < 1:
+            raise ValidationError("SmartSearch native PPO epochs must be a positive integer")
+        global_steps = self.planned_steps(train_rows)
+        steps = global_steps * (self.train_batch_size // self.ppo_mini_batch_size) * ppo_epochs
+        if steps > self.max_optimizer_steps:
+            raise ValidationError("SmartSearch native actor optimizer plan exceeds the declared cap; it is not truncated")
+        return steps
+
+
+def _native_grpo_config(source, *, model, data, output_root, controls, sandbox_url, reward_module):
+    try:
+        import yaml
+    except ImportError as exc:
+        raise ExternalDependencyError("Install agentinputlab[yaml] to build native GRPO config") from exc
+    if not isinstance(sandbox_url, str):
+        raise ValidationError("SmartSearch GRPO fixed tool URL must be operator-owned loopback HTTP")
+    try:
+        url = urlsplit(sandbox_url)
+        port = url.port
+    except ValueError as exc:
+        raise ValidationError("SmartSearch GRPO fixed tool URL is malformed") from exc
+    if url.scheme != "http" or url.hostname != "127.0.0.1" or not port or (
+        url.username or url.password or url.query or url.fragment
+    ):
+        raise ValidationError("SmartSearch GRPO fixed tool URL must be operator-owned loopback HTTP")
+    controls.planned_steps(data.train_rows)
+    config = yaml.safe_load((Path(source) / "src/verl/trainer/config/ppo_trainer.yaml").read_text())
+    config["data"].update(train_files=str(data.root / "train.parquet"), val_files=str(data.root / "validation.parquet"),
+        prompt_key="question", train_batch_size=controls.train_batch_size, max_prompt_length=8192,
+        max_response_length=8192, use_re_call=True, prompt_template_name="re_call_template_sys",
+        search_url=sandbox_url, filter_overlong_prompts=True, trust_remote_code=False, seed=controls.seed,
+        cache_dir=str(Path(output_root) / "data-cache"))
+    policy = config["actor_rollout_ref"]
+    policy["model"].update(path=str(model), enable_gradient_checkpointing=True, use_remove_padding=True)
+    actor = policy["actor"]
+    controls.planned_actor_optimizer_steps(data.train_rows, ppo_epochs=actor["ppo_epochs"])
+    actor["optim"]["lr"] = 1e-6
+    actor.update(ppo_mini_batch_size=controls.ppo_mini_batch_size, use_dynamic_bsz=True,
+                 ppo_max_token_len_per_gpu=32768, use_kl_loss=True, kl_loss_coef=.001, kl_loss_type="low_var_kl")
+    actor["fsdp_config"].update(param_offload=False, optimizer_offload=False)
+    # Preserve native shards plus its HF config/tokenizer metadata. The native
+    # checkpoint manager does NOT export HF weights; the live actor observer
+    # separately gathers the actual trained state into safe HF tensors.
+    actor["checkpoint"]["contents"] = [*actor["checkpoint"]["contents"], "hf_model"]
+    policy["rollout"].update(log_prob_max_token_len_per_gpu=65536, tensor_model_parallel_size=1,
+        name="vllm_with_tool", gpu_memory_utilization=controls.gpu_memory_utilization,
+        n=controls.rollout_samples, max_turns=5, sandbox_url=sandbox_url, enforce_eager=False, free_cache_engine=False)
+    policy["ref"]["log_prob_max_token_len_per_gpu"] = 65536
+    policy["ref"]["fsdp_config"]["param_offload"] = True
+    config["algorithm"].update(adv_estimator="grpo")
+    config["algorithm"]["kl_ctrl"]["kl_coef"] = .001
+    config["reward_model"]["reward_manager"] = "re_call"
+    config["custom_reward_function"].update(path=str(reward_module), name="compute_score")
+    config["trainer"].update(critic_warmup=0, logger=["console"], project_name="agentinputlab-smartsearch",
+        experiment_name="native-grpo", n_gpus_per_node=controls.gpu_processes, nnodes=1,
+        save_freq=10, test_freq=10, total_epochs=controls.total_epochs, resume_mode="disable",
+        resume_from_path=None, default_hdfs_dir=None, default_local_dir=str(output_root),
+        rollout_save_path=str(Path(output_root) / "rollouts"))
+    return config