Knowledge

Public exports for knowledge-graph integration.

BaseKnowledgeClient

Bases: ABC

Define the contract for knowledge-graph storage and retrieval backends.

Implementations are responsible for persisting provenance-aware graph contributions and returning normalized KnowledgeFact results.

delete_contribution(target) abstractmethod async

Delete one provenance-aware graph contribution by source ownership.

Parameters:

Name	Type	Description	Default
target	KnowledgeDeleteTarget	Contribution delete target.	required

Returns:

Type	Description
None	None

replace_contribution(contribution) abstractmethod async

Replace one provenance-aware graph contribution.

Parameters:

Name	Type	Description	Default
contribution	GraphContribution	Contribution payload to replace.	required

Returns:

Type	Description
None	None

traverse(*, seeds, user_id=None, agent_id=None, metadata=None, top_k=10, depth=2) abstractmethod async

Traverse the knowledge graph from one or more resolved seeds.

Parameters:

Name	Type	Description	Default
seeds	list[KnowledgeSeed]	Resolved traversal seeds.	required
user_id	str | None	Optional user scope filter. Defaults to None.	None
agent_id	str | None	Optional agent scope filter. Defaults to None.	None
metadata	dict[str, str] | None	Optional metadata filters. Defaults to None.	None
top_k	int	Maximum number of facts to return. Defaults to 10.	10
depth	int	Traversal depth. Defaults to 2.	2

Returns:

Type	Description
list[KnowledgeFact]	list[KnowledgeFact]: Normalized KG traversal results.

upsert_contribution(contribution) abstractmethod async

Upsert one provenance-aware graph contribution.

Parameters:

Name	Type	Description	Default
contribution	GraphContribution	Contribution payload to persist.	required

Returns:

Type	Description
None	None

BaseKnowledgeSeedResolver

Bases: ABC

Define the contract for query-to-seed resolution implementations.

Implementations are responsible for transforming a natural-language query into one or more traversal seeds suitable for the configured knowledge backend.

resolve(*, query, user_id=None, agent_id=None, metadata=None, top_k=3) abstractmethod async

Resolve one query into traversal seeds.

Parameters:

Name	Type	Description	Default
query	str	Natural-language retrieval query.	required
user_id	str | None	Optional user scope. Defaults to None.	None
agent_id	str | None	Optional agent scope. Defaults to None.	None
metadata	dict[str, str] | None	Optional metadata context. Defaults to None.	None
top_k	int	Maximum number of seeds to return. Defaults to 3.	3

Returns:

Type	Description
list[KnowledgeSeed]	list[KnowledgeSeed]: Ordered traversal seeds.

BaseTextToGraphExtractor

Bases: ABC

Define the contract for text-to-graph extraction implementations.

Implementations are responsible for converting one message batch into the backend-neutral ExtractedGraphPayload used by the rest of the KG flow.

extract(*, messages, user_id, agent_id, metadata=None, source_id=None) abstractmethod async

Extract one graph payload from a message batch.

Parameters:

Name	Type	Description	Default
messages	list[Message]	Input messages for graph extraction.	required
user_id	str	User identifier associated with the source batch.	required
agent_id	str	Agent identifier associated with the source batch.	required
metadata	dict[str, str] | None	Optional batch metadata. Defaults to None.	None
source_id	str | None	Stable contribution identifier when already known. Defaults to None.	None

Returns:

Name	Type	Description
ExtractedGraphPayload	ExtractedGraphPayload	One backend-neutral graph payload.

ExtractedGraphPayload

Bases: BaseModel

Defines one backend-neutral text-to-graph extraction result.

Attributes:

Name	Type	Description
nodes	list[Node]	Extracted graph nodes. Defaults to an empty list.
edges	list[Edge]	Extracted graph edges. Defaults to an empty list.
facts	list[str]	Optional textual fact summaries. Defaults to an empty list.
metadata	dict[str, Any]	Additional extraction metadata. Defaults to an empty dictionary.

GraphContribution

Bases: BaseModel

Defines one provenance-aware graph contribution.

Attributes:

Name	Type	Description
source_id	str	Stable contribution identifier.
user_id	str | None	Canonical user identifier for provenance. This value does not swap with agent_id based on MemoryScope. Defaults to None.
agent_id	str | None	Canonical agent identifier for provenance. This value does not swap with user_id based on MemoryScope. Defaults to None.
nodes	list[Node]	Nodes contributed by one extraction event. Defaults to an empty list.
edges	list[Edge]	Edges contributed by one extraction event. Defaults to an empty list.
facts	list[str]	Optional fact summaries. Defaults to an empty list.
metadata	dict[str, Any]	Contribution metadata. Defaults to an empty dictionary.

KnowledgeFact

Bases: BaseModel

Defines one normalized knowledge retrieval result.

Attributes:

Name	Type	Description
fact_id	str	Stable identifier for one knowledge fact.
text	str	User-facing textual rendering of the fact.
score	float | None	Optional relevance score. Defaults to None.
entities	list[str]	Related entities. Defaults to an empty list.
relations	list[str]	Related relations. Defaults to an empty list.
path	list[str]	Optional traversal path. Defaults to an empty list.
metadata	dict[str, Any]	Additional knowledge metadata. Defaults to an empty dictionary.
source	str	Source kind label. Defaults to "kg".

to_chunk()

Convert one knowledge fact into a Chunk.

Returns:

Name	Type	Description
Chunk	Chunk	Chunk representation of the fact with KG metadata attached.

KnowledgeSeed

Bases: BaseModel

Defines one traversal seed for knowledge-graph retrieval.

Attributes:

Name	Type	Description
node_properties	dict[str, Any]	Node property matchers used to start traversal.
seed_text	str	User-facing seed text for debugging and observability.
score	float | None	Optional resolver confidence or ranking score. Defaults to None.
source	str	Resolver source label such as "heuristic" or "extractor".