fastrag.normalization.models#

Source-preserving structural models independent of ingestion and packing.

Classes

`CoverageUnit`(id, node_id, span)	A nonoverlapping retained source interval owned by a structural node.
`Diagnostic`(code, message[, span])	Stable normalization diagnostic; no timing or secret values.
`Exclusion`(span, reason)	Explicitly omitted source with the policy reason.
`NormalizedDocument`(document, source_format, ...)	Tree and independent exact source coverage partition.
`NormalizedNode`(id, kind, content, spans[, ...])	Ordered structure; content is original syntax, not rewritten prose.
`Normalizer`(args, *kwargs)	Injectable format adapter with stable nonsecret cache identity.
`SourceSpan`(start_offset, end_offset)	Half-open Unicode offsets into the original Document content.

class fastrag.normalization.models.SourceSpan(start_offset, end_offset)[source]#

Bases: object

Half-open Unicode offsets into the original Document content.

Parameters:

start_offset (int)
end_offset (int)

class fastrag.normalization.models.NormalizedNode(id, kind, content, spans, children=(), parent_id=None, level=None, title=None, metadata=<factory>)[source]#

Bases: object

Ordered structure; content is original syntax, not rewritten prose.

Parameters:

id (str)
kind (str)
content (str)
spans (tuple[SourceSpan, ...])
children (tuple[NormalizedNode, ...])
parent_id (str | None)
level (int | None)
title (str | None)
metadata (dict[str, Any])

walk()[source]#

Yield this node and descendants in source order.

Return type:: Iterator[NormalizedNode]

class fastrag.normalization.models.CoverageUnit(id, node_id, span)[source]#

Bases: object

A nonoverlapping retained source interval owned by a structural node.

Parameters:

id (str)
node_id (str)
span (SourceSpan)

class fastrag.normalization.models.Exclusion(span, reason)[source]#

Bases: object

Explicitly omitted source with the policy reason.

Parameters:

span (SourceSpan)
reason (str)

class fastrag.normalization.models.Diagnostic(code, message, span=None)[source]#

Bases: object

Stable normalization diagnostic; no timing or secret values.

Parameters:

code (str)
message (str)
span (SourceSpan | None)

class fastrag.normalization.models.NormalizedDocument(document, source_format, roots, units, exclusions=(), diagnostics=())[source]#

Bases: object

Tree and independent exact source coverage partition.

Parameters:

document (Document)
source_format (str)
roots (tuple[NormalizedNode, ...])
units (tuple[CoverageUnit, ...])
exclusions (tuple[Exclusion, ...])
diagnostics (tuple[Diagnostic, ...])

property source: str#: Return the unchanged original string.

walk()[source]#

Yield all nodes in preorder.

Return type:: Iterator[NormalizedNode]

validate()[source]#

Check lineage, source slices and complete nonduplicated coverage.

Return type:: None

class fastrag.normalization.models.Normalizer(*args, **kwargs)[source]#

Bases: Protocol

Injectable format adapter with stable nonsecret cache identity.

property identity: str#: Describe every output-changing adapter option.

normalize(document)[source]#

Normalize a document without executing its markup.

Parameters:: document (Document)
Return type:: NormalizedDocument