fastrag.query#

Querying: turning retrieved documents and a question into a generated answer.

QueryEngine composes a Retriever, a PromptTemplate, and a ChatModel into one ask/stream surface. Chat models live under fastrag.query.llm, separately from this package’s own re-exports, the same way embedders live under fastrag.ingestion.steps.embedding.

class fastrag.query.Answer(text, sources)[source]#

Bases: object

One generated answer, with its sources.

Parameters:

text (str)
sources (list[Document])

class fastrag.query.DoneChunk(answer)[source]#

Bases: object

The stream is finished; carries the assembled Answer.

Parameters:: answer (Answer)

class fastrag.query.QueryEngine(*, retriever, llm, prompt=PromptTemplate(template='Documents:\n{context}\n\nQuestion: {question}\n\nAnswer:', system="Answer the question in its own language, using only the documents provided. If they do not contain the answer, say so.\n\nPrefer documents written in the language of the question. Use a document in another language only for what none of those say. When several documents say the same thing, such as one page in different languages, use only the one in the language of the question.\n\nDo not cite documents inside the text. End the answer with one line that lists the number of every document you used, in square brackets and each only once, like [1][3]. Never write a document's number anywhere else in the answer."))[source]#

Bases: object

Answers one question by retrieving, then generating.

Takes a Retriever, not a VectorStore — so every retrieval strategy (VectorRetriever, RerankingRetriever) is available to the engine without it knowing any of them exist, and there is exactly one place retrieval is configured.

import os

from fastrag.query import QueryEngine
from fastrag.query.llm import OpenAIChatModel

engine = QueryEngine(
    retriever=retriever,
    llm=OpenAIChatModel(
        model=os.environ["FASTRAG_CHAT_MODEL"],
        api_key=os.environ["FASTRAG_CHAT_API_KEY"],
        base_url=os.environ["FASTRAG_CHAT_BASE_URL"],
    ),
)

answer = await engine.ask("What is a data space?")
print(answer.text, [source.id for source in answer.sources])

Parameters:

retriever (Retriever) – Where the context for each question comes from.
llm (ChatModel) – Generates the answer from the rendered prompt.
prompt (PromptTemplate) – Turns a question and its retrieved context into messages.

async ask(question, history=())[source]#

Retrieve, then generate the whole answer at once.

history is inserted into the messages sent to llm as prior turns, so a follow-up question can resolve against earlier context. It is sent to the model only — retrieval embeds question alone.

Parameters:

question (str)
history (Sequence[Message])

Return type:

Answer

async stream(question, history=())[source]#

Retrieve, then yield the answer as it generates.

Sources first, then one TokenChunk per delta, then a DoneChunk.

history is inserted into the messages sent to llm as prior turns, so a follow-up question can resolve against earlier context. It is sent to the model only — retrieval embeds question alone.

Parameters:

question (str)
history (Sequence[Message])

Return type:

AsyncIterator[SourcesChunk | TokenChunk | DoneChunk]

class fastrag.query.SourcesChunk(sources)[source]#

Bases: object

The retrieved context, sent once before the first TokenChunk.

Parameters:: sources (list[Document])

class fastrag.query.TokenChunk(token)[source]#

Bases: object

One text delta from the chat model.

Parameters:: token (str)

fastrag.query.group_sources(context)[source]#

Group retrieved chunks into the sources a prompt cites as [n].

Chunks sharing a page_url() (one page, and each page of a PDF apart) form one group, placed where the page’s best-ranked chunk was retrieved and holding its chunks in page order (chunk_index). A chunk with no URL is a group of its own. groups[n - 1] is what [n] cites: the serving layer maps an answer’s citations back to pages through this same function.

Parameters:: context (Sequence[Document])
Return type:: list[list[Document]]

Modules

`chat`	Chat persistence: sessions, chats, and messages.
`engine`	The `QueryEngine`: retrieval plus generation, one question at a time.
`llm`	Chat models: turning a conversation into a generated answer.
`prompts`	Prompt templates: retrieved documents plus a question to chat messages.