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_numbersbecause this checker has nothing to say about it, not because a span entails it. Entailment is anotherGrounderbehind the same port. - No spans means unsupported, always.
scoreis 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.
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;
NUMby default.
Returns:
-
str–textwith 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–textwith collapsed whitespace, or a cut prefix ending inplaceholder. Every digit run -
str–in the result is a whole digit run of
text.
Raises:
-
ValueError–widthleaves no room for one character beforeplaceholder.
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.
- 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. - 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". - 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. maxLengthis not enforced alongsidepattern, 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 exactmax_lengthon the pydantic field too.- The converter's regex subset has no
(?:, so groups are plain(...).
Invariants
- Pure: no I/O.
- Over filled text,
beltis 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).
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
fillfrom 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.