Skip to main content

agrag.retrieval.search_engine.SearchEngine

SearchEngine(*, graph_store:GraphStore, embedder:Embedder, vector_store:VectorStore | None = None, settings:RetrievalSettings | None = None, entity_labels:Sequence[str] | None = None, graph_schema:GraphSchema | None = None, tracer:Tracer | None = None) -> None

Retrieval's public entry point, independent of Graph.

Fans a query out to every method a Recipe names, fuses the results, and optionally reranks them. Constructed from its own stores. It does not depend on a Graph instance existing.

A tracer opens the retrieval spans and flows to every retriever and free function the engine calls. It is not pushed into graph_store, embedder or vector_store. Pass the same tracer to those when you build them, so their adapter spans nest under these retrieval spans.

Functions:

  • find_entity – Resolve a named entity to its top search hit, or None.
  • list_relationship_types – List the relationship types directly attached to an entity.
  • search – Run recipe's methods, fuse, expand, and optionally rerank.
  • traverse – Expand one resolved entity into its neighbours.

Attributes:

Parameters:

  • graph_store (GraphStore) – Always required. It backs entity and chunk search when vector_store is absent, and it always backs BFS.
  • embedder (Embedder) – Produces query vectors for dense and hybrid search.
  • vector_store (VectorStore | None) – Optional. When set, entity, chunk, and community search run hybrid_search there instead of GraphStore's native search. Graph.open(vector_store=...) provisions the collections and dual-writes every embedding this package ingests, so the two paths see the same data. Point it at a store that Graph.open provisioned: a missing collection makes each method that reads it fail, and search raises AllRetrievalMethodsFailedError when every method fails. Collections that exist but hold no records return no hits.
  • settings (RetrievalSettings | None) – Retrieval configuration; defaults from environment.
  • entity_labels (Sequence[str] | None) – The entity labels native entity search runs against, one vector index each, as provisioned by Graph.open. Retained as a checked input only: it must name exactly the labels graph_schema declares, since the schema is what native search and generated Cypher both read. Omit it and let the schema drive both. Ignored when a vector_store is configured.
  • graph_schema (GraphSchema | None) – The graph's declared schema, ground truth for native entity labels and for generated Cypher. None uses GENERIC.
  • tracer (Tracer | None) – Opens the search span and flows to every retriever and free function the engine calls. None opens no recorded span.

Raises:

  • ValueError – entity_labels does not name exactly the labels graph_schema declares.

find_entity​

find_entity(name:str, *, filters:SearchFilters | None = None) -> SearchResult | None

Resolve a named entity to its top search hit, or None.

Searches this engine's configured entity_labels by default. A filters.labels value, when set, overrides which labels are searched rather than narrowing within entity_labels. This is the same EntityRetriever behavior that the entity search of search() already relies on.

Parameters:

  • name (str) – The entity name (or description) to resolve.
  • filters (SearchFilters | None) – Scope to resolve within. An entity that exists only outside it resolves to None, the same as one that does not exist.

Returns:

  • SearchResult | None – The top-ranked SearchResult, or None when nothing matched.

graph_schema​

graph_schema: GraphSchema

The schema retrieval is grounded in, GENERIC when none was given.

list_relationship_types​

list_relationship_types(seed:SearchResult, *, relation_type_filter:str | None = None, direction:TraversalDirection = 'both', filters:SearchFilters | None = None) -> list[str]

List the relationship types directly attached to an entity.

Depth-1 only: it reports what is attached to the seed, never what lies past it.

Parameters:

  • seed (SearchResult) – The resolved entity to read attached types from, normally from find_entity.
  • relation_type_filter (str | None) – Only report this type, if present.
  • direction (TraversalDirection) – Which way to inspect relationships, relative to the seed entity.
  • filters (SearchFilters | None) – Scope that limits visible relationship types.

Returns:

  • list[str] – The distinct attached relationship type names.
search(query:str, recipe:Recipe, *, filters:SearchFilters | None = None) -> list[SearchResult]

Run recipe's methods, fuse, expand, and optionally rerank.

Runs recipe.methods concurrently and fuses their output first. When recipe.bfs is set, BFS runs as a second, sequential step seeded from the fused entity results. BFS results are fused into the same list a second time before reranking.

Parameters:

  • query (str) – The natural-language query text.
  • recipe (Recipe) – Which methods to run, whether to expand via BFS afterward, and which reranker, if any, follows.
  • filters (SearchFilters | None) – Constraints applied identically to every method.

Returns:

  • list[SearchResult] – Up to recipe.limit results, ranked highest-relevance first.

Raises:

  • AllRetrievalMethodsFailedError – Every method the recipe names failed. A method failing while others succeed is logged and its results are absent.
  • UnknownRecipeMethodError – The recipe names one or more methods that are not in the retriever registry. A misspelled method name is a configuration error. It is reported instead of silently returning no results.

traverse​

traverse(seed:SearchResult, *, relation_type:str | None = None, direction:TraversalDirection = 'both', depth:int = 1, limit:int = 10, community_expand:bool = False, community_top_k:int = 3, filters:SearchFilters | None = None) -> list[SearchResult]

Expand one resolved entity into its neighbours.

Parameters:

  • seed (SearchResult) – The resolved entity to expand from, normally from find_entity.
  • relation_type (str | None) – Restrict the traversal to this one relationship type.
  • direction (TraversalDirection) – Which way a hop walks each relationship, relative to the seed entity.
  • depth (int) – Maximum hops.
  • limit (int) – Maximum neighbours returned.
  • community_expand (bool) – Also fuse in the reports of communities overlapping the seed.
  • community_top_k (int) – Maximum community reports to add when community_expand is set.
  • filters (SearchFilters | None) – Scope for the traversal. Its relation_types is an allowlist. A relation_type argument cannot widen it. Its properties, document_ids, and labels constrain returned neighbour nodes.

Returns:

  • list[SearchResult] – The neighbouring entities, deduplicated, highest-ranked first, with any requested community reports fused in.

Raises:

  • ScopeDeniedError – relation_type names a type the caller's scope does not permit.