groundgate 0.1.0__py3-none-any.whl

groundgate/__init__.py

@@ -0,0 +1,22 @@
+"""Deterministic admission for LLM-extracted facts."""
+
+from .admit import Verification, admit, verify
+from .canonical import digest, jcs
+from .model import Decision, Field, PacketError, Policy, Receipt, Schema
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Decision",
+    "Field",
+    "PacketError",
+    "Policy",
+    "Receipt",
+    "Schema",
+    "Verification",
+    "__version__",
+    "admit",
+    "digest",
+    "jcs",
+    "verify",
+]

groundgate/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters from other extraction tools' output to groundgate candidates."""

groundgate/adapters/langextract.py

@@ -0,0 +1,123 @@
+"""Admit LangExtract results.
+
+LangExtract checks that each ``extraction_text`` is found in the source and records where
+(``char_interval``). It does not check the typed value you asked for in the attributes. This
+adapter turns each extraction into a groundgate candidate so the value and unit are checked at
+that location::
+
+    result = lx.extract(text_or_documents=text, prompt_description=..., examples=...)
+    receipt = admit_document(result, schema)
+
+Works on ``lx.data.AnnotatedDocument`` objects and on the dicts LangExtract writes to JSONL
+(``lx.io.save_annotated_documents``). LangExtract itself is not imported.
+
+Mapping, per extraction:
+
+- ``field``: ``extraction_class``, renamed through ``fields`` when given;
+- ``value``: the ``value`` attribute, or ``extraction_text`` when there is none;
+- ``unit``: the ``unit`` attribute, when present;
+- ``evidence``: ``char_interval`` converted to UTF-8 byte offsets, quoting ``extraction_text``.
+  An extraction LangExtract could not align has no evidence and is rejected ``NO_EVIDENCE``.
+
+``alignment_status`` and ``extraction_class`` are kept on the candidate for the report; the
+checks ignore them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..admit import admit
+from ..canonical import Offsets, is_nfc
+from ..model import PacketError, Policy, Receipt, Schema
+
+
+def _get(obj: Any, name: str) -> Any:
+    if isinstance(obj, Mapping):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
+def _status(raw: Any) -> str | None:
+    if raw is None:
+        return None
+    return str(getattr(raw, "value", raw))  # an AlignmentStatus enum or its string value
+
+
+def document_text(document: Any) -> str:
+    text = _get(document, "text")
+    if not isinstance(text, str):
+        raise PacketError("the LangExtract document has no text")
+    if not is_nfc(text):
+        raise PacketError(
+            "the LangExtract document text is not NFC; normalise it before calling lx.extract "
+            "(unicodedata.normalize('NFC', text)) so offsets line up"
+        )
+    return text
+
+
+def to_candidates(
+    document: Any,
+    *,
+    fields: Mapping[str, str] | None = None,
+    value_attribute: str = "value",
+    unit_attribute: str = "unit",
+) -> list[dict[str, Any]]:
+    """One groundgate candidate per extraction in a LangExtract ``AnnotatedDocument``."""
+    text = document_text(document)
+    offsets = Offsets(text)
+    out = []
+    for i, x in enumerate(_get(document, "extractions") or []):
+        cls = _get(x, "extraction_class")
+        quote = _get(x, "extraction_text")
+        attrs = _get(x, "attributes") or {}
+        cand: dict[str, Any] = {
+            "id": i,
+            "field": (fields or {}).get(cls, cls),
+            "value": attrs.get(value_attribute, quote),
+            "extraction_class": cls,
+            "alignment_status": _status(_get(x, "alignment_status")),
+        }
+        if attrs.get(unit_attribute) is not None:
+            cand["unit"] = attrs[unit_attribute]
+        interval = _get(x, "char_interval")
+        start, end = _get(interval, "start_pos"), _get(interval, "end_pos")
+        if isinstance(start, int) and isinstance(end, int):
+            if not 0 <= start <= end <= len(text):
+                raise PacketError(f"extraction {i} has a char_interval outside the document text")
+            cand["evidence"] = {
+                "start": offsets.to_bytes(start),
+                "end": offsets.to_bytes(end),
+                "text": quote,
+            }
+        out.append(cand)
+    return out
+
+
+def admit_document(
+    document: Any,
+    schema: Schema | Mapping[str, Any],
+    policy: Policy | Mapping[str, Any] | None = None,
+    *,
+    document_id: str | None = None,
+    **options: Any,
+) -> Receipt:
+    """Admit every extraction in a LangExtract document. ``options`` go to ``to_candidates``.
+
+    ``document_id`` defaults to the id the caller gave LangExtract. An id LangExtract generated
+    itself is random, so it is left out to keep the receipt reproducible.
+    """
+    if document_id is None:
+        if isinstance(document, Mapping):
+            given = document.get("document_id")
+        else:  # reading the property would make LangExtract invent a random id
+            given = vars(document).get("_document_id") if hasattr(document, "__dict__") else None
+        document_id = given if isinstance(given, str) else None
+    return admit(
+        document_text(document),
+        schema,
+        to_candidates(document, **options),
+        policy,
+        document_id=document_id,
+    )

groundgate/admit.py

@@ -0,0 +1,333 @@
+"""The decision procedure (SPEC §3) and receipts (SPEC §5)."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any
+
+from .canonical import Offsets, digest, is_nfc
+from .model import Decision, Field, Outcome, PacketError, Policy, Receipt, Schema
+from .text import (
+    Token,
+    canonical,
+    normalize_ws,
+    parse_value,
+    qualifiers,
+    quote_pattern,
+    scale_word,
+    tokens,
+    unit_at,
+    verbatim_equal,
+)
+
+NULL_LITERALS = {"null", "none", "nil", "n/a"}
+FLAG_ORDER = (  # SPEC §3 table order; it is part of every receipt hash
+    "NON_VERBATIM_EVIDENCE",
+    "QUALIFIED_VALUE",
+    "SCALE_WORD",
+    "LOW_CONFIDENCE",
+    "CONFLICTING_CANDIDATES",
+)
+REANCHORED = "EVIDENCE_REANCHORED"
+
+
+class _Reject(Exception):
+    def __init__(self, code: str) -> None:
+        self.code = code
+
+
+def _span(obj: object) -> tuple[int, int] | None:
+    """(start, end) from a span object, or None if malformed (SPEC §3 step 1)."""
+    if not isinstance(obj, Mapping):
+        return None
+    s, e = obj.get("start"), obj.get("end")
+    if (
+        isinstance(s, bool)
+        or isinstance(e, bool)
+        or not isinstance(s, int)
+        or not isinstance(e, int)
+    ):
+        return None
+    return s, e
+
+
+def _valid(offsets: Offsets, span: tuple[int, int]) -> tuple[int, int] | None:
+    """Code-point span for a valid byte span (SPEC §2.2), else None."""
+    s, e = span
+    if not (0 <= s < e <= offsets.byte_length):
+        return None
+    cs, ce = offsets.to_char(s), offsets.to_char(e)
+    return None if cs is None or ce is None else (cs, ce)
+
+
+@dataclass
+class _Ctx:
+    text: str
+    offsets: Offsets
+    schema: Schema
+    policy: Policy
+
+
+@dataclass
+class _Passed:
+    """A candidate that passed steps 1-10."""
+
+    field: Field
+    value: str
+    unit: str | None
+    span: tuple[int, int]  # code points
+    token: Token | None
+    flags: list[str]
+    reanchored: bool
+
+
+def _value_at(
+    ctx: _Ctx, f: Field, value: Decimal | str, span: tuple[int, int]
+) -> tuple[Token | None, str | None]:
+    """Steps 9-10 at one span: the supporting token (None for strings) or a failure code."""
+    s, e = span
+    if f.type == "string":
+        assert isinstance(value, str)
+        if normalize_ws(value) not in normalize_ws(ctx.text[s:e]):
+            return None, "VALUE_NOT_IN_EVIDENCE"
+        return None, None
+    hits = [t for t in tokens(ctx.text, s, e) if t.value is not None and t.value == value]
+    if not hits:
+        return None, "VALUE_NOT_IN_EVIDENCE"
+    if f.unit is None:
+        return hits[0], None
+    prefixes, suffixes = ctx.schema.units.get(f.unit, ([], []))
+    for t in hits:
+        if unit_at(ctx.text, t, prefixes, suffixes, ctx.policy.unit_window):
+            return t, None
+    return None, "UNIT_NOT_IN_EVIDENCE"
+
+
+def _check(ctx: _Ctx, cand: object) -> _Passed:
+    """Steps 1-10 plus per-candidate flags. Raises _Reject."""
+    # 1. structure
+    if not isinstance(cand, Mapping):
+        raise _Reject("CANDIDATE_INVALID")
+    name, raw, unit = cand.get("field"), cand.get("value"), cand.get("unit")
+    conf, ev, region = cand.get("confidence"), cand.get("evidence"), cand.get("search_region")
+    if not isinstance(name, str) or isinstance(raw, bool) or not isinstance(raw, (str, int)):
+        raise _Reject("CANDIDATE_INVALID")
+    if unit is not None and not isinstance(unit, str):
+        raise _Reject("CANDIDATE_INVALID")
+    if conf is not None and (
+        isinstance(conf, bool) or not isinstance(conf, (int, float)) or not 0 <= conf <= 1
+    ):
+        raise _Reject("CANDIDATE_INVALID")
+    cited = None
+    if ev is not None:
+        cited = _span(ev)
+        if cited is None or not isinstance(ev.get("text", ""), str):
+            raise _Reject("CANDIDATE_INVALID")
+    region_span = None
+    if region is not None:
+        region_span = _span(region)
+        if region_span is None:
+            raise _Reject("CANDIDATE_INVALID")
+    # 2-6. field, value, type, range, unit
+    f = ctx.schema.fields.get(name)
+    if f is None:
+        raise _Reject("FIELD_UNKNOWN")
+    text_value = str(raw)
+    if text_value.strip().lower() in NULL_LITERALS:
+        raise _Reject("NULL_STRING_LITERAL")
+    value: Decimal | str
+    if f.type == "string":
+        if not isinstance(raw, str) or not normalize_ws(raw):
+            raise _Reject("TYPE_INVALID")
+        value = normalize_ws(raw)
+    else:
+        parsed = parse_value(text_value)
+        if parsed is None or (f.type == "integer" and parsed != parsed.to_integral_value()):
+            raise _Reject("TYPE_INVALID")
+        value = parsed
+        if (f.minimum is not None and parsed < f.minimum) or (
+            f.maximum is not None and parsed > f.maximum
+        ):
+            raise _Reject("RANGE_INVALID")
+    if unit != f.unit:
+        raise _Reject("UNIT_INVALID")
+    # 7-8. evidence
+    if cited is None:
+        raise _Reject("NO_EVIDENCE")
+    span = _valid(ctx.offsets, cited)
+    search = (0, len(ctx.text)) if region_span is None else _valid(ctx.offsets, region_span)
+    if span is None or search is None:
+        raise _Reject("SPAN_INVALID")
+    # 9-10. value and unit at the evidence, with re-anchoring
+    assert isinstance(ev, Mapping)
+    quote = ev.get("text")
+    token, failure = _value_at(ctx, f, value, span)
+    reanchored = False
+    if failure is not None:
+        if not (ctx.policy.reanchor and isinstance(quote, str) and normalize_ws(quote)):
+            raise _Reject(failure)
+        passing = []
+        for m in quote_pattern(quote).finditer(ctx.text, search[0], search[1]):
+            alt = (m.start(), m.end())
+            if alt != span:
+                alt_token, alt_failure = _value_at(ctx, f, value, alt)
+                if alt_failure is None:
+                    passing.append((alt, alt_token))
+        if len(passing) != 1:
+            raise _Reject(failure)
+        (span, token), reanchored = passing[0], True
+    # flags
+    flags = []
+    if isinstance(quote, str) and not verbatim_equal(quote, ctx.text[span[0] : span[1]]):
+        flags.append("NON_VERBATIM_EVIDENCE")
+    if token is not None:
+        found = qualifiers(ctx.text, token) - {f.comparator}
+        if found:
+            flags.append("QUALIFIED_VALUE")
+        if scale_word(ctx.text, token):
+            flags.append("SCALE_WORD")
+    mc = ctx.policy.min_confidence
+    if mc is not None and conf is not None and conf < mc:
+        flags.append("LOW_CONFIDENCE")
+    canon = value if isinstance(value, str) else canonical(value)
+    return _Passed(f, canon, unit, span, token, flags, reanchored)
+
+
+def admit(
+    text: str,
+    schema: Schema | Mapping[str, Any],
+    candidates: Sequence[object],
+    policy: Policy | Mapping[str, Any] | None = None,
+    document_id: str | None = None,
+) -> Receipt:
+    """Decide every candidate and return the receipt."""
+    if not isinstance(text, str) or not is_nfc(text):
+        raise PacketError("document text must be a string in Unicode NFC")
+    if not isinstance(schema, Schema):
+        schema = Schema.from_dict(schema)
+    if not isinstance(policy, Policy):
+        policy = Policy() if policy is None else Policy.from_dict(policy)
+    if isinstance(candidates, (str, bytes)) or not isinstance(candidates, Sequence):
+        raise PacketError("candidates must be a list")
+    ctx = _Ctx(text, Offsets(text), schema, policy)
+
+    results: list[tuple[str, int, object, _Passed | str]] = []
+    for i, cand in enumerate(candidates):
+        try:
+            outcome: _Passed | str = _check(ctx, cand)
+        except _Reject as r:
+            outcome = r.code
+        results.append((digest("candidate", cand), i, cand, outcome))
+
+    by_field: dict[str, set[tuple[str, str | None]]] = defaultdict(set)
+    for *_, p in results:
+        if isinstance(p, _Passed) and not p.field.multiple:
+            by_field[p.field.name].add((p.value, p.unit))
+    for *_, p in results:
+        if isinstance(p, _Passed) and len(by_field.get(p.field.name, ())) > 1:
+            p.flags.append("CONFLICTING_CANDIDATES")
+
+    decisions = []
+    for sha, _, cand, p in sorted(results, key=lambda r: (r[0], r[1])):
+        cid = cand.get("id") if isinstance(cand, Mapping) else None
+        decisions.append(_decision(ctx, sha, cand, cid, p))
+
+    live = {d.field for d in decisions if d.outcome != "rejected"}
+    coverage = tuple(
+        (name, "REQUIRED_FIELD_MISSING")
+        for name in sorted(schema.fields)
+        if schema.fields[name].required and name not in live
+    )
+    doc_sha = digest("document", {"text": text})
+    draft = Receipt(
+        document_id,
+        doc_sha,
+        digest("schema", schema.to_dict()),
+        digest("policy", policy.to_dict()),
+        tuple(decisions),
+        coverage,
+        "",
+    )
+    return Receipt(**{**draft.__dict__, "receipt_sha256": digest("receipt", draft.body())})
+
+
+def _decision(ctx: _Ctx, sha: str, cand: object, cid: object, p: _Passed | str) -> Decision:
+    if isinstance(p, _Passed):
+        flags = [c for c in FLAG_ORDER if c in p.flags]
+        codes = [*flags, REANCHORED] if p.reanchored else flags
+        byte_span = (ctx.offsets.to_bytes(p.span[0]), ctx.offsets.to_bytes(p.span[1]))
+        outcome: Outcome = "needs_verification" if flags else "admitted"
+        return Decision(
+            _json_id(cid), sha, p.field.name, outcome, tuple(codes), p.value, p.unit, byte_span
+        )
+    # rejected: report what is known about the candidate
+    field_name: str | None = None
+    value: str | None = None
+    unit: str | None = None
+    span: tuple[int, int] | None = None
+    if isinstance(cand, Mapping):
+        if isinstance(cand.get("field"), str):
+            field_name = cand["field"]
+        if isinstance(cand.get("unit"), str):
+            unit = cand["unit"]
+        f = ctx.schema.fields.get(field_name or "")
+        raw = cand.get("value")
+        if f is not None and isinstance(raw, (str, int)) and not isinstance(raw, bool):
+            if f.type == "string" and isinstance(raw, str) and normalize_ws(raw):
+                value = normalize_ws(raw)
+            elif f.type != "string" and (parsed := parse_value(str(raw))) is not None:
+                value = canonical(parsed)
+        cited = _span(cand.get("evidence"))
+        if cited is not None and _valid(ctx.offsets, cited) is not None:
+            span = cited
+    return Decision(_json_id(cid), sha, field_name, "rejected", (p,), value, unit, span)
+
+
+def _json_id(cid: object) -> object:
+    return (
+        cid if cid is None or (isinstance(cid, (str, int)) and not isinstance(cid, bool)) else None
+    )
+
+
+@dataclass(frozen=True)
+class Verification:
+    ok: bool
+    problems: tuple[str, ...]
+
+
+def verify(
+    receipt: Mapping[str, Any],
+    text: str,
+    schema: Schema | Mapping[str, Any],
+    candidates: Sequence[object],
+    policy: Policy | Mapping[str, Any] | None = None,
+) -> Verification:
+    """Re-derive the receipt from its inputs and compare it with ``receipt``."""
+    if not isinstance(receipt, Mapping):
+        raise PacketError("receipt must be a JSON object")
+    problems = []
+    body = {k: v for k, v in receipt.items() if k != "receipt_sha256"}
+    if digest("receipt", body) != receipt.get("receipt_sha256"):
+        problems.append("receipt_sha256 does not match the receipt body")
+    doc_id = (
+        receipt.get("document", {}).get("id")
+        if isinstance(receipt.get("document"), Mapping)
+        else None
+    )
+    fresh = admit(text, schema, candidates, policy, document_id=doc_id).to_dict()
+    for key in ("document", "schema_sha256", "policy_sha256", "coverage", "summary"):
+        if receipt.get(key) != fresh[key]:
+            problems.append(f"{key} differs from the re-derived receipt")
+    theirs, ours = receipt.get("decisions"), fresh["decisions"]
+    if not isinstance(theirs, list) or len(theirs) != len(ours):
+        problems.append("decision count differs from the re-derived receipt")
+    else:
+        for a, b in zip(theirs, ours, strict=True):
+            if a != b:
+                problems.append(f"decision for candidate {b['candidate_sha256']} differs")
+    if not problems and receipt.get("receipt_sha256") != fresh["receipt_sha256"]:
+        problems.append("receipt_sha256 differs from the re-derived receipt")  # pragma: no cover
+    return Verification(not problems, tuple(problems))

groundgate/canonical.py

@@ -0,0 +1,120 @@
+"""Canonical JSON (RFC 8785), digests, and UTF-8 byte offsets (SPEC §2.2, §6)."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import unicodedata
+from decimal import Decimal
+from typing import Any
+
+SPEC_VERSION = "0.1"
+_SAFE_INT = 2**53 - 1
+_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def is_nfc(text: str) -> bool:
+    return unicodedata.is_normalized("NFC", text)
+
+
+def _number(x: float) -> str:
+    """ECMAScript Number.prototype.toString for a finite float."""
+    if not math.isfinite(x):
+        raise ValueError("NaN and infinities are not permitted in canonical JSON")
+    if x == 0:
+        return "0"
+    if x < 0:
+        return "-" + _number(-x)
+    _, digits, exp = Decimal(repr(x)).as_tuple()
+    assert isinstance(exp, int)
+    ds = "".join(map(str, digits)).rstrip("0")
+    exp += len(digits) - len(ds)
+    k = len(ds)
+    n = exp + k
+    if k <= n <= 21:
+        return ds + "0" * (n - k)
+    if 0 < n <= 21:
+        return ds[:n] + "." + ds[n:]
+    if -6 < n <= 0:
+        return "0." + "0" * -n + ds
+    e = n - 1
+    mantissa = ds if k == 1 else ds[0] + "." + ds[1:]
+    return f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}"
+
+
+def _string(s: str) -> str:
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch in _ESCAPES:
+            out.append(_ESCAPES[ch])
+        elif o < 0x20 or 0xD800 <= o <= 0xDFFF:
+            out.append(f"\\u{o:04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def jcs(obj: Any) -> str:
+    """Serialise ``obj`` as RFC 8785 canonical JSON."""
+    if obj is None:
+        return "null"
+    if obj is True:
+        return "true"
+    if obj is False:
+        return "false"
+    if isinstance(obj, int):
+        if abs(obj) > _SAFE_INT:
+            raise ValueError(f"integer {obj} is outside the exactly representable range")
+        return str(obj)
+    if isinstance(obj, float):
+        return _number(obj)
+    if isinstance(obj, str):
+        return _string(obj)
+    if isinstance(obj, (list, tuple)):
+        return "[" + ",".join(jcs(v) for v in obj) + "]"
+    if isinstance(obj, dict):
+        for k in obj:
+            if not isinstance(k, str):
+                raise TypeError("object keys must be strings")
+        keys = sorted(obj, key=lambda k: k.encode("utf-16-be", "surrogatepass"))
+        return "{" + ",".join(_string(k) + ":" + jcs(obj[k]) for k in keys) + "}"
+    raise TypeError(f"{type(obj).__name__} is not JSON-serialisable")
+
+
+def digest(kind: str, obj: Any) -> str:
+    """Domain-separated SHA-256 of ``obj``'s canonical JSON (SPEC §6)."""
+    prefix = f"groundgate/{SPEC_VERSION}:{kind}\0".encode("ascii")
+    payload = jcs(obj).encode("utf-8", "surrogatepass")
+    return "sha256:" + hashlib.sha256(prefix + payload).hexdigest()
+
+
+class Offsets:
+    """Converts between UTF-8 byte offsets and code-point offsets in one text."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self._byte_at: list[int] = [0]
+        for ch in text:
+            self._byte_at.append(self._byte_at[-1] + len(ch.encode("utf-8", "surrogatepass")))
+        self._char_at = {b: i for i, b in enumerate(self._byte_at)}
+
+    @property
+    def byte_length(self) -> int:
+        return self._byte_at[-1]
+
+    def to_bytes(self, char_offset: int) -> int:
+        return self._byte_at[char_offset]
+
+    def to_char(self, byte_offset: int) -> int | None:
+        """Code-point offset for a byte offset, or None if it is not on a character boundary."""
+        return self._char_at.get(byte_offset)