Documentation

results

Rich result types for Context Fabric API.

These classes wrap raw node IDs with contextual information, making them suitable for serialization and agent interaction via MCP.

Classes

class

CorpusInfo

Information about a loaded corpus.

Information about a loaded corpus. Attributes: name: Corpus name (derived from path or user-specified) path: Path to the corpus node_types: List of node types with counts and ranges node_features: List of node feature names edge_features: List of edge feature names slot_type: The slot type name max_slot: Maximum slot node ID max_node: Maximum node ID section_types: Section type hierarchy (e.g., ['book', 'chapter', 'verse'])

Attributes

NameTypeDescription
edge_featureslist[str]—
max_nodeint—
max_slotint—
namestr—
node_featureslist[str]—
node_typeslist[dict[(str, Any)]]—
pathstr—
section_typeslist[str]—
slot_typestr—

Methods

__init__(self, name: str, path: str, node_types: list[dict[(str, Any)]] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}, node_features: list[str] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}, edge_features: list[str] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}, slot_type: str = '', max_slot: int = 0, max_node: int = 0, section_types: list[str] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}) → None
Parameters
  • name: str
  • path: str
  • node_types: list[dict[(str, Any)]]
  • node_features: list[str]
  • edge_features: list[str]
  • slot_type: str= ''
  • max_slot: int= 0
  • max_node: int= 0
  • section_types: list[str]
from_api(cls, api: Api, name: str, path: str) → CorpusInfo

Create CorpusInfo from API.

Parameters
  • cls
  • api: Api
  • name: str
  • path: str
to_dict(self) → dict[(str, Any)]

Convert to JSON-serializable dictionary.

to_json(self) → str

Serialize to JSON string.

class

FeatureInfo

Metadata about a feature.

Metadata about a feature. Attributes: name: Feature name kind: 'node' or 'edge' value_type: 'str', 'int', or '' for edges without values description: Feature description from metadata has_values: For edge features, whether edges have values

Attributes

NameTypeDescription
descriptionstr—
has_valuesbool | None—
kindstr—
namestr—
value_typestr—

Methods

__init__(self, name: str, kind: str, value_type: str = '', description: str = '', has_values: bool | None = None) → None
Parameters
  • name: str
  • kind: str
  • value_type: str= ''
  • description: str= ''
  • has_values: bool | None= None
from_api(cls, api: Api, name: str, kind: str) → FeatureInfo | None

Create FeatureInfo from API.

Parameters
  • cls
  • api: Api
  • name: str
  • kind: str
to_dict(self) → dict[(str, Any)]

Convert to JSON-serializable dictionary.

to_json(self) → str

Serialize to JSON string.

class

NodeInfo

Rich representation of a single node.

Rich representation of a single node. Attributes: node: The integer node ID otype: The node type (e.g., 'word', 'verse', 'chapter') text: Text representation of the node section_ref: Human-readable section reference (e.g., 'Genesis 1:1') slots: Tuple of slot node IDs this node spans (for non-slot nodes) features: Dict of feature values for this node (optional, populated on demand)

Attributes

NameTypeDescription
featuresdict[(str, str | int)] | None—
nodeint—
otypestr—
section_refstr—
slotstuple[(int, ...)] | None—
textstr—

Methods

__init__(self, node: int, otype: str, text: str = '', section_ref: str = '', slots: tuple[(int, ...)] | None = None, features: dict[(str, str | int)] | None = None) → None
Parameters
  • node: int
  • otype: str
  • text: str= ''
  • section_ref: str= ''
  • slots: tuple[(int, ...)] | None= None
  • features: dict[(str, str | int)] | None= None
from_api(cls, api: Api, node: int, include_text: bool = True, include_section: bool = True, include_slots: bool = False, include_features: list[str] | None = None) → NodeInfo

Create NodeInfo from API and node ID.

Parameters
  • cls
  • api: Api
  • node: int
  • include_text: bool= True
  • include_section: bool= True
  • include_slots: bool= False
  • include_features: list[str] | None= None
to_dict(self) → dict[(str, Any)]

Convert to JSON-serializable dictionary.

to_json(self) → str

Serialize to JSON string.

class

NodeList

A list of nodes with rich information.

A list of nodes with rich information. Attributes: nodes: List of NodeInfo objects total_count: Total number of nodes (may differ from len(nodes) if limited) query: Optional description of how nodes were obtained

Attributes

NameTypeDescription
nodeslist[NodeInfo]—
querystr | None—
total_countint—

Methods

__init__(self, nodes: list[NodeInfo] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}, total_count: int = 0, query: str | None = None) → None
Parameters
  • nodes: list[NodeInfo]
  • total_count: int= 0
  • query: str | None= None
from_nodes(cls, api: Api, nodes: list[int] | tuple[(int, ...)], limit: int | None = None, query: str | None = None, node_kwargs: Any = {}) → NodeList

Create NodeList from API and node IDs.

Parameters
  • cls
  • api: Api
  • nodes: list[int] | tuple[(int, ...)]
  • limit: int | None= None
  • query: str | None= None
  • node_kwargs: Any= {}
to_dict(self) → dict[(str, Any)]

Convert to JSON-serializable dictionary.

to_json(self) → str

Serialize to JSON string.

class

SearchResult

Result of a search query.

Result of a search query. Attributes: results: List of result tuples, each tuple is a list of NodeInfo total_count: Total number of results template: The search template used plan: Optional search plan description

Attributes

NameTypeDescription
planstr | None—
resultslist[list[NodeInfo]]—
templatestr—
total_countint—

Methods

__init__(self, results: list[list[NodeInfo]] = {'arguments': [], 'cls': 'ExprCall', 'function': {'cls': 'ExprName', 'member': None, 'name': 'list'}}, total_count: int = 0, template: str = '', plan: str | None = None) → None
Parameters
  • results: list[list[NodeInfo]]
  • total_count: int= 0
  • template: str= ''
  • plan: str | None= None
from_search(cls, api: Api, results: tuple[(tuple[(int, ...)], ...)] | list[tuple[(int, ...)]], template: str, limit: int | None = None, node_kwargs: Any = {}) → SearchResult

Create SearchResult from search results.

Parameters
  • cls
  • api: Api
  • results: tuple[(tuple[(int, ...)], ...)] | list[tuple[(int, ...)]]
  • template: str
  • limit: int | None= None
  • node_kwargs: Any= {}
to_dict(self) → dict[(str, Any)]

Convert to JSON-serializable dictionary.

to_json(self) → str

Serialize to JSON string.