sdm-learn 0.1.0.dev0__py3-none-any.whl

sdm/learn.py

@@ -0,0 +1,699 @@
+"""The learning algorithm: the gate, the control, and the run artifacts.
+
+Everything here is format-agnostic. The gate calls into a ``SkillFormat`` for
+anything that depends on how the hypothesis is written down, so adding a
+format never touches this file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+from pathlib import Path
+
+from .data import (Dataset, Report, _inputs, _revealed, content, describe,
+                   labeled)
+from .formats import (DOCUMENT_RE, GATE_LINE_RE, NO_FORMAT, SkillFormat,
+                      _clean_line, _copy, _rules_by_id, format_of, get_format,
+                      parse_predictions, record, render, skill_filename)
+from . import gateway
+from .gateway import EFFORT, MODEL, SetupNeeded, _borrowed
+
+
+
+def _atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(text)
+    os.replace(temporary, path)
+
+
+def save_state(state: dict, run_dir) -> None:
+    """Write ``state.json`` and the rendered skill file side by side.
+
+    The baseline control has no document, so it writes no skill file rather
+    than an empty one.
+    """
+    run_dir = Path(run_dir)
+    _atomic(run_dir / "state.json", json.dumps(state, indent=1))
+    document = render(state)
+    if document:
+        _atomic(run_dir / skill_filename(state), document)
+
+
+def archive(run_dir, relative: str, raw: str) -> str | None:
+    """Persist one raw model response so a finished run can be audited."""
+    if run_dir is None:
+        return None
+    path = Path(run_dir) / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(raw)
+    return relative
+
+
+def _resume(run_dir, config: dict, what: str) -> dict | None:
+    if run_dir is None:
+        return None
+    path = Path(run_dir) / "state.json"
+    if not path.exists():
+        return None
+    state = json.loads(path.read_text())
+    if state["config"] != config:
+        raise SetupNeeded(
+            f"{run_dir} already holds a {what} with different settings, so "
+            "resuming it would mix two experiments.\nPoint at a fresh "
+            "directory, or start this one over with resume=False."
+        )
+    return state
+
+
+# --------------------------------------------------------------------------
+
+class Skill:
+    """A learned skill document, plus the state that produced it."""
+
+    def __init__(self, state: dict, run_dir=None, report: Report | None = None):
+        self.state = state
+        self.run_dir = Path(run_dir) if run_dir else None
+        self.report = report
+
+    @property
+    def text(self) -> str:
+        return render(self.state)
+
+    @property
+    def format(self) -> str | None:
+        return self.state.get("config", {}).get("format", "markdown")
+
+    @property
+    def rules(self) -> list[dict]:
+        return list(self.state.get("rules", []))
+
+    @property
+    def accuracy(self) -> float | None:
+        return self.report.accuracy if self.report else None
+
+    def save(self, path) -> Path:
+        """Write the document to a file, or the whole run to a directory."""
+        path = Path(path)
+        if path.suffix:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(self.text)
+            return path
+        save_state(self.state, path)
+        return path / skill_filename(self.state)
+
+    @classmethod
+    def load(cls, path) -> "Skill":
+        path = Path(path)
+        state_path = path / "state.json" if path.is_dir() else path
+        return cls(json.loads(state_path.read_text()), state_path.parent)
+
+    def __str__(self):
+        return self.text
+
+    def __repr__(self):
+        parts = [f"format={self.format!r}"]
+        if self.rules:
+            parts.append(f"rules={len(self.rules)}")
+        if self.accuracy is not None:
+            parts.append(f"accuracy={self.accuracy:.1%}")
+        return f"Skill({', '.join(parts)})"
+
+def predict_batch(session, state: dict, rows: list[dict], description: str,
+                  representation: str, image_size: int = 224,
+                  attempts: int = 3, fmt: SkillFormat | None = None,
+                  cache=None):
+    """Classify one batch from the current skill. Labels stay hidden."""
+    fmt = fmt or format_of(state)
+    classes = state["config"]["classes"]
+    view_text, view_images = fmt.view(state, cache)
+    prompt = fmt.predict_prompt(description, classes, view_text, rows,
+                                representation)
+
+    for attempt in range(1, attempts + 1):
+        raw = gateway.complete(session, [{"role": "user", "content": content(
+            prompt, rows, representation, "CURRENT_INPUT", image_size,
+            labeled("SKILL_VIEW", view_images))}], 8000)
+        parsed, errors = parse_predictions(raw, len(rows), classes,
+                                          fmt.cites_rules)
+        if not errors:
+            known = set(_rules_by_id(state))
+            for prediction in parsed.values():
+                prediction["rules_used"] = [
+                    rule_id for rule_id in prediction["rules_used"]
+                    if rule_id in known]
+            return [parsed[i] for i in range(1, len(rows) + 1)], raw, attempt
+        problem = "; ".join(errors)
+        print(f"  [prediction format retry {attempt}/{attempts}: {problem}]",
+              flush=True)
+        prompt += (f"\n\nYour previous response was invalid: {problem}. "
+                   "Return a complete corrected <predictions> block only.")
+    raise RuntimeError("prediction output never satisfied the batch schema")
+
+
+# --------------------------------------------------------------------------
+
+DEFAULT_ORDER_SEED = 20260818
+ACCEPT_CRITERION = (
+    "strict held-out accuracy gain or 5pct prediction-preserving compression")
+
+
+def stratified_holdout(rows: list[dict], per_class: int, seed: int,
+                       order_seed: int, *, thin_classes_feedback_only=False
+                       ) -> tuple[list[int], list[int]]:
+    """Split training positions into (protected, feedback) index lists.
+
+    Both halves are drawn per class and then shuffled, so every request the
+    model sees is class balanced rather than sorted by label.
+    """
+    by_label: dict[str, list[int]] = {}
+    for position, row in enumerate(rows):
+        by_label.setdefault(str(row["label"]), []).append(position)
+
+    rng = random.Random(seed)
+    for positions in by_label.values():
+        rng.shuffle(positions)
+
+    thin = {label: len(positions) for label, positions in by_label.items()
+            if len(positions) <= per_class}
+    if thin and not thin_classes_feedback_only:
+        raise ValueError(
+            f"need more than {per_class} training example(s) per class to hold "
+            f"any out; these have too few: {thin}")
+
+    held, feedback = [], []
+    for _, positions in sorted(by_label.items()):
+        if len(positions) <= per_class:
+            # A singleton cannot sit on both sides of the gate without
+            # duplicating the same labeled input, so keep it feedback-only.
+            feedback += positions
+            continue
+        held += positions[:per_class]
+        feedback += positions[per_class:]
+    random.Random(order_seed).shuffle(held)
+    rng.shuffle(feedback)
+    return held, feedback
+
+
+def cycle_points(feedback: int, batch_size: int, cycles: int) -> tuple[int, ...]:
+    """Cumulative feedback counts at which a candidate revision is proposed.
+
+    A cycle is at least one whole batch, so asking for more cycles than there
+    are batches yields one per batch, and any remainder joins the final cycle
+    rather than becoming a short cycle of its own.
+    """
+    batches = feedback // batch_size
+    if batches == 0:
+        raise ValueError(
+            f"{feedback} feedback example(s) cannot fill one batch of "
+            f"{batch_size}; lower batch_size or hold out fewer rows")
+    cycles = max(1, min(cycles, batches))
+    per_cycle, extra = divmod(batches, cycles)
+    sizes = [per_cycle] * cycles
+    sizes[-1] += extra
+    points, total = [], 0
+    for size in sizes:
+        total += size * batch_size
+        points.append(total)
+    return tuple(points)
+
+
+def gate_prompt(fmt: SkillFormat, base: dict, candidate: dict,
+                rows: list[dict], order: list[str], description: str,
+                classes: list[str], representation: str, image_size: int,
+                cache=None):
+    """One request that scores both documents, with the letters shuffled."""
+    states = {"base": base, "candidate": candidate}
+    documents = {letter: states[name] for letter, name in zip("AB", order)}
+    views = {}
+    for letter in ("A", "B"):
+        views[letter] = fmt.view(documents[letter], cache)
+    prompt = f"""You are a deterministic evaluation component for two frozen
+{fmt.name} skill documents. {description}
+
+Classify every input independently once with document A and once with document
+B. Do not merge, compare, vote between, or transfer rules across documents. The
+inputs are identical for both documents and their true labels are absent.
+Document letters do not indicate recency or quality.
+
+<document id="A">
+{fmt.skill_section(views["A"][0])}
+</document>
+
+<document id="B">
+{fmt.skill_section(views["B"][0])}
+</document>
+
+{_inputs(rows, representation, "current_input")}
+
+Return only these two complete blocks, with exactly {len(rows)} lines each:
+<predictions document="A">
+P01 | class | evidence of at most 20 words
+</predictions>
+<predictions document="B">
+P01 | class | evidence of at most 20 words
+</predictions>
+
+The class must be exactly one of: {", ".join(classes)}.
+"""
+    return content(prompt, rows, representation, "CURRENT_INPUT", image_size,
+                   labeled("DOCUMENT_A_VIEW", views["A"][1])
+                   + labeled("DOCUMENT_B_VIEW", views["B"][1]))
+
+
+def candidate_prompt(fmt: SkillFormat, state: dict, rows: list[dict],
+                     predictions: list[dict], description: str,
+                     classes: list[str], representation: str, limits: dict,
+                     image_size: int, cache=None):
+    """Ask for one conservative revision, without the protected rows."""
+    view_text, view_images = fmt.view(state, cache)
+    prompt = f"""You maintain a {fmt.noun} for a supervised learner.
+{description}
+Classes: {", ".join(classes)}.
+
+The feedback inputs below were predicted before their labels were revealed.
+Propose one conservative candidate revision. It will be accepted or rejected
+only by Python accuracy on separate held-out training inputs whose labels and
+errors are never shown to you.
+
+<current_source>
+{fmt.source(state)}
+</current_source>
+
+<what_the_model_sees>
+{view_text}
+</what_the_model_sees>
+
+{_revealed(rows, predictions, representation, fmt.cites_rules)}
+
+{fmt.update_instructions(limits)}"""
+    return content(prompt, rows, representation, "FEEDBACK_INPUT", image_size,
+                   labeled("SKILL_VIEW", view_images))
+
+
+def parse_paired(raw: str, expected: int) -> tuple[dict | None, list[str]]:
+    """Read the two per-document prediction blocks out of one response."""
+    parsed: dict[str, dict[int, str]] = {}
+    errors: list[str] = []
+    for document, body in DOCUMENT_RE.findall(raw):
+        document = document.upper()
+        if document in parsed:
+            errors.append(f"duplicate document {document}")
+            continue
+        values: dict[int, str] = {}
+        for raw_line in body.splitlines():
+            match = GATE_LINE_RE.match(_clean_line(raw_line))
+            if not match:
+                continue
+            position = int(match.group(1))
+            if not 1 <= position <= expected:
+                errors.append(f"out-of-range P{position:02d} in {document}")
+            elif position in values:
+                errors.append(f"duplicate P{position:02d} in {document}")
+            else:
+                values[position] = match.group(2).strip()
+        missing = [position for position in range(1, expected + 1)
+                   if position not in values]
+        if missing:
+            errors.append(f"document {document} missing {missing}")
+        parsed[document] = values
+    for document in ("A", "B"):
+        if document not in parsed:
+            errors.append(f"missing document {document}")
+    if errors:
+        return None, errors
+    return {document: [parsed[document][position]
+                       for position in range(1, expected + 1)]
+            for document in ("A", "B")}, []
+
+
+def decide(base_labels: list, candidate_labels: list, true_labels: list,
+           base_words: int, candidate_words: int, valid: bool) -> dict:
+    """Keep a candidate only on a strict gain, or a safe compression.
+
+    A candidate wins by raising protected accuracy, or by shortening the
+    document at least 5% while predicting every protected row identically.
+    """
+    base_correct = sum(prediction == label for prediction, label
+                       in zip(base_labels, true_labels))
+    candidate_correct = sum(prediction == label for prediction, label
+                            in zip(candidate_labels, true_labels))
+    fixed = sum(before != label and after == label for before, after, label
+                in zip(base_labels, candidate_labels, true_labels))
+    broken = sum(before == label and after != label for before, after, label
+                 in zip(base_labels, candidate_labels, true_labels))
+    accuracy_accept = candidate_correct > base_correct
+    compression_accept = (base_labels == candidate_labels
+                          and candidate_words * 20 <= base_words * 19)
+    return {
+        "accepted": bool(valid and (accuracy_accept or compression_accept)),
+        "candidate_valid": bool(valid), "criterion": ACCEPT_CRITERION,
+        "base_correct": int(base_correct),
+        "candidate_correct": int(candidate_correct),
+        "total": len(true_labels), "fixed": int(fixed), "broken": int(broken),
+        "base_words": base_words, "candidate_words": candidate_words,
+        "reason": ("accuracy_gain" if accuracy_accept else
+                   "safe_compression" if compression_accept else
+                   "invalid_candidate" if not valid else "no_qualifying_gain"),
+    }
+
+
+def _propose(session, fmt: SkillFormat, state: dict, rows: list[dict],
+             predictions: list[dict], description: str, classes: list[str],
+             representation: str, limits: dict, image_size: int, cache=None):
+    """Ask for one bounded revision and apply it to a copy of the skill."""
+    raw = gateway.complete(session, [{"role": "user", "content": candidate_prompt(
+        fmt, state, rows, predictions, description, classes, representation,
+        limits, image_size, cache)}], 16000)
+    candidate = _copy(state)
+    changes, errors = fmt.propose(candidate, raw, limits)
+    if errors:
+        candidate = _copy(state)
+    return candidate, changes, raw, errors
+
+
+def fit_gated(data: Dataset, *, format=None, format_file=None,
+              fmt: SkillFormat | None = None, batch_size: int = 10,
+              holdout_per_class=None, cycles: int = 4, max_words=None,
+              max_rules=None, max_chars=None, max_semantic_edits=None,
+              max_support_edits=None, run_dir=None, resume: bool = True,
+              seed: int = 0, order_seed: int = DEFAULT_ORDER_SEED,
+              thin_classes_feedback_only: bool = False, session=None) -> Skill:
+    """Learn a skill document under the accept/reject gate."""
+    if not data.train:
+        raise ValueError("data.train is empty")
+    if not data.classes:
+        raise ValueError("the gate needs data.classes to hold out per class")
+
+    fmt = fmt or get_format(format, format_file)
+    limits = fmt.limits(max_words=max_words, max_rules=max_rules,
+                        max_chars=max_chars, max_semantic=max_semantic_edits,
+                        max_support=max_support_edits)
+    if holdout_per_class is None:
+        holdout_per_class = max(1, len(data.train) // (10 * len(data.classes)))
+    held, feedback = stratified_holdout(
+        data.train, holdout_per_class, seed, order_seed,
+        thin_classes_feedback_only=thin_classes_feedback_only)
+    points = cycle_points(len(feedback), batch_size, cycles)
+    description = describe(data)
+    classes = list(data.classes)
+    canonical = {label.lower(): label for label in classes}
+    config = {
+        "dataset": data.name, "title": data.title,
+        "algorithm": "accept/reject paired gate", "classes": classes,
+        "format": fmt.name, "format_md_sha": getattr(fmt, "digest", ""),
+        "skill_file": fmt.skill_file,
+        "representation": data.representation, "image_size": data.image_size,
+        "description": description, "train": len(data.train),
+        "feedback_examples": points[-1], "held_out_examples": len(held),
+        "held_out_positions": held,
+        "feedback_positions": feedback[:points[-1]],
+        "unused_feedback_positions": feedback[points[-1]:],
+        "thin_classes_feedback_only": thin_classes_feedback_only,
+        "held_out_labels_never_prompted": True, "batch_size": batch_size,
+        "candidate_update_points": list(points),
+        "max_semantic_edits_per_candidate": limits["max_semantic"],
+        "max_support_edits_per_candidate": limits["max_support"],
+        "max_words": limits["max_words"], "max_rules": limits["max_rules"],
+        "max_chars": limits["max_chars"],
+        "acceptance_criterion": ACCEPT_CRITERION, "seed": seed,
+        "gate_order_seed": order_seed, "model": MODEL, "effort": EFFORT,
+    }
+    run_dir = Path(run_dir) if run_dir else None
+    cache = (run_dir / "view_cache") if run_dir else None
+    state = _resume(run_dir if resume else None, config, "gate run")
+    if state is None:
+        state = fmt.new_state(config)
+        state["gate"] = {"cycles_completed": 0}
+        state["candidates"] = []
+        if run_dir:
+            save_state(state, run_dir)
+    else:
+        print(f"resuming after cycle {state['gate']['cycles_completed']}"
+              f"/{len(points)}", flush=True)
+
+    gate_rows = [data.train[position] for position in held]
+    truth = [str(row["label"]) for row in gate_rows]
+    with _borrowed(session) as session:
+        completed = int(state["gate"]["cycles_completed"])
+        for cycle, (start, stop) in enumerate(
+                zip((0,) + points[:-1], points), 1):
+            if cycle <= completed:
+                continue
+
+            # (a) Predict this cycle's feedback batches and reveal their labels.
+            cycle_rows, cycle_predictions = [], []
+            for offset in range(0, stop - start, batch_size):
+                positions = feedback[start + offset:
+                                     start + offset + batch_size]
+                rows = [data.train[position] for position in positions]
+                predictions, raw, tries = predict_batch(
+                    session, state, rows, description, data.representation,
+                    data.image_size, fmt=fmt, cache=cache)
+                archive(run_dir, f"raw/train/cycle_{cycle:02d}_batch_"
+                                 f"{offset // batch_size:02d}.txt", raw)
+                record(state, "feedback_prediction", cycle=cycle,
+                       examples=len(rows), attempts=tries)
+                fmt.credit(state, predictions,
+                           [str(row["label"]) for row in rows])
+                for position, row, prediction in zip(positions, rows,
+                                                     predictions):
+                    state["train"].append({
+                        "step": len(state["train"]) + 1, "position": position,
+                        "index": row.get("index", position),
+                        "true": str(row["label"]), "pred": prediction["pred"],
+                        "correct": prediction["pred"] == str(row["label"]),
+                        "rules_used": prediction["rules_used"],
+                        "evidence": prediction["evidence"]})
+                cycle_rows += rows
+                cycle_predictions += predictions
+
+            # (b) Ask for one conservative revision, applied only to a copy.
+            base_state = _copy(state)
+            candidate_state, changes, raw, candidate_errors = _propose(
+                session, fmt, base_state, cycle_rows, cycle_predictions,
+                description, classes, data.representation, limits,
+                data.image_size, cache)
+            archive(run_dir,
+                    f"raw/candidates/cycle_{cycle:02d}_update.txt", raw)
+            record(state, "candidate_update", cycle=cycle,
+                   examples=len(cycle_rows),
+                   candidate_valid=not candidate_errors)
+
+            # (c) Score both documents head to head on the protected rows.
+            paired = {"base": [], "candidate": []}
+            orders, gate_errors = [], []
+            for gate_batch, gate_start in enumerate(
+                    range(0, len(gate_rows), batch_size)):
+                slice_rows = gate_rows[gate_start:gate_start + batch_size]
+                order = ["base", "candidate"]
+                random.Random(order_seed + 10 * cycle + gate_batch).shuffle(
+                    order)
+                raw = gateway.complete(session, [{"role": "user",
+                                          "content": gate_prompt(
+                                              fmt, base_state,
+                                              candidate_state, slice_rows,
+                                              order, description, classes,
+                                              data.representation,
+                                              data.image_size, cache)}], 8000)
+                archive(run_dir, f"raw/gate/cycle_{cycle:02d}_batch_"
+                                 f"{gate_batch:02d}.txt", raw)
+                record(state, "paired_gate", cycle=cycle,
+                       gate_batch=gate_batch, examples=len(slice_rows),
+                       documents=2, document_order=order)
+                part, part_errors = parse_paired(raw, len(slice_rows))
+                orders.append(order)
+                gate_errors += part_errors
+                if part is None:
+                    paired = None
+                elif paired is not None:
+                    for letter, name in zip("AB", order):
+                        paired[name] += [
+                            canonical.get(value.lower(), value)
+                            for value in part[letter]]
+
+            # (d) Decide in Python. The protected labels never left this file.
+            if paired is None:
+                decision = {"accepted": False, "candidate_valid": False,
+                            "criterion": "valid paired prediction required",
+                            "base_correct": None, "candidate_correct": None,
+                            "total": len(gate_rows), "fixed": None,
+                            "broken": None, "reason": "gate_format_error"}
+            else:
+                decision = decide(
+                    paired["base"], paired["candidate"], truth,
+                    fmt.words(base_state), fmt.words(candidate_state),
+                    not candidate_errors and not gate_errors)
+
+            # The audit is a cost ledger, so it survives a rejected candidate.
+            audit = _copy(state["request_audit"])
+            state.clear()
+            state.update(candidate_state if decision["accepted"]
+                         else base_state)
+            state["request_audit"] = audit
+            state["candidates"].append({
+                "cycle": cycle, "feedback_through": stop,
+                "edits": [list(change) for change in changes],
+                "candidate_errors": candidate_errors,
+                "gate_errors": gate_errors, "document_orders": orders,
+                "gate_predictions_without_labels": paired,
+                "decision": decision})
+            state["gate"]["cycles_completed"] = cycle
+            if run_dir:
+                _atomic(run_dir / "candidate_skills" /
+                        f"candidate_{cycle:02d}{Path(fmt.skill_file).suffix}",
+                        render(candidate_state))
+                _atomic(run_dir / "candidates.json",
+                        json.dumps(state["candidates"], indent=2))
+                save_state(state, run_dir)
+                fmt.render_media(state, run_dir)
+            print(f"cycle {cycle}: candidate {decision['candidate_correct']}/"
+                  f"{len(gate_rows)} vs base {decision['base_correct']}/"
+                  f"{len(gate_rows)} -> "
+                  f"{'ACCEPT' if decision['accepted'] else 'REJECT'}",
+                  flush=True)
+    return Skill(state, run_dir)
+
+
+# --------------------------------------------------------------------------
+
+def baseline(data: Dataset, *, batch_size: int = 10, run_dir=None,
+             **_ignored) -> Skill:
+    """The zero-training control: no document, no requests spent."""
+    state = NO_FORMAT.new_state({
+        "dataset": data.name, "title": data.title,
+        "algorithm": "zero-training baseline", "classes": list(data.classes),
+        "format": None, "skill_file": "skill.txt",
+        "representation": data.representation, "image_size": data.image_size,
+        "description": describe(data), "train": 0, "batch_size": batch_size,
+        "model": MODEL, "effort": EFFORT,
+    })
+    if run_dir:
+        save_state(state, run_dir)
+    return Skill(state, run_dir)
+
+
+def score(skill: Skill, data: Dataset, *, batch_size: int = 10, run_dir=None,
+          session=None) -> Report:
+    """Score a frozen skill on ``data.test`` (or ``data.train`` if absent)."""
+    rows = data.test or data.train
+    if not rows:
+        raise ValueError("dataset has no rows to score")
+    state = skill.state
+    config = state.get("config", {})
+    fmt = format_of(state)
+    description = config.get("description") or describe(data)
+    representation = config.get("representation", data.representation)
+    image_size = int(config.get("image_size", data.image_size))
+    cache = (Path(run_dir) / "view_cache") if run_dir else None
+    results: list[dict] = []
+    requests = 0
+    with _borrowed(session) as session:
+        for start in range(0, len(rows), batch_size):
+            batch = rows[start:start + batch_size]
+            predictions, _, _ = predict_batch(
+                session, state, batch, description, representation,
+                image_size, fmt=fmt, cache=cache)
+            requests += 1
+            results += [
+                {"index": row["index"], "true": str(row["label"]),
+                 "pred": prediction["pred"],
+                 "correct": prediction["pred"] == str(row["label"]),
+                 "rules_used": prediction["rules_used"],
+                 "evidence": prediction["evidence"]}
+                for row, prediction in zip(batch, predictions)
+            ]
+            correct = sum(int(row["correct"]) for row in results)
+            print(f"  test {len(results):4d}/{len(rows)}: "
+                  f"{correct}/{len(results)}", flush=True)
+    report = Report(correct=sum(int(row["correct"]) for row in results),
+                    total=len(results), rows=results, requests=requests)
+    if run_dir:
+        state.setdefault("tests", {})[str(len(state["train"]))] = results
+        save_state(state, run_dir)
+    return report
+
+
+# --------------------------------------------------------------------------
+
+ALGOS = {"gate": fit_gated, "baseline": baseline}
+
+# The prequential learner this file used to carry. Silently remapping it to
+# the gate would run a different experiment under the old name.
+RETIRED_ALGOS = ("markdown",)
+
+
+def _coerce(data) -> Dataset:
+    if isinstance(data, Dataset):
+        return data
+    if isinstance(data, dict) and "train" in data:
+        return Dataset(**data)
+    if isinstance(data, (list, tuple)):
+        return Dataset(train=list(data))
+    raise TypeError(
+        "train() expects a Dataset, a list of labeled rows, or a mapping with "
+        f"a 'train' key; got {type(data).__name__}")
+
+
+def _algo(algo, method) -> str:
+    chosen = method if method is not None else algo
+    if chosen in RETIRED_ALGOS:
+        raise ValueError(
+            f"the {chosen!r} learning algorithm was removed; it accepted "
+            "every validated revision without a held-out check. Use "
+            "algo='gate' instead.")
+    if chosen not in ALGOS:
+        raise ValueError(
+            f"unknown algo {chosen!r}; choose one of {', '.join(ALGOS)}")
+    return chosen
+
+
+def train(data, *, algo: str = "gate", format=None, representation=None,
+          batch_size: int = 10, max_words=None, max_rules=None,
+          run_dir=None, resume: bool = True, evaluate_after: bool = False,
+          method=None, format_file=None, **options) -> Skill:
+    """Learn a skill document from labeled data.
+
+    ``algo`` is ``"gate"`` (keep a revision only when it beats the current
+    document on protected rows) or ``"baseline"`` (the zero-training control,
+    which is shown no document at all and spends no requests).
+
+    ``format`` names a section of ``format.md``; omitting it uses the file's
+    own default. The input representation is a property of the data, not of
+    the algorithm: pass rows carrying ``text`` for serialized features, or
+    ``image`` for pixels.
+    """
+    chosen = _algo(algo, method)
+    prepared = _coerce(data)
+    if representation is not None and representation != prepared.representation:
+        prepared = Dataset(
+            train=prepared.train, test=prepared.test,
+            classes=prepared.classes, name=prepared.name,
+            title=prepared.title, description=prepared.description,
+            representation=representation, image_size=prepared.image_size)
+    skill = ALGOS[chosen](
+        prepared, format=format, format_file=format_file,
+        batch_size=batch_size, max_words=max_words, max_rules=max_rules,
+        run_dir=run_dir, resume=resume, **options)
+    if evaluate_after and prepared.test:
+        skill.report = score(skill, prepared, batch_size=batch_size,
+                             run_dir=run_dir)
+    return skill
+
+
+def evaluate(skill: Skill, data, *, batch_size: int = 10,
+             run_dir=None) -> Report:
+    """Score a frozen skill on ``data.test`` (or ``data.train`` if absent)."""
+    report = score(skill, _coerce(data), batch_size=batch_size,
+                   run_dir=run_dir)
+    skill.report = report
+    return report
+
+def load(path) -> Skill:
+    """Reopen a saved run directory or ``state.json``."""
+    return Skill.load(path)
+
+
+# --------------------------------------------------------------------------