Skip to content

llm_ports.grounding

llm_ports.grounding

Grounded prose: the number law (numbers), the slot grammar (slots), and the belt.

The package exports the shapes every grounded generator shares (Problem, the retry text, the belt) and NumberLawGrounder. numbers and slots are read module-qualified: each has its own loose and belt.

Problem dataclass

Problem(path: str, reason: str, detail: str = '')

One thing wrong with a model answer.

Attributes:

  • path (str) –

    The part of the answer (headline, claims.3, ...).

  • reason (str) –

    What is wrong.

  • detail (str) –

    The evidence (the figures, the ids), when there is any.

NumberLawGrounder

A Grounder that applies the number law (numbers.uncited).

Every digit run and spelled number in the claim must appear in a cited span.

Invariants
  • It judges numbers only: a necessary check, never a sufficient one. A numberless claim passes with reason no_numbers because this checker has nothing to say about it, not because a span entails it. Entailment is another Grounder behind the same port.
  • No spans means unsupported, always.
  • score is None: the verdict has no scale.

Rationale: ADR-0003.

verdict

verdict(
    claim: Claim, spans: Sequence[Chunk]
) -> GroundingVerdict

Return supported only when every number in the claim appears in one of spans.

allowed_numbers

allowed_numbers(texts: Iterable[str]) -> set[str]

Return every digit run the inputs render, by value (numbers.digits).

belt

belt(
    text: str,
    allowed: set[str],
    words_ok: str = "",
    *,
    strip_links: bool = False
) -> int

Return how many figures in text no input rendered (loose, counted). Expected: 0.

describe

describe(problems: Iterable[Problem]) -> str

Return problems as path: reason (detail); ..., the one way they are said to a model or a log.

loose

loose(
    text: str,
    allowed: set[str],
    words_ok: str = "",
    *,
    strip_links: bool = False
) -> list[str]

Return the figures in text that no input rendered (numbers.loose).

Each figure is named, so a verifier can say which one it refused and a retry can fix exactly that.

Parameters:

  • text (str) –

    The text to check.

  • allowed (set[str]) –

    Licensed digit runs by value (see allowed_numbers).

  • words_ok (str, default: '' ) –

    A substring haystack for spelled numbers. To license a word found in any of several inputs, join them on a newline.

  • strip_links (bool, default: False ) –

    Drop every markdown link whole, label and target, before checking. Use it only where code writes the links: a number inside a label is not checked.

Returns:

  • list[str] –

    The unlicensed figures in order; empty when every number is licensed.

retry_message

retry_message(problems: Iterable[Problem]) -> str

Return the text of the one retry: what failed, so the model can fix exactly that.

llm_ports.grounding.numbers

The number law: how every grader, belt and validator reads a number, and its English statement.

A figure in model output is licensed when an input rendered the same value, as digits or spelled out. loose is the check; law_text is the same law stated for a model judge. Every reader goes through this module, so a rule and a reader can disagree about judgement but never about the law.

Invariants
  • Pure: no I/O.
  • Digit runs compare by value (canon), never by string.

Rationale: ADR-0003.

LawExamples dataclass

LawExamples(
    paraphrase: Sequence[str] = (),
    fact_names: Sequence[str] = (),
)

The consumer's own words, named in the slots law as examples of what is not a figure.

A judge reads a domain word more reliably when the law names one. Each item is rendered verbatim, so quote a literal word yourself ("'flat'") and leave a description bare.

Attributes:

  • paraphrase (Sequence[str]) –

    Words, labels and paraphrase that are not figures.

  • fact_names (Sequence[str]) –

    Words that name a fact, which are never a reason to fail, cited or not.

redact

redact(
    text: str, *, hole: str, pattern: Pattern[str] = NUM
) -> str

Replace every number in text with hole.

Use it on context that may back a fact but never a figure: the figure is gone before the model reads it, so there is nothing to copy, and the fact survives.

Parameters:

  • text (str) –

    The text to redact; None reads as empty.

  • hole (str) –

    The replacement glyph, e.g. [n]. The caller validates that the model did not copy it.

  • pattern (Pattern[str], default: NUM ) –

    What counts as a number; NUM by default.

Returns:

  • str –

    text with each match replaced.

Rationale: ADR-0004.

shorten

shorten(
    text: str, width: int, *, placeholder: str = "…"
) -> str

Return text cut to at most width characters on a word, never inside a number.

Whitespace collapses first. A text that fits is returned whole, with no placeholder. Otherwise the cut falls on the last word boundary that leaves room for placeholder. When the first word alone is too long, the cut is hard but steps back to the start of any digit run (DIGITS) it would split, so "25bp" can never read as "2…". Show the full text beside the short one (a tooltip, a detail row): the placeholder says text is missing, not what it was.

Parameters:

  • text (str) –

    The text to shorten; None reads as empty.

  • width (int) –

    The longest result, placeholder included.

  • placeholder (str, default: '…' ) –

    Appended to a cut text.

Returns:

  • str –

    text with collapsed whitespace, or a cut prefix ending in placeholder. Every digit run

  • str –

    in the result is a whole digit run of text.

Raises:

  • ValueError –

    width leaves no room for one character before placeholder.

Rationale: ADR-0003.

canon

canon(run: str) -> str

Return one digit run as its value reads.

Thousands separators and trailing decimal zeros are dropped: "2.20" and "2.2" are one number, "7.0" is "7", "1,234.50" is "1234.5". An integer keeps its zeros ("100").

Rationale: ADR-0003.

digits

digits(text: str) -> set[str]

Return the digit runs in text by value (canon): the set a belt compares against.

spelled

spelled(text: str) -> set[str]

Return the spelled numbers and number-word tails in text, lower-cased.

loose

loose(
    text: str, allowed: set[str], words_ok: str = ""
) -> list[str]

Return every figure in text that no input licensed.

The number law in one place: a digit run whose value (canon) is not in allowed, then a spelled number or number-word tail not found in words_ok. grounding.belt and slots.belt count the result, uncited sorts it, and call.graders.numbers_from_inputs scores it.

Parameters:

  • text (str) –

    The text to check; None reads as empty.

  • allowed (set[str]) –

    Licensed digit runs, already canonical (see digits).

  • words_ok (str, default: '' ) –

    A lower-cased substring haystack for spelled numbers. Join several inputs on a newline: a number word holds no whitespace, so a join never glues two halves into one. An input that shows % also licenses "percent".

Returns:

  • list[str] –

    The unlicensed figures in order of appearance, digit runs first, repeats kept. Empty when

  • list[str] –

    every number is licensed.

Rationale: ADR-0003.

uncited

uncited(
    claim: str, spans: Iterable[tuple[str, str]]
) -> list[str]

Return the figures in claim that no cited span renders: loose in the cited-spans shape.

A digit run is licensed by a span's title or text; a spelled number by a span's text.

Parameters:

  • claim (str) –

    The claim to check.

  • spans (Iterable[tuple[str, str]]) –

    (title, text) pairs the claim cites.

Returns:

  • list[str] –

    The unlicensed figures, digit runs then words, each group sorted and unique. Empty when

  • list[str] –

    every number is cited; with no spans, every number is missing.

law_text

law_text(
    mode: str,
    *,
    web: bool = False,
    examples: LawExamples | None = None
) -> str

Return the number law as one numbered rubric line for a model judge.

The statement matches what loose enforces for the same call, so a deterministic grader and a judge disagree only about judgement. A value the output grammar itself asks for (a score, an enum label) is always the model's answer, never a figure under this law.

Parameters:

  • mode (str) –

    The role's grounding mode. "slots" (the model cites {id} under a digit-free grammar, so any written number is invented) changes the law; any other word reads figures against the Input.

  • web (bool, default: False ) –

    The call read web pages the judge cannot see. A figure missing from the Input is then expected; only one that contradicts the Input fails. Takes precedence over mode.

  • examples (LawExamples | None, default: None ) –

    Domain words the "slots" law names as not figures; none by default.

Returns:

  • str –

    The law as rubric text, ending in a newline.

Rationale: ADR-0003.

llm_ports.grounding.slots

Grounded prose by construction: the model cites a value by name, and code prints the value.

  1. Code renders every value once, as text, under an id that holds no digits ([a-z_:]+): {"total": "1,284.50", "count": "3"}. The prompt shows the model {total} and what it means.
  2. The output grammar forbids digits in every prose run (prose_pattern, slot_pattern), so the model can write {total} and cannot write "1,284.50", "1,300" or "three more".
  3. Code fills each slot with its rendered value (fill), then runs the belt over the filled text (belt): every number in it must be a rendered value.

The grammar is a character whitelist (PROSE_CHARS), not a negated class such as [^0-9]. Compatibility facts for llama.cpp's json-schema-to-grammar converter:

  • A pattern string is compiled outside JSON string escaping, so a negated class admits raw control bytes that break json.loads. The whitelist admits nothing that needs escaping.
  • maxLength is not enforced alongside pattern, so a capped run carries its cap in the pattern as {0,N}. A slot counts as one repetition, so the grammar's cap is approximate; keep the exact max_length on the pydantic field too.
  • The converter's regex subset has no (?:, so groups are plain (...).
Invariants
  • Pure: no I/O.
  • Over filled text, belt is 0 by construction. A non-zero count is an alarm, never a rate.

Rationale: ADR-0002, ADR-0005.

prose_pattern

prose_pattern(n: int) -> str

Return the pattern for a words-only run of at most n characters, the cap inside the grammar.

slot_pattern

slot_pattern(ids: Iterable[str], n: int) -> str

Return the pattern for prose that may cite exactly these ids as {id}, and nothing else.

Parameters:

  • ids (Iterable[str]) –

    The slot ids the run may cite; duplicates are ignored.

  • n (int) –

    The cap, in repetitions per run (a slot counts as one).

Returns:

  • str –

    A pattern. With one or two ids, each slot may appear at most once, so the grammar itself

  • str –

    stops a value being cited where it means something else. With none, prose_pattern(n).

Raises:

  • ValueError –

    An id a digit-free grammar could not write (it does not match ID).

cited

cited(text: str) -> list[str]

Return the slot ids text cites, in order, repeats kept.

fill

fill(text: str, rendered: Mapping[str, str]) -> str

Replace each {id} in text with its rendered value.

An unknown id is left as written, so problems and the belt still see it.

Invariants
  • The model's text is never a template: one regex substitution over ids, nothing evaluated.

problems

problems(
    text: str,
    rendered: Mapping[str, str],
    *,
    once: bool = True
) -> list[str]

Return what is wrong with one prose run before it is filled, worded so a retry can fix it.

Parameters:

  • text (str) –

    The unfilled run.

  • rendered (Mapping[str, str]) –

    The rendered values by id.

  • once (bool, default: True ) –

    Also report a value cited twice (a figure pasted where it means something else).

Returns:

  • list[str] –

    One message per problem: a slot that names no value, a brace that is not a slot, a repeat.

  • list[str] –

    Empty when the run is clean.

loose

loose(text: str, rendered: Mapping[str, str]) -> list[str]

Return the figures in text that no rendered value shows, digits or spelled out, in order.

A thin wrapper over grounding.loose: a spelled word is licensed by any value that renders it. Over unfilled text it names what the model wrote around the grammar (a spelled number); over filled text it is the belt's evidence.

belt

belt(text: str, rendered: Mapping[str, str]) -> int

Return how many figures in filled text no rendered value shows (loose, counted).

Invariants
  • 0 for any text built by fill from a run the grammar admitted.

to_prose

to_prose(text: str) -> str

Return text as context a grounded writer may read.

Every digit run is removed whole (numbers.DIGITS, so 14:00, 3.1% and 5,000 leave no half a number behind), every character outside PROSE_CHARS becomes a space, and whitespace collapses. A figure stays citable by its slot id; the digits the model must not copy are gone before it reads them. Use it on free text placed in the prompt (a user's note, a tool's reason string, a JSON key), never on a rendered value: code fills those.

Rationale: ADR-0004.