Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

feat: extend scoped search (source_ids/tags) to AutoHypergraph and AutoSet

yifanfeng9749ed4ba9d516
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index 7978ca2..541c2c1 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -752,10 +752,17 @@ class AutoHypergraph(
top_k_nodes: int = 3,
top_k_edges: int = 3,
top_k: int | None = None,
+ *,
+ source_ids: list[str] | None = None,
+ tags: list[str] | None = None,
) -> tuple[list[NodeSchema], list[EdgeSchema]]:
"""Unified hypergraph search interface.
Retrieves nodes and hyperedges semantically related to the query.
+
+ Args:
+ source_ids: Optional scope — only knowledge contributed by these source documents.
+ tags: Optional scope — only knowledge from sources carrying any of these tags.
Always returns a tuple of (nodes, edges). If a count is 0, the corresponding list will be empty.
Args:
@@ -797,13 +804,31 @@ class AutoHypergraph(
return nodes, edges
- def search_nodes(self, query: str, top_k: int = 3) -> list[NodeSchema]:
+ def search_nodes(
+ self,
+ query: str,
+ top_k: int = 3,
+ *,
+ source_ids: list[str] | None = None,
+ tags: list[str] | None = None,
+ ) -> list[NodeSchema]:
"""Semantic search for nodes/entities only."""
- return self._node_memory.search(query=query, top_k=top_k)
+ return self._node_memory.search(
+ query=query, top_k=top_k, source_ids=source_ids, tags=tags
+ )
- def search_edges(self, query: str, top_k: int = 3) -> list[EdgeSchema]:
+ def search_edges(
+ self,
+ query: str,
+ top_k: int = 3,
+ *,
+ source_ids: list[str] | None = None,
+ tags: list[str] | None = None,
+ ) -> list[EdgeSchema]:
"""Semantic search for hyperedges/relationships only."""
- return self._edge_memory.search(query=query, top_k=top_k)
+ return self._edge_memory.search(
+ query=query, top_k=top_k, source_ids=source_ids, tags=tags
+ )
def chat(
self,
diff --git a/hyperextract/types/set.py b/hyperextract/types/set.py
index 959a6ca..007ab85 100644
--- a/hyperextract/types/set.py
+++ b/hyperextract/types/set.py
@@ -184,7 +184,8 @@ class AutoSet(BaseAutoType[AutoSetSchema[ItemSchema]], Generic[ItemSchema]):
embedder=embedder,
strategy_or_merger=self._merger,
verbose=verbose,
- fields_for_index=fields_for_index, # Pass field selection to OMem
+ fields_for_index=fields_for_index,
+ track_sources=True, # source ledger for per-document rollback (#84)
)
# Store label extractor for visualization
self._item_label_extractor = item_label_extractor
@@ -344,12 +345,21 @@ class AutoSet(BaseAutoType[AutoSetSchema[ItemSchema]], Generic[ItemSchema]):
"""
self._data_memory.build_index(force=force)
- def search(self, query: str, top_k: int = 3) -> list[ItemSchema]:
+ def search(
+ self,
+ query: str,
+ top_k: int = 3,
+ *,
+ source_ids: list[str] | None = None,
+ tags: list[str] | None = None,
+ ) -> list[ItemSchema]:
"""Searches items in the set using semantic similarity.
Args:
query: Search query string.
top_k: Number of results to return.
+ source_ids: Optional scope — only items contributed by these source documents.
+ tags: Optional scope — only items from sources carrying any of these tags.
Returns:
List of relevant items.
@@ -359,7 +369,9 @@ class AutoSet(BaseAutoType[AutoSetSchema[ItemSchema]], Generic[ItemSchema]):
return []
if not self._data_memory.has_index():
raise ValueError("Index not built. Call build_index() first.")
- return self._data_memory.search(query, top_k=top_k)
+ return self._data_memory.search(
+ query, top_k=top_k, source_ids=source_ids, tags=tags
+ )
# ==================== Index Storage ====================