Implementation:Run llama Llama index BaseAutoRetriever

Knowledge Sources	Run_llama_Llama_index
Domains	LLM Framework, Retrieval
Last Updated	2026-02-11 19:00 GMT

Overview

BaseAutoRetriever is an abstract base class that extends BaseRetriever to support automatic retrieval specification generation, where the retrieval parameters are dynamically determined from the query before executing retrieval.

Description

The BaseAutoRetriever class defines a two-phase retrieval pattern:

1. Spec generation: The query is analyzed (typically by an LLM) to produce a BaseModel retrieval specification that describes what to retrieve and how.
2. Retrieval execution: A concrete retriever is built from the generated spec, and the actual retrieval is performed using that retriever.

This pattern is useful for scenarios like auto-filtering vector store queries, where the LLM interprets a natural-language query and generates structured filter parameters (e.g., metadata filters, top-k values) before the vector search is executed.

The class defines three abstract methods that subclasses must implement:

• generate_retrieval_spec -- synchronous spec generation
• agenerate_retrieval_spec -- asynchronous spec generation
• _build_retriever_from_spec -- constructs a BaseRetriever and a potentially modified QueryBundle from the spec

The concrete _retrieve and _aretrieve methods orchestrate the two-phase flow by calling the spec generation methods followed by the retriever build and execution.

Usage

Subclass BaseAutoRetriever when building retrievers that need to dynamically determine retrieval parameters from the user query. The primary use case is VectorIndexAutoRetriever, which uses an LLM to generate metadata filters and query transformations before performing vector search.

Code Reference

Source Location

• Repository: Run_llama_Llama_index
• File: llama-index-core/llama_index/core/base/base_auto_retriever.py
• Lines: 1-43

Signature

class BaseAutoRetriever(BaseRetriever):
    """Base auto retriever."""

    @abstractmethod
    def generate_retrieval_spec(
        self, query_bundle: QueryBundle, **kwargs: Any
    ) -> BaseModel: ...

    @abstractmethod
    async def agenerate_retrieval_spec(
        self, query_bundle: QueryBundle, **kwargs: Any
    ) -> BaseModel: ...

    @abstractmethod
    def _build_retriever_from_spec(
        self, retrieval_spec: BaseModel
    ) -> Tuple[BaseRetriever, QueryBundle]: ...

    def _retrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]: ...

    async def _aretrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]: ...

Import

from llama_index.core.base.base_auto_retriever import BaseAutoRetriever

I/O Contract

Inputs

Name	Type	Required	Description
query_bundle	QueryBundle	Yes	The query to generate a retrieval specification for and to retrieve against.
**kwargs	Any	No	Additional keyword arguments passed to spec generation methods.

Outputs

Name	Type	Description
return (generate_retrieval_spec)	BaseModel	A Pydantic model describing retrieval parameters (filters, top-k, etc.).
return (_build_retriever_from_spec)	Tuple[BaseRetriever, QueryBundle]	A configured retriever and optionally modified query bundle.
return (_retrieve / _aretrieve)	List[NodeWithScore]	Retrieved nodes with relevance scores.

Usage Examples

Basic Usage

from llama_index.core.base.base_auto_retriever import BaseAutoRetriever
from llama_index.core.schema import QueryBundle, NodeWithScore
from llama_index.core.bridge.pydantic import BaseModel
from typing import Any, List, Tuple

class MyAutoRetriever(BaseAutoRetriever):
    def generate_retrieval_spec(
        self, query_bundle: QueryBundle, **kwargs: Any
    ) -> BaseModel:
        # Use LLM to generate spec from query
        return my_llm_generate_spec(query_bundle)

    async def agenerate_retrieval_spec(
        self, query_bundle: QueryBundle, **kwargs: Any
    ) -> BaseModel:
        return await my_llm_agenerate_spec(query_bundle)

    def _build_retriever_from_spec(
        self, retrieval_spec: BaseModel
    ) -> Tuple["BaseRetriever", QueryBundle]:
        retriever = build_retriever(retrieval_spec)
        query = QueryBundle(query_str=retrieval_spec.query)
        return retriever, query

# Usage
auto_retriever = MyAutoRetriever()
nodes = auto_retriever.retrieve("Find documents about machine learning")

Related Pages

• Environment:Run_llama_Llama_index_Python_LlamaIndex_Core