Skip to main content

Extraction API

The client.extract namespace exposes the document and tool-result extraction pipeline that turns raw inputs into structured CKF facts.

SDK proxy

crp.sdk.proxies._ExtractionProxy

Graduated extraction pipeline proxy (§2.5).

Runs extraction over text and returns facts or the full fact graph.

run(text, content_type=None, **kwargs)

Run the extraction pipeline on text.

Parameters:

Name	Type	Description	Default
text	str	Input text to extract facts from.	required
content_type	str | None	Optional MIME-like content hint.	None
**kwargs	Any	Additional options forwarded to extract.	{}

Returns:

Type	Description
Any	ExtractionResult / PipelineExtractionResult from the pipeline.

facts(text, **kwargs)

Return extracted facts from text as plain dicts.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required
**kwargs	Any	Options forwarded to :meth:run.	{}

Returns:

Type	Description
list[dict[str, Any]]	List of fact dicts.

graph(text, **kwargs)

Return the extracted fact graph from text.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required
**kwargs	Any	Options forwarded to :meth:run.	{}

Returns:

Type	Description
dict[str, Any]	Dict with nodes and edges lists.

Extraction Pipeline

crp.extraction.pipeline.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.

Fact

crp.extraction.types.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.