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

sdm/formats.py

@@ -0,0 +1,1182 @@
+"""How the hypothesis is written down, and how a revision is judged.
+
+This is the first of the four components, and the only one with real
+machinery. A skill format owns three things: where the learned hypothesis is
+stored, how the model perceives it, and what makes a proposed revision legal.
+
+There are three mechanisms, and every ``format.md`` section picks one:
+
+    edits      numbered rules with counters, revised by one bounded diff
+    document   one text document, replaced whole or kept
+    signal     a source the model never re-reads, only its rendering
+
+``edits`` and ``document`` are pure configuration, so a new text-based format
+is a new ``format.md`` section and no Python. ``signal`` needs a codec class,
+which lives in ``signals.py`` and is imported only on demand.
+
+The split of responsibility is deliberate: size knobs come from ``format.md``
+so a user can retune an experiment, but the safety rules are here in Python.
+The harness being able to refuse an illegal document is a premise of the
+method, not a preference.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from html.parser import HTMLParser
+from pathlib import Path
+
+from .data import _inputs
+from .gateway import SetupNeeded
+
+
+CONDITION_WORDS = 45
+
+PREDICTION_RE = re.compile(
+    r"^P(\d{1,5})\s*\|\s*([^|]+?)\s*\|\s*([^|]*)\|\s*(.+)$", re.IGNORECASE)
+PLAIN_PREDICTION_RE = re.compile(
+    r"^P(\d{1,5})\s*\|\s*([^|]+?)\s*\|\s*(.+)$", re.IGNORECASE)
+GATE_LINE_RE = re.compile(r"^P(\d{1,5})\s*\|\s*([^|]+?)(?:\s*\|.*)?$")
+EDITS_RE = re.compile(r"<edits>\s*(.*?)\s*</edits>", re.DOTALL | re.IGNORECASE)
+DOCUMENT_RE = re.compile(
+    r'<predictions\s+document=["\']?([AB])["\']?\s*>\s*(.*?)\s*</predictions>',
+    re.IGNORECASE | re.DOTALL)
+
+EDIT_GRAMMAR = """ADD | class | predicate for an unseen input
+ADD | general | reusable reading procedure or cross-class exclusion
+REVISE | R001 | complete replacement predicate
+SUPPORT | R001
+DELETE | R001
+NOOP"""
+
+
+def _base_state(config: dict) -> dict:
+    return {"version": 1, "config": config, "train": [], "tests": {},
+            "request_audit": []}
+
+
+def new_state(config: dict) -> dict:
+    """A fresh rulebook state."""
+    return {**_base_state(config), "next_rule_id": 1, "rules": []}
+
+
+def _copy(state: dict) -> dict:
+    return json.loads(json.dumps(state))
+
+
+def _rules_by_id(state: dict) -> dict[str, dict]:
+    return {rule["id"]: rule for rule in state.get("rules", [])}
+
+
+def _dedupe(errors: list[str], keep: int = 8) -> list[str]:
+    seen: list[str] = []
+    for error in errors:
+        if error not in seen:
+            seen.append(error)
+    return seen[:keep]
+
+
+def render_rulebook(state: dict) -> str:
+    """Render rulebook ``state`` as the Markdown document the model reads."""
+    config = state.get("config", {})
+    seen = len(state["train"])
+    correct = sum(int(row["correct"]) for row in state["train"])
+    rules = state.get("rules", [])
+    lines = [
+        f'# {config.get("title", "Rulebook")}',
+        "",
+        f"Seen: {seen} example(s). Prediction record: {correct}/{seen}.",
+        "",
+        "This complete document is the learned hypothesis. Rules must "
+        "describe only reusable evidence available in a new unlabeled input.",
+        "",
+        "## Reading procedure",
+    ]
+
+    def entry(rule):
+        return (f'{rule["id"]} [support={rule["support"]} used={rule["used"]} '
+                f'hit={rule["hit"]}] {rule["condition"]}')
+
+    general = [rule for rule in rules if rule["class"] == "general"]
+    if general:
+        lines += [f"{number}. {entry(rule)}"
+                  for number, rule in enumerate(general, 1)]
+    else:
+        lines.append("No learned cross-class procedure yet.")
+
+    lines += ["", "## Per-class signatures"]
+    for label in config.get("classes", ()):
+        selected = [rule for rule in rules if rule["class"] == label]
+        lines += ["", f"### {label}"]
+        lines += ([f"- {entry(rule)}" for rule in selected] or
+                  ["No reliable signature yet."])
+    return "\n".join(lines) + "\n"
+
+
+def render(state: dict) -> str:
+    """Render any skill state as its source document.
+
+    Document formats keep their source in ``state["doc"]``; the rulebook is
+    rendered from its rules, so neither needs ``format.md`` to be readable.
+    """
+    if state.get("config", {}).get("format", "markdown") is None:
+        return ""
+    if "doc" in state:
+        return state["doc"]
+    return render_rulebook(state)
+
+
+def parse_edits(text: str):
+    """Split an ``<edits>`` block into operation tuples plus syntax errors."""
+    match = EDITS_RE.search(text)
+    if not match:
+        return None, ["missing <edits> block"]
+    edits, errors = [], []
+    for raw in match.group(1).splitlines():
+        line = raw.strip().lstrip("- ").strip()
+        if not line or line.upper() == "NOOP":
+            continue
+        parts = [part.strip() for part in line.split("|")]
+        operation = parts[0].upper()
+        if operation == "ADD" and len(parts) == 3:
+            edits.append((operation, parts[1].lower(), parts[2]))
+        elif operation == "REVISE" and len(parts) == 3:
+            edits.append((operation, parts[1].upper(), parts[2]))
+        elif operation in {"DELETE", "SUPPORT"} and len(parts) == 2:
+            edits.append((operation, parts[1].upper()))
+        else:
+            errors.append(f"malformed edit: {line!r}")
+    return edits, errors
+
+
+def clean_condition(condition: str, label: str) -> str:
+    """Strip the ``IF ...`` and ``... then predict X`` wrappers models add."""
+    condition = re.sub(r"^IF\s+", "", condition.strip(), flags=re.I)
+    condition = re.sub(
+        rf"\s*,?\s*(?:THEN\s+)?(?:predict|classify as)\s+{re.escape(label)}[.!]?$",
+        "", condition, flags=re.I)
+    return condition.strip()
+
+
+def apply_edits(state: dict, edits: list[tuple], max_words: int,
+                max_rules: int) -> list[str]:
+    """Validate every edit against a copy, then commit them all or none."""
+    valid = {label.lower(): label
+             for label in state.get("config", {}).get("classes", ())}
+    valid["general"] = "general"
+    candidate = _copy(state)
+    rules = _rules_by_id(candidate)
+    errors: list[str] = []
+    touched: set[str] = set()
+
+    for edit in edits:
+        operation = edit[0]
+        if operation == "ADD":
+            _, raw_label, raw_condition = edit
+            label = valid.get(str(raw_label).strip().lower())
+            if label is None:
+                errors.append(f"ADD has invalid class {raw_label!r}")
+                continue
+            condition = clean_condition(raw_condition, label)
+            if not condition:
+                errors.append("ADD has an empty condition")
+            elif len(condition.split()) > CONDITION_WORDS:
+                errors.append(f"ADD condition exceeds {CONDITION_WORDS} words")
+            else:
+                rule_id = f'R{candidate["next_rule_id"]:03d}'
+                candidate["next_rule_id"] += 1
+                rule = {"id": rule_id, "class": label, "condition": condition,
+                        "support": 1, "used": 0, "hit": 0}
+                candidate["rules"].append(rule)
+                rules[rule_id] = rule
+            continue
+
+        rule_id = edit[1]
+        if rule_id not in rules:
+            errors.append(f"{operation} references unknown rule {rule_id}")
+        elif rule_id in touched:
+            errors.append(f"multiple edits target {rule_id}")
+        else:
+            touched.add(rule_id)
+            if operation == "DELETE":
+                candidate["rules"] = [rule for rule in candidate["rules"]
+                                      if rule["id"] != rule_id]
+                rules.pop(rule_id)
+            elif operation == "SUPPORT":
+                rules[rule_id]["support"] += 1
+            elif operation == "REVISE":
+                condition = clean_condition(edit[2], rules[rule_id]["class"])
+                if not condition:
+                    errors.append(f"REVISE {rule_id} has an empty condition")
+                elif len(condition.split()) > CONDITION_WORDS:
+                    errors.append(f"REVISE {rule_id} condition exceeds "
+                                  f"{CONDITION_WORDS} words")
+                else:
+                    rules[rule_id]["condition"] = condition
+                    rules[rule_id]["support"] += 1
+
+    if len(candidate["rules"]) > max_rules:
+        errors.append(
+            f'rule count {len(candidate["rules"])} exceeds {max_rules}')
+    words = len(render_rulebook(candidate).split())
+    if words > max_words:
+        errors.append(f"skill has {words} words; hard limit is {max_words}")
+    if errors:
+        return errors
+    state.clear()
+    state.update(candidate)
+    return []
+
+
+def _clean_line(raw: str) -> str:
+    """One response line with the decoration models add stripped off."""
+    line = raw.strip().strip("|").strip().replace("**", "").replace("`", "")
+    return re.sub(r"^[-*]\s*", "", line)
+
+
+def parse_predictions(raw: str, count: int, classes,
+                      cites_rules: bool = True) -> tuple[dict, list[str]]:
+    """Read one ``<predictions>`` block into position-indexed predictions."""
+    canonical = {str(label).lower(): str(label) for label in classes}
+    pattern = PREDICTION_RE if cites_rules else PLAIN_PREDICTION_RE
+    parsed: dict[int, dict] = {}
+    errors: list[str] = []
+    for raw_line in raw.splitlines():
+        match = pattern.match(_clean_line(raw_line))
+        if not match:
+            continue
+        groups = match.groups()
+        if cites_rules:
+            number, label, ids, evidence = groups
+        else:
+            number, label, evidence = groups
+            ids = ""
+        position = int(number)
+        label = label.strip().lower()
+        if not 1 <= position <= count:
+            errors.append(f"out-of-range P{position:02d}")
+        elif canonical and label not in canonical:
+            errors.append(f"invalid class {label!r} for P{position:02d}")
+        elif position in parsed:
+            errors.append(f"duplicate P{position:02d}")
+        else:
+            parsed[position] = {
+                "pred": canonical.get(label, label),
+                "rules_used": re.findall(r"R\d+", ids.upper()),
+                "evidence": evidence.strip()[:500],
+            }
+    missing = [position for position in range(1, count + 1)
+               if position not in parsed]
+    if missing:
+        errors.append(f"missing {missing}")
+    return parsed, errors
+
+
+def credit(state: dict, predictions: list[dict], labels: list[str]) -> None:
+    """Attribute one batch outcome to every rule the predictor cited."""
+    rules = _rules_by_id(state)
+    for prediction, label in zip(predictions, labels):
+        for rule_id in set(prediction["rules_used"]):
+            rule = rules.get(rule_id)
+            if rule is not None:
+                rule["used"] += 1
+                rule["hit"] += int(prediction["pred"] == label)
+
+
+def record(state: dict, kind: str, **values) -> None:
+    """Append one billed model request to the run's cost ledger."""
+    state["request_audit"].append(
+        {"request": len(state["request_audit"]) + 1, "kind": kind, **values})
+
+
+# --------------------------------------------------------------------------
+
+# Everything a static, self-contained document never needs. Scripts and frames
+# could change what the graders see; external references would make the
+# document depend on the network instead of on what was learned.
+FORBIDDEN_TAGS = {
+    "script", "iframe", "object", "embed", "link", "base", "form", "applet",
+    "frame", "frameset", "audio", "video", "source",
+}
+# Containers whose truncation or misnesting silently swallows later content.
+BALANCED_TAGS = {"html", "body", "svg", "table", "div"}
+
+
+class _Auditor(HTMLParser):
+    """One pass over the document: safety, nesting, and the visible words."""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.errors: list[str] = []
+        self.words = 0
+        self.stack: list[str] = []
+        self._invisible = 0
+
+    def handle_starttag(self, tag, attrs):
+        self._check(tag, attrs)
+        if tag in BALANCED_TAGS:
+            self.stack.append(tag)
+        if tag == "style":
+            self._invisible += 1
+
+    def handle_startendtag(self, tag, attrs):
+        self._check(tag, attrs)
+
+    def handle_endtag(self, tag):
+        if tag == "style" and self._invisible:
+            self._invisible -= 1
+        if tag in BALANCED_TAGS:
+            if self.stack and self.stack[-1] == tag:
+                self.stack.pop()
+            else:
+                self.errors.append(f"misnested or unopened </{tag}>")
+
+    def handle_data(self, data):
+        if not self._invisible:
+            self.words += len(data.split())
+
+    def _check(self, tag, attrs):
+        if tag in FORBIDDEN_TAGS:
+            self.errors.append(f"forbidden tag <{tag}>")
+        for name, value in attrs:
+            name = name.lower()
+            if name.startswith("on"):
+                self.errors.append(
+                    f"forbidden event attribute {name!r} on <{tag}>")
+            if name == "xmlns" or name.startswith("xmlns:"):
+                # A namespace declaration identifies a vocabulary; nothing is
+                # fetched from it, so the standard SVG xmlns is fine.
+                continue
+            lowered = (value or "").strip().lower()
+            if lowered.startswith(("http://", "https://", "//",
+                                   "javascript:")):
+                self.errors.append(
+                    f"<{tag} {name}=...> references outside the document; "
+                    "it must be self-contained")
+
+
+def _audit(document: str) -> _Auditor:
+    auditor = _Auditor()
+    auditor.feed(document)
+    auditor.close()
+    return auditor
+
+
+def _too_long(document: str, max_chars: int) -> list[str]:
+    if len(document) <= max_chars:
+        return []
+    return [f"document is {len(document)} characters; hard limit is "
+            f"{max_chars}"]
+
+
+def validate_text(document: str, max_words: int, max_chars: int) -> list[str]:
+    """The generic size guard every text document gets."""
+    errors = _too_long(document, max_chars)
+    if not document.strip():
+        errors.append("the document is empty")
+    words = len(document.split())
+    if words > max_words:
+        errors.append(f"document has {words} words; hard limit is {max_words}")
+    return _dedupe(errors)
+
+
+def _validate_markup(document: str, max_words: int, max_chars: int,
+                     root: str, shape: str) -> list[str]:
+    """Size, safety, nesting, and truncation for one markup document."""
+    errors = _too_long(document, max_chars)
+    lowered = document.lower()
+    if f"<{root}" not in lowered:
+        errors.append(f"document must be {shape}")
+    if f"</{root}>" not in lowered:
+        # The one reliable truncation guard: a cut-off rewrite never ends.
+        errors.append(f"document does not end with </{root}>; it looks "
+                      "truncated")
+    try:
+        auditor = _audit(document)
+    except Exception as error:  # noqa: BLE001 - reported to the model
+        errors.append(f"document does not parse as markup: {error}")
+        return _dedupe(errors)
+    errors += auditor.errors
+    if auditor.stack:
+        errors.append("unclosed tag(s): "
+                      + ", ".join(f"<{tag}>" for tag in auditor.stack))
+    if auditor.words > max_words:
+        # Markup is not counted: this is what a reader of the page would see.
+        errors.append(f"document has {auditor.words} visible words; hard "
+                      f"limit is {max_words}")
+    return _dedupe(errors)
+
+
+def validate_html(document: str, max_words: int, max_chars: int) -> list[str]:
+    """Everything wrong with a candidate HTML page, or an empty list."""
+    return _validate_markup(document, max_words, max_chars, "html",
+                            "a standalone page with an <html> tag")
+
+
+def validate_svg(document: str, max_words: int, max_chars: int) -> list[str]:
+    """Everything wrong with a candidate standalone SVG, or an empty list."""
+    return _validate_markup(document, max_words, max_chars, "svg",
+                            "one standalone <svg> element")
+
+
+VALIDATORS = {"text": validate_text, "html": validate_html,
+              "svg": validate_svg}
+
+
+# --------------------------------------------------------------------------
+
+SVG_RE = re.compile(r"<svg\b.*?</svg>", re.DOTALL | re.IGNORECASE)
+
+
+def _render_media_enabled() -> bool:
+    return os.environ.get("SDM_RENDER_MEDIA", "1") != "0"
+
+
+FRAME_WIDTH, FRAME_HEIGHT = 640, 360
+
+
+def _svg_png(svg: str) -> bytes | None:
+    """Rasterize one SVG in process; None when no renderer is available."""
+    try:
+        os.environ.setdefault("DYLD_FALLBACK_LIBRARY_PATH",
+                              "/opt/homebrew/lib")
+        import cairosvg
+
+        if "xmlns" not in svg:
+            svg = svg.replace(
+                "<svg", '<svg xmlns="http://www.w3.org/2000/svg"', 1)
+        return cairosvg.svg2png(bytestring=svg.encode(),
+                                output_width=FRAME_WIDTH,
+                                output_height=FRAME_HEIGHT,
+                                background_color="white")
+    except Exception:  # noqa: BLE001 - fall back to QuickLook below
+        return None
+
+
+def _svg_png_quicklook(svg: str, number: int = 1) -> bytes | None:
+    """The macOS fallback rasterizer, via QuickLook on a wrapper page."""
+    if not shutil.which("qlmanage"):
+        return None
+    page = (
+        '<!DOCTYPE html><html><head><meta charset="utf-8"><style>'
+        f"body{{margin:0;width:{FRAME_WIDTH}px;height:{FRAME_HEIGHT}px;"
+        "display:flex;align-items:center;justify-content:center;"
+        "background:#fff}"
+        f"</style></head><body>{svg}</body></html>"
+    )
+    with tempfile.TemporaryDirectory() as scratch:
+        source = Path(scratch) / f"frame_{number:02d}.html"
+        source.write_text(page)
+        subprocess.run(
+            ["qlmanage", "-t", "-s", str(FRAME_WIDTH), "-o", scratch,
+             str(source)],
+            capture_output=True, timeout=60, check=False,
+        )
+        thumb = source.with_suffix(".html.png")
+        return thumb.read_bytes() if thumb.exists() else None
+
+
+def rasterize(svg: str, number: int = 1) -> bytes:
+    """One SVG as PNG bytes, or a clear error about the missing renderer."""
+    png = _svg_png(svg) or _svg_png_quicklook(svg, number)
+    if png is None:
+        raise SetupNeeded(
+            "no SVG rasterizer available, so a format that renders SVG "
+            "cannot run. Install cairosvg (pip install cairosvg, plus "
+            "'brew install cairo' on macOS), or choose a text-only format "
+            "in format.md."
+        )
+    return png
+
+
+def _canvas(png: bytes) -> bytes:
+    """Letterbox a rendered frame onto a fixed white canvas."""
+    from PIL import Image
+
+    size = (FRAME_WIDTH, FRAME_HEIGHT)
+    canvas = Image.new("RGB", size, "white")
+    tile = Image.open(io.BytesIO(png)).convert("RGB")
+    tile.thumbnail(size)
+    canvas.paste(tile, ((FRAME_WIDTH - tile.width) // 2,
+                        (FRAME_HEIGHT - tile.height) // 2))
+    buffer = io.BytesIO()
+    canvas.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+# --------------------------------------------------------------------------
+
+def codecs() -> dict:
+    """The audio and video codecs, imported only when a format asks for one.
+
+    They live in ``signals.py`` because they are the only code in this project
+    that wants numpy, Pillow, or ffmpeg. Nothing in the learning loop touches
+    them, so a text-only install never pays for them.
+    """
+    from . import signals
+
+    return signals.CODECS
+
+
+# --------------------------------------------------------------------------
+
+class SkillFormat:
+    """One skill format: a mechanism parameterized by a format.md section.
+
+    Subclasses are the mechanisms. Each owns how the hypothesis is stored,
+    how the model perceives it, and how a proposed revision is validated.
+    """
+
+    mechanism = ""
+    block = "skill_document"
+    skill_file = "skill.txt"
+    cites_rules = False
+    channel = ""
+    noun = "skill document"
+
+    def __init__(self, name: str, spec: str = "", knobs: dict | None = None,
+                 seed: str | None = None):
+        self.name = name
+        self.spec = spec.strip()
+        self.knobs = dict(knobs or {})
+        self._seed = seed
+
+    def __repr__(self):
+        return f"SkillFormat(name={self.name!r}, mechanism={self.mechanism!r})"
+
+    # -- limits ----------------------------------------------------------
+    def limits(self, **overrides) -> dict:
+        """The knobs from format.md, with explicit arguments winning."""
+        merged = {"max_words": 8000, "max_chars": 30000, "max_rules": 100,
+                  "max_semantic": 4, "max_support": 4}
+        merged.update({key: value for key, value in self.knobs.items()
+                       if key in merged})
+        merged.update({key: value for key, value in overrides.items()
+                       if value is not None})
+        return merged
+
+    # -- the hypothesis --------------------------------------------------
+    def seed(self, config: dict) -> str:
+        return self._seed or ""
+
+    def new_state(self, config: dict) -> dict:
+        return {**_base_state(config), "doc": self.seed(config)}
+
+    def source(self, state: dict) -> str:
+        """The document as the model wrote it."""
+        return state.get("doc", "")
+
+    def words(self, state: dict) -> int:
+        return len(self.source(state).split())
+
+    def view(self, state: dict, cache=None) -> tuple[str, list[bytes]]:
+        """What the model perceives: prompt text plus attached images."""
+        return self.source(state), []
+
+    def credit(self, state: dict, predictions: list[dict],
+               labels: list[str]) -> None:
+        """Attribute a batch outcome to the parts of the skill it cited."""
+
+    def render_media(self, state: dict, run_dir: Path) -> None:
+        """Write any playable or viewable rendering beside the source."""
+
+    # -- proposing a revision --------------------------------------------
+    def update_instructions(self, limits: dict) -> str:
+        raise NotImplementedError
+
+    def validate(self, document: str, limits: dict) -> list[str]:
+        """Every reason the harness refuses this document, or nothing."""
+        raise NotImplementedError
+
+    def propose(self, state: dict, raw: str,
+                limits: dict) -> tuple[list[tuple], list[str]]:
+        """Parse, validate, and apply one revision, all or nothing.
+
+        The default is whole-document replacement, which is what every format
+        but the edit grammar does.
+        """
+        document, errors = parse_document(raw, self.block)
+        if errors:
+            return [], errors
+        if document is KEEP:
+            return [], []
+        errors = self.validate(document, limits)
+        if errors:
+            return [], errors
+        state["doc"] = document
+        return [("REPLACE", self.name)], []
+
+    # -- prompts ---------------------------------------------------------
+    def prediction_line(self) -> str:
+        if self.cites_rules:
+            return ("P01 | class | R001,R002 or none | evidence of at most "
+                    "20 words")
+        return "P01 | class | evidence of at most 20 words"
+
+    def skill_section(self, view_text: str) -> str:
+        return f'<skill_file format="{self.name}">\n{view_text}</skill_file>'
+
+    def rendering_note(self) -> str:
+        """One sentence about how the document is presented, if it needs one."""
+        return ""
+
+    def reading_instruction(self) -> str:
+        return (f"Use the learned {self.name} skill document to classify "
+                f"every input independently. {self.rendering_note()}All "
+                "inputs share the same document snapshot; do not learn from "
+                "the other inputs in this batch. If the document is empty or "
+                "ambiguous, make your best guess.")
+
+    def predict_prompt(self, description: str, classes, view_text: str,
+                       rows: list[dict], representation: str) -> str:
+        head = (f"You are the prediction component of a supervised learner.\n"
+                f'{description}\nClasses: {", ".join(classes)}.')
+        tail = (f"Output ONLY a <predictions> block with exactly {len(rows)} "
+                f"lines, one per\ninput, in this format:\n"
+                f"{self.prediction_line()}\n\nThe class must be exactly one "
+                f'of: {", ".join(classes)}.\n</predictions>')
+        # A no-document format contributes no skill section, and an image
+        # representation contributes no input text, so skip empty parts
+        # rather than leaving a hole in the prompt.
+        parts = [head, self.reading_instruction(),
+                 self.skill_section(view_text),
+                 _inputs(rows, representation), tail]
+        return "\n\n".join(part for part in parts if part)
+
+
+class EditsFormat(SkillFormat):
+    """Numbered rules revised by one bounded, atomic diff."""
+
+    mechanism = "edits"
+    block = "edits"
+    skill_file = "skill.md"
+    cites_rules = True
+    noun = "bounded Markdown rulebook"
+
+    def new_state(self, config: dict) -> dict:
+        return new_state(config)
+
+    def source(self, state: dict) -> str:
+        return render_rulebook(state)
+
+    def credit(self, state, predictions, labels):
+        credit(state, predictions, labels)
+
+    def update_instructions(self, limits: dict) -> str:
+        return f"""Return only an <edits> block. Allowed operations are:
+{EDIT_GRAMMAR}
+
+Use at most {limits["max_semantic"]} total ADD/REVISE/DELETE operations and at
+most {limits["max_support"]} SUPPORT operations. {self.spec} Every predicate
+states a reusable condition on the current input alone and contains at most
+{CONDITION_WORDS} words. The complete rulebook is bounded to
+{limits["max_rules"]} rules and {limits["max_words"]} words.
+</edits>"""
+
+    def propose(self, state, raw, limits):
+        edits, errors = parse_edits(raw)
+        if edits is None:
+            return [], errors
+        semantic = sum(edit[0] in {"ADD", "REVISE", "DELETE"}
+                       for edit in edits)
+        supports = sum(edit[0] == "SUPPORT" for edit in edits)
+        if semantic > limits["max_semantic"]:
+            errors.append(f"semantic edit count {semantic} exceeds "
+                          f'{limits["max_semantic"]}')
+        if supports > limits["max_support"]:
+            errors.append(f"support edit count {supports} exceeds "
+                          f'{limits["max_support"]}')
+        if not errors:
+            errors += apply_edits(state, edits, limits["max_words"],
+                                  limits["max_rules"])
+        return edits, errors
+
+
+class DocumentFormat(SkillFormat):
+    """A whole text document, replaced outright or kept with NOOP.
+
+    ``validator`` picks the harness-enforced checks (``text``, ``html``, or
+    ``svg``); ``render: svg`` additionally shows the model its own document
+    rasterized, so it can see what it drew.
+    """
+
+    mechanism = "document"
+    noun = "bounded skill document"
+
+    @property
+    def validator(self):
+        return VALIDATORS.get(self.knobs.get("validator", "text"),
+                              validate_text)
+
+    @property
+    def block(self) -> str:
+        return str(self.knobs.get("block", f"skill_{self.name}"))
+
+    @property
+    def skill_file(self) -> str:
+        suffix = {"html": "html", "svg": "svg"}.get(
+            self.knobs.get("validator"), "txt")
+        return f"skill.{suffix}"
+
+    @property
+    def rasterized(self) -> bool:
+        return str(self.knobs.get("render", "")).lower() == "svg"
+
+    def seed(self, config: dict) -> str:
+        if self._seed:
+            return self._seed
+        return _default_seed(self.knobs.get("validator", "text"), config)
+
+    def view(self, state, cache=None):
+        source = self.source(state)
+        if not (self.rasterized and _render_media_enabled()):
+            return source, []
+        svg = SVG_RE.search(source)
+        if svg is None:
+            return source, []
+        return source, [_canvas(rasterize(svg.group(0)))]
+
+    def render_media(self, state, run_dir):
+        if not (self.rasterized and _render_media_enabled()):
+            return
+        svg = SVG_RE.search(self.source(state))
+        if svg is not None:
+            (run_dir / "skill.png").write_bytes(
+                _canvas(rasterize(svg.group(0))))
+
+    def rendering_note(self) -> str:
+        if not self.rasterized:
+            return ""
+        return ("Its rendering is attached as an image; read the drawing as "
+                "part of the hypothesis. ")
+
+    def update_instructions(self, limits: dict) -> str:
+        return f"""Return ONLY a <{self.block}> block holding the complete
+replacement document, or NOOP to keep the current one.
+
+{self.spec}
+
+The document is a hypothesis, not an example log: no input IDs, no labels
+copied from individual examples, no memorized per-example values. Every
+statement must be checkable on a new unlabeled input alone. Keep what already
+works and revise conservatively. Hard limits: {limits["max_words"]} words and
+{limits["max_chars"]} characters."""
+
+    def validate(self, document, limits):
+        return self.validator(document, limits["max_words"],
+                              limits["max_chars"])
+
+
+class SignalFormat(SkillFormat):
+    """A source the model writes but never re-reads: only the channel view.
+
+    At update time the model sees its source *and* what the source becomes
+    through the channel, so it can learn what survives. At prediction time
+    the source is withheld.
+    """
+
+    mechanism = "signal"
+
+    @property
+    def codec(self):
+        available = codecs()
+        name = self.knobs.get("signal", self.name)
+        if name not in available:
+            raise SetupNeeded(
+                f"format {self.name!r} needs 'signal: audio' or "
+                f"'signal: video' in format.md; got {name!r}")
+        return available[name]
+
+    @property
+    def block(self) -> str:
+        return self.codec.block
+
+    @property
+    def skill_file(self) -> str:
+        return self.codec.skill_file
+
+    @property
+    def channel(self) -> str:
+        return self.codec.channel
+
+    @property
+    def noun(self) -> str:
+        return self.codec.noun
+
+    def seed(self, config: dict) -> str:
+        return self._seed or self.codec.seed
+
+    def view(self, state, cache=None):
+        return self.codec.view(self.source(state), _cache_dir(cache))
+
+    def render_media(self, state, run_dir):
+        if _render_media_enabled():
+            self.codec.render_media(self.source(state), Path(run_dir))
+
+    def skill_section(self, view_text: str) -> str:
+        return f"<skill_signal_analysis>\n{view_text}\n</skill_signal_analysis>"
+
+    def reading_instruction(self) -> str:
+        return (f"Your learned skill is stored ONLY as a rendered "
+                f"{self.codec.name} signal. You are not shown its source. "
+                f"You perceive it through {self.channel}. Read the reading "
+                "procedure and per-class signatures that the signal presents, "
+                "and apply them. Classify every input independently; if the "
+                "signal is uninformative, make your best guess.")
+
+    def update_instructions(self, limits: dict) -> str:
+        return f"""Your entire long-term memory for this task is one rendered
+{self.codec.name} signal. At prediction time you will NOT see its source; you
+will perceive the signal only through {self.channel}. Write the replacement
+source so that the channel view still presents, clearly enough for your
+prediction step to use, the general reading procedure, per-class signatures,
+and known error modes learned so far.
+
+Return ONLY a <{self.block}> block holding the complete replacement source, or
+NOOP to keep the current one.
+
+{self.spec}"""
+
+    def validate(self, document, limits):
+        # The codec's own structural caps (events, seconds, frames) bind
+        # here; a signal has no meaningful word count.
+        return self.codec.validate(document)
+
+
+class NoFormat(SkillFormat):
+    """No skill document at all: the zero-training control.
+
+    It contributes an empty skill section, so the shared prediction prompt
+    omits the section entirely rather than showing a blank one.
+    """
+
+    mechanism = "none"
+    skill_file = "skill.txt"
+
+    def new_state(self, config: dict) -> dict:
+        return _base_state(config)
+
+    def source(self, state):
+        return ""
+
+    def view(self, state, cache=None):
+        return "", []
+
+    def skill_section(self, view_text: str) -> str:
+        return ""
+
+    def reading_instruction(self) -> str:
+        return ("Classify every input independently from your own prior "
+                "knowledge. There is no learned skill document. Do not learn "
+                "from the other inputs in this batch.")
+
+    def update_instructions(self, limits):
+        raise SetupNeeded("the baseline control has no document to revise")
+
+    def propose(self, state, raw, limits):
+        raise SetupNeeded("the baseline control has no document to revise")
+
+
+MECHANISMS = {"edits": EditsFormat, "document": DocumentFormat,
+              "signal": SignalFormat, "none": NoFormat}
+
+NO_FORMAT = NoFormat("none")
+
+KEEP = object()  # the sentinel for a NOOP revision
+
+
+def parse_document(raw: str, block: str):
+    """The replacement document in ``raw``: a string, ``KEEP``, or errors."""
+    if raw.strip().upper() == "NOOP":
+        return KEEP, []
+    pattern = re.compile(rf"<{re.escape(block)}>\s*(.*?)\s*</{re.escape(block)}>",
+                         re.DOTALL | re.IGNORECASE)
+    match = pattern.search(raw)
+    if not match:
+        return None, [f"missing <{block}> block"]
+    body = match.group(1)
+    if body.strip().upper() == "NOOP":
+        return KEEP, []
+    return body, []
+
+
+def _default_seed(validator: str, config: dict) -> str:
+    """The empty hypothesis: the section layout, with nothing learned yet."""
+    title = config.get("title", "Skill document")
+    if validator == "svg":
+        return f"""<svg width="640" height="480" viewBox="0 0 640 480">
+<text x="20" y="40" font-size="22">{title}</text>
+<text x="20" y="80" font-size="16">nothing learned yet</text>
+</svg>
+"""
+    if validator == "html":
+        sections = "\n".join(
+            f"<h3>{label}</h3>\n<p>No reliable signature yet.</p>"
+            for label in config.get("classes", ()))
+        return f"""<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>{title}</title></head>
+<body>
+<h1>{title}</h1>
+<p>This complete document is the learned hypothesis. It must describe only
+reusable evidence available in a new unlabeled input.</p>
+<h2>Reading procedure</h2>
+<p>No learned cross-class procedure yet.</p>
+<h2>Per-class signatures</h2>
+{sections}
+<h2>Decision boundaries and error log</h2>
+<p>No errors recorded yet.</p>
+</body>
+</html>
+"""
+    signatures = "\n".join(f"### {label}\nNo reliable signature yet.\n"
+                           for label in config.get("classes", ()))
+    return (f"# {title}\n\n## Reading procedure\nNo learned cross-class "
+            f"procedure yet.\n\n## Per-class signatures\n{signatures}")
+
+
+def _cache_dir(cache) -> Path:
+    if cache is not None:
+        return Path(cache)
+    return Path(tempfile.gettempdir()) / "sdm_view_cache"
+
+
+# --------------------------------------------------------------------------
+
+FRONT_MATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+SECTION_RE = re.compile(r"^##\s+(\S+)\s*$", re.MULTILINE)
+KNOB_RE = re.compile(r"^([a-z][a-z0-9_]*)\s*:\s*(\S.*?)\s*$")
+SEED_RE = re.compile(r"```seed\s*\n(.*?)```", re.DOTALL)
+
+DEFAULT_FORMAT_MD = '''---
+format: markdown
+---
+
+# Skill formats
+
+Pick a format by editing the `format:` line above. Each section below defines
+one. The `mechanism:` line says which machinery the harness uses:
+
+- `edits` numbered rules revised by one bounded atomic diff
+- `document` one text document replaced outright, or kept with NOOP
+- `signal` a source the model writes but never re-reads, only its rendering
+
+Sections using `edits` or `document` are pure configuration, so a new
+text-based format needs nothing but another section here. Safety checks stay
+in Python: `validator:` selects them.
+
+## markdown
+
+mechanism: edits
+max_words: 8000
+max_rules: 100
+
+Use one operation per line and never put "|" inside a condition. Rules are a
+rulebook, not an example log: no input IDs, no labels copied from individual
+examples, no memorized values. Prefer revising an existing rule over adding a
+near-duplicate. Write only the predicate: do not start it with IF or end it
+with a prediction. IDs and the reliability counters are maintained by the
+harness; do not write them.
+
+## html
+
+mechanism: document
+validator: html
+block: skill_html
+max_words: 8000
+max_chars: 30000
+
+One standalone static page, ending with `</html>`. No scripts, no frames, no
+forms, no event handler attributes, and no external references of any kind.
+Inline SVG is encouraged where a sketch beats a sentence: small labelled
+prototype drawings per class, a workflow diagram for the reading procedure,
+and contrast pairs for classes that get confused. Track recurring mistakes in
+an error-log section so the same confusion is not repeated.
+
+## image
+
+mechanism: document
+validator: svg
+render: svg
+block: skill_svg
+max_words: 2000
+max_chars: 20000
+
+One standalone `<svg>` element, ending with `</svg>`. This is a diagram you
+will be shown as a picture on every future prediction, so draw the decision
+procedure rather than writing paragraphs: labelled class prototypes, a
+flowchart of the reading procedure, and contrast pairs for confusable classes.
+Text inside the SVG is fine, but anything that only makes sense as prose
+belongs in a caption. No external references.
+
+## audio
+
+mechanism: signal
+signal: audio
+
+Write a synthesis score, one event per line:
+TONE <frequency_hz 50-4000> <seconds 0.05-2>
+REST <seconds 0.05-2>
+Lines starting with # are stripped before rendering and will NOT survive.
+At most 400 events and 30s total.
+
+## video
+
+mechanism: signal
+signal: video
+
+Write a standalone HTML storyboard. Each frame is:
+<section class="frame" data-seconds="N">
+  <svg width="640" height="360" viewBox="0 0 640 360"> ... </svg>
+</section>
+with 1 <= N <= 10, at most 12 frames, 60s total. No scripts, no external
+references. Anything you draw or write inside the SVGs survives as pixels;
+nothing outside them does.
+'''
+
+
+PACKAGED_FORMAT_FILE = Path(__file__).parent / "format.md"
+
+
+def format_file(path=None) -> Path:
+    """Which ``format.md`` this run reads, and why that order.
+
+    The whole point of the file is that a user edits it, so an installed copy
+    under ``site-packages`` is the last resort, not the first. A project keeps
+    its own ``format.md`` beside its data and gets it picked up automatically;
+    ``sdm init`` writes one out to start from.
+
+    1. an explicit path, or ``SDM_FORMAT_FILE``
+    2. ``./format.md`` in the working directory
+    3. the copy shipped inside the package
+    """
+    if path is not None:
+        return Path(path)
+    override = os.environ.get("SDM_FORMAT_FILE")
+    if override:
+        return Path(override)
+    local = Path.cwd() / "format.md"
+    if local.is_file():
+        return local
+    return PACKAGED_FORMAT_FILE
+
+
+def write_format_file(target=None, *, force: bool = False) -> Path:
+    """Copy the packaged ``format.md`` into a project so it can be edited."""
+    destination = Path(target or Path.cwd() / "format.md")
+    if destination.is_dir():
+        destination = destination / "format.md"
+    if destination.exists() and not force:
+        raise SetupNeeded(
+            f"{destination} already exists; pass force=True to overwrite it.")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(PACKAGED_FORMAT_FILE.read_text())
+    return destination
+
+
+def _parse_knobs(body: str) -> tuple[dict, str]:
+    """The contiguous ``key: value`` lines at the top, then the prose."""
+    knobs: dict = {}
+    lines = body.splitlines()
+    index = 0
+    while index < len(lines):
+        line = lines[index].strip()
+        if not line:
+            index += 1
+            continue
+        match = KNOB_RE.match(line)
+        if not match:
+            break
+        value = match.group(2)
+        knobs[match.group(1)] = int(value) if value.isdigit() else value
+        index += 1
+    return knobs, "\n".join(lines[index:]).strip()
+
+
+def parse_format_md(text: str) -> tuple[str | None, dict]:
+    """Read a format.md into its default choice and its format objects."""
+    default = None
+    front = FRONT_MATTER_RE.match(text)
+    if front:
+        for line in front.group(1).splitlines():
+            match = KNOB_RE.match(line.strip())
+            if match and match.group(1) == "format":
+                default = match.group(2)
+        text = text[front.end():]
+
+    built: dict = {}
+    matches = list(SECTION_RE.finditer(text))
+    for position, match in enumerate(matches):
+        name = match.group(1)
+        stop = (matches[position + 1].start() if position + 1 < len(matches)
+                else len(text))
+        body = text[match.end():stop]
+        seed_match = SEED_RE.search(body)
+        seed = seed_match.group(1) if seed_match else None
+        if seed_match:
+            body = body[:seed_match.start()] + body[seed_match.end():]
+        knobs, spec = _parse_knobs(body)
+        mechanism = knobs.pop("mechanism", None)
+        if mechanism is None:
+            continue
+        if mechanism not in MECHANISMS:
+            raise SetupNeeded(
+                f"format {name!r} in format.md asks for unknown mechanism "
+                f"{mechanism!r}; choose one of "
+                f"{', '.join(sorted(MECHANISMS))}")
+        built[name] = MECHANISMS[mechanism](name, spec, knobs, seed)
+    return default, built
+
+
+def load_formats(path=None) -> tuple[str, dict, str]:
+    """The default format name, every defined format, and the file's hash."""
+    file = format_file(path)
+    text = file.read_text() if file.is_file() else DEFAULT_FORMAT_MD
+    default, built = parse_format_md(text)
+    if not built:
+        raise SetupNeeded(
+            f"{file} defines no formats. Every section needs a 'mechanism:' "
+            "line; see the shipped format.md.")
+    if default is None or default not in built:
+        default = next(iter(built))
+    return default, built, hashlib.sha256(text.encode()).hexdigest()[:16]
+
+
+def formats(path=None) -> dict:
+    """Every skill format defined in ``format.md``, by name."""
+    return load_formats(path)[1]
+
+
+def get_format(name=None, path=None) -> SkillFormat:
+    """One skill format by name, or the default ``format.md`` selects."""
+    default, built, digest = load_formats(path)
+    chosen = name or default
+    if chosen not in built:
+        raise ValueError(
+            f"unknown skill format {chosen!r}; format.md defines "
+            f"{', '.join(sorted(built))}")
+    picked = built[chosen]
+    picked.digest = digest
+    return picked
+
+
+def format_of(state: dict) -> SkillFormat:
+    """The format a saved state was produced with."""
+    name = state.get("config", {}).get("format", "markdown")
+    if name is None:
+        return NO_FORMAT
+    return get_format(name)
+
+
+def skill_filename(state: dict) -> str:
+    return state.get("config", {}).get("skill_file", "skill.md")
+
+
+# --------------------------------------------------------------------------