haiku.rag
Agentic RAG that answers questions about your own documents with citations to page numbers and section headings. It runs on an embedded LanceDB database with open models through Ollama by default, so no server or API key is needed. Any provider Pydantic AI supports works in their place, and the same database can live on S3, GCS, Azure or LanceDB Cloud.
Built on LanceDB, Pydantic AI and Docling. Documentation: ggozad.github.io/haiku.rag.
Features
- Ingest PDFs, office documents, HTML, Markdown and images with Docling, in-process or on docling-serve. The stored DoclingDocument keeps headings, tables, pictures and page provenance.
- Search with hybrid vector and full-text retrieval, optional reranking (cross-encoders, Jina, Cohere, Zero Entropy, vLLM, OpenRouter), section-aware context expansion, and image search with a multimodal embedder (vLLM, OpenRouter, VoyageAI, Cohere). Across several named databases at once.
- Answer with the RAG capability: it searches, runs sandboxed Python over the documents for counting and aggregation, and cites page numbers and headings. Vision models receive the figures. Optional capabilities compact earlier evidence in long conversations and require every answer to declare its grounding.
- Check a citation by drawing its chunk on the page image, from the CLI, the chat TUI or Python.
- Integrate through the Python API, native Pydantic AI capabilities, plugin hooks that observe document writes and transform searches, an MCP server for Claude Code, Codex and Claude Desktop, and a reference web app.
- Operate with the
haiku-ingesterservice (filesystem, HTTP, S3 and WebDAV sources, a SQLite or Postgres job queue with retries, a control plane and dashboard), tags and rollback, vacuum, andhaiku-rag doctorhealth checks.
Installation
Python 3.12 or newer.
pip install haiku.rag # Docling, the VoyageAI and Cohere embedders, every reranker, the TUI
pip install haiku.rag-slim # the core, with extras chosen by you
The ingester, S3 access and model providers other than Ollama and OpenAI-compatible endpoints are extras. See Installation.
Quick start
The default configuration uses Ollama for embeddings and answers. The quickstart covers the models to pull and using OpenAI instead.
haiku-rag init # create the database
haiku-rag add-src paper.pdf # index a file, URL or directory
haiku-rag search "attention mechanism"
haiku-rag ask "What datasets were used for evaluation?"
haiku-rag ask "How many documents mention transformers?"
haiku-rag ask "Does this figure match the spec?" --image figure.png
haiku-rag chat # multi-turn chat in the terminal
Continuous ingestion from configured sources runs as a separate service, with the ingester extra (pip install 'haiku.rag[ingester]'):
haiku-ingester serve
Python API
from haiku.rag.client import HaikuRAG
async with HaikuRAG("knowledge.lancedb", create=True) as rag:
await rag.create_document_from_source("paper.pdf")
await rag.create_document_from_source("https://arxiv.org/pdf/1706.03762")
results = await rag.search("self-attention")
for result in results:
print(f"{result.score:.2f} | p.{result.page_numbers} | {result.content[:100]}")
answer, citations = await rag.ask("What is the complexity of self-attention?")
print(answer)
for cite in citations:
print(f" [{cite.chunk_id}] p.{cite.page_numbers}: {cite.content[:80]}")
To compose your own agent, see Capabilities.
MCP server
haiku-rag mcp --stdio
The server gives an assistant search, document reading and a Python sandbox over the documents. In Claude Code, the plugin registers it with a skill:
claude plugin marketplace add ggozad/haiku.rag
claude plugin install haiku-rag
Codex and Claude Desktop setup is in the MCP docs.
Examples
- Docker setup: docling-serve, the ingester and the MCP server
- Web application: chat, ingestion, inspector and doctor in the browser
Documentation
- Quickstart: install, index, chat
- Installation: packages and extras
- Architecture: how a document becomes a cited answer
- CLI and Chat and inspector
- Capabilities: native Pydantic AI capabilities
- Configuration: every setting, and tuning
- Ingester, MCP and remote processing
- Python API and custom pipelines
- Benchmarks and the changelog
License
MIT.
mcp-name: io.github.ggozad/haiku-rag
1 maintainer
Metadata
1 maintainer
Release files for haiku.rag 0.99.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| haiku_rag-0.99.0.tar.gz | 668.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| haiku_rag-0.99.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 676.0 kB
Release files / haiku_rag-0.99.0.tar.gz
| Download URL | haiku_rag-0.99.0.tar.gz |
|---|---|
| Size | 668.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f62a105a92e4775eeb0aa6615837dcdc2baffc01e7355dddd820dc629a04f0d
|
|
BLAKE2b-256 checksum How to use checksums |
ce270c0cdb459b3b60e34c21ff1a5a97341e577bf3bdd983308858cab397ba24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / haiku_rag-0.99.0-py3-none-any.whl
| Download URL | haiku_rag-0.99.0-py3-none-any.whl |
|---|---|
| Size | 7.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1146c0770f893f4328a135a1a4e9c25c0de1c3ea5172c6cdbd669bb0c733e70
|
|
BLAKE2b-256 checksum How to use checksums |
a14324757ca083a543807aa7cfb48c36ecdc0de453ed3431b431806ff00406b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for haiku.rag 0.99.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
