Skip to content

Retrieval API

Retriever

Retriever

Retriever(
    vector_store: BaseVectorStore,
    number_of_chunks: int,
    method: Literal["simple"] = "simple",
    search_mode: Literal["vector", "hybrid", "graph"] = "vector",
    ranker_strategy: str | None = None,
    ranker_k: int | None = None,
    ranker_alpha: float | None = None,
    search_kwargs: dict[str, Any] | None = None,
)

Class responsible for retrieving data from given vector store.

Parameters:

  • vector_store (BaseVectorStore) –

    Vector store / vector index to retrieve data from.

  • method (Literal['simple'], default: 'simple' ) –

    Method describing how data should be retrieved.

  • number_of_chunks (int) –

    Number of chunks to retrieve.

  • search_mode (Literal['vector', 'hybrid', 'graph'], default: "vector" ) –

    Search mode passed to the vector store: "vector", "hybrid", or "graph".

  • ranker_strategy (str | None, default: None ) –

    Ranking strategy for hybrid search: "rrf", "weighted", or "normalized".

  • ranker_k (int | None, default: None ) –

    Parameter k for the ranking function.

  • ranker_alpha (float | None, default: None ) –

    Alpha parameter for weighted ranking strategy.

Source code in ai4rag/rag/retrieval/retriever.py
def __init__(  # pylint: disable=too-many-arguments,too-many-positional-arguments
    self,
    vector_store: BaseVectorStore,
    number_of_chunks: int,
    method: Literal["simple"] = "simple",
    search_mode: Literal["vector", "hybrid", "graph"] = "vector",
    ranker_strategy: str | None = None,
    ranker_k: int | None = None,
    ranker_alpha: float | None = None,
    search_kwargs: dict[str, Any] | None = None,
):
    self._vector_store = vector_store
    self.method = method
    self.number_of_chunks = number_of_chunks
    self.search_mode = search_mode
    self.ranker_strategy = ranker_strategy
    self.ranker_k = ranker_k
    self.ranker_alpha = ranker_alpha
    self.search_kwargs = search_kwargs or {}

Methods:

retrieve

retrieve(query: str, **kwargs) -> list[AI4RAGChunk]

Retrieve relevant chunks from vector store.

Parameters:

  • query (str) –

    Question for which chunks should be retrieved.

Returns:

  • list[AI4RAGChunk] –

    Chunks with their metadata corresponding to the query.

Source code in ai4rag/rag/retrieval/retriever.py
def retrieve(self, query: str, **kwargs) -> list[AI4RAGChunk]:
    """Retrieve relevant chunks from vector store.

    Parameters
    ----------
    query : str
        Question for which chunks should be retrieved.

    Returns
    -------
    list[AI4RAGChunk]
        Chunks with their metadata corresponding to the query.
    """
    _number_of_chunks = kwargs.get("number_of_chunks", self.number_of_chunks)

    return self._vector_store.search(
        query,
        k=_number_of_chunks,
        search_mode=self.search_mode,
        ranker_strategy=self.ranker_strategy,
        ranker_k=self.ranker_k,
        ranker_alpha=self.ranker_alpha,
        **self.search_kwargs,
    )

Document Compressor

LLMDocumentCompressor uses a LangChain chat model to extract query-relevant, verbatim excerpts from AI4RAGChunk objects while preserving their metadata. AgenticRAG uses it for its context-overflow fallback. Both Retriever and LLMDocumentCompressor are exported from ai4rag.rag.retrieval.

LLMDocumentCompressor

LLMDocumentCompressor(chat_model: BaseChatModel)

Extract query-relevant excerpts from chunks with a LangChain chat model.

Parameters:

  • chat_model (BaseChatModel) –

    Model used to identify relevant passages in each chunk.

Source code in ai4rag/rag/retrieval/document_compressor.py
def __init__(self, chat_model: BaseChatModel):
    self._chat_model = chat_model

Methods:

compress

compress(query: str, chunks: list[AI4RAGChunk], *, config: RunnableConfig | None = None) -> list[AI4RAGChunk]

Return relevant excerpts while preserving each source chunk's metadata.

Parameters:

  • query (str) –

    Query used to determine which passages are relevant.

  • chunks (list[AI4RAGChunk]) –

    Retrieved chunks to compress.

  • config (RunnableConfig | None, default: None ) –

    Invocation configuration, including callbacks for compression model calls.

Returns:

  • list[AI4RAGChunk] –

    Extracted excerpts, omitting chunks with no relevant evidence.

Source code in ai4rag/rag/retrieval/document_compressor.py
def compress(
    self, query: str, chunks: list[AI4RAGChunk], *, config: RunnableConfig | None = None
) -> list[AI4RAGChunk]:
    """Return relevant excerpts while preserving each source chunk's metadata.

    Parameters
    ----------
    query : str
        Query used to determine which passages are relevant.
    chunks : list[AI4RAGChunk]
        Retrieved chunks to compress.
    config : RunnableConfig | None, optional
        Invocation configuration, including callbacks for compression model calls.

    Returns
    -------
    list[AI4RAGChunk]
        Extracted excerpts, omitting chunks with no relevant evidence.
    """
    excerpts = []
    excerpt_tokens = 0
    for chunk in chunks:
        response = self._chat_model.invoke(
            [
                SystemMessage(content=_EXCERPT_EXTRACTION_INSTRUCTIONS),
                HumanMessage(content=f"User question:\n{query}\n\nSource document:\n{chunk.text}"),
            ],
            config=config,
            max_completion_tokens=_MAX_COMPLETION_TOKENS,
        )
        excerpt = self._extract_excerpt(str(response.text), chunk.text)
        if excerpt is None:
            excerpt = chunk.text
        if excerpt:
            estimated_tokens = self._estimate_tokens(excerpt)
            if excerpt_tokens + estimated_tokens > _MAX_TOTAL_EXCERPT_TOKENS:
                break
            excerpts.append(AI4RAGChunk(text=excerpt, metadata=dict(chunk.metadata)))
            excerpt_tokens += estimated_tokens
    return excerpts

compression_stats staticmethod

compression_stats(original: list[AI4RAGChunk], compressed: list[AI4RAGChunk]) -> dict[str, int]

Return JSON-safe estimated-token and chunk counts for one compression pass.

Source code in ai4rag/rag/retrieval/document_compressor.py
@staticmethod
def compression_stats(original: list[AI4RAGChunk], compressed: list[AI4RAGChunk]) -> dict[str, int]:
    """Return JSON-safe estimated-token and chunk counts for one compression pass."""
    return {
        "input_chunks": len(original),
        "retained_chunks": len(compressed),
        "dropped_chunks": len(original) - len(compressed),
        "original_tokens": sum(LLMDocumentCompressor._estimate_tokens(chunk.text) for chunk in original),
        "compressed_tokens": sum(LLMDocumentCompressor._estimate_tokens(chunk.text) for chunk in compressed),
        "max_completion_tokens": _MAX_COMPLETION_TOKENS,
    }