Search Toolkit

Search Toolkit is a Python framework for building information retrieval (IR) systems. It provides components for ingestion, retrieval, and evaluation. It works across backends, and every component can be swapped.

LLMs aren't trained on your private data. To ground their answers in your documents, you need a retrieval pipeline that ingests, indexes, and searches your content. Search Toolkit provides the building blocks for that pipeline.

Ingestion includes:

• Multi-format extraction: PDF, DOCX, and PPTX through Mistral OCR, HTML, spreadsheets, emails, plain text
• File loading: Load from the local filesystem, S3, Google Cloud Storage, or Azure Blob Storage, or implement custom loaders for any source
• Flexible chunking: Character, token, markdown-aware, or separator-based splitting
• Enrichment: Enrich documents and chunks with custom metadata or LLM-generated summaries
• Indexing: Index into a Mistral Search Index

Retrieval includes:

• Search: Vector or hybrid search on the index in one call
• Custom retrieval: With retrieve, combine vector and keyword retrievers, match custom fields, and weight the fusion
• Filters: Narrow retrieve results by category, date, source, or any custom field

Ingestion transforms raw documents into searchable chunks. A FileLoader reads raw bytes from a source, a DocumentExtractor converts them into a structured document, a TextSplitter divides it into chunks, optional DocumentProcessor stages (such as a ChunkEnricher or SummaryEnricher) add metadata, and an Embedder produces vectors for indexing into a Mistral Search Index.

Retrieval finds relevant chunks for a given query. The search index runs the query through one of two methods: search for a vector or hybrid search, or retrieve for a retrieval query that you compose yourself, with filters.

Pipeline orchestrates ingestion. You can swap every ingestion component: use the built-in implementations or bring your own.

Install the core package:

uv add mistralai-search-toolkit

uv add mistralai-search-toolkit

The core package includes the Mistral Search Index backend, the default storage for Search Toolkit pipelines. Self-hosted backends such as Vespa and Postgres ship as extras.

Optional extras add specialized functionality:

Install extras with the core package:

uv add "mistralai-search-toolkit[extractor-pymupdf]"
uv add "mistralai-search-toolkit[extractor-pymupdf,storage-s3]"

uv add "mistralai-search-toolkit[extractor-pymupdf]"
uv add "mistralai-search-toolkit[extractor-pymupdf,storage-s3]"

All packages are available on PyPI.

• Everything is async. Await every index, service, and pipeline call, and run them inside an async function or with asyncio.run.
• Models are immutable. Document, DocumentChunk, their metadata, and SearchResult are frozen Pydantic models. To change one, create a copy with model_copy(update={...}).
• Pass request context in a context object. Every ingestion and retrieval call takes an optional IngestContext or RetrievalContext. To pass tenant IDs, tracing spans, or per-request Mistral API headers through the stack without adding arguments, subclass these context classes.

Before you build on a new index, check it end to end:

1. Check that (await service.get_index_info(name)).status is ready.
2. Ingest one document.
3. Check that a search or retrieve for a phrase from that document returns the document.

The Quickstart runs these three steps.

• Quickstart: build your first ingestion and retrieval pipeline end to end.
• Document model: understand Document, DocumentChunk, and the identity that ties them together.
• Embedding model: understand how the schema describes embedding vectors, separately from the embedder.
• Search index: set up your vector store.
• Ingestion: load, extract, chunk, enrich, and index your documents.
• Retrieval: query the index with search and retrieve.