Skip to main content
Version: 0.0.7 (stable)

agrag.evidence.entities.entity_search

entity_search(store:GraphStore, embedder:Embedder, query:str, *, scope:frozenset[str], labels:Sequence[str] | None = None, mode:EvidenceSearchMode = EvidenceSearchMode.HYBRID, limit:int = DEFAULT_SEARCH_LIMIT, support_limit:int = DEFAULT_SUPPORT_LIMIT, vector_store:VectorStore | None = None, settings:RetrievalSettings | None = None, timeout:float | None = None) -> EntityResult

Find up to limit entities that match a query by name or by meaning.

The lexical leg matches the words of the query against the name of each entity. The semantic leg embeds the query and searches the embedding of each entity. The hybrid mode runs both and fuses the rankings with reciprocal rank fusion, or delegates fusion to an external store. A missing or offline index or vector collection gives index_not_ready.

An entity is returned only when a passage in scope mentions it. Its support lists up to support_limit visible passages, as evidence ids. An entity with passages in scope and no visible passage is returned with kind unsupported and an empty support list.

Parameters:

  • store (GraphStore) – The graph store to search.
  • embedder (Embedder) – Embeds the query for the semantic leg. The lexical leg does not use it.
  • query (str) – The query text. Lucene syntax is not applied: each word is searched as a plain term.
  • scope (frozenset[str]) – Keys of the documents whose passages may be used.
  • labels (Sequence[str] | None) – The entity labels to search. None discovers labels from graph indexes for native search, or entity name indexes for external search.
  • mode (EvidenceSearchMode) – Which legs to run.
  • limit (int) – The most entities to return. Must be positive.
  • support_limit (int) – The most supporting passages listed for each entity. Must be positive.
  • vector_store (VectorStore | None) – Optional external vector store. Placement is not validated by this function.
  • settings (RetrievalSettings | None) – Fusion configuration. None uses the defaults.
  • timeout (float | None) – Server-side transaction timeout in seconds for each store read. None uses the server's default.

Returns:

  • EntityResult – The entities, best first, with the status and the index state.

Raises:

  • ValueError – limit or support_limit is not positive.