Contextual Knowledge Fabric API¶
The client.ckf namespace exposes the Contextual Knowledge Fabric (CKF): the semantic memory graph that carries facts across windows and enables cross-document retrieval.
SDK proxy¶
crp.sdk.proxies._CKFProxy ¶
Contextual Knowledge Fabric proxy (SPEC-009, SPEC-025).
Exposes CKF query, search, graph walk, community detection, CDGR expansion, persistence, pub/sub, and health introspection.
query(**kwargs) ¶
Run a pattern query on the CKF fact graph.
Returns:
| Type | Description |
|---|---|
Any | PatternQueryResult from the CKF. |
search(query, top_k=5, **kwargs) ¶
Semantic search over the CKF.
Embeds query when an embedding function is available; otherwise falls back to the CKF's text/keyword modes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query | str | Query text. | required |
top_k | int | Maximum number of facts to return. | 5 |
**kwargs | Any | Additional retrieval options. | {} |
Returns:
| Type | Description |
|---|---|
Any | MergeResult containing ranked facts. |
graph_walk(start_fact_id, max_hops=3, **kwargs) ¶
Walk the CKF graph from a seed fact.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_fact_id | str | Seed fact identifier. | required |
max_hops | int | Maximum BFS distance from the seed. | 3 |
**kwargs | Any | Additional options forwarded to | {} |
Returns:
| Type | Description |
|---|---|
Any | GraphWalkResult. |
community_summary(**kwargs) ¶
Run community detection on the CKF fact graph.
Returns:
| Type | Description |
|---|---|
Any | CommunityResult. |
cdgr_expand(query, **kwargs) ¶
Run Coverage-Differential Graph Retrieval expansion (SPEC-025).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query | str | Query text used to seed CDR anchors. | required |
**kwargs | Any | Additional options for | {} |
Returns:
| Type | Description |
|---|---|
Any | CDGRResult with anchors and connector facts. |
persist(path=None) ¶
Persist CKF state to path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | None | Destination path. If | None |
Raises:
| Type | Description |
|---|---|
NotImplementedError | If the CKF does not support persistence. |
restore(path=None) ¶
Restore CKF state from path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | None | Source path. If | None |
Returns:
| Type | Description |
|---|---|
Any | Restore warnings if available. |
Raises:
| Type | Description |
|---|---|
NotImplementedError | If the CKF does not support restore. |
subscribe(event_type, callback) ¶
Subscribe to CKF pub/sub events if available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type | Any | CKF event type or string. | required |
callback | Any | Callable invoked when the event fires. | required |
health() ¶
Return a CKF health snapshot.
Returns:
| Type | Description |
|---|---|
Any | CKFHealth report. |
fact_count() ¶
Return the number of facts in the CKF.
CKF fabric¶
crp.ckf.fabric.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.
CDGR result¶
crp.ckf.cdgr.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. |