pycurate 0.4.0__py3-none-any.whl

pycurate/__init__.py

@@ -0,0 +1,612 @@
+"""pycurate: data curation and curation auto-research. One verb that escalates:
+
+    import pycurate as pc
+
+    ds = pc.load("data/*.parquet")                                 # any tabular source -> a Lance-backed Dataset
+    cur = pc.curate(ds)                                            # 1. routes to the right domain, applies its default
+    cur = pc.curate(ds, eval=train_eval, budget=20)                # 2. + TPE tuning on your eval, guarded by the default
+    cur = pc.curate(ds, eval=train_eval, budget=20, agent=True)    # 3. + agent: literature signals, LLM-written recipes
+    cur.report                                                     # level, guard decision (pick vs default), trials
+    loader = cur.to_torch(columns=["text"], batch_size=256)        # zero-copy, globally shuffled training batches
+
+``pc.diagnose(ds)`` runs pre-flight checks; ``target_samples=`` makes curation compute-aware. ``agent=True`` is the
+only path that calls an LLM. Building blocks: ``pc.search`` (returns a ``SearchResult``), ``pc.prepare`` (compute /
+discover / register signals), ``pc.discover_signals``, ``pc.signals`` (catalog, provenance, protected columns),
+``pc.harness``, ``pc.research``. Domain modules load lazily: ``pc.text``, ``pc.labels``, ``pc.image_text``,
+``pc.sft``, ``pc.preference``, ``pc.rl``, ``pc.robotics``, ``pc.detection``, ``pc.segmentation``. Every curation decision is a :class:`Recipe` over signal
+columns. Docs: docs/index.md (``mkdocs serve``).
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .data import Dataset
+from .recipe import Recipe, RecipeError
+from .router import DOMAINS, detect
+
+__version__ = "0.4.0"
+__all__ = ["Dataset", "Recipe", "RecipeError", "Curated", "load", "curate", "diagnose", "search", "detect", "DOMAINS",
+           "default_knob_space", "prepare", "discover_signals", "Prepared", "AgentUnavailable", "LiteratureRequired",
+           "AGENT_STRATEGY"]
+
+_LAZY = {*DOMAINS, "core", "research", "compute", "io", "signals", "harness"}
+
+
+def __getattr__(name: str):
+    if name == "discover_signals":
+        from .signals.discover import discover_signals
+
+        return discover_signals
+    if name == "LiteratureRequired":
+        from .signals.discover import LiteratureRequired
+
+        return LiteratureRequired
+    if name in DOMAINS:
+        return importlib.import_module(f"pycurate.domains.{name}")
+    if name in _LAZY:
+        return importlib.import_module(f"pycurate.{name}")
+    raise AttributeError(f"module 'pycurate' has no attribute {name!r}")
+
+
+def load(source: Any, name: str | None = None, uri: str | None = None, overwrite: bool = False) -> Dataset:
+    """Open or ingest a dataset.
+
+    ``source``: an existing ``Dataset`` / lancedb table, a table name in ``uri``, parquet path(s) or glob,
+    a pandas / pyarrow table, a dict of arrays, or ``"hf://<repo>[:<split>]"`` for a Hugging Face dataset.
+    Ingesting into a ``name`` that already exists in ``uri`` raises unless ``overwrite=True``.
+    """
+    import glob as _glob
+    import os
+
+    from .data import DEFAULT_URI
+
+    if isinstance(source, Dataset):
+        return source
+    if isinstance(source, str) and source.startswith("hf://"):
+        from datasets import load_dataset
+
+        repo, _, split = source[5:].partition(":")
+        hf = load_dataset(repo, split=split or "train")
+        return Dataset.create(name or repo.split("/")[-1].replace("-", "_"), hf.data.table, uri=uri or DEFAULT_URI,
+                              mode="overwrite" if overwrite else "create")
+    if isinstance(source, str) and not any(ch in source for ch in "*/.") and uri is not None:
+        return Dataset.open(source, uri)
+    if isinstance(source, str) and any(ch in source for ch in "*?"):
+        pattern, source = source, sorted(_glob.glob(source))
+        if not source:
+            raise FileNotFoundError(f"pc.load: no files match {pattern!r} (relative to {os.getcwd()})")
+    elif isinstance(source, str) and "://" not in source and not os.path.exists(source):
+        raise FileNotFoundError(f"pc.load: {source!r} is not a file, a glob, a table name in uri=, or an hf:// / "
+                                "object-store path")
+    if name is None and uri is None:
+        return Dataset.wrap(source)
+    try:
+        return Dataset.create(name or "dataset", source, uri=uri or DEFAULT_URI,
+                              mode="overwrite" if overwrite else "create")
+    except ValueError as e:
+        if "already exists" not in str(e):
+            raise
+        raise ValueError(f"pc.load: table {name or 'dataset'!r} already exists in {uri or DEFAULT_URI!r}. Reopen it "
+                         f"with pc.load({name or 'dataset'!r}, uri={uri or DEFAULT_URI!r}), or pass overwrite=True to "
+                         "ingest again") from e
+
+
+def _domain(ds: Dataset, domain: str | None):
+    return importlib.import_module(f"pycurate.domains.{domain or detect(ds.schema)}")
+
+
+@dataclass
+class Curated:
+    """The result of :func:`curate`: the ids to train on, the recipe that produced them, a lazy view, and ``report``
+    (``level``, ``search``, ``guard``, ``discovery``, ...: what ran and why this recipe was applied)."""
+
+    dataset: Dataset
+    recipe: Recipe
+    ids: Any
+    domain: str
+    report: dict = field(default_factory=dict)
+
+    def __len__(self) -> int:
+        return len(self.ids)
+
+    def view(self, columns: list[str] | None = None):
+        """Zero-copy ``Permutation`` over the base table (iterate, index, or hand to a torch DataLoader)."""
+        if len(self.ids) == 0:
+            raise ValueError(f"{self!r} selected no rows; nothing to view (loosen the recipe's where / keep)")
+        return self.dataset.permutation(self.ids, columns=columns)
+
+    def to_torch(self, columns: list[str] | None = None, batch_size: int = 256, num_workers: int = 0, **loader_kw):
+        """A ``torch.utils.data.DataLoader`` over :meth:`view`: batches are dicts of column -> values, read straight
+        from the base table in the curated (globally shuffled) order; nothing is copied. ``columns``: what to read
+        (default: all; name only what you train on). Worker processes use ``spawn`` (Lance is not fork-safe)."""
+        try:
+            from torch.utils.data import DataLoader
+        except ImportError as e:
+            raise ImportError("Curated.to_torch needs PyTorch: pip install torch (or iterate cur.view() yourself)") from e
+        if num_workers and "multiprocessing_context" not in loader_kw:
+            loader_kw["multiprocessing_context"] = "spawn"
+        return DataLoader(self.view(columns=columns), batch_size=batch_size, num_workers=num_workers, **loader_kw)
+
+    def to_arrow(self, columns: list[str] | None = None):
+        """Materialise the curated rows in training order (a copy; prefer :meth:`view` for training)."""
+        return self.dataset.lance().take(_offsets(self.dataset, self.ids), columns=columns)
+
+    def to_pandas(self, columns: list[str] | None = None):
+        """Materialise the curated rows as a pandas DataFrame (a copy; for inspection)."""
+        return self.to_arrow(columns).to_pandas()
+
+    def mask(self):
+        """Boolean array over ``id`` (``mask()[i]`` is True if row ``i`` was kept at least once)."""
+        import numpy as np
+
+        m = np.zeros(int(self.dataset.ids().max()) + 1, bool)
+        m[np.asarray(self.ids, dtype=np.int64)] = True
+        return m
+
+    def __repr__(self) -> str:
+        return f"Curated({len(self):,} of {len(self.dataset):,} rows, domain={self.domain!r}, {self.recipe})"
+
+
+def _offsets(ds: Dataset, ids):
+    """Row offsets (positions in scan order) for ``id`` values, for ``LanceDataset.take``."""
+    import numpy as np
+
+    all_ids = ds.lance().to_table(columns=["id"]).column("id").to_numpy()
+    pos = np.empty(all_ids.max() + 1, np.int64)
+    pos[all_ids] = np.arange(len(all_ids))
+    return pos[np.asarray(ids)]
+
+
+AGENT_STRATEGY = "agent+diag"  # agent=True's recipe proposer: the LLM agent + the diagnose report (benchmark headline)
+
+
+def curate(data: Any, keep: float | int | None = None, recipe: Recipe | dict | str | None = None,
+           domain: str | None = None, signals: bool | list[str] | tuple = True, seed: int = 0,
+           target_samples: float | None = None, cap_passes: float | None = None, *, eval: Callable | None = None,
+           budget: int = 20, agent: bool = False, strategy: str | None = None, trials: str | None = None,
+           guard: str | None = "auto", guard_margin: float = 0.0, subpool: int | None = None, goal: str = "",
+           harness: Any = None, offline: bool = False, allow_code: bool = False, **opts) -> Curated:
+    """Curate ``data`` in one call and return a :class:`Curated` (ids + recipe + lazy view). One verb, three levels:
+
+        cur = pc.curate(ds)                                          # 1. default: domain recipe, no LLM, no training
+        cur = pc.curate(ds, eval=train_eval, budget=20)              # 2. tuned: TPE on your eval, guarded by the default
+        cur = pc.curate(ds, eval=train_eval, budget=20, agent=True)  # 3. agent: literature signals + LLM recipes, guarded
+        cur.report                                                   # level, guard decision, trials, discovery
+
+    **Level 1 (default).** Route to a domain (``domain=`` overrides :func:`detect`), compute the domain's default
+    signals as columns (existing columns are reused; ``signals=False`` skips this, ``signals=["clip_score"]`` computes
+    only those), and apply ``recipe`` (a :class:`Recipe`, its dict form, or a SQL ``where`` string) or the domain's
+    default recipe at ``keep``. The default is the strongest established public method for the domain (image_text:
+    DFN top 30% + SemDeDup; text: DCLM fastText top 10% + SemDeDup; sft: reward-model top 50%; ...). Model-backed
+    scores run only where they can (DFN needs a GPU; nothing downloads under ``HF_HUB_OFFLINE``); otherwise the
+    domain falls back to the next-best signal, logs why, and records it in ``recipe.notes`` / ``report["default"]``.
+
+    **Level 2 (tuned): ``eval=``.** Runs :func:`search` (``strategy="tpe"`` unless given; ``budget`` trials) with the
+    guard on: the domain default (at ``keep``) is evaluated as a trial and the search's pick is applied only if it
+    beats the default on the validation metric your eval returns (``heldout`` / ``val``; never shown to the search) by
+    more than ``guard_margin``; otherwise the default is applied. ``eval`` has :func:`search`'s objective contract:
+    ``eval(recipe, ids)`` or ``eval(recipe, ids, device)`` returns a float or a dict with ``score`` (higher is better)
+    and ideally ``heldout``. Without a validation key the pick is unchecked: one warning, and
+    ``report["guard"]["decision"] == "unavailable"``. ``guard=None`` turns the guard off. ``subpool=N`` runs every trial
+    on the ``id % N = 0`` sub-pool (ratio-matched proxy; ``pc.research.matched_subpool``) and applies the pick to the
+    full pool. ``trials``: where every trial is recorded (default ``<uri>/_trials/<table>-<time>-<tag>.jsonl``).
+
+    **Level 3 (agent): ``eval=`` + ``agent=True``** (opt-in; calls an LLM). Before the search an agent surveys the
+    literature and proposes new signals (:func:`prepare` with ``discover=True``; written for review, run only with
+    ``allow_code=True``); then the agent proposes recipes (``strategy="agent+diag"``: it also sees :func:`diagnose`),
+    guarded by the default as in level 2. ``harness`` / ``offline`` / ``goal``: see :func:`search`.
+    ``agent=True`` **without** ``eval=`` runs the discovery step only and applies the default recipe: no recipe search
+    runs (there is nothing to compare recipes on); ``report["search"]`` is None and ``report["note"]`` says so.
+
+    ``cur.report``: ``level`` ("default" / "tuned" / "agent"), ``search`` (strategy, name, trials location, trial
+    count, pick and default search scores, applied = "pick" or "default"), ``guard`` (the decision dict),
+    ``discovery`` (agent mode), ``default`` (fallback notes), ``budget`` (with ``target_samples``).
+
+    ``keep``: fraction in (0, 1] or a row count; ``None`` lets the domain choose. ``opts`` go to the domain's
+    ``prepare`` / ``default_recipe`` (e.g. ``devices="cpu"``, ``k=20``, ``score="clip_l14"``, ``dfn=False``) and, with
+    ``eval=``, to :func:`search` (e.g. ``devices=[0, 1]``, ``batch``, ``task``, ``warm_start``).
+    ``target_samples`` (opt-in): the training budget in samples seen; ``report["budget"]`` = passes over the unique
+    kept rows, with a ``UserWarning`` above 8 passes. ``cap_passes``: raise ``keep`` to
+    ``ceil(target_samples / cap_passes)`` rows when the recipe keeps fewer (never lowers it).
+
+        cur = pc.curate(ds, keep=0.3)
+        cur = pc.curate(ds, recipe="lang = 'en'", keep=0.5, signals=False)
+        cur = pc.curate(ds, target_samples=128e6, cap_passes=6)
+    """
+    import dataclasses
+    import warnings
+
+    ds = load(data)
+    mod = _domain(ds, domain)
+    report: dict = {}
+    if eval is not None:
+        if recipe is not None:
+            raise ValueError("pc.curate: pass recipe= (apply it) or eval= (search for one), not both; to check your "
+                             "recipe against a search, use pc.search(..., guard='auto', incumbent=recipe)")
+        res, recipe, report = _curate_search(ds, mod, eval, keep, budget, agent, strategy, signals, trials, guard,
+                                             guard_margin, subpool, goal, harness, offline, allow_code, seed, opts)
+    else:
+        if strategy is not None:
+            raise ValueError("pc.curate: strategy= picks a recipe search, which needs eval=")
+        report["level"] = "agent" if agent else "default"
+        if agent:
+            prep, _ = _agent_prepare(ds, mod, signals, goal, harness, offline, allow_code, opts)
+            report["discovery"] = prep.discovery
+            report["note"] = ("agent=True without eval=: literature discovery ran and the default recipe was applied; "
+                              "no recipe search ran. Pass eval= (and budget=) to search recipes against your eval.")
+        else:
+            _prepare(mod, ds, signals, opts)
+        report["search"] = None
+        default = recipe is None
+        if default:
+            recipe = mod.default_recipe(ds, keep=keep, **opts)
+        elif isinstance(recipe, str):
+            recipe = Recipe(where=recipe)
+        elif isinstance(recipe, dict):
+            recipe = Recipe.from_dict(recipe)
+        else:
+            recipe = dataclasses.replace(recipe)  # never mutate the caller's recipe
+        if keep is not None and recipe.keep is None:
+            recipe.keep = keep
+        if default and recipe.notes:
+            report["default"] = recipe.notes
+    recipe.validate(ds)  # fail fast with the missing columns named, before any rows are read
+    if target_samples:
+        from .domains._base import compute_aware
+
+        recipe, ids, report["budget"] = compute_aware(recipe, ds, target_samples, cap_passes, seed=seed)
+    else:
+        ids = recipe.select(ds, seed=seed)
+    if len(ids) == 0:
+        warnings.warn(f"{recipe} selected 0 of {len(ds):,} rows", stacklevel=2)
+    return Curated(ds, recipe, ids, mod.__name__.rsplit(".", 1)[-1], report)
+
+
+def _default_trials(ds) -> str:
+    """``<uri>/_trials/<table>-<time>.jsonl`` (next to ``_discovery``): curate's searches leave a record."""
+    import os
+    import time
+    import uuid
+
+    from .signals import store
+
+    uri, name = store._location(ds)
+    root = os.path.join(uri if "://" not in uri else os.path.join(os.getcwd(), "autocurate_trials"), "_trials")
+    os.makedirs(root, exist_ok=True)
+    return os.path.join(root, f"{name}-{time.strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:6]}.jsonl")
+
+
+def _curate_search(ds, mod, eval, keep, budget, agent, strategy, signals, trials, guard, guard_margin, subpool, goal,
+                   harness, offline, allow_code, seed, opts):
+    """Levels 2 / 3 of :func:`curate`: a guarded search; returns (SearchResult, recipe to apply, report)."""
+    import warnings
+
+    strategy = strategy or (AGENT_STRATEGY if agent else "tpe")
+    trials = trials or _default_trials(ds)
+    res = search(ds, eval, budget=budget, strategy=strategy, signals=signals, trials=trials, agent=agent, goal=goal,
+                 harness=harness, offline=offline, allow_code=allow_code, seed=seed, subpool=subpool,
+                 guard=guard, guard_margin=guard_margin, incumbent="default", _default_keep=keep, **opts)
+    default = res.default_recipe
+    g = res.guard or {"decision": "off" if not guard else "no_trials"}
+    use_default = res.best is None or g.get("decision") in ("default", "incumbent_best")
+    if res.best is None:
+        warnings.warn(f"pc.curate: no search trial completed (see {res.trials_path}); applying the default recipe",
+                      stacklevel=3)
+    recipe = default if use_default else res.best_recipe_full_pool
+    sb = res.search_best
+    report = {"level": "agent" if agent else "tuned", "guard": g,
+              "search": {"strategy": res.strategy, "name": res.name, "trials": res.trials_path,
+                         "n_trials": len(res.trials), "budget": budget, "subpool": res.subpool,
+                         "applied": "default" if use_default else "pick",
+                         "pick_score": sb and sb["score"], "default_score": g.get("default_score")}}
+    if use_default and default.notes:
+        report["default"] = default.notes
+    if res.discovery is not None:
+        report["discovery"] = res.discovery
+    if g.get("decision") == "unavailable":
+        report["search"]["note"] = ("the eval returned no validation metric (heldout / val), so the pick was not "
+                                    "checked against the default")
+    report["search_result"] = res  # the full SearchResult (trials, proposer log, adoption)
+    return res, recipe, report
+
+
+def _prepare(mod, ds, signals, opts):
+    if signals is True:
+        mod.prepare(ds, **opts)
+    elif signals:
+        mod.prepare(ds, signals=tuple([signals] if isinstance(signals, str) else signals), **opts)
+
+
+class AgentUnavailable(RuntimeError):
+    """Agent mode was requested but no usable LLM agent harness was found (the message says how to set one up)."""
+
+
+_NO_AGENT_HINT = ("Without an agent, drop agent=True: pc.search(ds, train_eval) runs TPE (no LLM, no API key) and "
+                  "pc.curate(ds) applies the established default recipe.")
+
+
+def _agent_harness(harness: Any, offline: bool):
+    """Resolve the harness for agent mode, failing early with what to do next."""
+    from . import harness as H
+    from .signals.discover import LiteratureRequired
+
+    try:
+        h = H.get_harness(harness)
+    except RuntimeError as e:
+        raise AgentUnavailable(
+            "agent=True needs an LLM agent, and none was found. Do one of: install and log in to Claude Code "
+            "(the `claude` CLI), set ANTHROPIC_API_KEY or OPENAI_API_KEY (+ PYCURATE_OPENAI_MODEL), install the "
+            "Codex CLI (`codex`), or pass harness=<name or Harness>. " + _NO_AGENT_HINT) from e
+    if not h.has_web and not offline:
+        raise LiteratureRequired(
+            f"agent=True starts with a literature survey (new signals must be grounded in published methods), and "
+            f"the agent harness {h.name!r} has no web access. Use a web-capable harness (claude-code, codex, "
+            "anthropic or openai; set PYCURATE_HARNESS or pass harness=), or pass offline=True to skip the survey "
+            "(recorded in provenance and flagged in the report). " + _NO_AGENT_HINT)
+    return h
+
+
+def _agent_prepare(ds, mod, signals, goal, harness, offline, allow_code, opts, discover_opts=None):
+    """Agent mode's preparation: the domain's signals + literature-first discovery (propose-only by default)."""
+    import logging
+    import subprocess
+
+    h = _agent_harness(harness, offline)
+    names = "recommended" if signals is True else (([signals] if isinstance(signals, str) else list(signals))
+                                                   if signals else None)
+    dom = mod.__name__.rsplit(".", 1)[-1]
+    try:
+        prep = prepare(ds, domain=dom, discover=True, goal=goal, harness=h, offline=offline, allow_code=allow_code,
+                       signals=names, discover_opts=discover_opts, **opts)
+    except (subprocess.SubprocessError, TimeoutError, RuntimeError) as e:
+        if isinstance(e, AgentUnavailable):
+            raise
+        raise AgentUnavailable(f"signal discovery failed on the agent harness {h.name!r}: {e}. Check that it "
+                               "works on its own (for claude-code: run `claude -p hi`; for API harnesses: the key and "
+                               "network), or pass harness= to use another one. " + _NO_AGENT_HINT) from e
+    rep = prep.discovery
+    if rep is not None and not rep.allow_code and rep.candidates:
+        logging.getLogger("pycurate").warning(
+            "pycurate agent mode: %d signal proposal(s) written to %s for review and not run; pass "
+            "allow_code=True (or call pc.discover_signals(..., approve=fn)) to validate and add them",
+            len(rep.candidates), rep.out_dir)
+    return prep, h
+
+
+def diagnose(data: Any, domain: str | None = None, signals: bool | list[str] | tuple = True, **opts):
+    """Pre-flight checks for ``data``: will curation pay off, roughly how much to keep, what could go wrong.
+
+    Domain-specific (see each domain's ``diagnose``). The checks read signal columns, so the domain's default
+    signals are computed first, exactly as :func:`curate` would (existing columns are reused; ``signals=False``
+    diagnoses only what is already there). Returns a ``Report``: ``print`` it, or ``report.to_dict()`` for what a
+    search agent sees.
+    """
+    ds = load(data)
+    mod = _domain(ds, domain)
+    _prepare(mod, ds, signals, opts)
+    return mod.diagnose(ds, **opts)
+
+
+def default_knob_space(space: dict) -> dict:
+    """A random / TPE knob space from a domain ``search_space``: which column to rank by (either direction),
+    the keep fraction (log scale), and the group columns offered for ``balance_by`` / ``dedup_by``."""
+    numeric = [c for c in space.get("stats", {}) if not c.startswith("_")]
+    lo, hi = space.get("keep", [0.05, 1.0])
+    knobs: dict = {"score": [None, *numeric], "keep": ("float", float(lo), float(hi), "log")}
+    if numeric:
+        knobs["ascending"] = [False, True]
+        knobs["band"] = [None, [0.0, 0.9], [0.1, 1.0], [0.25, 0.75]]  # score-percentile band (dropped when score=None)
+    if space.get("balance_by"):
+        knobs["balance_by"] = [None, *space["balance_by"]]
+        knobs["balance"] = ["proportional", "sqrt", "uniform"]
+    if space.get("dedup_by"):
+        knobs["dedup_by"] = [None, *space["dedup_by"]]
+    return knobs
+
+
+def _accepts_device(fn: Callable) -> bool:
+    import inspect
+
+    try:
+        params = inspect.signature(fn).parameters.values()
+    except (TypeError, ValueError):
+        return True
+    if any(p.kind in (p.VAR_POSITIONAL,) for p in params):
+        return True
+    return len([p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]) >= 3
+
+
+def search(data: Any, eval: Callable | None = None, budget: int = 20, strategy: str = "tpe",
+           domain: str | None = None, space: dict | None = None, diagnostics: bool = True, trials: str | None = None,
+           knob_space: dict | None = None, signals: bool | list[str] | tuple = True,
+           allow_unregistered: bool = False, *, agent: bool = False, goal: str = "", harness: Any = None,
+           offline: bool = False, allow_code: bool = False, objective: Callable | None = None, **opts):
+    """Search curation recipes against your eval; returns a ``SearchResult`` (``.best_recipe``, ``.guard``, ``.trials``).
+
+    The building block under ``pc.curate(ds, eval=...)``, which runs this with the guard on and applies the pick. Use
+    it directly to inspect trials, run several searches, or choose your own strategy / incumbent / guard:
+
+        res = pc.search(ds, train_eval, budget=20)                                   # TPE: no LLM, no API key
+        res = pc.search(ds, train_eval, budget=20, guard="auto", incumbent="default") # + the guard, as pc.curate does
+        cur = pc.curate(ds, recipe=res.best_recipe)
+
+    ``eval(recipe, ids)`` or ``eval(recipe, ids, device)`` returns a float or a dict with ``score`` (higher is better)
+    and optional metrics / ``cost``; return held-out scores as ``heldout`` / ``val`` (never shown to a proposer; the
+    guard compares on them). ``objective=`` is the deprecated keyword name of ``eval``.
+
+    ``strategy``: ``"tpe"`` (default; Bayesian optimisation with optuna, no LLM), ``"random"``, or (advanced; prefer
+    ``agent=True``) the LLM proposers ``"agent"`` (writes recipes from the columns, statistics and every previous
+    trial) and ``"agent+diag"`` (also sees :func:`diagnose`). A bare ``strategy="agent"`` runs no discovery, no
+    default warm start and no guard.
+
+    ``agent=True`` is agent mode in one switch: (1) the domain's recommended signals are computed; (2) an agent
+    surveys the literature (web access required, else pass ``offline=True``) and proposes new signals for ``goal``,
+    written to disk for review and run only with ``allow_code=True``; (3) the agent proposes recipes
+    (``strategy="agent+diag"`` unless you pass ``"agent"``), starting from the domain's default recipe as the first
+    trial. The harness is ``harness=`` (a name or a :class:`~pycurate.harness.Harness`), else
+    ``PYCURATE_HARNESS``, else auto-detected (``ANTHROPIC_API_KEY``, ``claude`` CLI, ``OPENAI_API_KEY``, ``codex``
+    CLI); the same harness runs discovery and the recipe agent. ``res.discovery`` is the discovery report.
+
+    The guard (on by default in agent mode; ``guard="auto", incumbent="default"`` turns it on for any strategy): the
+    pick is returned only if it beats the incumbent (``"default"`` = the domain default recipe, or a recipe / dict) on
+    a validation metric the proposer never sees, else ``res.best`` is the incumbent; ``res.guard`` records the
+    decision and both scores, ``res.search_best`` is the best by search score. Without such a metric the pick stands
+    and one warning says so. ``guard=None`` turns it off, ``guard="<metric>"`` / ``guard_margin=`` tune it.
+    ``subpool=N`` runs every trial on the ``id % N = 0`` sub-pool (a ratio-matched proxy; ``N`` from
+    ``pc.research.matched_subpool``); apply ``res.best_recipe_full_pool`` to the full pool.
+    ``knob_space`` (random / TPE) defaults to :func:`default_knob_space` of the domain's search space. ``trials``:
+    a ``.jsonl`` path or ``"<lancedb uri>::<table>"`` shared by concurrent workers (default: a temporary file;
+    ``res.trials_path``). Domain signals are computed first, as in :func:`curate` (``signals=False`` to skip). Other
+    keyword arguments go to :func:`pycurate.research.run_search` (e.g. ``devices=[0, 1]``, ``seed``,
+    ``warm_start``, ``task``) or, if it does not take them, to the domain's ``prepare`` / ``diagnose``.
+
+    The search only sees registered signal columns (catalog spec + provenance, or raw ingested data) and never a
+    protected one (:mod:`pycurate.signals`); an unregistered column raises ``SignalGateError`` unless
+    ``allow_unregistered=True``, which is recorded with every trial and flagged in the result.
+    """
+    import inspect
+
+    from .research import run_search
+
+    from .research.proposers import AgentProposer, make_proposer
+
+    if objective is not None:
+        import warnings
+
+        warnings.warn("pc.search(objective=) is deprecated; pass eval= (or the eval as the second argument)",
+                      DeprecationWarning, stacklevel=2)
+        eval = eval or objective
+    if eval is None:
+        raise TypeError("pc.search needs eval: a function (recipe, ids) -> score, see help(pc.search)")
+    if agent:  # the default (or "tpe") gives way to the agent; another explicit non-agent strategy is a conflict
+        if strategy not in (None, "tpe", "agent", "agent+diag", "agent_diag"):
+            raise ValueError(f"agent=True runs the LLM recipe agent, but strategy={strategy!r} was also given; drop "
+                             "one of them (strategy='agent' / 'agent+diag' is allowed with agent=True)")
+        strategy = AGENT_STRATEGY if strategy in (None, "tpe") else strategy
+    strategy = strategy or "tpe"  # None (from pc.curate) = the default
+    default_keep = opts.pop("_default_keep", None)  # pc.curate(keep=): the incumbent default's keep
+
+    accepted = {*inspect.signature(run_search).parameters, *inspect.signature(make_proposer).parameters,
+                *inspect.signature(AgentProposer).parameters} - {"devices", "kw", "proposer_kw", "space"}
+    run_opts = {k: v for k, v in opts.items() if k in accepted}
+    dom_opts = {k: v for k, v in opts.items() if k not in run_opts}
+    devices = opts.get("devices")
+    if isinstance(devices, (str, int)):  # "cpu" / "auto" / one GPU index: one worker
+        devices = [devices if devices != "auto" else None]
+    ds = load(data)
+    mod = _domain(ds, domain)
+    prep = default = None
+    if agent:
+        prep, harness = _agent_prepare(ds, mod, signals, goal, harness, offline, allow_code, dom_opts,
+                                       discover_opts=run_opts.get("discover_opts"))
+    else:
+        _prepare(mod, ds, signals, dom_opts)
+    inc = run_opts.get("incumbent")
+    if isinstance(inc, str) and inc != "default":
+        raise ValueError(f"incumbent={inc!r}: pass 'default' (the domain default recipe), a Recipe or a recipe dict")
+    if agent or inc == "default":
+        default = mod.default_recipe(ds, keep=default_keep, **dom_opts)
+        if default_keep is not None and default.keep is None:
+            default.keep = default_keep
+        if inc is None or inc == "default":
+            run_opts["incumbent"] = default.to_dict()  # the pick must beat it on held-out (guard=)
+    if agent:
+        if "warm_start" not in run_opts:  # the established default is the first trial: the search is checked against it
+            run_opts["warm_start"] = [{**default.to_dict(), "rationale": "domain default"}]
+        run_opts.setdefault("guard", "auto")
+    if harness is not None:
+        run_opts["harness"] = harness
+    from .signals.gate import gate, gate_knobs, gate_space
+
+    from .signals.adoption import extend_space
+
+    g = gate(ds, allow_unregistered, opts.get("allowed_columns"), opts.get("exclude_columns"))
+    space = gate_space(ds, space or mod.search_space(ds), allow_unregistered, g=g)
+    if opts.get("extend_signals", True):  # survey-new / discovered signal columns the domain space does not list
+        space = extend_space(ds, space, g)
+    if strategy in ("random", "tpe") and knob_space is None:
+        knob_space = default_knob_space(space)
+    elif knob_space is not None:
+        knob_space = gate_knobs(knob_space, g)
+    context = mod.diagnose(ds, **dom_opts).to_dict() if diagnostics and strategy in ("agent+diag", "agent_diag") \
+        else None
+    fn = eval if _accepts_device(eval) else (lambda recipe, ids, device: eval(recipe, ids))
+    res = run_search(ds, fn, budget=budget, strategy=strategy, space=space, knob_space=knob_space, context=context,
+                     trials=trials, devices=devices, allow_unregistered=allow_unregistered, **run_opts)
+    if prep is not None:
+        res.discovery = prep.discovery
+    res.default_recipe = default  # the domain default Recipe when it was the incumbent, else None
+    return res
+
+
+@dataclass
+class Prepared:
+    """The result of :func:`prepare`: what was computed, discovered and registered on the dataset."""
+
+    dataset: Dataset
+    domain: str
+    computed: list
+    registered_base: list
+    discovery: Any = None
+    protected: list = field(default_factory=list)
+    skipped: dict = field(default_factory=dict)  # recommended survey signals not computed here, with the reason
+
+    def columns(self):
+        """Every column with its search status and source (``pc.signals.describe``)."""
+        from .signals import describe
+
+        return describe(self.dataset)
+
+    def __repr__(self) -> str:
+        disc = "" if self.discovery is None else f", discovered={self.discovery.accepted}" + \
+            (" [OFFLINE]" if self.discovery.offline else "")
+        skip = f", skipped={sorted(self.skipped)}" if self.skipped else ""
+        return (f"Prepared({self.dataset.name!r}, domain={self.domain!r}, computed={self.computed}{disc}, "
+                f"protected={self.protected}{skip})")
+
+
+def prepare(data: Any, domain: str | None = None, discover: bool = False, goal: str = "", harness: Any = None,
+            offline: bool = False, allow_code: bool = False, approve: Callable | None = None, budget: int = 3,
+            signals: Any = "recommended", protect: list[str] | tuple = (), discover_opts: dict | None = None,
+            **opts) -> Prepared:
+    """The standard pipeline step: compute the domain's recommended catalog signals (zero-copy columns with
+    provenance), optionally discover new ones, and register everything so a search can use it.
+
+    1. ``signals``: ``"recommended"`` (default; what :func:`curate` computes), a list of catalog names, or ``None``;
+    2. ``protect``: oracle / eval / label columns to protect (in addition to the defaults, e.g. ``clean_label``);
+    3. ``discover=True``: :func:`discover_signals` with the mandatory literature step on the configured harness
+       (``harness=`` / ``PYCURATE_HARNESS``; ``offline=True`` skips the survey and is recorded); running the
+       proposed code needs ``allow_code=True`` or ``approve=fn``;
+    4. raw ingested columns are registered as base data.
+
+        prep = pc.prepare(ds)                                         # recommended signals only
+        prep = pc.prepare(ds, discover=True, goal="...", allow_code=True)   # benchmarks: + agentic discovery
+    """
+    from . import signals as S
+
+    ds = load(data)
+    dom = domain or detect(ds.schema)
+    if protect:
+        S.protect(ds, list(protect))
+    rep: dict = {}
+    computed = S.add_signals(ds, signals, domain=dom, report=rep, **opts) if signals else []
+    disc = None
+    if discover:
+        from .signals.discover import discover_signals
+
+        disc = discover_signals(ds, domain=dom, goal=goal, budget=budget, harness=harness, offline=offline,
+                                allow_code=allow_code, approve=approve, **(discover_opts or {}))
+    try:
+        base = S.register_base(ds)
+    except ValueError as e:  # version 1 cleaned up: raw columns must be declared explicitly
+        import logging
+
+        logging.getLogger("pycurate").warning("pycurate.prepare: %s", e)
+        base = []
+    return Prepared(ds, dom, computed, base, disc, sorted(S.protected_columns(ds)), rep.get("skipped", {}))
+
+
+curate.prepare = prepare  # ``pc.curate.prepare(ds, ...)``: the same entry point, next to the call it prepares for