crp.ckf¶
Auto-generated reference for the crp.ckf subpackage.
ckf¶
crp.ckf ¶
Contextual Knowledge Fabric - 4-mode retrieval, community detection, pub/sub.
Community dataclass ¶
A cluster of semantically related facts.
size property ¶
Return the current size count.
CommunityDetector ¶
Manages community detection with incremental updates.
Tracks the previous community state and decides whether to run a full rebuild or incremental update based on the change ratio.
CommunityResult dataclass ¶
Result from community detection.
CKFConfig dataclass ¶
Configuration for the Contextual Knowledge Fabric.
Attributes:
| Name | Type | Description |
|---|---|---|
max_facts | int | Maximum facts retained in the warm store. |
hnsw_threshold | int | Minimum facts before building an HNSW index. |
persist_path | str | Optional path for cold-state persistence. |
gc_budget_bytes | int | Memory budget for garbage collection. |
gc_trigger_ratio | float | Ratio of budget that triggers GC. |
gc_target_ratio | float | Ratio of budget GC aims to reclaim to. |
community_detect_enabled | bool | Whether community detection runs. |
CKFHealth dataclass ¶
Health snapshot for monitoring.
Attributes:
| Name | Type | Description |
|---|---|---|
fact_count | int | Number of facts in the warm store. |
edge_count | int | Number of edges in the graph. |
community_count | int | Number of detected communities. |
event_count | int | Number of events in the event log. |
tombstoned_count | int | Facts marked for removal by GC. |
estimated_bytes | int | Estimated memory footprint. |
hnsw_active | bool | Whether an HNSW index is currently built. |
leiden_available | bool | Whether the leidenalg library is installed. |
ContextualKnowledgeFabric ¶
Unified interface for fact storage and 4-mode retrieval (§3.8).
Methods (per spec 4F.1a): - store(facts) / retrieve(query, modes, budget) - query(pattern) / persist(path) / restore(path) - fact_count() / health() - temporal_query(window_range) - graph_walk(seeds, hops) / community_summary(topic) - subscribe(event, callback)
store(facts, window_id='') ¶
Ingest facts into the warm store and emit events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
facts | list[Fact] | Facts to store. | required |
window_id | str | Optional source window ID to stamp on facts. | '' |
store_edges(edges) ¶
Add edges to the fact graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
edges | list[FactEdge] | Edges to add. | required |
retrieve(query_embedding=None, seed_ids=None, entity_type=None, relationship_type=None, topic=None, modes=None, budget=200) ¶
Retrieve facts using up to 4 modes, merged and ranked.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query_embedding | list[float] | None | Query embedding for semantic mode. | None |
seed_ids | set[str] | None | Seed fact IDs for graph-walk mode. | None |
entity_type | str | None | Entity type filter for pattern mode. | None |
relationship_type | str | RelationType | None | Relation type filter for pattern mode. | None |
topic | str | None | Topic string for community mode. | None |
modes | list[str] | None | Subset of ["graph_walk", "pattern", "semantic", "community"]. Defaults to all applicable modes. | None |
budget | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
MergeResult | A merged and ranked |
query(entity_type=None, relationship_type=None, min_confidence=0.0, max_results=200) ¶
Convenience: pattern query on the fact graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entity_type | str | None | Entity type filter. | None |
relationship_type | str | RelationType | None | Relation type filter. | None |
min_confidence | float | Minimum fact confidence. | 0.0 |
max_results | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
PatternQueryResult | A |
graph_walk(seed_ids, max_hops=2, max_results=200) ¶
BFS traversal from seed facts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seed_ids | set[str] | Seed fact IDs. | required |
max_hops | int | Maximum graph hops. | 2 |
max_results | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
GraphWalkResult | A |
community_summary(topic) ¶
Return communities matching topic.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | Topic string to match against community summaries. | required |
Returns:
| Type | Description |
|---|---|
list[Community] | Matching communities. |
detect_communities() ¶
Force a community detection run.
Returns:
| Type | Description |
|---|---|
CommunityResult | The community detection result. |
temporal_query(start_window, end_window) ¶
Return fact IDs active between two windows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_window | str | Start window identifier. | required |
end_window | str | End window identifier. | required |
Returns:
| Type | Description |
|---|---|
list[str] | List of fact IDs created between the two windows. |
persist(path) ¶
Persist full state to cold storage, including community IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | Destination file path. | required |
restore(path) ¶
Restore state from cold storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | Source file path. | required |
Returns:
| Type | Description |
|---|---|
list[str] | List of restore warnings. |
subscribe(event_type, callback) ¶
Register a callback for CKF events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type | CKFEventType | Event type to subscribe to. | required |
callback | EventCallback | Function called when the event fires. | required |
fact_count() ¶
Return the number of facts in the warm store.
health() ¶
Return a health snapshot.
run_gc(current_window=0) ¶
Run cross-session garbage collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
current_window | int | Current window number for recency-aware GC. | 0 |
Returns:
| Type | Description |
|---|---|
GCResult | The GC result. |
should_gc() ¶
Check if GC should be triggered based on memory budget.
GarbageCollector ¶
Cross-session GC for the CKF fact store.
Lifecycle: active → tombstoned → purged. Tombstoned facts are excluded from retrieval but retained for TOMBSTONE_AGE_WINDOWS before final purge.
should_gc(estimated_bytes) ¶
Return True if GC should run (estimated usage ≥ trigger).
run(facts, estimated_bytes, current_window=0) ¶
Execute a GC pass.
- Purge old tombstones (aged out).
- If still over target, tombstone lowest-scoring active facts.
is_tombstoned(fact_id) ¶
Return True if fact_id is currently tombstoned.
tombstone_count() ¶
Return the number of currently tombstoned facts.
estimate_store_bytes(facts) staticmethod ¶
Estimate total bytes for the fact store.
GCResult dataclass ¶
Result of a GC pass.
GraphWalkResult dataclass ¶
Result of a graph walk query.
MergedFact dataclass ¶
A fact with a merged score from multiple retrieval modes.
MergeResult dataclass ¶
Result of multi-mode merge.
PatternQueryResult dataclass ¶
Result of a pattern query.
CKFEvent dataclass ¶
Payload for a CKF event.
CKFEventType ¶
Bases: str, Enum
Events emitted by the CKF subsystem.
PubSubEventBus ¶
Thread-safe pub/sub for CKF lifecycle events.
Usage::
bus = PubSubEventBus()
bus.subscribe(CKFEventType.FACT_CREATED, my_handler)
bus.publish(CKFEvent(CKFEventType.FACT_CREATED, {"fact_id": "abc"}))
subscribe(event_type, callback) ¶
Register callback for events of event_type.
subscribe_all(callback) ¶
Register callback for all event types.
unsubscribe(event_type, callback) ¶
Remove callback from event_type subscribers.
publish(event) ¶
Dispatch event to all subscribers. Fire-and-forget - errors logged.
subscriber_count(event_type=None) ¶
Return number of subscribers, optionally filtered by event type.
clear() ¶
Remove all subscribers.
SemanticResult dataclass ¶
Result of a semantic similarity query.
CKFEdge dataclass ¶
Bidirectional similarity edge between two CKF fact nodes (SPEC-009 §5.2).
Stored once per pair (source < target lexicographically) but accessible from either end via GraphEdgeStore.
EdgeType ¶
Edge type constants used in the CKF graph.
GraphEdgeStore ¶
Adjacency index for fast neighbour lookup.
Stores edges in both directions so neighbours(fact_id) is O(degree) regardless of which end of the edge was requested.
add_edge(edge) ¶
Add (or update) an edge in the adjacency index.
remove_fact(fact_id) ¶
Remove all edges involving fact_id (called on tombstone/GC).
neighbours(fact_id) ¶
Return {neighbour_id: similarity} for all edges from fact_id.
has_edge(a, b) ¶
True if an edge exists between a and b.
edge(a, b) ¶
Return the edge between a and b, or None.
edge_count() ¶
Return the number of unique edges in the store.
node_count() ¶
Return the number of distinct nodes with at least one edge.
path_length(start, end, max_hops=4) ¶
BFS shortest path length, capped at max_hops.
Returns max_hops + 1 if no path found within the hop limit.
CDGRResult dataclass ¶
Full output of cdgr_expand().
Attributes:
| Name | Type | Description |
|---|---|---|
anchors | list[Any] | CDR-ranked anchor facts. |
connectors | list[CDGRConnector] | Bridge-value-ranked connector records. |
assembled | list[Any] | Anchors + connectors merged for packing. |
anchor_count | int | Number of anchor facts. |
connector_count | int | Number of connector facts selected. |
candidates_explored | int | Number of BFS candidates examined. |
CDGRConnector dataclass ¶
A connector fact selected by CDGR bridge scoring.
Attributes:
| Name | Type | Description |
|---|---|---|
fact_id | str | Connector fact identifier. |
fact | Any | The actual Fact / StateFact object (may be None). |
bridge_value | float | SPEC-025 §2.4 bridge_value score. |
novelty | float | CDR novelty from the Coverage Set. |
combined_score | float |
|
touched_anchors | list[str] | Anchor IDs linked through this connector. |
multi_mode_merge(mode_results, fact_to_community=None, mode_weights=None, max_results=200) ¶
Merge results from multiple CKF retrieval modes.
Parameters¶
mode_results : dict[str, list[tuple[Fact, float]]] Mapping of mode name → list of (fact, score) tuples. Mode names: "graph_walk", "pattern", "semantic", "community". fact_to_community : dict[str, int] | None Mapping of fact_id → community_id for community boosting. mode_weights : dict[str, float] | None Override default mode weights. max_results : int Maximum number of facts to return.
semantic_fallback(query_embedding, facts, top_k=None, hnsw_index=None) ¶
Retrieve the top_k most similar facts to query_embedding.
Uses HNSW index if provided and store is large enough; otherwise brute-force. Adaptive top_k: 20→200 based on store size.
build_edges(facts, threshold=0.6, *, embedding_attr='_embedding') ¶
Build similarity edges for a list of fact objects.
facts must have id (str) and an embedding accessible via embedding_attr (list[float] | None).
Facts whose embedding is None are skipped.
This is an O(N²) pairwise scan - acceptable up to ~5000 facts. For larger CKFs the HNSW index should be used for ANN-based edge construction (see build_edges_from_hnsw).
build_edges_from_hnsw(fact_ids, hnsw_index, threshold=0.6, k_neighbours=20) ¶
Build similarity edges using an existing HNSW index for scalability.
For each fact, query HNSW for k nearest neighbours and add edges for those meeting the similarity threshold. O(N × K) instead of O(N²).
hnsw_index must support: index.get_items([id_int]) → list[embedding] index.knn_query(embedding, k) → (labels, distances)
Distances from hnswlib cosine space are (1 - cosine_sim), so similarity = 1 - distance.
get_neighbours(fact_id, store) ¶
Convenience wrapper - return neighbours from a GraphEdgeStore.
Returns {neighbour_id: similarity_score}.
cdgr_expand(anchor_facts, edge_store, coverage_set, fact_lookup=None, *, max_hops=CDGR_MAX_HOPS, min_bridge_value=CDGR_MIN_BRIDGE_VALUE, max_connectors=CDGR_MAX_CONNECTOR_FACTS) ¶
CDGR three-phase expansion.
Phase A: anchor_facts are the CDR-ranked anchors (already provided). Phase B: BFS from anchors up to max_hops to find connector candidates. Phase C: Score candidates by bridge_value × novelty; take top connectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
anchor_facts | list[Any] | CDR-ranked anchor facts. | required |
edge_store | GraphEdgeStore | Graph edge store for neighbour/path lookup. | required |
coverage_set | CoverageSet | Session coverage set for novelty computation. | required |
fact_lookup | dict[str, Any] | None | Optional | None |
max_hops | int | Maximum BFS expansion hops. | CDGR_MAX_HOPS |
min_bridge_value | float | Minimum bridge value for a connector to be kept. | CDGR_MIN_BRIDGE_VALUE |
max_connectors | int | Maximum connectors to return. | CDGR_MAX_CONNECTOR_FACTS |
Returns:
| Type | Description |
|---|---|
CDGRResult | A |
cdr_cdgr_pipeline(facts, query_embedding, coverage_set, edge_store, *, fact_budget=20, importance_fn=None, min_relevance=0.55, max_hops=CDGR_MAX_HOPS, max_connectors=CDGR_MAX_CONNECTOR_FACTS) ¶
Run CDR ranking then CDGR expansion in one call.
The top 70% of fact_budget become CDR anchors; the remainder is reserved for CDGR connectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
facts | list[Any] | Candidate facts. | required |
query_embedding | list[float] | Query embedding for CDR ranking. | required |
coverage_set | CoverageSet | Session coverage set. | required |
edge_store | GraphEdgeStore | Graph edge store for CDGR expansion. | required |
fact_budget | int | Total number of facts for the envelope. | 20 |
importance_fn | Any | Optional importance-weight function for CDR. | None |
min_relevance | float | CDR minimum relevance gate. | 0.55 |
max_hops | int | Maximum CDGR expansion hops. | CDGR_MAX_HOPS |
max_connectors | int | Maximum connectors to return. | CDGR_MAX_CONNECTOR_FACTS |
Returns:
| Type | Description |
|---|---|
CDGRResult | A |
ckf.cdgr¶
crp.ckf.cdgr ¶
Coverage-Differential Graph Retrieval (CDGR) - SPEC-025.
CDGR closes the gap that flat CDR leaves open: connector facts required for multi-hop reasoning have low query similarity and are systematically invisible to similarity-based retrieval. CDGR seeds from CDR anchor facts, walks the CKF graph to find connectors, and scores them by bridge value - how many otherwise-disconnected anchor pairs they link.
Three-phase algorithm (SPEC-025 §2): Phase A - SEED: CDR-ranked anchor facts (top 70% of budget) Phase B - EXPAND: BFS walk ≤ MAX_HOPS hops to find connector candidates Phase C - ASSEMBLE: Score by bridge_value × novelty, pack seeds + bridges
The bridge_value function scores connectors by graph topology, not query similarity - this is the key innovation (SPEC-025 §2.4).
Performance target: < 2 ms per call (SPEC-025 §6.1). The graph is already in memory (built by graph_edges.py); no extra I/O.
CDGRConnector dataclass ¶
A connector fact selected by CDGR bridge scoring.
Attributes:
| Name | Type | Description |
|---|---|---|
fact_id | str | Connector fact identifier. |
fact | Any | The actual Fact / StateFact object (may be None). |
bridge_value | float | SPEC-025 §2.4 bridge_value score. |
novelty | float | CDR novelty from the Coverage Set. |
combined_score | float |
|
touched_anchors | list[str] | Anchor IDs linked through this connector. |
CDGRResult dataclass ¶
Full output of cdgr_expand().
Attributes:
| Name | Type | Description |
|---|---|---|
anchors | list[Any] | CDR-ranked anchor facts. |
connectors | list[CDGRConnector] | Bridge-value-ranked connector records. |
assembled | list[Any] | Anchors + connectors merged for packing. |
anchor_count | int | Number of anchor facts. |
connector_count | int | Number of connector facts selected. |
candidates_explored | int | Number of BFS candidates examined. |
cdgr_expand(anchor_facts, edge_store, coverage_set, fact_lookup=None, *, max_hops=CDGR_MAX_HOPS, min_bridge_value=CDGR_MIN_BRIDGE_VALUE, max_connectors=CDGR_MAX_CONNECTOR_FACTS) ¶
CDGR three-phase expansion.
Phase A: anchor_facts are the CDR-ranked anchors (already provided). Phase B: BFS from anchors up to max_hops to find connector candidates. Phase C: Score candidates by bridge_value × novelty; take top connectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
anchor_facts | list[Any] | CDR-ranked anchor facts. | required |
edge_store | GraphEdgeStore | Graph edge store for neighbour/path lookup. | required |
coverage_set | CoverageSet | Session coverage set for novelty computation. | required |
fact_lookup | dict[str, Any] | None | Optional | None |
max_hops | int | Maximum BFS expansion hops. | CDGR_MAX_HOPS |
min_bridge_value | float | Minimum bridge value for a connector to be kept. | CDGR_MIN_BRIDGE_VALUE |
max_connectors | int | Maximum connectors to return. | CDGR_MAX_CONNECTOR_FACTS |
Returns:
| Type | Description |
|---|---|
CDGRResult | A |
cdr_cdgr_pipeline(facts, query_embedding, coverage_set, edge_store, *, fact_budget=20, importance_fn=None, min_relevance=0.55, max_hops=CDGR_MAX_HOPS, max_connectors=CDGR_MAX_CONNECTOR_FACTS) ¶
Run CDR ranking then CDGR expansion in one call.
The top 70% of fact_budget become CDR anchors; the remainder is reserved for CDGR connectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
facts | list[Any] | Candidate facts. | required |
query_embedding | list[float] | Query embedding for CDR ranking. | required |
coverage_set | CoverageSet | Session coverage set. | required |
edge_store | GraphEdgeStore | Graph edge store for CDGR expansion. | required |
fact_budget | int | Total number of facts for the envelope. | 20 |
importance_fn | Any | Optional importance-weight function for CDR. | None |
min_relevance | float | CDR minimum relevance gate. | 0.55 |
max_hops | int | Maximum CDGR expansion hops. | CDGR_MAX_HOPS |
max_connectors | int | Maximum connectors to return. | CDGR_MAX_CONNECTOR_FACTS |
Returns:
| Type | Description |
|---|---|
CDGRResult | A |
ckf.community¶
crp.ckf.community ¶
CKF Mode 4: Community detection - Leiden cluster summaries (§3.8).
Batch community detection per window. Incremental update for <10% change, full rebuild for ≥30%. Falls back to connected components when leidenalg is unavailable.
Community dataclass ¶
A cluster of semantically related facts.
size property ¶
Return the current size count.
CommunityResult dataclass ¶
Result from community detection.
CommunityDetector ¶
Manages community detection with incremental updates.
Tracks the previous community state and decides whether to run a full rebuild or incremental update based on the change ratio.
ckf.fabric¶
crp.ckf.fabric ¶
Contextual Knowledge Fabric - unified 4-mode retrieval interface (§3.8).
The CKF is the top-level interface for fact storage, retrieval, community detection, pub/sub events, and cross-session persistence. It combines graph walk, pattern query, semantic fallback, and community summary modes into a single merged result.
CKFConfig dataclass ¶
Configuration for the Contextual Knowledge Fabric.
Attributes:
| Name | Type | Description |
|---|---|---|
max_facts | int | Maximum facts retained in the warm store. |
hnsw_threshold | int | Minimum facts before building an HNSW index. |
persist_path | str | Optional path for cold-state persistence. |
gc_budget_bytes | int | Memory budget for garbage collection. |
gc_trigger_ratio | float | Ratio of budget that triggers GC. |
gc_target_ratio | float | Ratio of budget GC aims to reclaim to. |
community_detect_enabled | bool | Whether community detection runs. |
CKFHealth dataclass ¶
Health snapshot for monitoring.
Attributes:
| Name | Type | Description |
|---|---|---|
fact_count | int | Number of facts in the warm store. |
edge_count | int | Number of edges in the graph. |
community_count | int | Number of detected communities. |
event_count | int | Number of events in the event log. |
tombstoned_count | int | Facts marked for removal by GC. |
estimated_bytes | int | Estimated memory footprint. |
hnsw_active | bool | Whether an HNSW index is currently built. |
leiden_available | bool | Whether the leidenalg library is installed. |
ContextualKnowledgeFabric ¶
Unified interface for fact storage and 4-mode retrieval (§3.8).
Methods (per spec 4F.1a): - store(facts) / retrieve(query, modes, budget) - query(pattern) / persist(path) / restore(path) - fact_count() / health() - temporal_query(window_range) - graph_walk(seeds, hops) / community_summary(topic) - subscribe(event, callback)
store(facts, window_id='') ¶
Ingest facts into the warm store and emit events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
facts | list[Fact] | Facts to store. | required |
window_id | str | Optional source window ID to stamp on facts. | '' |
store_edges(edges) ¶
Add edges to the fact graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
edges | list[FactEdge] | Edges to add. | required |
retrieve(query_embedding=None, seed_ids=None, entity_type=None, relationship_type=None, topic=None, modes=None, budget=200) ¶
Retrieve facts using up to 4 modes, merged and ranked.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query_embedding | list[float] | None | Query embedding for semantic mode. | None |
seed_ids | set[str] | None | Seed fact IDs for graph-walk mode. | None |
entity_type | str | None | Entity type filter for pattern mode. | None |
relationship_type | str | RelationType | None | Relation type filter for pattern mode. | None |
topic | str | None | Topic string for community mode. | None |
modes | list[str] | None | Subset of ["graph_walk", "pattern", "semantic", "community"]. Defaults to all applicable modes. | None |
budget | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
MergeResult | A merged and ranked |
query(entity_type=None, relationship_type=None, min_confidence=0.0, max_results=200) ¶
Convenience: pattern query on the fact graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entity_type | str | None | Entity type filter. | None |
relationship_type | str | RelationType | None | Relation type filter. | None |
min_confidence | float | Minimum fact confidence. | 0.0 |
max_results | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
PatternQueryResult | A |
graph_walk(seed_ids, max_hops=2, max_results=200) ¶
BFS traversal from seed facts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seed_ids | set[str] | Seed fact IDs. | required |
max_hops | int | Maximum graph hops. | 2 |
max_results | int | Maximum facts to return. | 200 |
Returns:
| Type | Description |
|---|---|
GraphWalkResult | A |
community_summary(topic) ¶
Return communities matching topic.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topic | str | Topic string to match against community summaries. | required |
Returns:
| Type | Description |
|---|---|
list[Community] | Matching communities. |
detect_communities() ¶
Force a community detection run.
Returns:
| Type | Description |
|---|---|
CommunityResult | The community detection result. |
temporal_query(start_window, end_window) ¶
Return fact IDs active between two windows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_window | str | Start window identifier. | required |
end_window | str | End window identifier. | required |
Returns:
| Type | Description |
|---|---|
list[str] | List of fact IDs created between the two windows. |
persist(path) ¶
Persist full state to cold storage, including community IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | Destination file path. | required |
restore(path) ¶
Restore state from cold storage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | Source file path. | required |
Returns:
| Type | Description |
|---|---|
list[str] | List of restore warnings. |
subscribe(event_type, callback) ¶
Register a callback for CKF events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type | CKFEventType | Event type to subscribe to. | required |
callback | EventCallback | Function called when the event fires. | required |
fact_count() ¶
Return the number of facts in the warm store.
health() ¶
Return a health snapshot.
run_gc(current_window=0) ¶
Run cross-session garbage collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
current_window | int | Current window number for recency-aware GC. | 0 |
Returns:
| Type | Description |
|---|---|
GCResult | The GC result. |
should_gc() ¶
Check if GC should be triggered based on memory budget.
ckf.gc¶
crp.ckf.gc ¶
CKF cross-session garbage collection (§3.8).
gc_score formula determines fact retention priority. Tombstone → purge lifecycle. Budget 500 MB, trigger 80%, target 70%.
GCResult dataclass ¶
Result of a GC pass.
GarbageCollector ¶
Cross-session GC for the CKF fact store.
Lifecycle: active → tombstoned → purged. Tombstoned facts are excluded from retrieval but retained for TOMBSTONE_AGE_WINDOWS before final purge.
should_gc(estimated_bytes) ¶
Return True if GC should run (estimated usage ≥ trigger).
run(facts, estimated_bytes, current_window=0) ¶
Execute a GC pass.
- Purge old tombstones (aged out).
- If still over target, tombstone lowest-scoring active facts.
is_tombstoned(fact_id) ¶
Return True if fact_id is currently tombstoned.
tombstone_count() ¶
Return the number of currently tombstoned facts.
estimate_store_bytes(facts) staticmethod ¶
Estimate total bytes for the fact store.
gc_score(fact, current_window=0) ¶
Compute GC retention score for a fact.
Higher score = more worth keeping. Components: - Confidence: raw confidence value - Freshness: inverse of age (recently created facts score higher) - Usage: how many envelopes consumed this fact - Graph connectivity: number of edges (well-connected facts are more valuable)
Formula
gc_score = 0.3 * confidence + 0.3 * freshness + 0.2 * usage + 0.2 * connectivity
ckf.graph_edges¶
crp.ckf.graph_edges ¶
CKF Similarity Edges - prerequisite for CDGR multi-hop graph walk (SPEC-025 §1.3).
Builds and maintains bidirectional similarity edges between CKF fact nodes. SPEC-009 §5.2 specifies that facts with cosine similarity ≥ 0.60 are connected by similarity edges. These edges are the foundation for the CDGR graph walk.
This module is intentionally dependency-light so it can be imported early without triggering heavy subsystem initialisation.
EdgeType ¶
Edge type constants used in the CKF graph.
CKFEdge dataclass ¶
Bidirectional similarity edge between two CKF fact nodes (SPEC-009 §5.2).
Stored once per pair (source < target lexicographically) but accessible from either end via GraphEdgeStore.
GraphEdgeStore ¶
Adjacency index for fast neighbour lookup.
Stores edges in both directions so neighbours(fact_id) is O(degree) regardless of which end of the edge was requested.
add_edge(edge) ¶
Add (or update) an edge in the adjacency index.
remove_fact(fact_id) ¶
Remove all edges involving fact_id (called on tombstone/GC).
neighbours(fact_id) ¶
Return {neighbour_id: similarity} for all edges from fact_id.
has_edge(a, b) ¶
True if an edge exists between a and b.
edge(a, b) ¶
Return the edge between a and b, or None.
edge_count() ¶
Return the number of unique edges in the store.
node_count() ¶
Return the number of distinct nodes with at least one edge.
path_length(start, end, max_hops=4) ¶
BFS shortest path length, capped at max_hops.
Returns max_hops + 1 if no path found within the hop limit.
build_edges(facts, threshold=0.6, *, embedding_attr='_embedding') ¶
Build similarity edges for a list of fact objects.
facts must have id (str) and an embedding accessible via embedding_attr (list[float] | None).
Facts whose embedding is None are skipped.
This is an O(N²) pairwise scan - acceptable up to ~5000 facts. For larger CKFs the HNSW index should be used for ANN-based edge construction (see build_edges_from_hnsw).
build_edges_from_hnsw(fact_ids, hnsw_index, threshold=0.6, k_neighbours=20) ¶
Build similarity edges using an existing HNSW index for scalability.
For each fact, query HNSW for k nearest neighbours and add edges for those meeting the similarity threshold. O(N × K) instead of O(N²).
hnsw_index must support: index.get_items([id_int]) → list[embedding] index.knn_query(embedding, k) → (labels, distances)
Distances from hnswlib cosine space are (1 - cosine_sim), so similarity = 1 - distance.
get_neighbours(fact_id, store) ¶
Convenience wrapper - return neighbours from a GraphEdgeStore.
Returns {neighbour_id: similarity_score}.
ckf.graph_walk¶
crp.ckf.graph_walk ¶
CKF Mode 1: Graph walk - BFS traversal from seed facts (§3.8).
graph_walk(seed_facts, max_hops=2) returns a ranked list of facts reachable within max_hops of the seed set, ordered by proximity.
ckf.merge¶
crp.ckf.merge ¶
CKF multi-mode merge - deduplicate, score, rank, community boost (§3.8).
multi_mode_merge() combines results from all four CKF retrieval modes into a single ranked list, applying deduplication and community-coherence boosting.
MergedFact dataclass ¶
A fact with a merged score from multiple retrieval modes.
MergeResult dataclass ¶
Result of multi-mode merge.
multi_mode_merge(mode_results, fact_to_community=None, mode_weights=None, max_results=200) ¶
Merge results from multiple CKF retrieval modes.
Parameters¶
mode_results : dict[str, list[tuple[Fact, float]]] Mapping of mode name → list of (fact, score) tuples. Mode names: "graph_walk", "pattern", "semantic", "community". fact_to_community : dict[str, int] | None Mapping of fact_id → community_id for community boosting. mode_weights : dict[str, float] | None Override default mode weights. max_results : int Maximum number of facts to return.
ckf.pattern_query¶
crp.ckf.pattern_query ¶
CKF Mode 2: Pattern query - structured matching by entity/relation type (§3.8).
pattern_query(graph, entity_type, relationship_type) filters facts and edges by category and relation type.
PatternQueryResult dataclass ¶
Result of a pattern query.
pattern_query(graph, entity_type=None, relationship_type=None, min_confidence=0.0, max_results=200, metadata_filter=None) ¶
Structured query: filter facts by category and edges by relation type.
Parameters¶
graph : FactGraph entity_type : str | None Filter facts whose category matches (case-insensitive). relationship_type : str | RelationType | None Filter edges whose relation_type matches. min_confidence : float Minimum confidence threshold for both facts and edges. max_results : int Cap on returned facts. metadata_filter : dict | None Key-value pairs that must all appear in fact.metadata.
ckf.pubsub¶
crp.ckf.pubsub ¶
PubSub event bus for CKF internal notifications (§3.8).
Events: fact_created, fact_superseded, edge_added, community_updated, anomaly_detected. Subscribers receive typed payloads asynchronously (fire-and-forget).
CKFEventType ¶
Bases: str, Enum
Events emitted by the CKF subsystem.
CKFEvent dataclass ¶
Payload for a CKF event.
PubSubEventBus ¶
Thread-safe pub/sub for CKF lifecycle events.
Usage::
bus = PubSubEventBus()
bus.subscribe(CKFEventType.FACT_CREATED, my_handler)
bus.publish(CKFEvent(CKFEventType.FACT_CREATED, {"fact_id": "abc"}))
subscribe(event_type, callback) ¶
Register callback for events of event_type.
subscribe_all(callback) ¶
Register callback for all event types.
unsubscribe(event_type, callback) ¶
Remove callback from event_type subscribers.
publish(event) ¶
Dispatch event to all subscribers. Fire-and-forget - errors logged.
subscriber_count(event_type=None) ¶
Return number of subscribers, optionally filtered by event type.
clear() ¶
Remove all subscribers.
ckf.semantic¶
crp.ckf.semantic ¶
CKF Mode 3: Semantic fallback - ANN similarity retrieval (§3.8).
semantic_fallback(query, facts, top_k) retrieves the top_k most semantically similar facts to query. Uses HNSW when hnswlib is available, otherwise brute-force cosine similarity.
Adaptive top_k: 20 (default), scales up to 200 for large stores.
SemanticResult dataclass ¶
Result of a semantic similarity query.
HNSWIndex ¶
Thin wrapper around hnswlib for ANN queries.
count property ¶
Return the current count count.
add(fact_id, embedding) ¶
Add a fact embedding to the HNSW index.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fact_id | str | External identifier for the fact. | required |
embedding | list[float] | Dense vector representing the fact. | required |
query(embedding, k) ¶
Return [(fact_id, distance), ...] for top-k nearest.
adaptive_top_k(fact_count, base_k=MIN_TOP_K) ¶
Scale top_k based on store size: 20 for small, up to 200 for large.
semantic_fallback(query_embedding, facts, top_k=None, hnsw_index=None) ¶
Retrieve the top_k most similar facts to query_embedding.
Uses HNSW index if provided and store is large enough; otherwise brute-force. Adaptive top_k: 20→200 based on store size.