{
  "markdown": "# haiku.rag\n\n[![PyPI](https://img.shields.io/pypi/v/haiku.rag)](https://pypi.org/project/haiku.rag/)\n[![Python](https://img.shields.io/pypi/pyversions/haiku.rag)](https://pypi.org/project/haiku.rag/)\n[![Downloads](https://static.pepy.tech/badge/haiku-rag-slim/month)](https://pepy.tech/projects/haiku-rag-slim)\n[![Docs](https://img.shields.io/badge/docs-ggozad.github.io-blue)](https://ggozad.github.io/haiku.rag/)\n[![Tests](https://github.com/ggozad/haiku.rag/actions/workflows/test.yml/badge.svg)](https://github.com/ggozad/haiku.rag/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/ggozad/haiku.rag/graph/badge.svg)](https://codecov.io/gh/ggozad/haiku.rag)\n\nAgentic RAG that answers questions about your own documents with citations to page numbers and section headings. Runs locally on an embedded database, no server required.\n\nBuilt on [LanceDB](https://lancedb.com/), [Pydantic AI](https://ai.pydantic.dev/), and [Docling](https://docling-project.github.io/docling/). Full documentation at [ggozad.github.io/haiku.rag](https://ggozad.github.io/haiku.rag/).\n\n## Features\n\n- **Hybrid search** — Vector + full-text with Reciprocal Rank Fusion\n- **Multimodal & cross-modal search** — Multimodal embedders (vLLM, VoyageAI, Cohere) put picture vectors in the same space as text; supports text-as-query → figure hits and image-as-query\n- **Question answering** — RAG capability with citations (page numbers, section headings)\n- **Vision QA** — Vision-capable models receive figure bytes alongside chunk text; attach your own images to questions in `ask`, `analyze` and the chat TUI\n- **Reranking** — local cross-encoders, Cohere, Zero Entropy, or vLLM\n- **Analysis capability** — Complex analytical tasks via sandboxed Python code execution (aggregation, computation, multi-document analysis)\n- **Evidence compaction** — Optional capability that replaces earlier questions' search results on the request with the evidence they cited, so long conversations stop resending everything they retrieved\n- **Citation policy** — Optional capability that requires every answer to declare what grounds it, including declaring that nothing does\n- **Conversational RAG** — Chat TUI and web application for multi-turn conversations with session memory\n- **Document structure** — Stores full [DoclingDocument](https://docling-project.github.io/docling/concepts/docling_document/), enabling structure-aware context expansion\n- **Multiple providers** — Embeddings: Ollama, OpenAI, VoyageAI, Cohere, LM Studio, vLLM (multimodal via `multimodal: true` on vLLM/VoyageAI/Cohere). QA: any model supported by Pydantic AI\n- **Multi-database search** — Search, ask, analyze, or chat across named databases with source attribution on results and citations\n- **Local-first** — Embedded LanceDB, no servers required. Also supports S3, GCS, Azure, and LanceDB Cloud\n- **CLI & Python API** — Full functionality from command line or code\n- **MCP server** — Expose as tools for AI assistants (Claude Desktop, etc.)\n- **Visual grounding** — View chunks highlighted on original page images\n- **Production ingester** — Long-lived `haiku-ingester` service with persistent SQLite queue, async worker pool with retries and a dead-letter queue, FS / HTTP / S3 / WebDAV source adapters, FastAPI control plane, and a browser dashboard for operators. See [docs/ingester.md](docs/ingester.md).\n- **Tags** — Name database states with `haiku-rag tag` and roll back to them\n- **Inspector** — TUI for browsing documents, chunks, and search results\n\n## Installation\n\n**Python 3.12 or newer required**\n\n### Full Package (Recommended)\n\n```bash\npip install haiku.rag\n```\n\nIncludes all features: document processing, all embedding providers, and rerankers.\n\nUsing [uv](https://docs.astral.sh/uv/)? `uv pip install haiku.rag`\n\n### Slim Package (Minimal Dependencies)\n\n```bash\npip install haiku.rag-slim\n```\n\nInstall only the extras you need. See the [Installation](https://ggozad.github.io/haiku.rag/installation/) documentation for available options.\n\n## Quick Start\n\n> **Note**: Requires an embedding provider (Ollama, OpenAI, etc.). See the [Tutorial](https://ggozad.github.io/haiku.rag/tutorial/) for setup instructions.\n\n```bash\n# Index a PDF\nhaiku-rag add-src paper.pdf\n\n# Search\nhaiku-rag search \"attention mechanism\"\n\n# Ask questions with citations\nhaiku-rag ask \"What datasets were used for evaluation?\"\n\n# Ask about an image (vision-capable model)\nhaiku-rag ask \"Does this figure match the spec in the design doc?\" --image figure.png\n\n# Analyze — complex analytical tasks via code execution\nhaiku-rag analyze \"How many documents mention transformers?\"\n\n# Interactive chat — multi-turn conversations with memory\nhaiku-rag chat\n\n# Continuously ingest from configured sources (FS, HTTP, S3, WebDAV)\nhaiku-ingester serve\n```\n\nSee [Configuration](https://ggozad.github.io/haiku.rag/configuration/) for customization options.\n\n## Python API\n\n```python\nfrom haiku.rag.client import HaikuRAG\n\nasync with HaikuRAG(\"knowledge.lancedb\", create=True) as rag:\n    # Index documents\n    await rag.create_document_from_source(\"paper.pdf\")\n    await rag.create_document_from_source(\"https://arxiv.org/pdf/1706.03762\")\n\n    # Search — returns chunks with provenance\n    results = await rag.search(\"self-attention\")\n    for result in results:\n        print(f\"{result.score:.2f} | p.{result.page_numbers} | {result.content[:100]}\")\n\n    # QA with citations\n    answer, citations = await rag.ask(\"What is the complexity of self-attention?\")\n    print(answer)\n    for cite in citations:\n        print(f\"  [{cite.chunk_id}] p.{cite.page_numbers}: {cite.content[:80]}\")\n```\n\nFor direct agent composition, see the [capabilities documentation](https://ggozad.github.io/haiku.rag/capabilities/).\n\n## MCP Server\n\nUse with AI assistants like Claude Code, Codex, and Claude Desktop:\n\n```bash\nhaiku-rag mcp --stdio\n```\n\nIn Claude Code, install the plugin, which registers the server and a skill:\n\n```bash\nclaude plugin marketplace add ggozad/haiku.rag\nclaude plugin install haiku-rag\n```\n\nIn Codex, install the same plugin from its marketplace:\n\n```bash\ncodex plugin marketplace add ggozad/haiku.rag\ncodex plugin add haiku-rag@haiku-rag\n```\n\nAdd to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"haiku-rag\": {\n      \"command\": \"haiku-rag\",\n      \"args\": [\"mcp\", \"--stdio\"]\n    }\n  }\n}\n```\n\nProvides search, document reading, and analysis tools directly in your AI assistant.\n\n## Examples\n\nSee the [examples directory](examples/) for working examples:\n\n- **[Docker Setup](examples/docker/)** - Complete Docker deployment with continuous ingestion (`haiku-ingester`) and MCP server\n- **[Web Application](app/)** - Full-stack conversational RAG with CopilotKit frontend\n\n## Documentation\n\nFull documentation at: https://ggozad.github.io/haiku.rag/\n\n- [Quickstart](https://ggozad.github.io/haiku.rag/tutorial/) - Provider setup and first ingestion\n- [Installation](https://ggozad.github.io/haiku.rag/installation/) - Packages and extras\n- [Configuration](https://ggozad.github.io/haiku.rag/configuration/) - YAML reference\n- [CLI](https://ggozad.github.io/haiku.rag/cli/) - Command reference\n- [Python API](https://ggozad.github.io/haiku.rag/python/) - Complete API docs\n- [Capabilities](https://ggozad.github.io/haiku.rag/capabilities/) - Native Pydantic AI RAG and analysis capabilities\n- [Tuning](https://ggozad.github.io/haiku.rag/tuning/) - Retrieval and answer-quality tuning\n- [Ingester](https://ggozad.github.io/haiku.rag/ingester/) - Production ingester for continuous indexing from FS, HTTP, S3, and WebDAV\n- [MCP](https://ggozad.github.io/haiku.rag/mcp/) - Model Context Protocol integration\n- [Remote processing](https://ggozad.github.io/haiku.rag/remote-processing/) - Offload conversion to docling-serve\n- [Applications](https://ggozad.github.io/haiku.rag/apps/) - Chat TUI, web app, and inspector\n- [Benchmarks](https://ggozad.github.io/haiku.rag/benchmarks/) - Performance benchmarks\n- [Changelog](https://ggozad.github.io/haiku.rag/changelog/) - Version history\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n<!-- mcp-name is used by the MCP registry to identify this server -->\nmcp-name: io.github.ggozad/haiku-rag\n",
  "bytes": 8218,
  "sha": "32b5dd435fbf12a6289e3fa935f3887ffe4221c975a49eb6ee2eb48bcd5c7817",
  "repo_slug": "ggozad/haiku.rag",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ggozad_haiku_rag_17f2e3d6/readme"
}