Data Models

Response types returned by HyperBinder API operations.

Search Results

SearchResult

hybi.SearchResult dataclass

A single result from a search query.

SearchResult provides dict-like access to row data along with a similarity score indicating match quality. Returned by search(), semantic search, and compose query operations.

Attributes:

Name	Type	Description
data	Dict[str, Any]	Row data as a dictionary mapping column names to values.
score	float	Similarity score between 0.0 and 1.0. Higher values indicate better matches. Comparable across queries on the same collection.
id	int	Internal row identifier. Used for updates and join operations.

Example

results = hb.search("enterprise AI", collection="customers") for r in results: ... print(f"{r['company_name']}: {r.score:.2f}") ... # Or access via data dict ... print(r.data.get('industry', 'Unknown'))

See Also

MultihopResult: For graph traversal results with path information. ComposeResult: For schema-aware query results.

__getitem__(key)

Allow dict-like access: result['name']

get(key, default=None)

Dict-like get with default.

MultihopResult

hybi.MultihopResult dataclass

A single result from a multi-hop graph traversal query.

Extends SearchResult with path information showing how the result was reached through the graph.

Attributes:

Name	Type	Description
data	Dict[str, Any]	Row data as a dictionary mapping column names to values.
score	float	Cumulative similarity score across all hops (0.0 to 1.0).
id	int	Internal row identifier.
path	List[Dict[str, Any]]	List of intermediate rows traversed to reach this result. Each entry is a dict with the row data at that hop.
explanation	Optional[PathTrace]	Optional PathTrace with detailed execution information. Available when explain=True in the query.

Example

results = hb.multihop("Alice", ["manager", "department"], "employees") for r in results: ... print(f"Found: {r['name']} (score: {r.score:.2f})") ... print(f" Path: {' -> '.join(p.get('name', '?') for p in r.path)}")

See Also

SearchResult: For simple search results without path information. PathTrace: For detailed execution trace.

HopTrace

hybi.HopTrace dataclass

A single hop in a multihop query execution path.

Records how many candidates existed before and after applying a filter at each step of a multi-hop traversal.

Attributes:

Name	Type	Description
field	str	The column name used for this hop's filter.
value	Any	The value matched or searched for.
filter_type	str	Type of filter applied - "vector" for semantic similarity, "exact" for exact match, "range" for numeric ranges.
candidates_before	int	Number of candidate rows before this filter.
candidates_after	int	Number of rows remaining after this filter.

Example

result = hb.multihop("Alice", ["manager", "department"], "employees") for hop in result.explanation.hops: ... print(f"{hop.field}: {hop.candidates_before} -> {hop.candidates_after}")

PathTrace

hybi.PathTrace dataclass

Structured explanation of multihop query execution.

Provides both machine-readable hop data and human-readable trace lines for debugging and understanding query execution paths.

Attributes:

Name	Type	Description
initial_filters_matched	int	Rows matching the initial query before traversal.
final_result_count	int	Number of results after all hops completed.
hops	List[HopTrace]	List of HopTrace objects, one per traversal step.
trace	List[str]	Pre-formatted human-readable explanation lines from the server.

Example

result = hb.multihop("Alice", ["manager", "department"], "employees") print(result.explanation) # Full trace print(result.explanation.summary()) # "10 initial -> 3 results via 2 hops"

__str__()

Print the full trace.

summary()

One-line summary of the path.

Query Results

SelectResult

hybi.SelectResult dataclass

Result from a SQL-like SELECT query.

Iterable collection of rows matching the query conditions. Supports len() and iteration.

Attributes:

Name	Type	Description
rows	List[Dict[str, Any]]	List of row dictionaries. Each dict maps column names to values.
total_rows	int	Total matching rows in the collection (may exceed len(rows) if LIMIT was applied).
execution_time_ms	float	Query execution time in milliseconds.

Example

result = hb.select({"status": "active"}, collection="users", limit=10) print(f"Showing {len(result)} of {result.total_rows} total") for row in result: ... print(row['email'])

See Also

AggregateResult: For GROUP BY aggregation queries. JoinResult: For cross-collection JOIN queries.

AggregateResult

hybi.AggregateResult dataclass

Result from a GROUP BY aggregation query.

Iterable collection of aggregation groups with computed values.

Attributes:

Name	Type	Description
groups	List[Dict[str, Any]]	List of group dictionaries. Each contains the group key(s) and aggregated value(s). Keys match the group_by fields; values are named by the aggregation function (e.g., "count", "sum").
total_groups	int	Total number of distinct groups.
execution_time_ms	float	Query execution time in milliseconds.

Example

result = hb.aggregate( ... group_by="department", ... field="salary", ... function="avg", ... collection="employees" ... ) for group in result: ... print(f"{group['department']}: ${group['avg']:.2f}")

See Also

SelectResult: For filtering without aggregation.

JoinResult

hybi.JoinResult dataclass

Result from a cross-collection JOIN query.

Contains merged rows from two collections based on matching criteria. Column names are prefixed with collection names to avoid conflicts.

Attributes:

Name	Type	Description
rows	List[Dict[str, Any]]	List of joined row dictionaries. Keys are prefixed: "left_collection.column" and "right_collection.column".
total_rows	int	Total matching joined rows.
execution_time_ms	float	Query execution time in milliseconds.

Example

result = hb.join( ... "employees", "departments", ... on=("dept_id", "id") ... ) for row in result: ... print(f"{row['employees.name']} in {row['departments.name']}")

See Also

SelectResult: For single-collection queries. Intersection: For declaring joinable relationships.

RAG Models

Context

hybi.Context dataclass

Retrieved context ready for LLM consumption.

Assembles relevant chunks into a single text block with token counting for context window management.

Attributes:

Name	Type	Description
text	str	Concatenated chunk contents, formatted for LLM input. Use str(context) to get this value.
chunks	List[Chunk]	Individual Chunk objects that comprise this context, ordered by relevance score (highest first).
token_count	int	Estimated token count using tiktoken cl100k_base. Use for context window budgeting.
query	str	The original query used to retrieve this context.

Example

context = hb.get_context("quarterly revenue", collection="reports") print(f"Retrieved {len(context.chunks)} chunks ({context.token_count} tokens)")

Use in LLM prompt

prompt = f"Context:\n{context}\n\nQuestion: {context.query}"

See Also

Chunk: Individual document segments within context. Answer: End-to-end RAG response with generated text.

Answer

hybi.Answer dataclass

Response from an end-to-end RAG query.

Contains the generated answer text, source citations, and metadata about the generation process.

Attributes:

Name	Type	Description
text	str	The generated answer text. Use str(answer) to get this.
sources	List[Source]	List of Source objects citing the retrieved documents used to generate this answer, ordered by relevance.
confidence	float	Model's confidence in the answer (0.0 to 1.0). Lower values may indicate insufficient context.
model	str	Name of the LLM model used for generation.
query	str	The original question asked.

Example

answer = hb.ask("Summarize the project status", collection="docs") print(answer) if answer.confidence < 0.7: ... print("Warning: Low confidence answer") print(f"\nGenerated by: {answer.model}")

See Also

Context: For retrieving context without generation. Source: Individual citation in the sources list.

Chunk

hybi.Chunk dataclass

A document chunk retrieved for RAG context.

Represents a segment of a document that matched the query, with relevance score and source metadata.

Attributes:

Name	Type	Description
content	str	The text content of this chunk.
score	float	Relevance score between 0.0 and 1.0.
metadata	Dict[str, Any]	Source information dict. Common keys include: - "source": Original filename or URL - "page": Page number (for PDFs) - "section": Section heading
id	Optional[int]	Optional row identifier in the source collection.

Example

context = hb.get_context("What is RAG?", collection="docs") for chunk in context.chunks: ... print(f"[{chunk.score:.2f}] {chunk.content[:100]}...") ... print(f" Source: {chunk.metadata.get('source', 'unknown')}")

See Also

Context: Assembled context containing multiple chunks. Source: Similar structure used in Answer citations.

Source

hybi.Source dataclass

A source reference in a RAG answer.

Similar to Chunk but represents a citation in a generated answer, linking claims to their source documents.

Attributes:

Name	Type	Description
content	str	The relevant text excerpt from the source.
score	float	Relevance score used when selecting this source (0.0 to 1.0).
metadata	Dict[str, Any]	Source information dict with keys like "source", "page".

Example

answer = hb.ask("What are the Q3 results?", collection="reports") print(answer.text) print("\nSources:") for src in answer.sources: ... print(f" - {src.metadata.get('source')}: {src.content[:50]}...")

See Also

Chunk: Similar structure used in Context retrieval. Answer: Contains list of Source citations.

Collection Models

CollectionInfo

hybi.CollectionInfo dataclass

Basic information about a collection.

Lightweight metadata returned by list_collections() and collection checks. For detailed statistics, use CollectionStats via get_collection_stats().

Attributes:

Name	Type	Description
name	str	Collection name (unique identifier).
rows	int	Number of rows in the collection.
columns	List[str]	List of column names.
has_semantic	bool	True if semantic (vector) search is enabled.
has_symbolic	bool	True if symbolic (exact/SQL) queries are enabled.
created_at	Optional[str]	ISO timestamp when collection was created, or None.
type	str	Collection type - "structured" for tabular data, "document" for ingested documents (PDF, DOCX, etc.).

Example

collections = hb.list_collections() for c in collections: ... search_type = "semantic" if c.has_semantic else "symbolic" ... print(f"{c.name}: {c.rows} rows ({search_type})")

See Also

CollectionStats: For detailed collection statistics.

CollectionStats

hybi.CollectionStats dataclass

Detailed statistics about a collection.

Example

stats = hb.collection("customers").stats() print(stats) # "customers: 1000 rows, 5 columns (structured)" print(f"Vector dimension: {stats.dimension}")

Access stored Compose schema

if stats.template_name: schema = stats.get_schema() print(f"Schema type: {schema.molecule_type}")

schema_version = 1 class-attribute instance-attribute

Version number for the schema, incremented on each change.

evolution_mode = 'adaptive' class-attribute instance-attribute

Schema evolution mode: 'adaptive', 'strict', or 'locked'.

reasoning_enabled = False class-attribute instance-attribute

Whether MHV reasoning is enabled for this collection (paid feature).

reasoning_config = None class-attribute instance-attribute

Reasoning engine configuration (dim, size, relations, etc.).

reasoning_model_version = None class-attribute instance-attribute

Version identifier for the trained reasoning model.

reasoning_trained_at = None class-attribute instance-attribute

ISO timestamp when reasoning model was last trained.

get_schema()

Deserialize stored schema to molecule object.

Returns:

Type	Description
Optional[BaseMolecule]	BaseMolecule instance (Triple, Record, etc.) or None if no schema stored.

Example

stats = hb.collection("facts").stats() schema = stats.get_schema() if schema: print(f"Schema: {schema.molecule_type}") print(f"Slots: {schema.slots()}")

get_evolution_mode()

Get the schema evolution mode as an enum value.

Returns:

Type	Description
SchemaEvolution	SchemaEvolution enum value

get_reasoning_config()

Get the reasoning configuration if available.

Returns:

Type	Description
Optional[ReasoningConfig]	ReasoningConfig instance or None if reasoning not configured.

Example

stats = hb.collection("org").stats() if stats.reasoning_enabled: config = stats.get_reasoning_config() print(f"Relations: {config.relations}")

IngestResult

hybi.IngestResult dataclass

Result from a data ingestion operation.

Returned by ingest() to confirm successful data loading.

Attributes:

Name	Type	Description
collection	str	Name of the collection data was ingested into.
rows_ingested	int	Number of rows successfully ingested.
status	str	Operation status - "success", "partial", or "error".
columns	List[str]	List of column names in the ingested data. Empty list if ingesting documents.
message	Optional[str]	Optional status message with details about the operation, especially useful for partial success or errors.

Example

result = hb.ingest("data.csv", collection="customers") print(f"Ingested {result.rows_ingested} rows into {result.collection}") if result.status != "success": ... print(f"Warning: {result.message}")

See Also

CollectionStats: For checking collection state after ingestion.