Skip to main content

crp.extraction

Auto-generated reference for the crp.extraction subpackage.

extraction

crp.extraction

6-stage graduated extraction pipeline - regex → statistical → GLiNER → UIE → discourse → LLM.

ExtractionPipeline

Blackboard-reactive 6-stage extraction pipeline.

Usage::

pipeline = ExtractionPipeline()
result = pipeline.extract(text, task_intent)

Stages 1-2 always run. Stages 3-6 run conditionally based on content complexity, yield thresholds, and availability.

calibration property

Current self-calibration state.

set_dispatch_fn(fn)

Set the dispatch function for Stage 6 (LLM-assisted extraction).

Parameters:

Name	Type	Description	Default
fn	DispatchFn	Dispatch function conforming to DispatchFn.	required

register_regex_pattern(name, pattern, category, confidence=0.9)

Register a custom regex pattern in Stage 1.

Parameters:

Name	Type	Description	Default
name	str	Pattern identifier.	required
pattern	str	Regex string.	required
category	str	Fact category to assign.	required
confidence	float	Confidence for matched facts.	0.9

extract(text, task_intent=None, source_window_id='')

Run the graduated extraction pipeline.

Stages 1-2 always run. Stages 3-6 run conditionally based on content complexity, yield thresholds, and availability.

Parameters:

Name	Type	Description	Default
text	str	Source text to extract facts from.	required
task_intent	TaskIntent | None	Optional task intent for context-aware extraction.	None
source_window_id	str	Window ID to stamp on extracted facts.	''

Returns:

Type	Description
ExtractionResult	An ExtractionResult with facts, edges, and pipeline metadata.

StructuredOutputHandler

Orchestrates structured-output enforcement.

Priority order: 1. Outlines FSM (if available and provider supports it) 2. GBNF grammar (if provider is llama.cpp compatible) 3. Logit masking (if provider supports token-level constraints) 4. Fallback: post-hoc JSON repair + validation

outlines_available property

Return the outlines available.

enforce(raw_output, schema=None)

Attempt to parse and validate raw_output against schema.

Returns (parsed_data, errors) where errors is empty on success.

build_gbnf(schema)

Build a GBNF grammar string for llama.cpp providers.

build_outlines_guide(schema)

Build an Outlines FSM guide (returns None if unavailable).

ContentType

Bases: str, Enum

Content complexity classification used to route extraction stages.

ENTITY_RICH = 'ENTITY_RICH' class-attribute instance-attribute

Text rich in named entities; favours regex/GLiNER stages.

REASONING_DENSE = 'REASONING_DENSE' class-attribute instance-attribute

Text with arguments, causality, and discourse structure.

NARRATIVE = 'NARRATIVE' class-attribute instance-attribute

General prose; default routing.

Contradiction dataclass

A detected contradiction between two facts.

Attributes:

Name	Type	Description
fact_a	Fact | None	First fact.
fact_b	Fact | None	Second fact.
similarity	float	Semantic similarity between the facts.
content_diff	float	Normalised content difference score.
confidence	float	Confidence that the pair is contradictory.

ExtractionResult dataclass

Complete extraction result from the graduated pipeline.

Attributes:

Name	Type	Description
extraction_id	str	Unique extraction run identifier.
source_window_id	str	Window that produced this extraction.
timestamp	float	Unix timestamp of extraction completion.
facts	list[Fact]	Extracted facts.
edges	list[FactEdge]	Extracted relations.
fact_graph	FactGraph	Built graph from facts and edges.
stages_run	list[int]	Pipeline stages that executed.
stages_skipped	list[int]	Pipeline stages that were skipped.
total_extraction_latency_ms	float	Total extraction time.
per_stage_latency	dict[int, float]	Latency per stage.
total_facts	int	Total number of facts.
total_edges	int	Total number of edges.
average_confidence	float	Mean fact confidence.
entity_density	float	Entities per word.
relation_density	float	Edges per fact.
content_type	ContentType	Detected content complexity.
discourse_markers_found	int	Number of discourse markers found.
stage_yields	dict[int, int]	Fact counts per stage.
escalation_triggers	list[str]	Reasons stages were escalated.
quality_gate_passed	bool	Whether the quality gate passed.
quality_issues	list[str]	Quality gate issue messages.
facts_after_normalization	int	Fact count after normalization.

success property

Return True if the quality gate passed.

finalize()

Compute aggregate metrics and build the fact graph.

Fact dataclass

Single extracted fact produced by the extraction pipeline.

Lightweight record - embeddings are typically computed lazily in the state layer when facts are added to the warm store or CKF.

Attributes:

Name	Type	Description
id	str	Unique fact identifier.
text	str	Normalised fact text.
category	str	Semantic category (e.g. "entity", "noun_phrase", "relation").
source_window_id	str	Window that produced this fact.
confidence	float	Extraction confidence in [0, 1].
extraction_stage	int	Pipeline stage that produced this fact (1-6).
created_at	float	Unix timestamp of extraction.
metadata	dict[str, Any]	Arbitrary structured metadata.
source	ContextSource | None	Context-source provenance (CRP 2.1+, §7.14.3).
flagged_confidence	bool	True if confidence failed quality gate.
confidence_flag_reason	str	Reason for confidence flag.
superseded_by	str | None	ID of the fact that superseded this one.
supersession_confidence	float	Confidence of the supersession decision.

validate_metadata()

Enforce metadata size limits (§audit M4).

Raises:

Type	Description
ValueError	If metadata exceeds configured key/value/count bounds.

set_metadata(key, value)

Set a metadata key with size validation.

Parameters:

Name	Type	Description	Default
key	str	Metadata key.	required
value	Any	Metadata value.	required

Raises:

Type	Description
ValueError	If the key or value exceeds configured size limits.

FactEdge dataclass

Directed relation between two facts or text spans.

Attributes:

Name	Type	Description
id	str	Unique edge identifier.
source_id	str	ID of the source fact.
target_id	str	ID of the target fact.
relation_type	RelationType | str	Semantic relation type.
confidence	float	Relation confidence in [0, 1].
source_stage	int	Pipeline stage that produced this edge.
metadata	dict[str, Any]	Arbitrary structured metadata.

FactEvent dataclass

Immutable audit-log entry for fact lifecycle events.

Attributes:

Name	Type	Description
event_id	int	Monotonic event identifier.
timestamp	float	Unix timestamp of the event.
window_id	str	Window that triggered the event.
event_type	str	One of "created", "superseded", "compacted", "archived", or "restored".
fact_id	str	Affected fact ID.
payload	dict[str, Any]	Additional structured context.

FactGraph dataclass

In-memory graph of facts and edges.

Maintains adjacency indices for O(1) edge lookup (§audit L4).

Attributes:

Name	Type	Description
nodes	dict[str, Fact]	Mapping from fact ID to Fact.
edges	list[FactEdge]	List of all edges in the graph.
_edges_from	dict[str, list[FactEdge]]	Index of outgoing edges by source fact ID.
_edges_to	dict[str, list[FactEdge]]	Index of incoming edges by target fact ID.

add_fact(fact)

Add or update a fact node.

remove_fact(fact_id)

Remove a fact and all its edges from the graph (§audit2 STATE-H5).

Parameters:

Name	Type	Description	Default
fact_id	str	ID of the fact to remove.	required

add_edge(edge)

Add an edge if both endpoint facts exist.

Skips edges referencing non-existent facts (§audit G7) and maintains the O(1) adjacency indices.

Parameters:

Name	Type	Description	Default
edge	FactEdge	Edge to add.	required

edges_from(fact_id)

Return outgoing edges from fact_id.

edges_to(fact_id)

Return incoming edges to fact_id.

subgraph_for(fact_ids, max_hops=1)

Return subgraph containing fact_ids plus neighbours within max_hops.

Parameters:

Name	Type	Description	Default
fact_ids	set[str]	Seed fact IDs.	required
max_hops	int	Number of graph hops to include around seeds.	1

Returns:

Type	Description
FactGraph	A new FactGraph containing the induced subgraph.

serialize_for_envelope()

Plain-text serialisation for envelope packing.

Returns:

Type	Description
str	Bulleted list of facts and their outgoing relations.

RelationType

Bases: str, Enum

Semantic relation types stored on FactEdge records.

ValidationIssue dataclass

Single issue found by the quality gate.

Attributes:

Name	Type	Description
type	str	Issue classification.
severity	ValidationSeverity	Issue severity.
detail	str	Human-readable description.

ValidationResult dataclass

Result from one quality-gate tier.

Attributes:

Name	Type	Description
tier	int	Quality-gate tier number.
passed	bool	True if the tier passed.
issues	list[ValidationIssue]	Issues found at this tier.

ValidationSeverity

Bases: str, Enum

Severity levels for quality-gate issues.

detect_content_complexity(text)

Classify text complexity for pipeline routing.

Thresholds per spec

ENTITY_RICH: entity_density > 0.05 REASONING_DENSE: discourse_ratio > 0.30 OR subordinate_clause_ratio > 0.40 NARRATIVE: everything else

apply_supersessions(contradictions)

Mark fact_a as superseded by fact_b for each contradiction.

Returns a list of FactEvent records for the audit log.

detect_contradictions(new_facts, existing_facts, similarity_threshold=0.85, content_diff_threshold=0.3)

Detect contradictions between new and existing facts.

A contradiction occurs when two facts are semantically very similar (sim > similarity_threshold) but textually different enough (edit distance > content_diff_threshold) to suggest conflicting info.

run_quality_gate(result, *, output_schema=None, confidence_floor=0.6, history=None)

Run all 3 quality-gate tiers and update the ExtractionResult in-place.

extraction.complexity

crp.extraction.complexity

Content complexity detection - classifies text as ENTITY_RICH, REASONING_DENSE, or NARRATIVE.

Applied to every window output to determine pipeline routing.

detect_content_complexity(text)

Classify text complexity for pipeline routing.

Thresholds per spec

ENTITY_RICH: entity_density > 0.05 REASONING_DENSE: discourse_ratio > 0.30 OR subordinate_clause_ratio > 0.40 NARRATIVE: everything else

extraction.contradiction

crp.extraction.contradiction

Contradiction detection - identifies and handles superseded facts (§3.4).

Detection rule: cosine similarity > 0.85 AND normalised edit distance > 0.3. Action: mark earlier fact as superseded, 0.5× score multiplier in envelope.

detect_contradictions(new_facts, existing_facts, similarity_threshold=0.85, content_diff_threshold=0.3)

Detect contradictions between new and existing facts.

A contradiction occurs when two facts are semantically very similar (sim > similarity_threshold) but textually different enough (edit distance > content_diff_threshold) to suggest conflicting info.

apply_supersessions(contradictions)

Mark fact_a as superseded by fact_b for each contradiction.

Returns a list of FactEvent records for the audit log.

extraction.pipeline

crp.extraction.pipeline

Extraction pipeline orchestration - blackboard-reactive 6-stage pipeline.

Implements the graduated extraction decision tree, self-calibrating baselines, and stage escalation logic per §3.2 and SPEC-024/SPEC-025.

CalibrationState dataclass

Tracks self-calibrating baselines for stage escalation.

Baselines are initially locked after _CALIBRATION_WINDOW_COUNT windows. After that, the system periodically recalibrates every _RECALIBRATION_INTERVAL windows using a rolling window of the most recent results. This prevents stale baselines when extraction profiles change (e.g. when new content domains appear or stages come online).

results_count property

Number of results recorded for calibration.

record(result)

Record an extraction result. Calibrates/recalibrates as needed.

should_escalate_stage_3(stage_1_2_yield)

Return True if stages 1-2 yielded fewer facts than baseline.

should_escalate_stage_4(stage_3_relation_yield)

Return True if Stage 3 relation yield per sentence is below 0.1.

ExtractionPipeline

Blackboard-reactive 6-stage extraction pipeline.

Usage::

pipeline = ExtractionPipeline()
result = pipeline.extract(text, task_intent)

Stages 1-2 always run. Stages 3-6 run conditionally based on content complexity, yield thresholds, and availability.

calibration property

Current self-calibration state.

set_dispatch_fn(fn)

Set the dispatch function for Stage 6 (LLM-assisted extraction).

Parameters:

Name	Type	Description	Default
fn	DispatchFn	Dispatch function conforming to DispatchFn.	required

register_regex_pattern(name, pattern, category, confidence=0.9)

Register a custom regex pattern in Stage 1.

Parameters:

Name	Type	Description	Default
name	str	Pattern identifier.	required
pattern	str	Regex string.	required
category	str	Fact category to assign.	required
confidence	float	Confidence for matched facts.	0.9

extract(text, task_intent=None, source_window_id='')

Run the graduated extraction pipeline.

Stages 1-2 always run. Stages 3-6 run conditionally based on content complexity, yield thresholds, and availability.

Parameters:

Name	Type	Description	Default
text	str	Source text to extract facts from.	required
task_intent	TaskIntent | None	Optional task intent for context-aware extraction.	None
source_window_id	str	Window ID to stamp on extracted facts.	''

Returns:

Type	Description
ExtractionResult	An ExtractionResult with facts, edges, and pipeline metadata.

extraction.quality_gate

crp.extraction.quality_gate

Post-extraction quality gate - 3-tier validation (§3.2 2H).

Tier 1: Structural validation (schema, parse success, empty facts). Tier 2: Confidence threshold filter (flag low-confidence facts). Tier 3: Anomaly detection (fact explosion, zero facts, duplicates).

structural_validation(result, output_schema=None)

Check schema compliance, parse success rate, and empty facts.

confidence_threshold_filter(result, floor=0.6)

Mark facts below the confidence floor as flagged.

Low-confidence facts are NOT excluded - they remain but get a 0.5× score multiplier in envelope packing.

anomaly_detection(result, history=None)

Check for fact-count explosion, zero facts, and duplicates.

normalize_facts(facts, max_tokens=100, min_tokens=5)

Split overly long facts and merge very short ones.

Uses word count as a proxy for token count (accurate tokenisation is Phase 4).

run_quality_gate(result, *, output_schema=None, confidence_floor=0.6, history=None)

Run all 3 quality-gate tiers and update the ExtractionResult in-place.

extraction.stage1_regex

crp.extraction.stage1_regex

Stage 1 - Regex extraction (~1ms, MUST).

Extracts structured entities: IPs, CVEs, URLs, emails, JSON blocks, error codes, versions, ports, and cryptographic hashes.

RegexPattern dataclass

A single extraction pattern.

RegexExtractor

Stage 1 - fast regex extraction with extensible pattern registry.

pattern_count property

Return the current pattern count.

register_pattern(name, pattern, category, confidence=0.9)

Add a user-defined extraction pattern.

extract(text, source_window_id='')

Extract all regex-matched facts from text.

Returns de-duplicated facts ordered by position in text.

extraction.stage2_statistical

crp.extraction.stage2_statistical

Stage 2 - Statistical NLP extraction (~5ms, MUST).

Pure-Python: TextRank key-sentence extraction, noun-phrase heuristics, section-header detection, list-item extraction, and numerical-value extraction. No ML model dependencies.

StatisticalExtractor

Stage 2 - statistical NLP extraction (no ML models).

extract(text, source_window_id='')

Extract key sentences, noun phrases, headers, list items, numbers.

textrank_sentences(sentences, top_k=5, damping=0.85, iterations=30, convergence=0.0001)

Return indices + scores of top-K sentences via TextRank.

Steps: 1. Build sentence similarity graph. 2. Run PageRank-style iteration. 3. Return top-K by score (original order preserved).

extraction.stage3_gliner

crp.extraction.stage3_gliner

Stage 3 - GLiNER zero-shot NER extraction (SHOULD, ~50ms, lazy model load).

Trigger: Stage 2 yield < self-calibrated baseline. Model: GLiNER (~200MB), loaded lazily, unloaded after 20 idle windows. Graceful fallback: if model unavailable, returns empty and logs warning.

GLiNERModel

Bases: Protocol

Minimal interface a GLiNER-compatible model must satisfy.

predict_entities(text, labels, threshold=0.5)

Return list of dicts with keys: text, label, score, start, end.

GLiNERExtractor

Stage 3 - zero-shot NER via GLiNER (lazy, optional).

The model is loaded on first call and unloaded after idle_limit windows without a call. If gliner is not installed, all calls return [].

is_available property

Return whether this object is available.

unload()

Release model from memory.

tick_idle()

Called once per window. Unloads model after idle_limit.

extract(text, labels=None, source_window_id='', threshold=0.5)

Run zero-shot NER over text using labels.

If no labels provided, uses a small set of generic security/tech labels. Returns [] if model is unavailable - never raises.

derive_labels_from_noun_phrases(noun_phrases, max_labels=15)

Convert Stage 2 noun phrases into zero-shot NER labels.

Strips determiners and lowercases. De-duplicates and caps at max_labels.

extraction.stage4_uie

crp.extraction.stage4_uie

Stage 4 - UIE relational extraction (SHOULD, ~100ms, lazy model load).

Extracts (subject, predicate, object) triples and converts them to FactEdge records. Trigger: Stage 3 relation yield < 0.1 per sentence. Model: UIE / universal IE (~400MB), loaded lazily. Graceful fallback: returns empty if unavailable.

UIEModel

Bases: Protocol

Minimal interface for a Universal Information Extraction model.

extract_triples(text)

Return list of dicts with keys: subject, predicate, object, confidence.

UIEExtractor

Stage 4 - UIE triple extraction (lazy, optional).

Loads the model on first use. Returns (facts, edges) where facts are the subject/object entities and edges are the relations. If the UIE library is unavailable, all calls return ([], []).

is_available property

Return whether this object is available.

unload()

Release the loaded UIE model from memory.

extract(text, source_window_id='')

Extract relational triples from text.

Returns (facts, edges) - each triple yields two Fact items (subject, object) and one FactEdge. Returns ([], []) on failure or if model unavailable.

extraction.stage5_discourse

crp.extraction.stage5_discourse

Stage 5 - Discourse structure extraction (SHOULD, ~150ms, CPU-only).

Detects discourse markers and maps them to semantic relation types (RST-inspired). Trigger: content_type in {REASONING_DENSE, NARRATIVE}. No ML model - pure pattern matching over sentences.

DiscourseExtractor

Stage 5 - discourse-structure extraction (CPU-only).

extract(text, source_window_id='')

Detect discourse markers and create FactEdge relations.

Returns (marker_facts, edges) where marker_facts are the clauses surrounding each detected marker, and edges link them.

count_discourse_markers(text)

Count total discourse-marker occurrences in text (fast).

extraction.stage6_llm

crp.extraction.stage6_llm

Stage 6 - LLM-assisted relational extraction (MAY, expensive).

Dispatches a dedicated extraction window to a small LLM to extract logical relationships from reasoning-dense content. Trigger: content_type == REASONING_DENSE AND Stage 5 edge_yield < 0.1 edges/sentence.

This stage is user-configurable (can be disabled via config flag).

LLMExtractor

Stage 6 - LLM-assisted extraction (optional, expensive).

Requires a dispatch_fn to be injected by the pipeline. If not set, extract() returns empty.

is_available property

Return whether this object is available.

set_dispatch(fn)

Inject the dispatch function used to call the LLM.

Parameters:

Name	Type	Description	Default
fn	DispatchFn	Callable with signature (system_prompt, task_input, max_output_tokens) -> str.	required

extract(text, source_window_id='', max_input_chars=8000, max_output_tokens=1024)

Dispatch extraction window and parse results.

Returns (facts, edges) or ([], []) if dispatch unavailable.

extraction.structured_output

crp.extraction.structured_output

Structured output handling - schema/grammar enforcement (§06 §6.9, 2J).

Supports: Outlines FSM, GBNF grammar, logit masking, fallback JSON repair. All integrations are optional - graceful fallback if libraries unavailable.

OutlinesFSMHandler

Outlines-based constrained generation via finite state machine.

is_available property

Return whether this object is available.

build_guide(schema)

Build an Outlines JSON guide from a JSON Schema.

StructuredOutputHandler

Orchestrates structured-output enforcement.

Priority order: 1. Outlines FSM (if available and provider supports it) 2. GBNF grammar (if provider is llama.cpp compatible) 3. Logit masking (if provider supports token-level constraints) 4. Fallback: post-hoc JSON repair + validation

outlines_available property

Return the outlines available.

enforce(raw_output, schema=None)

Attempt to parse and validate raw_output against schema.

Returns (parsed_data, errors) where errors is empty on success.

build_gbnf(schema)

Build a GBNF grammar string for llama.cpp providers.

build_outlines_guide(schema)

Build an Outlines FSM guide (returns None if unavailable).

repair_json(raw)

Best-effort repair of malformed JSON.

Handles: trailing commas, unquoted keys, single quotes, truncated output. Returns the repaired JSON string, or None if unrecoverable.

validate_json_schema(data, schema)

Validate data against JSON Schema. Returns list of error messages.

json_schema_to_gbnf(schema)

Convert a simple JSON Schema to GBNF grammar string.

Handles flat object schemas with string/number/boolean/array properties. Complex nested schemas require the full llama.cpp grammar converter.

extraction.types

crp.extraction.types

Extraction pipeline data types - Fact, FactEdge, FactGraph, ExtractionResult.

These dataclasses form the shared data model produced by the 6-stage graduated extraction pipeline and consumed by the warm store, CKF, and envelope builder.

ContentType

Bases: str, Enum

Content complexity classification used to route extraction stages.

ENTITY_RICH = 'ENTITY_RICH' class-attribute instance-attribute

Text rich in named entities; favours regex/GLiNER stages.

REASONING_DENSE = 'REASONING_DENSE' class-attribute instance-attribute

Text with arguments, causality, and discourse structure.

NARRATIVE = 'NARRATIVE' class-attribute instance-attribute

General prose; default routing.

RelationType

Bases: str, Enum

Semantic relation types stored on FactEdge records.

Fact dataclass

Single extracted fact produced by the extraction pipeline.

Lightweight record - embeddings are typically computed lazily in the state layer when facts are added to the warm store or CKF.

Attributes:

Name	Type	Description
id	str	Unique fact identifier.
text	str	Normalised fact text.
category	str	Semantic category (e.g. "entity", "noun_phrase", "relation").
source_window_id	str	Window that produced this fact.
confidence	float	Extraction confidence in [0, 1].
extraction_stage	int	Pipeline stage that produced this fact (1-6).
created_at	float	Unix timestamp of extraction.
metadata	dict[str, Any]	Arbitrary structured metadata.
source	ContextSource | None	Context-source provenance (CRP 2.1+, §7.14.3).
flagged_confidence	bool	True if confidence failed quality gate.
confidence_flag_reason	str	Reason for confidence flag.
superseded_by	str | None	ID of the fact that superseded this one.
supersession_confidence	float	Confidence of the supersession decision.

validate_metadata()

Enforce metadata size limits (§audit M4).

Raises:

Type	Description
ValueError	If metadata exceeds configured key/value/count bounds.

set_metadata(key, value)

Set a metadata key with size validation.

Parameters:

Name	Type	Description	Default
key	str	Metadata key.	required
value	Any	Metadata value.	required

Raises:

Type	Description
ValueError	If the key or value exceeds configured size limits.

FactEdge dataclass

Directed relation between two facts or text spans.

Attributes:

Name	Type	Description
id	str	Unique edge identifier.
source_id	str	ID of the source fact.
target_id	str	ID of the target fact.
relation_type	RelationType | str	Semantic relation type.
confidence	float	Relation confidence in [0, 1].
source_stage	int	Pipeline stage that produced this edge.
metadata	dict[str, Any]	Arbitrary structured metadata.

FactGraph dataclass

In-memory graph of facts and edges.

Maintains adjacency indices for O(1) edge lookup (§audit L4).

Attributes:

Name	Type	Description
nodes	dict[str, Fact]	Mapping from fact ID to Fact.
edges	list[FactEdge]	List of all edges in the graph.
_edges_from	dict[str, list[FactEdge]]	Index of outgoing edges by source fact ID.
_edges_to	dict[str, list[FactEdge]]	Index of incoming edges by target fact ID.

add_fact(fact)

Add or update a fact node.

remove_fact(fact_id)

Remove a fact and all its edges from the graph (§audit2 STATE-H5).

Parameters:

Name	Type	Description	Default
fact_id	str	ID of the fact to remove.	required

add_edge(edge)

Add an edge if both endpoint facts exist.

Skips edges referencing non-existent facts (§audit G7) and maintains the O(1) adjacency indices.

Parameters:

Name	Type	Description	Default
edge	FactEdge	Edge to add.	required

edges_from(fact_id)

Return outgoing edges from fact_id.

edges_to(fact_id)

Return incoming edges to fact_id.

subgraph_for(fact_ids, max_hops=1)

Return subgraph containing fact_ids plus neighbours within max_hops.

Parameters:

Name	Type	Description	Default
fact_ids	set[str]	Seed fact IDs.	required
max_hops	int	Number of graph hops to include around seeds.	1

Returns:

Type	Description
FactGraph	A new FactGraph containing the induced subgraph.

serialize_for_envelope()

Plain-text serialisation for envelope packing.

Returns:

Type	Description
str	Bulleted list of facts and their outgoing relations.

ValidationSeverity

Bases: str, Enum

Severity levels for quality-gate issues.

ValidationIssue dataclass

Single issue found by the quality gate.

Attributes:

Name	Type	Description
type	str	Issue classification.
severity	ValidationSeverity	Issue severity.
detail	str	Human-readable description.

ValidationResult dataclass

Result from one quality-gate tier.

Attributes:

Name	Type	Description
tier	int	Quality-gate tier number.
passed	bool	True if the tier passed.
issues	list[ValidationIssue]	Issues found at this tier.

Contradiction dataclass

A detected contradiction between two facts.

Attributes:

Name	Type	Description
fact_a	Fact | None	First fact.
fact_b	Fact | None	Second fact.
similarity	float	Semantic similarity between the facts.
content_diff	float	Normalised content difference score.
confidence	float	Confidence that the pair is contradictory.

FactEvent dataclass

Immutable audit-log entry for fact lifecycle events.

Attributes:

Name	Type	Description
event_id	int	Monotonic event identifier.
timestamp	float	Unix timestamp of the event.
window_id	str	Window that triggered the event.
event_type	str	One of "created", "superseded", "compacted", "archived", or "restored".
fact_id	str	Affected fact ID.
payload	dict[str, Any]	Additional structured context.

ExtractionResult dataclass

Complete extraction result from the graduated pipeline.

Attributes:

Name	Type	Description
extraction_id	str	Unique extraction run identifier.
source_window_id	str	Window that produced this extraction.
timestamp	float	Unix timestamp of extraction completion.
facts	list[Fact]	Extracted facts.
edges	list[FactEdge]	Extracted relations.
fact_graph	FactGraph	Built graph from facts and edges.
stages_run	list[int]	Pipeline stages that executed.
stages_skipped	list[int]	Pipeline stages that were skipped.
total_extraction_latency_ms	float	Total extraction time.
per_stage_latency	dict[int, float]	Latency per stage.
total_facts	int	Total number of facts.
total_edges	int	Total number of edges.
average_confidence	float	Mean fact confidence.
entity_density	float	Entities per word.
relation_density	float	Edges per fact.
content_type	ContentType	Detected content complexity.
discourse_markers_found	int	Number of discourse markers found.
stage_yields	dict[int, int]	Fact counts per stage.
escalation_triggers	list[str]	Reasons stages were escalated.
quality_gate_passed	bool	Whether the quality gate passed.
quality_issues	list[str]	Quality gate issue messages.
facts_after_normalization	int	Fact count after normalization.

success property

Return True if the quality gate passed.

finalize()

Compute aggregate metrics and build the fact graph.