API reference

Every public symbol has exactly one canonical module. The top-level fastrag package re-exports the handful used in almost every script — Document, ContentFormat, Pipeline, Policy, Source — and both forms are equivalent. Names reachable only through a _-prefixed module are internal and may change without notice; see Architecture for why.

Symbol	Canonical module
Every exception	fastrag.exceptions

fastrag.ingestion is the ingestion pipeline. Two types it produces or depends on are shared beyond ingestion, so each lives at the top level instead of under fastrag.ingestion: Document (parsed/chunked/embedded by ingestion, but also what retrieval, querying, serving, and benchmarking will consume) at fastrag.models, and VectorStore (written at ingest time, read at query time) at fastrag.vector_store.

Symbol	Canonical module
Source	fastrag.ingestion (from fastrag.ingestion.models)
Document, ContentFormat	fastrag.models — shared by retrieval, querying, serving and benchmarking, not ingestion-only, so it is not re-exported from fastrag.ingestion
Policy	fastrag.ingestion (from fastrag.ingestion.policy)
Filter, MediaTypeFilter, URLFilter, ContentFormatFilter	fastrag.ingestion.filters
PipelineEvent and its subclasses (StepStarted, StepProgress, StepCompleted, StepFailed, ItemFailed, DocumentFetched, DocumentParsed, DocumentChunked, DocumentEmbedded, DocumentSaved, DocumentsPruned)	fastrag.ingestion (from fastrag.ingestion.events)
PipelineStep, ExecutionContext, SourceStep, DocumentStep, RoutedStep	fastrag.ingestion (from fastrag.ingestion.steps.base)
Pipeline	fastrag.ingestion (from fastrag.ingestion.pipeline)
CacheStore, PostgresCache, SQLiteCache, SourceFreshnessValidator	fastrag.ingestion.cache
Logger, ConsoleLogger, DocumentsLogger, SourceLogger, SourceListLogger, SourceTreeLogger, ChunkLogger	fastrag.ingestion.logger
Fetcher, SitemapCrawler, WebCrawler, FileSource, LocalFileFetcher, Sources	fastrag.ingestion.steps.fetching
Parser, ParserRouter, HtmlParser, DefaultParser, DocusaurusParser, TrafilaturaParser, DoclingParser	fastrag.ingestion.steps.parsing
Chunker, ChunkerRouter, CharacterTextSplitter, RecursiveCharacterTextSplitter, HeadingChunker, DoclingChunker, SemanticChunker, EmbeddingSemanticChunker, LangchainSemanticChunker, StructureAwareChunker, Tokenizer, TiktokenTokenizer, Utf8ByteTokenizer, build_embedding_text, ChatBoundaryRefiner, RefinementResult, ChunkValidation, validate_structure_chunks	fastrag.ingestion.steps.chunking
Embedder, Model2VecEmbedder, OpenAIEmbedder	fastrag.ingestion.steps.embedding
VectorStore, ChromaVectorStore, MilvusVectorStore, OpenSearchVectorStore	fastrag.vector_store

fastrag.normalization interprets parsed content into source-preserving trees.

Symbol	Canonical module
NormalizedDocument, NormalizedNode, SourceSpan, CoverageUnit, Exclusion, Diagnostic, Normalizer, NormalizerRegistry, TextNormalizer, MarkdownNormalizer, RstNormalizer, HtmlNormalizer	fastrag.normalization

fastrag.retrieval turns a query into the documents that answer it, on top of a VectorStore opened by the caller.

Symbol	Canonical module
SectionIndex, SectionContext, Retriever, VectorRetriever, BM25Retriever, HybridRetriever, RankFusion, ReciprocalRankFusion	fastrag.retrieval (VectorRetriever from fastrag.retrieval.vector)
LexicalStore	fastrag.lexical_store
RerankingRetriever	fastrag.retrieval (from fastrag.retrieval.reranking_retriever)
Reranker, CohereReranker	fastrag.retrieval.reranking
LanguageAwareRetriever, LanguageDetector, LinguaLanguageDetector	fastrag.retrieval (from fastrag.retrieval.language)

fastrag.query turns a retrieved-and-rendered prompt into a generated answer. QueryEngine composes a Retriever, a PromptTemplate, and a ChatModel into one ask/stream surface; chat models live under their own fastrag.query.llm subpackage, the same shape as embedders under fastrag.ingestion.steps.embedding.

Symbol	Canonical module
QueryEngine, Answer, SourcesChunk, TokenChunk, DoneChunk, StreamChunk	fastrag.query (from fastrag.query.engine)
PromptTemplate, DEFAULT_RAG_PROMPT, group_sources	fastrag.query (from fastrag.query.prompts.templates)
ChatModel, Message, OpenAIChatModel	fastrag.query.llm

fastrag.query.chat persists the conversations a serving layer builds on top of QueryEngine: anonymous sessions, the chats inside them, and the messages inside those. Storage only — no FastAPI, no HTTP types, no SSE.

Symbol	Canonical module
ChatStore, Session, Chat, ChatMessage, Page, MessageRole, FinishReason, ErrorCode, to_llm_history	fastrag.query.chat (from fastrag.query.chat.base)
PostgresChatStore	fastrag.query.chat (from fastrag.query.chat.postgres)

fastrag.benchmark scores a retrieval or query pipeline against a QA dataset: load a QADataset, run every sample through a Benchmark against a Retriever (retrieval metrics) or a QueryEngine (generation and operational metrics too), and compare runs with Comparison.

Symbol	Canonical module
Benchmark, BenchmarkTarget	fastrag.benchmark (from fastrag.benchmark.benchmark)
Comparison	fastrag.benchmark (from fastrag.benchmark.comparison)
QADataset, EvalSample, ColumnMapping	fastrag.benchmark (from fastrag.benchmark.datasets)
BenchmarkResult, SampleResult, StatusCounts	fastrag.benchmark (from fastrag.benchmark.results)
Metric, DistributionSummary, QueryOutcome	fastrag.benchmark.metrics (from fastrag.benchmark.metrics.base)
Recall, Precision, MRR, NDCG, HitRate, RetrievalMetric	fastrag.benchmark.metrics (from fastrag.benchmark.metrics.retrieval)
TokenOverlap, Faithfulness, AnswerRelevancy, Correctness, JudgeMetric	fastrag.benchmark.metrics (from fastrag.benchmark.metrics.generation)
Latency, TokenUsage, Cost	fastrag.benchmark.metrics (from fastrag.benchmark.metrics.operational)

fastrag.serve is the FastAPI app that exposes a QueryEngine plus a ChatStore as the /v1 chats API over SSE. The app owns no database engine and no ORM session — it is a thin adapter over the two collaborators a caller hands to create_app().

Symbol	Canonical module
create_app	fastrag.serve (from fastrag.serve.app)
ServeConfig	fastrag.serve (from fastrag.serve.config)
CLI	fastrag.serve (from fastrag.serve.cli)
cleanup_expired, CleanupReport	fastrag.serve (from fastrag.serve.cleanup)

The full tree, generated from docstrings:

fastrag

fastrag — SDK for building RAG chatbots from dynamic sources.