Skip to main content
Version: 0.0.5 (stable)

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.
  • search_candidates – Search candidates the extractor kept out of the graph.
  • 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 DEFAULT_SCHEMA.
  • 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, DEFAULT_SCHEMA 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.

search_candidates​

search_candidates(query:str, *, kind:CandidateKind | None = None, limit:int = 10) -> list[CandidateRecord]

Search candidates the extractor kept out of the graph.

Candidates are unreviewed and have no citation key. This search has no scope filter, so scoped callers must not expose it.

Parameters:

  • query (str) – The words to look for.
  • kind (CandidateKind | None) – Only this kind. None searches every kind.
  • limit (int) – The most candidates to return.

Returns:

  • list[CandidateRecord] – Matching pending and approved candidates, best match first.

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.