Reference · print me

Paxman recognition layer — glossary & file map

The compressed vocabulary of paxman/capabilities/*/grammar/ and paxman/core/grammar/. Terms graduate here only once demonstrated in practice.

Terms

RecognitionL0001
The syntactic act of finding where representations occur in raw text. Recognition never validates, never deduplicates across sources, never assigns canonical meaning. _Avoid_: parsing, extraction, matching (too loose).
Validation
The semantic counterpart: rules check recognized notations against authoritative specifications and produce canonical values with provenance. Distinct layer from recognition. _Reserved for later lessons_.
Span (half-open)L0001
A character interval written [start, end): start included, end excluded — identical to Python slice/range convention. End is always one past the last matched character. _Avoid_: “position pair”, index math without the bracket notation.
RecognitionMatchL0001
Frozen dataclass (paxman/core/domain.py): fields notation, start, end, raw_text, with invariant len(raw_text) == end − start enforced at construction. Spans are relative to the original input text. _Avoid_: bare notation, tuple spans.
GrammarL0001
A capability-level class satisfying the Grammar ABC: implements recognize(text) → list[RecognitionMatch] plus identity (name, non-empty semantics). Emits matches; owns no cross-match policy. _Avoid_: parser, lexer, validator.
NotationL0001
A per-capability typed record describing the shape of what was found (e.g. CountryNotation(shape="name", value=raw)). Carries no canonical meaning and no validity judgment. One notation type per capability (NotationT generic).
Kernel
paxman/core/grammar/ — shared machinery every grammar composes: scan context & views, normalizers, matchers, boundary specs. Covered from Lesson 0002 onward.
Engine policy (dedup & order)
The engine owns all cross-match decisions: within one grammar, a match fully contained in a longer match is dropped (“longer wins”); identical spans keep the first-emitted. Matches from different grammars are both preserved (ambiguity stays observable). Final order is document order: (start, end, active-set index, grammar name).

File map — where to look when reading

PathWhat lives there
paxman/core/domain.pyGrammar ABC (~L299), RecognitionMatch (~L68) — the contract source of truth
paxman/core/grammar/Kernel: scan_context, normalizers, boundary_spec, lexicon, composer, engine_loop
paxman/core/grammar/matchers/lexicon · regex · scanner · combinator · label · property · candidates
paxman/capabilities/<Cap>/grammar/One module per representation form (<name>_recognition.py)
paxman/capabilities/<Cap>/capability.pyget_grammars() wiring — the registry of that capability's grammars
ARCHITECTURE.md L17–48Separation principle + Recognition Pipeline Contract
HOW_TO_ADD_NEW_GRAMMAR.mdStep-by-step guide incl. strategy choice & TDD flow

Cited sources