Schema

Pydantic schemas for knowledge-graph integration.

This module defines backend-neutral payloads for text-to-graph extraction, knowledge contributions, and traversal seeds.

`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.

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.

Bases: BaseModel

Defines one provenance-aware contribution delete target.

Attributes:

Name	Type	Description
`memory_id`	`str`	Memory row identifier whose contribution should be removed.
`source_id`	`str`	Stable KG contribution identifier to detach from the graph.
`user_id`	`str \| None`	Canonical user identifier for observability. Defaults to None.
`agent_id`	`str \| None`	Canonical agent identifier for observability. Defaults to None.
`metadata`	`dict[str, Any]`	Contribution scope metadata such as namespace and app ID. Defaults to an empty dictionary.

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"`.

Convert one knowledge fact into a Chunk.

Returns:

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

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"`.