scrip-harness 0.3.0__tar.gz

scrip_harness-0.3.0/.gitignore

@@ -0,0 +1,31 @@
+# Python / uv
+.venv/
+**/.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+# DuckDB scratch / temp writes
+*.duckdb
+*.duckdb.wal
+*.tmp
+
+# OS
+.DS_Store
+
+# Embeddings index: a large, regenerable binary cache (rebuild with `scrip index`)
+/.kb/embeddings/
+
+# Advisory write lock: ephemeral runtime state, never committed (see SPEC §11)
+/.kb/lock
+
+# Manifest: a regenerable speed cache. SPEC §8 says it *may* be committed; we
+# choose not to — it stores (mtime, size) that are wrong on every fresh clone
+# anyway, and its hashes/timestamps churn diffs. Rebuild any time with
+# `scrip status --rebuild-manifest`.
+/.kb/manifest.json
+
+# roborev snapshots
+/.roborev/

scrip_harness-0.3.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: scrip-harness
+Version: 0.3.0
+Summary: Runnable AGENT.md compile loop for scriptorium: drives `scrip` via subprocess + Claude. Not part of the deterministic scrip core.
+Project-URL: Homepage, https://github.com/coredipper/scriptorium/tree/main/harness
+Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/coredipper/scriptorium/issues
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: pydantic>=2
+Requires-Dist: scriptoria>=0.3
+Description-Content-Type: text/markdown
+
+# scrip-harness — the runnable compile loop
+
+The deterministic `scrip` keeper does staleness, provenance, and queries. It never
+calls a model. **scrip-harness** is the optional *judgment* layer that makes the
+[AGENT.md](../AGENT.md) COMPILE step runnable: it asks Claude to synthesize a wiki
+page from a source, then hands every verifiable step back to `scrip`.
+
+The dependency points one way only: the harness depends on `scrip` (and the
+Anthropic SDK); `scrip` depends on neither. Removing this directory leaves a fully
+valid, fully deterministic vault and CLI behind.
+
+## How a compile runs
+
+`scrip-harness compile <slug>` (for `vault/raw/<slug>.md`):
+
+1. **Draft** — Claude (`claude-opus-4-8`, adaptive thinking, structured output)
+   returns a `DraftPage`: a title, markdown prose with footnote markers
+   `[^a1], [^a2], …`, and one *verbatim quote* per marker.
+2. **Mint** — each quote goes through `scrip anchor`, which **fails the compile**
+   if the quote isn't present in the source or isn't unique. A hallucinated or
+   paraphrased quote cannot get past this step.
+3. **Scaffold + fill** — `scrip new` writes the frontmatter; the harness fills the
+   body with the prose + the minted footnote definitions.
+4. **Stamp + verify** — `scrip stamp` records provenance hashes; `scrip verify`
+   proves every citation resolves. If verify fails, the compile errors out rather
+   than leaving a stamped-but-broken page.
+
+So the model owns *what to say*; `scrip` owns *what is true on disk*.
+
+## How an extract runs
+
+`scrip-harness extract <slug>` (for `vault/raw/<slug>.md`):
+
+1. **Draft** — Claude returns a `DraftExtraction`: structured claims, each with a
+   *verbatim quote*, a subject/predicate/object triple, and a polarity.
+2. **Mint + append** — the claims go to `scrip fact add --stdin`, which verifies
+   every quote (minting anchors), assigns ids and timestamps, skips exact
+   duplicates, and appends **all-or-nothing** under the write lock.
+3. **Retry** — if quotes come back BROKEN/AMBIGUOUS, the failures go back to
+   Claude for one replacement per failure (lengthened until unique, or an empty
+   quote to drop the claim); bounded retries, then the extract fails cleanly.
+4. **Stamp + verify** — `scrip stamp vault/facts/_meta.yaml`, then `scrip verify`;
+   contradiction candidates from `scrip query contradictions` are surfaced for
+   the operator to RECONCILE per [AGENT.md](../AGENT.md).
+
+## Install & run
+
+Both packages are on PyPI. `scrip-harness` bundles `scriptoria` as a dependency
+and drives it through its own interpreter, so it is self-sufficient — install
+`scriptoria` as a tool too only if you want the `scrip` command on PATH for
+direct use:
+
+```sh
+uv tool install scrip-harness            # this package → `scrip-harness` (pulls scriptoria)
+uv tool install 'scriptoria[ingest]'     # optional: `scrip` on PATH + HTML/PDF ingest
+export ANTHROPIC_API_KEY=...              # the harness calls Claude; scrip never does
+
+scrip-harness compile article            # synthesize + verify a page from raw/article
+scrip-harness extract article            # pull claims into facts/
+scrip ingest <url> --slug article        # bring a source in (needs the install above)
+```
+
+(From a checkout, `uv tool install ./scrip` and `uv tool install ./harness`
+install the local versions instead.)
+
+## Develop / test
+
+```sh
+cd harness && uv run pytest        # hermetic: the model is stubbed; scrip runs for real
+```
+
+The tests inject a stub draft function (no network, no API key) and drive the real
+`scrip` subcommands over a temp vault, asserting the result is stamped and verified.
+
+## Scope & limits (v1)
+
+- Covers **COMPILE** (one source → one wiki page) and **EXTRACT** (one source →
+  claims in `facts/`, with the bounded quote-retry loop). Entities/edges go
+  through `scrip fact add --table entities|edges` by hand; PROMOTE (merge/dedup)
+  and RECONCILE (contradictions) are not yet automated here — drive them with
+  `scrip` directly per [AGENT.md](../AGENT.md).
+- Single source per page/extract. Multi-source synthesis, and adopting the
+  quote-retry loop in COMPILE too, are future work.

scrip_harness-0.3.0/README.md

@@ -0,0 +1,83 @@
+# scrip-harness — the runnable compile loop
+
+The deterministic `scrip` keeper does staleness, provenance, and queries. It never
+calls a model. **scrip-harness** is the optional *judgment* layer that makes the
+[AGENT.md](../AGENT.md) COMPILE step runnable: it asks Claude to synthesize a wiki
+page from a source, then hands every verifiable step back to `scrip`.
+
+The dependency points one way only: the harness depends on `scrip` (and the
+Anthropic SDK); `scrip` depends on neither. Removing this directory leaves a fully
+valid, fully deterministic vault and CLI behind.
+
+## How a compile runs
+
+`scrip-harness compile <slug>` (for `vault/raw/<slug>.md`):
+
+1. **Draft** — Claude (`claude-opus-4-8`, adaptive thinking, structured output)
+   returns a `DraftPage`: a title, markdown prose with footnote markers
+   `[^a1], [^a2], …`, and one *verbatim quote* per marker.
+2. **Mint** — each quote goes through `scrip anchor`, which **fails the compile**
+   if the quote isn't present in the source or isn't unique. A hallucinated or
+   paraphrased quote cannot get past this step.
+3. **Scaffold + fill** — `scrip new` writes the frontmatter; the harness fills the
+   body with the prose + the minted footnote definitions.
+4. **Stamp + verify** — `scrip stamp` records provenance hashes; `scrip verify`
+   proves every citation resolves. If verify fails, the compile errors out rather
+   than leaving a stamped-but-broken page.
+
+So the model owns *what to say*; `scrip` owns *what is true on disk*.
+
+## How an extract runs
+
+`scrip-harness extract <slug>` (for `vault/raw/<slug>.md`):
+
+1. **Draft** — Claude returns a `DraftExtraction`: structured claims, each with a
+   *verbatim quote*, a subject/predicate/object triple, and a polarity.
+2. **Mint + append** — the claims go to `scrip fact add --stdin`, which verifies
+   every quote (minting anchors), assigns ids and timestamps, skips exact
+   duplicates, and appends **all-or-nothing** under the write lock.
+3. **Retry** — if quotes come back BROKEN/AMBIGUOUS, the failures go back to
+   Claude for one replacement per failure (lengthened until unique, or an empty
+   quote to drop the claim); bounded retries, then the extract fails cleanly.
+4. **Stamp + verify** — `scrip stamp vault/facts/_meta.yaml`, then `scrip verify`;
+   contradiction candidates from `scrip query contradictions` are surfaced for
+   the operator to RECONCILE per [AGENT.md](../AGENT.md).
+
+## Install & run
+
+Both packages are on PyPI. `scrip-harness` bundles `scriptoria` as a dependency
+and drives it through its own interpreter, so it is self-sufficient — install
+`scriptoria` as a tool too only if you want the `scrip` command on PATH for
+direct use:
+
+```sh
+uv tool install scrip-harness            # this package → `scrip-harness` (pulls scriptoria)
+uv tool install 'scriptoria[ingest]'     # optional: `scrip` on PATH + HTML/PDF ingest
+export ANTHROPIC_API_KEY=...              # the harness calls Claude; scrip never does
+
+scrip-harness compile article            # synthesize + verify a page from raw/article
+scrip-harness extract article            # pull claims into facts/
+scrip ingest <url> --slug article        # bring a source in (needs the install above)
+```
+
+(From a checkout, `uv tool install ./scrip` and `uv tool install ./harness`
+install the local versions instead.)
+
+## Develop / test
+
+```sh
+cd harness && uv run pytest        # hermetic: the model is stubbed; scrip runs for real
+```
+
+The tests inject a stub draft function (no network, no API key) and drive the real
+`scrip` subcommands over a temp vault, asserting the result is stamped and verified.
+
+## Scope & limits (v1)
+
+- Covers **COMPILE** (one source → one wiki page) and **EXTRACT** (one source →
+  claims in `facts/`, with the bounded quote-retry loop). Entities/edges go
+  through `scrip fact add --table entities|edges` by hand; PROMOTE (merge/dedup)
+  and RECONCILE (contradictions) are not yet automated here — drive them with
+  `scrip` directly per [AGENT.md](../AGENT.md).
+- Single source per page/extract. Multi-source synthesis, and adopting the
+  quote-retry loop in COMPILE too, are future work.

scrip_harness-0.3.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "scrip-harness"
+version = "0.3.0"
+description = "Runnable AGENT.md compile loop for scriptorium: drives `scrip` via subprocess + Claude. Not part of the deterministic scrip core."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "anthropic>=0.40",
+    # Imported directly for the structured-output schemas (compile/extract) — don't
+    # rely on anthropic to pull it in transitively; declare what we import.
+    "pydantic>=2",
+    # Version floor (not the dev path source below) is what ships in the wheel's
+    # Requires-Dist, so an installed scrip-harness pulls scriptoria from PyPI.
+    "scriptoria>=0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/coredipper/scriptorium/tree/main/harness"
+Changelog = "https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md"
+Issues = "https://github.com/coredipper/scriptorium/issues"
+
+[project.scripts]
+scrip-harness = "scrip_harness.cli:main"
+
+[tool.uv.sources]
+scriptoria = { path = "../scrip" }
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scrip_harness"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

scrip_harness-0.3.0/pyrightconfig.json

@@ -0,0 +1,7 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "extraPaths": ["src"],
+  "include": ["src", "tests"],
+  "reportMissingModuleSource": "none"
+}

scrip_harness-0.3.0/src/scrip_harness/__init__.py

@@ -0,0 +1,13 @@
+"""scrip-harness — the runnable AGENT.md compile loop for scriptorium.
+
+This is the **judgment** layer: it calls a model (Claude) to synthesize a wiki
+page from a source, then delegates every *verifiable* step to the deterministic
+``scrip`` CLI via subprocess — minting each citation with ``scrip anchor`` (which
+rejects a quote that is not verbatim and unique) and recording provenance with
+``scrip stamp``. So a hallucinated quote cannot survive into a stamped page.
+
+``scrip`` never imports this package or any SDK; the dependency points the other
+way. The harness is optional and lives outside the deterministic core.
+"""
+
+__version__ = "0.2.0"

scrip_harness-0.3.0/src/scrip_harness/cli.py

@@ -0,0 +1,92 @@
+"""``scrip-harness compile|extract <slug>`` — run the AGENT.md COMPILE or
+EXTRACT step for one source.
+
+This is the model-driven entry point. It resolves the scriptorium root, calls
+Claude to draft the page or the claims, and hands every verifiable step to
+``scrip``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _resolve_root(root_arg: str | None) -> Path:
+    if root_arg:
+        return Path(root_arg).expanduser()
+    cur = Path.cwd().resolve()
+    for cand in (cur, *cur.parents):
+        if (cand / "vault").is_dir() and ((cand / "SPEC.md").exists() or (cand / ".kb").is_dir()):
+            return cand
+    raise SystemExit("scrip-harness: could not locate a scriptorium root; pass --root")
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="scrip-harness",
+        description="Runnable scriptorium compile loop (drives scrip + Claude).",
+    )
+    sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
+    pc = sub.add_parser(
+        "compile",
+        help="synthesize wiki/<kind>s/<slug> from raw/<slug> via Claude, then stamp + verify",
+    )
+    pc.add_argument("slug")
+    pc.add_argument("--kind", choices=["concept", "entity"], default="concept")
+    pc.add_argument("--root")
+    pc.add_argument("--model", help="Claude model id (default: claude-opus-4-8)")
+    pe = sub.add_parser(
+        "extract",
+        help="extract claims from raw/<slug> into facts/ via Claude (anchors minted "
+        "and verified by `scrip fact add`), then stamp + verify",
+    )
+    pe.add_argument("slug")
+    pe.add_argument("--root")
+    pe.add_argument("--model", help="Claude model id (default: claude-opus-4-8)")
+    args = p.parse_args(argv)
+
+    from . import model as model_mod
+    from .runner import CompileError, ExtractError, compile_page, extract_facts
+
+    root = _resolve_root(args.root)
+    chosen_model = args.model or model_mod.DEFAULT_MODEL
+
+    if args.command == "extract":
+        def extract_draft_fn(text: str, *, source_id: str, failures=None):
+            return model_mod.draft_extraction(
+                text, source_id=source_id, model=chosen_model, failures=failures
+            )
+
+        try:
+            result = extract_facts(root, args.slug, draft_fn=extract_draft_fn)
+        except ExtractError as e:
+            print(f"scrip-harness: {e}", file=sys.stderr)
+            return 1
+        appended, skipped = result["appended"], result["skipped"]
+        print(
+            f"extracted {len(appended)} claim(s) from raw/{args.slug}  (verified"
+            f"{f', {len(skipped)} duplicate(s) skipped' if skipped else ''})"
+        )
+        if result["contradictions"]:
+            print(
+                f"  {len(result['contradictions'])} contradiction candidate(s) — "
+                f"run `scrip query contradictions` and RECONCILE per AGENT.md"
+            )
+        return 0
+
+    def draft_fn(text: str, *, source_id: str):
+        return model_mod.draft_page(text, source_id=source_id, model=chosen_model)
+
+    try:
+        page = compile_page(root, args.slug, kind=args.kind, draft_fn=draft_fn)
+    except CompileError as e:
+        print(f"scrip-harness: {e}", file=sys.stderr)
+        return 1
+    print(f"compiled {page.relative_to(root)}  (verified)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scrip_harness-0.3.0/src/scrip_harness/compile.py

@@ -0,0 +1,69 @@
+"""Deterministic pieces of the compile loop: the structured draft schema, prompt
+construction, and page-body assembly. No network, no scrip — unit-testable."""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+# Match ANY footnote reference label, not just well-formed a-markers, so that a
+# foreign ([^b1]) or malformed ([^a01]) reference is surfaced and rejected rather
+# than silently ignored (which would leave an undefined footnote in the page).
+_MARKER = re.compile(r"\[\^([^\]]+)\]")
+
+
+def extract_markers(body: str) -> list[str]:
+    """Footnote reference *labels* in ``body``, distinct, in first-appearance order
+    (``[^a1]`` → ``"a1"``). Returned verbatim — the caller requires them to be
+    exactly ``a1..aN`` (no leading zeros, no foreign labels) before stamping."""
+    seen: list[str] = []
+    for m in _MARKER.finditer(body):
+        label = m.group(1)
+        if label not in seen:
+            seen.append(label)
+    return seen
+
+SYSTEM = (
+    "You are the scribe for a scriptorium knowledge base. From the single source "
+    "you are given, synthesize a concise, accurate concept page in markdown.\n"
+    "Rules:\n"
+    "- Write only what the source supports; do not add outside facts.\n"
+    "- Mark each claim-bearing sentence with a footnote marker ([^a1], [^a2], …) "
+    "in order of first appearance.\n"
+    "- For every marker, return one claim whose `quote` is copied VERBATIM from the "
+    "source (it is machine-verified against the source text; paraphrases are "
+    "rejected). Quote enough words to be unique.\n"
+    "- Keep the body free of the footnote *definitions* — only the markers. The "
+    "definitions are generated from your quotes."
+)
+
+
+class DraftClaim(BaseModel):
+    quote: str
+    """Verbatim text copied from the source, supporting the matching marker."""
+    note: str = ""
+    """Optional human-readable note on what the claim asserts."""
+
+
+class DraftPage(BaseModel):
+    title: str
+    body: str
+    """Markdown prose containing footnote markers [^a1], [^a2], … in order."""
+    claims: list[DraftClaim]
+    """One claim per marker, in the same order as the markers in `body`."""
+
+
+def build_user_prompt(source_text: str) -> str:
+    return (
+        "Synthesize a concept page from the source below. In the body, mark each "
+        "claim-bearing sentence with a footnote marker [^a1], [^a2], … in order. "
+        "Return one claim per marker (same order), each with a `quote` copied "
+        "verbatim from the source.\n\n----- SOURCE -----\n" + source_text
+    )
+
+
+def assemble_body(draft: DraftPage, footnotes: list[str]) -> str:
+    """Combine the model's prose (with markers) and the scrip-minted footnote
+    definition lines into the final page body."""
+    return draft.body.rstrip() + "\n\n" + "\n".join(footnotes) + "\n"

scrip_harness-0.3.0/src/scrip_harness/extract.py

@@ -0,0 +1,97 @@
+"""Deterministic pieces of the extract loop: the structured fact schema, prompt
+construction, and the NDJSON serialization `scrip fact add` consumes. No
+network, no scrip — unit-testable."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from pydantic import BaseModel
+
+EXTRACT_SYSTEM = (
+    "You are the scribe for a scriptorium knowledge base. From the single source "
+    "you are given, extract atomic factual claims as structured records.\n"
+    "Rules:\n"
+    "- Extract only what the source supports; do not add outside facts.\n"
+    "- Each claim's `quote` is copied VERBATIM from the source (it is "
+    "machine-verified against the source text; paraphrases are rejected). Quote "
+    "enough words to be unique within the source.\n"
+    "- `subject`/`predicate`/`object` form a coarse triple used for grouping and "
+    "contradiction detection: keep them short, lowercase noun/verb phrases, and "
+    "reuse the same wording for the same idea across claims.\n"
+    "- `polarity` is `asserts`, `denies`, or `qualifies` — what the source does "
+    "to the triple, not your judgment of it.\n"
+    "- `claim_text` is an optional one-sentence restatement; leave it empty to "
+    "reuse the quote.\n"
+    "- `confidence` in [0, 1] is your honest rating that the claim faithfully "
+    "represents the source."
+)
+
+
+class DraftFact(BaseModel):
+    quote: str
+    """Verbatim text copied from the source; anchors are minted from this."""
+    subject: str
+    predicate: str
+    object: str
+    polarity: Literal["asserts", "denies", "qualifies"] = "asserts"
+    confidence: float = 0.8
+    claim_text: str = ""
+    """Optional restatement; empty means the quote itself is the claim text."""
+    tags: list[str] = []
+
+
+class DraftExtraction(BaseModel):
+    claims: list[DraftFact]
+
+
+def build_extract_prompt(source_text: str) -> str:
+    return (
+        "Extract the atomic factual claims from the source below as structured "
+        "records. Each claim needs a verbatim `quote`, a subject/predicate/object "
+        "triple, and a polarity.\n\n----- SOURCE -----\n" + source_text
+    )
+
+
+def build_retry_prompt(source_text: str, failures: list[dict]) -> str:
+    """Ask for a replacement for each failed quote, in the reported order. An
+    empty replacement quote tells the runner to drop that claim."""
+    listing = "\n".join(
+        f"- status {f['status']}: {json.dumps(f.get('quote', ''), ensure_ascii=False)}"
+        f" ({f.get('detail', '')})"
+        for f in failures
+    )
+    return (
+        "Some quotes you proposed did not verify against the source: an AMBIGUOUS "
+        "quote appears more than once (lengthen it until unique); a BROKEN quote "
+        "is not present verbatim (re-copy it exactly).\n\n"
+        f"Failed quotes, in order:\n{listing}\n\n"
+        "Return exactly one replacement claim per failed quote, in the same "
+        "order, with the corrected verbatim `quote` and the claim's triple/"
+        "polarity. If a claim cannot be supported by a verbatim quote, return it "
+        "with an empty `quote` to drop it.\n\n----- SOURCE -----\n" + source_text
+    )
+
+
+def to_ndjson(facts: list[DraftFact], source_id: str) -> str:
+    """Serialize proposed facts as the NDJSON `scrip fact add --stdin` expects.
+    scrip owns `anchor`/`claim_id`/`extracted_at`, so they never appear here;
+    empty `claim_text`/`tags` are omitted so scrip applies its defaults."""
+    lines = []
+    for f in facts:
+        rec: dict = {
+            "quote": f.quote,
+            "subject": f.subject,
+            "predicate": f.predicate,
+            "object": f.object,
+            "polarity": f.polarity,
+            "confidence": f.confidence,
+            "source_id": source_id,
+        }
+        if f.claim_text:
+            rec["claim_text"] = f.claim_text
+        if f.tags:
+            rec["tags"] = f.tags
+        lines.append(json.dumps(rec, ensure_ascii=False))
+    return "".join(line + "\n" for line in lines)

scrip_harness-0.3.0/src/scrip_harness/model.py

@@ -0,0 +1,78 @@
+"""The only LLM-touching module. ``scrip`` never imports this; the harness does.
+
+Uses the Anthropic SDK's structured-output parse helper so the draft comes back
+as a validated ``DraftPage`` rather than free text to scrape.
+"""
+
+from __future__ import annotations
+
+from .compile import SYSTEM, DraftPage, build_user_prompt
+from .extract import (
+    EXTRACT_SYSTEM,
+    DraftExtraction,
+    build_extract_prompt,
+    build_retry_prompt,
+)
+
+DEFAULT_MODEL = "claude-opus-4-8"
+
+
+def draft_page(
+    source_text: str,
+    *,
+    source_id: str,
+    model: str = DEFAULT_MODEL,
+    client=None,
+) -> DraftPage:
+    """Ask Claude to synthesize a concept page from ``source_text``. Returns a
+    validated :class:`DraftPage`. Lazily imports the SDK so the rest of the
+    harness (and its tests) need no network or API key."""
+    import anthropic
+
+    client = client or anthropic.Anthropic()
+    resp = client.messages.parse(
+        model=model,
+        max_tokens=16000,
+        thinking={"type": "adaptive"},
+        system=SYSTEM,
+        messages=[{"role": "user", "content": build_user_prompt(source_text)}],
+        output_format=DraftPage,
+    )
+    out = resp.parsed_output
+    if out is None:
+        raise RuntimeError(f"model returned no parseable draft for {source_id}")
+    return out
+
+
+def draft_extraction(
+    source_text: str,
+    *,
+    source_id: str,
+    model: str = DEFAULT_MODEL,
+    client=None,
+    failures: list[dict] | None = None,
+) -> DraftExtraction:
+    """Ask Claude to extract structured claims from ``source_text``. With
+    ``failures`` (the per-record findings from ``scrip fact add``), asks instead
+    for one replacement claim per failure, in order — the retry half of the
+    extract loop. Lazily imports the SDK so tests need no network or API key."""
+    import anthropic
+
+    client = client or anthropic.Anthropic()
+    prompt = (
+        build_extract_prompt(source_text)
+        if failures is None
+        else build_retry_prompt(source_text, failures)
+    )
+    resp = client.messages.parse(
+        model=model,
+        max_tokens=16000,
+        thinking={"type": "adaptive"},
+        system=EXTRACT_SYSTEM,
+        messages=[{"role": "user", "content": prompt}],
+        output_format=DraftExtraction,
+    )
+    out = resp.parsed_output
+    if out is None:
+        raise RuntimeError(f"model returned no parseable extraction for {source_id}")
+    return out