Routing API

The routed model is additive. Legacy SurveyVariable and SurveySVIS fields and ordered JSON semantics remain unchanged.

Router methods

Method	Return	Behavior
route(source, svis, source_binding=...)	ExtractionResult[RoutedSurveySVIS]	Synchronous routing outside an event loop
aroute(source, svis, source_binding=...)	ExtractionResult[RoutedSurveySVIS]	Async routing

The constructor accepts a StructuredProvider | None, optional RoutingConfig, and optional SourceRegistry. None is valid only for complete native routing. The exact source name, media type, digest, survey ID, and binding version must match before provider work starts.

Expected source, binding, provider, and graph failures become safe failed result envelopes. An unexpected programming error can propagate. route() raises RuntimeError when called inside an active event loop.

routing

Immutable public models for routed questionnaire SVIS artifacts.

CandidateEdge

Bases: StrictRoutingModel

Non-authoritative edge candidate that can preserve an unresolved target.

candidate_id instance-attribute

candidate_id: NonEmptyStr

source_node_id instance-attribute

source_node_id: NonEmptyStr

target_node_id instance-attribute

target_node_id: NonEmptyStr | None

target_reference instance-attribute

target_reference: ItemReference

kind instance-attribute

kind: EdgeKind

condition instance-attribute

condition: ExtractedRoutingCondition | None

priority instance-attribute

priority: NonNegativeInt | None

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

confidence instance-attribute

confidence: Confidence

status instance-attribute

status: CandidateStatus

validate_candidate_shape

validate_candidate_shape() -> CandidateEdge

CandidateStatus

Bases: str, Enum

Current audit state of a non-authoritative edge candidate.

proposed class-attribute instance-attribute

proposed = 'proposed'

needs_agent_review class-attribute instance-attribute

needs_agent_review = 'needs_agent_review'

needs_human_review class-attribute instance-attribute

needs_human_review = 'needs_human_review'

accepted class-attribute instance-attribute

accepted = 'accepted'

rejected class-attribute instance-attribute

rejected = 'rejected'

Containment

Bases: StrictRoutingModel

Parent relation plus derived stable children and explicit group entry.

parent_node_id instance-attribute

parent_node_id: NonEmptyStr | None

child_node_ids instance-attribute

child_node_ids: tuple[NonEmptyStr, ...]

entry_child_node_id instance-attribute

entry_child_node_id: NonEmptyStr | None

validate_containment

validate_containment() -> Containment

DiagnosticSeverity

Bases: str, Enum

Stable routing diagnostic severity.

info class-attribute instance-attribute

info = 'info'

warning class-attribute instance-attribute

warning = 'warning'

error class-attribute instance-attribute

error = 'error'

DiscrepancyKind

Bases: str, Enum

Bounded discrepancy categories available to review.

conflicting_target class-attribute instance-attribute

conflicting_target = 'conflicting_target'

conflicting_condition class-attribute instance-attribute

conflicting_condition = 'conflicting_condition'

ambiguous_target class-attribute instance-attribute

ambiguous_target = 'ambiguous_target'

unresolved_target class-attribute instance-attribute

unresolved_target = 'unresolved_target'

multiple_defaults class-attribute instance-attribute

multiple_defaults = 'multiple_defaults'

incoming_mismatch class-attribute instance-attribute

incoming_mismatch = 'incoming_mismatch'

opaque_condition class-attribute instance-attribute

opaque_condition = 'opaque_condition'

unsupported_cycle class-attribute instance-attribute

unsupported_cycle = 'unsupported_cycle'

activation_routing_conflict class-attribute instance-attribute

activation_routing_conflict = 'activation_routing_conflict'

other class-attribute instance-attribute

other = 'other'

EdgeKind

Bases: str, Enum

Accepted questionnaire flow semantics.

conditional class-attribute instance-attribute

conditional = 'conditional'

default class-attribute instance-attribute

default = 'default'

unconditional class-attribute instance-attribute

unconditional = 'unconditional'

sequential class-attribute instance-attribute

sequential = 'sequential'

EvidenceRecord

Bases: StrictRoutingModel

Python-assigned stable identifier around one immutable observation.

evidence_id instance-attribute

evidence_id: NonEmptyStr

observation instance-attribute

observation: EvidenceObservation

InventoryItem

Bases: StrictRoutingModel

One complete logical questionnaire item before reconciliation.

node_id instance-attribute

node_id: NonEmptyStr

source_item_id instance-attribute

source_item_id: NonEmptyStr | None

raw_reference instance-attribute

raw_reference: NonEmptyStr

section_path instance-attribute

section_path: tuple[NonEmptyStr, ...]

source_order instance-attribute

source_order: NonNegativeInt

block_ids instance-attribute

block_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

kind instance-attribute

kind: NodeKind

repeat_group_node_id instance-attribute

repeat_group_node_id: NonEmptyStr | None

parent_node_id instance-attribute

parent_node_id: NonEmptyStr | None

linked_variable_indices instance-attribute

linked_variable_indices: tuple[NonNegativeInt, ...]

validate_inventory_item

validate_inventory_item() -> InventoryItem

LoopDefinition

Bases: StrictRoutingModel

Bounded metadata for one declared or source-supported loop region.

loop_id instance-attribute

loop_id: NonEmptyStr

kind instance-attribute

kind: LoopKind

repeat_group_node_id instance-attribute

repeat_group_node_id: NonEmptyStr | None

member_node_ids instance-attribute

member_node_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

entry_edge_ids instance-attribute

entry_edge_ids: tuple[NonEmptyStr, ...]

member_edge_ids instance-attribute

member_edge_ids: tuple[NonEmptyStr, ...]

return_edge_ids instance-attribute

return_edge_ids: tuple[NonEmptyStr, ...]

exit_edge_ids instance-attribute

exit_edge_ids: tuple[NonEmptyStr, ...]

source_supported instance-attribute

source_supported: Literal[True]

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

validate_loop_shape

validate_loop_shape() -> LoopDefinition

LoopKind

Bases: str, Enum

Supported topological or declared loop classification.

repeat_group class-attribute instance-attribute

repeat_group = 'repeat_group'

correction_return class-attribute instance-attribute

correction_return = 'correction_return'

repeat_until class-attribute instance-attribute

repeat_until = 'repeat_until'

other class-attribute instance-attribute

other = 'other'

RepeatKind

Bases: str, Enum

Logical template represented by a repeat group.

household_member class-attribute instance-attribute

household_member = 'household_member'

consumption_item class-attribute instance-attribute

consumption_item = 'consumption_item'

visit class-attribute instance-attribute

visit = 'visit'

plot class-attribute instance-attribute

plot = 'plot'

enterprise class-attribute instance-attribute

enterprise = 'enterprise'

until_condition class-attribute instance-attribute

until_condition = 'until_condition'

other class-attribute instance-attribute

other = 'other'

RepeatSpec

Bases: StrictRoutingModel

Logical repeat template without runtime unrolling.

repeat_kind instance-attribute

repeat_kind: RepeatKind

iterator_label instance-attribute

iterator_label: NonEmptyStr

collection_source instance-attribute

collection_source: NonEmptyStr | None

continuation_condition instance-attribute

continuation_condition: CanonicalRoutingCondition | None

maximum_iterations instance-attribute

maximum_iterations: PositiveInt | None

ReplacementEdge

Bases: StrictRoutingModel

Typed reviewer replacement content before canonical edge assignment.

source_node_id instance-attribute

source_node_id: NonEmptyStr

target_node_id instance-attribute

target_node_id: NonEmptyStr

target_reference instance-attribute

target_reference: ItemReference

kind instance-attribute

kind: EdgeKind

condition instance-attribute

condition: ExtractedRoutingCondition | None

priority instance-attribute

priority: NonNegativeInt | None

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

validate_replacement_shape

validate_replacement_shape() -> ReplacementEdge

ReviewAction

Bases: str, Enum

Append-only reviewer action.

confirm_candidate class-attribute instance-attribute

confirm_candidate = 'confirm_candidate'

replace_candidate class-attribute instance-attribute

replace_candidate = 'replace_candidate'

reject_candidate class-attribute instance-attribute

reject_candidate = 'reject_candidate'

unresolved class-attribute instance-attribute

unresolved = 'unresolved'

ReviewDecision

Bases: StrictRoutingModel

One append-only source-cited reviewer decision.

decision_id instance-attribute

decision_id: NonEmptyStr

discrepancy_ids instance-attribute

discrepancy_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

candidate_ids instance-attribute

candidate_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

cited_span_ids instance-attribute

cited_span_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

action instance-attribute

action: ReviewAction

replacement instance-attribute

replacement: ReplacementEdge | None

rationale instance-attribute

rationale: NonEmptyStr

confidence instance-attribute

confidence: Confidence

needs_human_review instance-attribute

needs_human_review: StrictBool

prompt_version instance-attribute

prompt_version: NonEmptyStr

prompt_sha256 instance-attribute

prompt_sha256: Sha256

provider_response_sha256 instance-attribute

provider_response_sha256: Sha256

supersedes_decision_id instance-attribute

supersedes_decision_id: NonEmptyStr | None

validate_decision_shape

validate_decision_shape() -> ReviewDecision

RoutingDiagnostic

Bases: StrictRoutingModel

Stable safe graph diagnostic without source-derived prose fields.

diagnostic_id instance-attribute

diagnostic_id: NonEmptyStr

code instance-attribute

code: NonEmptyStr

severity instance-attribute

severity: DiagnosticSeverity

message instance-attribute

message: NonEmptyStr

node_ids instance-attribute

node_ids: tuple[NonEmptyStr, ...]

edge_ids instance-attribute

edge_ids: tuple[NonEmptyStr, ...]

evidence_ids instance-attribute

evidence_ids: tuple[NonEmptyStr, ...]

candidate_ids instance-attribute

candidate_ids: tuple[NonEmptyStr, ...]

validate_unique_references

validate_unique_references() -> RoutingDiagnostic

RoutingDiscrepancy

Bases: StrictRoutingModel

Bounded discrepancy packet retained in the primary routed artifact.

discrepancy_id instance-attribute

discrepancy_id: NonEmptyStr

kind instance-attribute

kind: DiscrepancyKind

candidate_ids instance-attribute

candidate_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

source_span_ids instance-attribute

source_span_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

summary instance-attribute

summary: NonEmptyStr

needs_human_review instance-attribute

needs_human_review: StrictBool

resolved_by_decision_id instance-attribute

resolved_by_decision_id: NonEmptyStr | None

validate_unique_references

validate_unique_references() -> RoutingDiscrepancy

RoutingNode

Bases: StrictRoutingModel

One canonical logical node with accepted-edge adjacency projections.

node_id instance-attribute

node_id: NonEmptyStr

kind instance-attribute

kind: NodeKind

source_item_id instance-attribute

source_item_id: NonEmptyStr | None

raw_name instance-attribute

raw_name: NonEmptyStr | None

label instance-attribute

label: NonEmptyStr

terminal_kind instance-attribute

terminal_kind: TerminalKind | None

activation_condition instance-attribute

activation_condition: CanonicalRoutingCondition | None

repeat_spec instance-attribute

repeat_spec: RepeatSpec | None

containment instance-attribute

containment: Containment

next_node_ids instance-attribute

next_node_ids: tuple[NonEmptyStr, ...]

previous_node_ids instance-attribute

previous_node_ids: tuple[NonEmptyStr, ...]

outgoing_edge_ids instance-attribute

outgoing_edge_ids: tuple[NonEmptyStr, ...]

incoming_edge_ids instance-attribute

incoming_edge_ids: tuple[NonEmptyStr, ...]

validate_node_shape

validate_node_shape() -> RoutingNode

RoutingEdge

Bases: StrictRoutingModel

One authoritative accepted edge in the canonical multigraph.

edge_id instance-attribute

edge_id: NonEmptyStr

source_node_id instance-attribute

source_node_id: NonEmptyStr

target_node_id instance-attribute

target_node_id: NonEmptyStr

kind instance-attribute

kind: EdgeKind

condition instance-attribute

condition: CanonicalRoutingCondition | None

priority instance-attribute

priority: NonNegativeInt | None

evidence_ids instance-attribute

evidence_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

confidence instance-attribute

confidence: Confidence

review_decision_id instance-attribute

review_decision_id: NonEmptyStr | None

validate_edge_shape

validate_edge_shape() -> RoutingEdge

RoutingSourceBinding

Bases: StrictRoutingModel

Identity of the validated private source snapshot used for routing.

survey_id instance-attribute

survey_id: NonEmptyStr

source_name instance-attribute

source_name: NonEmptyStr

media_type instance-attribute

media_type: NonEmptyStr

snapshot_sha256 instance-attribute

snapshot_sha256: Sha256

source_conversion_schema_version instance-attribute

source_conversion_schema_version: NonEmptyStr

TerminalKind

Bases: str, Enum

Meaning of a terminal flow state.

survey_complete class-attribute instance-attribute

survey_complete = 'survey_complete'

screened_out class-attribute instance-attribute

screened_out = 'screened_out'

interview_terminated class-attribute instance-attribute

interview_terminated = 'interview_terminated'

unknown_terminal class-attribute instance-attribute

unknown_terminal = 'unknown_terminal'

QuestionnaireRoutingGraph

Bases: StrictRoutingModel

Canonical directed multigraph plus its separate append-only audit.

schema_version instance-attribute

schema_version: RoutingSchemaVersion

entry_node_ids instance-attribute

entry_node_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

nodes instance-attribute

nodes: Annotated[
    tuple[RoutingNode, ...], Field(min_length=1)
]

edges instance-attribute

edges: tuple[RoutingEdge, ...]

loops instance-attribute

loops: tuple[LoopDefinition, ...]

diagnostics instance-attribute

diagnostics: tuple[RoutingDiagnostic, ...]

routing_audit instance-attribute

routing_audit: RoutingAudit

validate_graph

validate_graph() -> QuestionnaireRoutingGraph

RoutingAudit

Bases: StrictRoutingModel

Evidence-first append-only audit layer outside the accepted graph facts.

source_binding instance-attribute

source_binding: RoutingSourceBinding

inventory instance-attribute

inventory: tuple[InventoryItem, ...]

source_spans instance-attribute

source_spans: tuple[SourceSpan, ...]

evidence instance-attribute

evidence: tuple[EvidenceRecord, ...]

candidate_edges instance-attribute

candidate_edges: tuple[CandidateEdge, ...]

discrepancies instance-attribute

discrepancies: tuple[RoutingDiscrepancy, ...]

review_decisions instance-attribute

review_decisions: tuple[ReviewDecision, ...]

validate_audit_references

validate_audit_references() -> RoutingAudit

RoutedSurveyVariable

Bases: SurveyVariable

Legacy-compatible variable with one nullable canonical node link.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    hide_input_in_errors=True,
    revalidate_instances="always",
)

categories class-attribute instance-attribute

categories: tuple[RoutedAnswerCategory, ...] | None = None

numeric_range class-attribute instance-attribute

numeric_range: RoutedNumericRange | None = None

routing_node_id instance-attribute

routing_node_id: NonEmptyStr | None

detach_categories classmethod

detach_categories(value: object) -> object

Detach mutable legacy categories before routed validation.

detach_numeric_range classmethod

detach_numeric_range(value: object) -> object

Detach a mutable legacy numeric range before routed validation.

to_survey_variable

to_survey_variable() -> SurveyVariable

Reconstruct the exact ordered legacy variable type.

RoutedSurveySVIS

Bases: SurveySVIS

Versioned routed extension with an exact typed legacy projection.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    hide_input_in_errors=True,
    revalidate_instances="always",
)

variables instance-attribute

variables: tuple[RoutedSurveyVariable, ...]

routing_schema_version instance-attribute

routing_schema_version: RoutingSchemaVersion

routing_graph instance-attribute

routing_graph: QuestionnaireRoutingGraph

validate_routed_links_and_versions

validate_routed_links_and_versions() -> RoutedSurveySVIS

to_survey_svis

to_survey_svis() -> SurveySVIS

Reconstruct an exact ordered v1 SVIS without dictionary deletion.

RoutedAnswerCategory

Bases: AnswerCategory

Deeply immutable routed form of one legacy answer category.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    hide_input_in_errors=True,
    revalidate_instances="always",
)

code instance-attribute

code: StrictInt | StrictStr

label instance-attribute

label: StrictStr

is_missing class-attribute instance-attribute

is_missing: StrictBool = False

RoutedNumericRange

Bases: NumericRange

Deeply immutable routed form of one legacy numeric range.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    hide_input_in_errors=True,
    revalidate_instances="always",
)

min_value class-attribute instance-attribute

min_value: FiniteFloat | None = None

max_value class-attribute instance-attribute

max_value: FiniteFloat | None = None

notes class-attribute instance-attribute

notes: StrictStr | None = None

canonical_routing_schema_json

canonical_routing_schema_json() -> str

Return the canonical graph JSON Schema with deterministic formatting.

contracts

Strict provider-facing contracts for questionnaire routing extraction.

EvidenceObservation module-attribute

EvidenceObservation: TypeAlias = Annotated[
    TransitionEvidence | ActivationEvidence,
    Field(discriminator="evidence_type"),
]

RoutingScalar module-attribute

RoutingScalar: TypeAlias = (
    StrictStr | StrictInt | FiniteFloat | StrictBool
)

ActivationEvidence

Bases: StrictRoutingModel

One provider-facing observation of item or group applicability.

evidence_type instance-attribute

evidence_type: Literal['activation']

local_id instance-attribute

local_id: NonEmptyStr

origin instance-attribute

origin: EvidenceOrigin

item instance-attribute

item: ItemReference

condition instance-attribute

condition: ExtractedRoutingCondition

source_span instance-attribute

source_span: SourceSpan

native_expression instance-attribute

native_expression: NativeExpression | None

explicitly_stated instance-attribute

explicitly_stated: StrictBool

confidence instance-attribute

confidence: Confidence

ambiguity_note instance-attribute

ambiguity_note: StrictStr | None

validate_activation_origin

validate_activation_origin() -> ActivationEvidence

CanonicalRoutingCondition

Bases: StrictRoutingModel

Condition whose controlling questions are canonical graph nodes.

operator instance-attribute

operator: ConditionOperator

question_node_id instance-attribute

question_node_id: NonEmptyStr | None

value instance-attribute

value: RoutingScalar | None

values instance-attribute

values: tuple[RoutingScalar, ...] | None

children instance-attribute

children: tuple[CanonicalRoutingCondition, ...] | None

raw_text instance-attribute

raw_text: StrictStr

ast_depth property

ast_depth: int

Return the validated root-to-leaf depth.

ast_node_count property

ast_node_count: int

Return the validated number of nodes.

validate_shape_and_limits

validate_shape_and_limits() -> CanonicalRoutingCondition

ConditionOperator

Bases: str, Enum

Supported routing-condition operations.

always class-attribute instance-attribute

always = 'always'

equals class-attribute instance-attribute

equals = 'equals'

not_equals class-attribute instance-attribute

not_equals = 'not_equals'

in_set class-attribute instance-attribute

in_set = 'in_set'

not_in_set class-attribute instance-attribute

not_in_set = 'not_in_set'

greater_than class-attribute instance-attribute

greater_than = 'greater_than'

greater_than_or_equal class-attribute instance-attribute

greater_than_or_equal = 'greater_than_or_equal'

less_than class-attribute instance-attribute

less_than = 'less_than'

less_than_or_equal class-attribute instance-attribute

less_than_or_equal = 'less_than_or_equal'

between class-attribute instance-attribute

between = 'between'

answered class-attribute instance-attribute

answered = 'answered'

not_answered class-attribute instance-attribute

not_answered = 'not_answered'

selected class-attribute instance-attribute

selected = 'selected'

not_selected class-attribute instance-attribute

not_selected = 'not_selected'

all class-attribute instance-attribute

all = 'all'

any class-attribute instance-attribute

any = 'any'

not_ class-attribute instance-attribute

not_ = 'not'

opaque class-attribute instance-attribute

opaque = 'opaque'

EvidenceOrigin

Bases: str, Enum

Producer of one source-grounded observation.

forward_extraction class-attribute instance-attribute

forward_extraction = 'forward_extraction'

incoming_extraction class-attribute instance-attribute

incoming_extraction = 'incoming_extraction'

native_parser class-attribute instance-attribute

native_parser = 'native_parser'

EvidencePerspective

Bases: str, Enum

Direction from which a transition was independently examined.

outgoing class-attribute instance-attribute

outgoing = 'outgoing'

incoming class-attribute instance-attribute

incoming = 'incoming'

ExtractedRoutingCondition

Bases: StrictRoutingModel

Condition that preserves an unresolved source item reference.

operator instance-attribute

operator: ConditionOperator

item_reference instance-attribute

item_reference: ItemReference | None

value instance-attribute

value: RoutingScalar | None

values instance-attribute

values: tuple[RoutingScalar, ...] | None

children instance-attribute

children: tuple[ExtractedRoutingCondition, ...] | None

raw_text instance-attribute

raw_text: StrictStr

ast_depth property

ast_depth: int

Return the validated root-to-leaf depth.

ast_node_count property

ast_node_count: int

Return the validated number of nodes.

validate_shape_and_limits

validate_shape_and_limits() -> ExtractedRoutingCondition

ItemReference

Bases: StrictRoutingModel

Preserved printed or unresolved questionnaire item reference.

raw_reference instance-attribute

raw_reference: NonEmptyStr

source_item_id instance-attribute

source_item_id: NonEmptyStr | None

canonical_hint instance-attribute

canonical_hint: NonEmptyStr | None

section_path instance-attribute

section_path: tuple[NonEmptyStr, ...]

node_kind instance-attribute

node_kind: NodeKind

binding_key property

binding_key: ItemReferenceKey

Return an exact hashable key for caller-supplied reference bindings.

NodeKind

Bases: str, Enum

Logical role of a canonical questionnaire node.

entry class-attribute instance-attribute

entry = 'entry'

question class-attribute instance-attribute

question = 'question'

section class-attribute instance-attribute

section = 'section'

repeat_group class-attribute instance-attribute

repeat_group = 'repeat_group'

terminal class-attribute instance-attribute

terminal = 'terminal'

RoutingPassKind

Bases: str, Enum

Independent extraction pass represented by one batch.

forward class-attribute instance-attribute

forward = 'forward'

incoming_activation class-attribute instance-attribute

incoming_activation = 'incoming_activation'

RoutingEvidenceBatch

Bases: StrictRoutingModel

Complete strict response for one independent provider extraction pass.

chunk_id instance-attribute

chunk_id: NonEmptyStr

pass_kind instance-attribute

pass_kind: RoutingPassKind

examined_item_ids instance-attribute

examined_item_ids: Annotated[
    tuple[NonEmptyStr, ...], Field(min_length=1)
]

evidence instance-attribute

evidence: tuple[EvidenceObservation, ...]

unresolved_references instance-attribute

unresolved_references: tuple[ItemReference, ...]

notes instance-attribute

notes: tuple[StrictStr, ...]

validate_batch

validate_batch() -> RoutingEvidenceBatch

SourceSpan

Bases: StrictRoutingModel

Bounded quote and physical provenance in one normalized source block.

span_id instance-attribute

span_id: NonEmptyStr

block_id instance-attribute

block_id: NonEmptyStr

source_name instance-attribute

source_name: NonEmptyStr

pages instance-attribute

pages: tuple[PositiveInt, ...]

sheet instance-attribute

sheet: NonEmptyStr | None

row_start instance-attribute

row_start: PositiveInt | None

row_end instance-attribute

row_end: PositiveInt | None

source_quote instance-attribute

source_quote: Annotated[
    StrictStr,
    Field(min_length=1, max_length=MAX_SOURCE_QUOTE_CHARS),
]

validate_provenance

validate_provenance() -> SourceSpan

NativeExpression

Bases: StrictRoutingModel

Exact native syntax plus its bounded canonical projection.

language instance-attribute

language: NonEmptyStr

version instance-attribute

version: NonEmptyStr

exact_expression instance-attribute

exact_expression: NonEmptyStr

parsed_references instance-attribute

parsed_references: tuple[ItemReference, ...]

canonical_projection instance-attribute

canonical_projection: CanonicalRoutingCondition

validate_unique_references

validate_unique_references() -> NativeExpression

StrictRoutingModel

Bases: BaseModel

Immutable base for every routing boundary model.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    hide_input_in_errors=True,
    revalidate_instances="always",
)

TransitionEvidence

Bases: StrictRoutingModel

One provider-facing observation of movement through the questionnaire.

evidence_type instance-attribute

evidence_type: Literal['transition']

local_id instance-attribute

local_id: NonEmptyStr

perspective instance-attribute

perspective: EvidencePerspective

origin instance-attribute

origin: EvidenceOrigin

source instance-attribute

source: ItemReference

target instance-attribute

target: ItemReference

transition_kind instance-attribute

transition_kind: TransitionKind

condition instance-attribute

condition: ExtractedRoutingCondition | None

source_span instance-attribute

source_span: SourceSpan

native_expression instance-attribute

native_expression: NativeExpression | None

explicitly_stated instance-attribute

explicitly_stated: StrictBool

confidence instance-attribute

confidence: Confidence

ambiguity_note instance-attribute

ambiguity_note: StrictStr | None

validate_transition_shape

validate_transition_shape() -> TransitionEvidence

TransitionKind

Bases: str, Enum

Flow semantics available to extraction and canonical edges.

conditional class-attribute instance-attribute

conditional = 'conditional'

default class-attribute instance-attribute

default = 'default'

unconditional class-attribute instance-attribute

unconditional = 'unconditional'

sequential class-attribute instance-attribute

sequential = 'sequential'

project_extracted_condition

project_extracted_condition(
    condition: ExtractedRoutingCondition,
    resolved_references: Mapping[ItemReferenceKey, str],
) -> CanonicalRoutingCondition

Project through caller-supplied exact bindings without resolving identities.

pipeline

Public questionnaire routing pipeline over native and provider evidence.

QuestionnaireRouter

QuestionnaireRouter(
    provider: StructuredProvider | None,
    *,
    config: RoutingConfig | None = None,
    sources: SourceRegistry | None = None,
)

Route one existing detached SVIS against its exact validated source snapshot.

route

route(
    source: LocalSource | SourceBundle,
    svis: SurveySVIS,
    *,
    source_binding: RoutingSourceBinding,
) -> ExtractionResult[RoutedSurveySVIS]

Run routing synchronously when no event loop is active in this thread.

aroute async

aroute(
    source: LocalSource | SourceBundle,
    svis: SurveySVIS,
    *,
    source_binding: RoutingSourceBinding,
) -> ExtractionResult[RoutedSurveySVIS]

Build a routed SVIS with native bypass or provider-backed enrichment.

config

Stable routing configuration import path.

RoutingConfig

Bases: BaseModel

Provider-neutral routing limits and thresholds.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

max_source_quote_chars class-attribute instance-attribute

max_source_quote_chars: int = Field(
    default=2000, ge=1, le=2000, strict=True
)

max_request_tokens class-attribute instance-attribute

max_request_tokens: int = Field(
    default=32000, ge=1, le=32000, strict=True
)

max_inventory_items_per_call class-attribute instance-attribute

max_inventory_items_per_call: int = Field(
    default=250, ge=1, le=250, strict=True
)

max_candidate_targets_per_reference class-attribute instance-attribute

max_candidate_targets_per_reference: int = Field(
    default=10, ge=1, le=10, strict=True
)

max_discrepancies_per_review_call class-attribute instance-attribute

max_discrepancies_per_review_call: int = Field(
    default=25, ge=1, le=25, strict=True
)

max_source_spans_per_decision class-attribute instance-attribute

max_source_spans_per_decision: int = Field(
    default=8, ge=1, le=8, strict=True
)

max_condition_depth class-attribute instance-attribute

max_condition_depth: int = Field(
    default=6, ge=1, le=6, strict=True
)

max_condition_nodes class-attribute instance-attribute

max_condition_nodes: int = Field(
    default=100, ge=1, le=100, strict=True
)

low_confidence_threshold class-attribute instance-attribute

low_confidence_threshold: float = Field(
    default=0.7,
    ge=0.0,
    le=1.0,
    strict=True,
    allow_inf_nan=False,
)

unusual_in_degree_threshold class-attribute instance-attribute

unusual_in_degree_threshold: int = Field(
    default=4, ge=1, strict=True
)

unusual_out_degree_threshold class-attribute instance-attribute

unusual_out_degree_threshold: int = Field(
    default=3, ge=1, strict=True
)

max_concurrency class-attribute instance-attribute

max_concurrency: int = Field(
    default=4, ge=1, le=128, strict=True
)

generation class-attribute instance-attribute

generation: GenerationConfig = Field(
    default_factory=GenerationConfig
)

retry class-attribute instance-attribute

retry: RetryConfig = Field(default_factory=RetryConfig)