seqforge 2026.7.1__py3-none-any.whl

seqforge/harvest/providers.py

@@ -0,0 +1,321 @@
+"""Provider layer — the LLM is a swappable component, not a foundation.
+
+seqforge is a compiler whose only LLM touchpoint proposes claims that code then re-verifies from
+first principles. That makes the provider genuinely pluggable: nothing downstream trusts the model,
+so the choice is about cost and extraction quality, never about correctness guarantees.
+
+Two providers ship:
+
+- ``anthropic``          — strict ``json_schema`` structured output; the returned shape is guaranteed.
+- ``openai-compatible``  — any OpenAI-shaped endpoint via ``base_url``. **DeepSeek** is a preset; so
+  are vLLM, Ollama, Together, and friends. These offer ``response_format={"type": "json_object"}``
+  only: valid JSON is guaranteed, the *shape* is not.
+
+**That capability gap is contained, not papered over.** For json-object providers we put the schema
+and a worked example in the prompt, and then — as always — ``ExtractionResult.model_validate_json``
+is the gate. A provider that returns the wrong shape fails validation and the batch is refused; it
+cannot produce a half-parsed assertion. This is exactly the division of labor working: agents propose, code decides.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+#: Anthropic. Adaptive thinking + strict schema.
+ANTHROPIC_DEFAULT_MODEL = "claude-opus-4-8"
+
+#: DeepSeek V4. `-pro` is the default for the accuracy-critical extraction stage; `-flash` is ~3x
+#: cheaper and also V4 (1M ctx) if throughput matters more than recall — pass --model to switch.
+#: NB `deepseek-chat` / `deepseek-reasoner` are deprecated (2026-07-24) aliases onto V4-Flash; we
+#: name a V4 model explicitly so nothing breaks when they are withdrawn.
+DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-pro"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+
+#: How many extra times to re-issue a json_object request that came back with EMPTY content. DeepSeek
+#: documents that json_object mode intermittently returns an empty body, and v4-pro does it often
+#: enough to abort a whole harvest (#4). An empty body is a provider hiccup, not "the document says
+#: nothing" (that is a well-formed `{"drafts": []}`), so a bounded retry recovers it instead of failing
+#: the dataset. A real API error is not retried here — it raises on the first attempt.
+_EMPTY_CONTENT_RETRIES = 3
+
+
+class ProviderUnavailable(RuntimeError):
+    """No usable provider: SDK missing, credential absent, or the endpoint failed."""
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    """Raw model output plus normalized usage. The text is UNVALIDATED — the caller decides."""
+
+    text: str
+    usage: dict[str, int]
+    #: How the call was made, recorded for the cost/provenance ledger: reasoning ``thinking`` mode,
+    #: the ``max_tokens`` ceiling, and which structured-output ``response_format`` was in force. The
+    #: same prompt at a different effort is a different run, and this is what lets a reader see it.
+    mode: dict[str, Any] = field(default_factory=dict)
+
+
+class LLMProvider(Protocol):
+    """What extraction needs from a model: JSON text back, and a name to record in provenance."""
+
+    name: str
+
+    def default_model(self) -> str: ...
+
+    def complete_json(
+        self, *, system: str, user: str, schema: dict[str, Any], model: str, max_tokens: int
+    ) -> LLMResponse: ...
+
+
+class AnthropicProvider:
+    """Claude via the official SDK: strict schema, explicit prefix caching, adaptive thinking."""
+
+    name = "anthropic"
+
+    def __init__(self, *, client: Any | None = None, api_key: str | None = None) -> None:
+        self._client = client
+        self._api_key = api_key
+
+    def default_model(self) -> str:
+        return ANTHROPIC_DEFAULT_MODEL
+
+    def _resolve(self) -> Any:
+        if self._client is not None:
+            return self._client
+        try:
+            import anthropic
+        except ImportError as exc:  # pragma: no cover - host dependent
+            raise ProviderUnavailable("the `anthropic` SDK is not installed") from exc
+        return (
+            anthropic.Anthropic(api_key=self._api_key) if self._api_key else anthropic.Anthropic()
+        )
+
+    def complete_json(
+        self, *, system: str, user: str, schema: dict[str, Any], model: str, max_tokens: int
+    ) -> LLMResponse:
+        client = self._resolve()
+        try:
+            response = client.messages.create(
+                model=model,
+                max_tokens=max_tokens,
+                # cache breakpoint on the last system block: render order is tools -> system ->
+                # messages, so the stable prefix caches and the volatile document does not.
+                system=[{"type": "text", "text": system, "cache_control": {"type": "ephemeral"}}],
+                messages=[{"role": "user", "content": user}],
+                output_config={"format": {"type": "json_schema", "schema": schema}},
+                thinking={"type": "adaptive"},
+            )
+        except Exception as exc:
+            raise ProviderUnavailable(f"anthropic call failed: {exc}") from exc
+        text = next((b.text for b in response.content if getattr(b, "type", None) == "text"), "")
+        return LLMResponse(
+            text=text,
+            usage=_anthropic_usage(response),
+            mode={
+                "thinking": "adaptive",
+                "max_tokens": max_tokens,
+                "response_format": "json_schema",
+            },
+        )
+
+
+class OpenAICompatibleProvider:
+    """Any OpenAI-shaped endpoint (DeepSeek, vLLM, Ollama, Together, ...) selected by ``base_url``.
+
+    These expose ``json_object`` mode only, so the schema travels in the prompt and Pydantic — not
+    the provider — enforces the shape. Prefix caching is automatic server-side (DeepSeek reports it
+    as cache hit/miss tokens), so there is no ``cache_control`` to place; keeping the prefix stable
+    is the whole job.
+    """
+
+    name = "openai-compatible"
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        default_model: str = DEEPSEEK_DEFAULT_MODEL,
+        name: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self._api_key = api_key
+        self._default_model = default_model
+        self._client = client
+        if name:
+            self.name = name
+
+    def default_model(self) -> str:
+        return self._default_model
+
+    def _resolve(self) -> Any:
+        if self._client is not None:
+            return self._client
+        try:
+            from openai import OpenAI
+        except ImportError as exc:  # pragma: no cover - host dependent
+            raise ProviderUnavailable(
+                "the `openai` SDK is not installed (it is the client for OpenAI-compatible "
+                "endpoints such as DeepSeek)"
+            ) from exc
+        if not self._api_key:
+            raise ProviderUnavailable(f"no API key for {self.name} ({self.base_url})")
+        return OpenAI(api_key=self._api_key, base_url=self.base_url)
+
+    def complete_json(
+        self, *, system: str, user: str, schema: dict[str, Any], model: str, max_tokens: int
+    ) -> LLMResponse:
+        client = self._resolve()
+        # Re-issue on EMPTY content, bounded (#4). DeepSeek's json_object mode intermittently returns
+        # an empty body; that is a provider hiccup, not the document saying nothing (which is a
+        # well-formed `{"drafts": []}`), so a few retries recover it instead of aborting the harvest.
+        # Usage is ACCUMULATED across attempts: an empty response still cost tokens, and the harvest
+        # ledger is meant to reflect what the calls actually cost, not just the final one.
+        usage_total: dict[str, int] = {}
+        for _ in range(_EMPTY_CONTENT_RETRIES + 1):
+            try:
+                response = client.chat.completions.create(
+                    model=model,
+                    max_tokens=max_tokens,
+                    messages=[
+                        {"role": "system", "content": system},
+                        {"role": "user", "content": user},
+                    ],
+                    # json_object guarantees valid JSON, NOT the right shape — Pydantic checks shape.
+                    response_format={"type": "json_object"},
+                )
+            except Exception as exc:
+                # A real API error is not a content hiccup — fail on the first attempt, do not retry.
+                raise ProviderUnavailable(f"{self.name} call failed: {exc}") from exc
+            for key, val in _openai_usage(response).items():
+                usage_total[key] = usage_total.get(key, 0) + val
+            choice = response.choices[0] if response.choices else None
+            text = (getattr(choice.message, "content", None) or "") if choice else ""
+            if text.strip():
+                # `thinking` is the MODEL's own (v4-pro/-reasoner reason inherently); the API takes no
+                # toggle, so it is reported as the model name's business, not a flag we set.
+                # `response_format` is the weaker json_object contract, which is why Pydantic — not the
+                # provider — enforces the shape.
+                return LLMResponse(
+                    text=text,
+                    usage=usage_total,  # summed over every attempt, including the empty ones
+                    mode={
+                        "thinking": "model-default",
+                        "max_tokens": max_tokens,
+                        "response_format": "json_object",
+                    },
+                )
+        # Every attempt came back empty: refuse loudly rather than let it read as "says nothing". The
+        # hint is provider-agnostic (this class also serves vLLM/Ollama/Together) and names no
+        # soon-deprecated model.
+        raise ProviderUnavailable(
+            f"{self.name} returned empty content in JSON mode on {_EMPTY_CONTENT_RETRIES + 1} "
+            f"attempts (a known json_object-mode failure; try a different model or provider)"
+        )
+
+
+def deepseek_provider(api_key: str | None = None, **kwargs: Any) -> OpenAICompatibleProvider:
+    """DeepSeek preset of the OpenAI-compatible provider."""
+    return OpenAICompatibleProvider(
+        base_url=DEEPSEEK_BASE_URL,
+        api_key=api_key or os.environ.get("DEEPSEEK_API_KEY"),
+        default_model=DEEPSEEK_DEFAULT_MODEL,
+        name="deepseek",
+        **kwargs,
+    )
+
+
+def resolve_provider(name: str | None = None) -> LLMProvider:
+    """Pick a provider explicitly, or auto-detect from the environment.
+
+    Explicit beats implicit: ``--provider`` / ``SEQFORGE_LLM_PROVIDER`` wins. Otherwise we take
+    whichever credential is present, and refuse (listing the options) rather than guess when neither
+    is — an extraction that silently picks a different model than you expected is a provenance bug.
+    """
+    choice = (name or os.environ.get("SEQFORGE_LLM_PROVIDER") or "").strip().lower()
+    if choice in ("deepseek", "deepseek-v4"):
+        return deepseek_provider()
+    if choice == "anthropic":
+        return AnthropicProvider()
+    if choice in ("openai-compatible", "custom"):
+        base = os.environ.get("SEQFORGE_LLM_BASE_URL")
+        if not base:
+            raise ProviderUnavailable("provider 'openai-compatible' needs SEQFORGE_LLM_BASE_URL")
+        return OpenAICompatibleProvider(
+            base_url=base,
+            api_key=os.environ.get("SEQFORGE_LLM_API_KEY"),
+            default_model=os.environ.get("SEQFORGE_LLM_MODEL", DEEPSEEK_DEFAULT_MODEL),
+            name="openai-compatible",
+        )
+    if choice:
+        raise ProviderUnavailable(
+            f"unknown provider {choice!r}; known: anthropic, deepseek, openai-compatible"
+        )
+
+    if os.environ.get("DEEPSEEK_API_KEY"):
+        return deepseek_provider()
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return AnthropicProvider()
+    raise ProviderUnavailable(
+        "no LLM credential found. Set DEEPSEEK_API_KEY or ANTHROPIC_API_KEY, or pass "
+        "--provider with SEQFORGE_LLM_BASE_URL/-API_KEY for any OpenAI-compatible endpoint."
+    )
+
+
+def _anthropic_usage(response: Any) -> dict[str, int]:
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return {}
+    return {
+        "input_tokens": int(getattr(usage, "input_tokens", 0) or 0),
+        "output_tokens": int(getattr(usage, "output_tokens", 0) or 0),
+        "cache_read_tokens": int(getattr(usage, "cache_read_input_tokens", 0) or 0),
+        "cache_write_tokens": int(getattr(usage, "cache_creation_input_tokens", 0) or 0),
+    }
+
+
+def _openai_usage(response: Any) -> dict[str, int]:
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return {}
+    out = {
+        "input_tokens": int(getattr(usage, "prompt_tokens", 0) or 0),
+        "output_tokens": int(getattr(usage, "completion_tokens", 0) or 0),
+    }
+    # DeepSeek reports automatic prefix caching this way; normalize onto the common key.
+    hit = getattr(usage, "prompt_cache_hit_tokens", None)
+    if hit is not None:
+        out["cache_read_tokens"] = int(hit or 0)
+    return out
+
+
+def schema_prompt(schema: dict[str, Any]) -> str:
+    """The json-mode contract: say 'json', show the schema, show an example (DeepSeek requires both).
+
+    Harmless on providers that enforce a strict schema, so extraction keeps ONE prompt across
+    providers — one ``prompt_version``, one thing for evals to compare.
+    """
+    example = {
+        "drafts": [
+            {
+                "field": "library.chemistry",
+                "value": "10x-3p-gex-v3",
+                "span": {
+                    "doc_sha256": "<echo the sha given below>",
+                    "quote": "Chromium Single Cell 3' v3",
+                    "context": None,
+                },
+                "llm_confidence": 0.95,
+            }
+        ]
+    }
+    return (
+        "Return a single json object matching this JSON Schema exactly:\n"
+        f"{json.dumps(schema, separators=(',', ':'))}\n\n"
+        "Example of a well-formed json response (an empty `drafts` list is valid and common):\n"
+        f"{json.dumps(example, indent=2)}\n"
+    )

seqforge/harvest/verify.py

@@ -0,0 +1,251 @@
+"""``harvest verify`` — the hallucination tripwire, owned by code and failing closed.
+
+The LLM emits only ``{field, value, quote}``; it never emits offsets, because models cannot count
+characters and a wrong offset would reject a truthful claim. Code searches the normalized text,
+computes the offsets, and sets **both** verification flags. An Assertion only reaches ``manifest fill``
+if all three hold:
+
+- ``field`` is in the allowlist — the claim names a manifest path the model may set at all. This is
+  the *only* check that is not about the document, and it is the one the other two cannot stand in
+  for: see :mod:`seqforge.harvest.fields` for the real quote that entails a real value on a field
+  nobody ever authorized.
+- ``span_verified``  — the quote really occurs in the cited document. Catches **fabricated provenance**.
+- ``entailment_ok``  — the quote actually *supports the value*. Catches the more common and more
+  dangerous failure: a **real quote mis-attached to a wrong value** (a verbatim "single-cell RNA-seq"
+  span pinned to "10x 3' v3.1"). Without this, span-verification alone is theatre — a model can quote
+  the paper faithfully and still invent the conclusion.
+
+All three are deterministic. Anything unverifiable is rejected, never waved through.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ..kb import load_all_specs
+from ..models.assertion import Assertion, AssertionDraft, ExtractorProvenance, SourceSpan
+from .fields import PERMITTED_FIELDS, permitted_for
+from .normalize import NormalizedDoc, page_for_offset
+from .prep import normalize_prep_type
+
+_WS = re.compile(r"\s+")
+_TOKEN = re.compile(r"[a-z0-9']+")
+#: tokens too generic to carry entailment weight on their own
+_STOPWORDS = frozenset(
+    {"the", "a", "an", "of", "for", "with", "and", "or", "was", "were", "used", "using", "kit"}
+)
+
+
+@dataclass(frozen=True)
+class VerifyReport:
+    """Outcome of verifying a batch of drafts: what survived, and precisely why the rest did not."""
+
+    assertions: list[Assertion]
+    rejected: list[dict[str, object]]
+
+    @property
+    def n_accepted(self) -> int:
+        return len(self.assertions)
+
+
+def _squash(text: str) -> str:
+    return _WS.sub(" ", text).strip()
+
+
+def _tokens(text: str) -> list[str]:
+    return _TOKEN.findall(text.lower().replace("-", " "))
+
+
+def find_span(text: str, quote: str) -> tuple[int, int] | None:
+    """Locate ``quote`` in ``text``, tolerating whitespace differences. Returns ``(start, end)``.
+
+    Exact first; then a whitespace-flexible regex, because a quote copied across a line wrap differs
+    from the canonical text only in runs of space — rejecting that would punish an honest quote.
+    """
+    if not quote.strip():
+        return None
+    idx = text.find(quote)
+    if idx >= 0:
+        return idx, idx + len(quote)
+    squashed = _squash(quote)
+    idx = text.find(squashed)
+    if idx >= 0:
+        return idx, idx + len(squashed)
+    pattern = r"\s+".join(re.escape(part) for part in squashed.split(" ") if part)
+    if not pattern:
+        return None
+    match = re.search(pattern, text)
+    return (match.start(), match.end()) if match else None
+
+
+def _kb_chemistry_aliases(value: str) -> list[str]:
+    """A paper says "Chromium Single Cell 3' v3", not "10x-3p-gex-v3". The KB curates those aliases."""
+    forms: list[str] = []
+    for tech_id, spec in load_all_specs().items():
+        candidates = {tech_id, spec.identity.id, spec.identity.name, *spec.identity.aliases}
+        if any(_squash(c).lower() == _squash(value).lower() for c in candidates):
+            forms.extend(candidates)
+    return forms
+
+
+#: field -> extra acceptable surface forms. EXACT-match dispatch, replacing a substring test
+#: (`if "chemistry" in field or "assay" in field`) that would have misfired the moment a field was
+#: named e.g. `processing.assay_override`.
+#:
+#: **`processing.quantification` is deliberately absent, and that absence is the design.** Its values
+#: are STARsolo's own spellings, so a quote naming the feature already matches the bare value —
+#: `entails` lowercases and substring-matches, so "pass --soloFeatures GeneFull" needs no alias. An
+#: alias table here could therefore only ever LOOSEN the check, and loosening is exactly the hazard:
+#: teach it `"nuclei" -> GeneFull` and the sentence "we prepared single nuclei" entails a processing
+#: decision, at which point span verification is theatre — the model would be INFERRING the decision from a biological
+#: fact, and that inference is code's to own. The instruction document's documented contract is **name
+#: the STARsolo feature**; "count introns too" is correctly rejected as not-entailed.
+#:
+#: That rigor is affordable only because of the all-five default: the case that most tempts you to add the alias — a
+#: nuclear prep — is the case the all-five default already covers. If the default ever narrows,
+#: revisit this comment at the same time.
+_ALIAS_SOURCES: dict[str, Callable[[str], list[str]]] = {
+    "library.chemistry": _kb_chemistry_aliases,
+    "library.assay": _kb_chemistry_aliases,
+}
+
+
+def surface_forms(field: str, value: str) -> list[str]:
+    """Acceptable surface forms for a value — the value itself plus any curated aliases for its field."""
+    extra = _ALIAS_SOURCES.get(field)
+    return list(dict.fromkeys([value, *(extra(value) if extra else [])]))
+
+
+def entails(quote: str, field: str, value: str) -> bool:
+    """Does ``quote`` support ``value``? True iff some surface form is carried by the quote.
+
+    A form matches when it is a substring, or when all of its significant tokens appear in the quote
+    (order-independent — "Chromium Single Cell 3' v3" carries the alias "Chromium 3' v3"). Purely
+    generic tokens cannot entail on their own, so a quote saying only "single-cell RNA-seq" can never
+    entail a specific chemistry version.
+
+    **Know what this check cannot do.** Its power comes entirely from ``value`` being drawn from a
+    controlled vocabulary: for ``library.chemistry`` the value is a KB id, so the quote must contain a
+    real alias, and a quote about "droplet-based single-cell" cannot smuggle in a v3 chemistry. For a
+    free-text field the model supplies a value copied *out of* the quote, so ``form in quote`` is
+    trivially true and this returns True for anything. **Entailment is vacuous when value ⊆ quote.**
+
+    So span verification is a tripwire for fabricated and mis-attributed claims, NOT for field-assignment errors. A
+    real quote filed under the wrong field passes here by construction — `eval run --llm` caught
+    exactly that (worm husbandry filed as an experimental `condition`). The defense for free-text
+    fields is the prompt's operational definition of the field plus the evals corpus that measures it,
+    not this function. Tightening the matcher would not help; there is nothing here left to check.
+
+    **``library.prep_type`` is the one field checked by NORMALIZED match, not surface forms.** It is a
+    controlled biological concept (cells vs nuclei), so a terse quote ("snRNA-seq") must support a
+    verbose value ("single-nucleus RNA sequencing (snRNA-seq)") and a cell quote must never support a
+    nucleus value. Both sides are normalized to one of two preps and compared. This lets a nuclei claim
+    through — after which :func:`policy.resolve_features`, not the model, promotes ``GeneFull`` — while
+    never letting prose entail a *counting* decision: ``prep_type`` names no STARsolo feature, which is
+    exactly why ``processing.quantification`` is deliberately NOT handled this way (see ``_ALIAS_SOURCES``).
+    """
+    if field == "library.prep_type":
+        qp = normalize_prep_type(quote)
+        return qp is not None and qp == normalize_prep_type(value)
+    q = _squash(quote).lower()
+    q_tokens = set(_tokens(q))
+    for form in surface_forms(field, value):
+        f = _squash(form).lower()
+        if f and f in q:
+            return True
+        f_tokens = [t for t in _tokens(f) if t not in _STOPWORDS]
+        if f_tokens and set(f_tokens) <= q_tokens:
+            return True
+    return False
+
+
+def verify_drafts(
+    drafts: list[AssertionDraft],
+    docs: list[NormalizedDoc],
+    *,
+    extractor: ExtractorProvenance,
+) -> VerifyReport:
+    """Compose code-owned :class:`Assertion`s from LLM drafts. Only fully-verified claims survive."""
+    by_sha = {d.doc_sha256: d for d in docs}
+    assertions: list[Assertion] = []
+    rejected: list[dict[str, object]] = []
+
+    for i, draft in enumerate(drafts):
+        # FIRST, and before anything about the document's CONTENT: may the model set this field at
+        # all? A quote can be real and entailing on a field that was never on offer, so no amount of
+        # document-checking below can substitute for this one (see .fields).
+        if draft.field not in PERMITTED_FIELDS:
+            rejected.append(
+                _reject(draft, "field_not_permitted", f"{draft.field!r} is not an assertable field")
+            )
+            continue
+        doc = by_sha.get(draft.span.doc_sha256)
+        if doc is not None and not permitted_for(draft.field, doc.scope, doc.role):
+            # ...and may it set this field from THIS document? A downloaded methods PDF may never
+            # steer the pipeline, and a BioSample record has no opinion about the chemistry. Both
+            # scope and role are code-owned — the flag the document arrived under, and the record it
+            # was rendered from — so this is a deterministic refusal, not a judgement about the
+            # sentence.
+            rejected.append(
+                _reject(
+                    draft,
+                    "field_not_permitted_for_doc",
+                    f"{draft.field!r} may not be set by {doc.source_basename!r}, which is a "
+                    f"{doc.scope}-scoped {doc.role} document",
+                )
+            )
+            continue
+        if doc is None:
+            rejected.append(
+                _reject(draft, "unknown_doc", f"no normalized doc {draft.span.doc_sha256}")
+            )
+            continue
+        found = find_span(doc.text, draft.span.quote)
+        if found is None:
+            # fabricated provenance: the quote is not in the document it cites
+            rejected.append(
+                _reject(draft, "span_not_found", "quote does not occur in the document")
+            )
+            continue
+        if not entails(draft.span.quote, draft.field, draft.value):
+            # real quote, wrong value — the failure span-verification alone would miss
+            rejected.append(
+                _reject(draft, "not_entailed", f"quote does not support value {draft.value!r}")
+            )
+            continue
+        start, end = found
+        assertions.append(
+            Assertion(
+                id=f"assert-{draft.span.doc_sha256[:8]}-{i}",
+                field=draft.field,
+                value=draft.value,
+                span=SourceSpan(
+                    doc_sha256=draft.span.doc_sha256,
+                    quote=draft.span.quote,
+                    context=draft.span.context,
+                    char_start=start,  # computed by code, never by the model
+                    char_end=end,
+                    # ...and the page the offset falls on, same discipline: code reads it off the
+                    # document's page index, the model's value (if any) is discarded. None unless it
+                    # is a PDF, where "p.4" is a real, checkable location.
+                    page=page_for_offset(doc.pages, start),
+                ),
+                span_verified=True,
+                entailment_ok=True,
+                llm_confidence=draft.llm_confidence,
+                extractor=extractor,
+            )
+        )
+    return VerifyReport(assertions=assertions, rejected=rejected)
+
+
+def _reject(draft: AssertionDraft, reason: str, detail: str) -> dict[str, object]:
+    return {
+        "field": draft.field,
+        "value": draft.value,
+        "quote": draft.span.quote[:120],
+        "reason": reason,
+        "detail": detail,
+    }

seqforge/hooks/__init__.py

@@ -0,0 +1,33 @@
+"""``hooks`` — policy becomes mechanism (design §4.2).
+
+`CLAUDE.md` can *say* "never read a whole FASTQ". Only a hook can stop one. These are the checked
+edges of the rules: bounded reads, no absolute path in a manifest, and code — not the model — decides
+whether an edit validated.
+
+Wire them with ``seqforge hook install`` — see :mod:`.guards` for why the logic is typed and tested
+rather than living in a shell script.
+"""
+
+from __future__ import annotations
+
+from .guards import (
+    HOOKS_VERSION,
+    Denial,
+    check_absolute_path_write,
+    check_unbounded_fastq,
+    post_tool_use_targets,
+    pre_tool_use,
+    questions_outstanding,
+    stop_decision,
+)
+
+__all__ = [
+    "HOOKS_VERSION",
+    "Denial",
+    "pre_tool_use",
+    "post_tool_use_targets",
+    "stop_decision",
+    "check_unbounded_fastq",
+    "check_absolute_path_write",
+    "questions_outstanding",
+]