diff --git a/README.md b/README.md index 24a32046..2351b518 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,19 @@ Agentic RAG built on [LanceDB](https://lancedb.com/), [Pydantic AI](https://ai.p ## Features - **Hybrid search** — Vector + full-text with Reciprocal Rank Fusion -- **Reranking** — MxBAI, Cohere, Zero Entropy, or vLLM - **Question answering** — QA agents with citations (page numbers, section headings) +- **Reranking** — MxBAI, Cohere, Zero Entropy, or vLLM - **Research agents** — Multi-agent workflows via pydantic-graph: plan, search, evaluate, synthesize - **Conversational RAG** — Chat TUI and web application for multi-turn conversations with session memory - **Document structure** — Stores full [DoclingDocument](https://docling-project.github.io/docling/concepts/docling_document/), enabling structure-aware context expansion -- **Visual grounding** — View chunks highlighted on original page images -- **Time travel** — Query the database at any historical point with `--before` - **Multiple providers** — Embeddings: Ollama, OpenAI, VoyageAI, LM Studio, vLLM. QA/Research: any model supported by Pydantic AI - **Local-first** — Embedded LanceDB, no servers required. Also supports S3, GCS, Azure, and LanceDB Cloud -- **MCP server** — Expose as tools for AI assistants (Claude Desktop, etc.) -- **File monitoring** — Watch directories and auto-index on changes -- **Inspector** — TUI for browsing documents, chunks, and search results - **CLI & Python API** — Full functionality from command line or code +- **MCP server** — Expose as tools for AI assistants (Claude Desktop, etc.) +- **Visual grounding** — View chunks highlighted on original page images +- **File monitoring** — Watch directories and auto-index on changes +- **Time travel** — Query the database at any historical point with `--before` +- **Inspector** — TUI for browsing documents, chunks, and search results ## Installation @@ -29,21 +29,25 @@ Agentic RAG built on [LanceDB](https://lancedb.com/), [Pydantic AI](https://ai.p ### Full Package (Recommended) ```bash -uv pip install haiku.rag +pip install haiku.rag ``` Includes all features: document processing, all embedding providers, and rerankers. +Using [uv](https://docs.astral.sh/uv/)? `uv pip install haiku.rag` + ### Slim Package (Minimal Dependencies) ```bash -uv pip install haiku.rag-slim +pip install haiku.rag-slim ``` -Install only the extras you need. See the [Installation](https://ggozad.github.io/haiku.rag/installation/) documentation for available options +Install only the extras you need. See the [Installation](https://ggozad.github.io/haiku.rag/installation/) documentation for available options. ## Quick Start +> **Note**: Requires an embedding provider (Ollama, OpenAI, etc.). See the [Tutorial](https://ggozad.github.io/haiku.rag/tutorial/) for setup instructions. + ```bash # Index a PDF haiku-rag add-src paper.pdf @@ -139,4 +143,9 @@ Full documentation at: https://ggozad.github.io/haiku.rag/ - [Benchmarks](https://ggozad.github.io/haiku.rag/benchmarks/) - Performance benchmarks - [Changelog](https://ggozad.github.io/haiku.rag/changelog/) - Version history +## License + +This project is licensed under the [MIT License](LICENSE). + + mcp-name: io.github.ggozad/haiku-rag diff --git a/docs/apps.md b/docs/apps.md index 635b611d..1d952cfe 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -25,6 +25,8 @@ The chat interface provides: - Session memory for context-aware follow-up questions - Visual grounding to inspect chunk source locations +![Chat TUI interface](img/tui-qa.svg) + ### Command Palette Press `Ctrl+P` to open the command palette: @@ -146,6 +148,8 @@ Three panels display your data: - **Chunks** (top right) - Chunks for the selected document - **Detail View** (bottom right) - Full content and metadata +![Inspector search](img/inspector-search.svg) + ### Navigation | Key | Action | @@ -182,10 +186,21 @@ Press `c` while viewing a chunk to see the expanded context that would be provid ### Visual Grounding +Visual grounding shows exactly where a chunk appears in the original document by highlighting its bounding box on the page image. This helps verify chunk boundaries and understand how content was extracted. + Press `v` while viewing a chunk to see page images with the chunk's location highlighted: -- Use `←` / `→` arrow keys to navigate between pages -- Requires documents processed with Docling that include page images +- Bounding boxes show the exact region of the page that maps to the chunk +- Use `←` / `→` arrow keys to navigate between pages when a chunk spans multiple pages +- Press `Esc` to close the modal -!!! note - Visual grounding requires documents with a stored DoclingDocument that includes page images. Text-only documents won't have visual grounding available. +![Visual grounding modal](img/tui-visual-grounding.png) + +#### Requirements + +- **Page images**: Documents must be processed with Docling's page image extraction enabled (default for PDFs) +- **Terminal image support**: Your terminal must support inline images (e.g., iTerm2, WezTerm, Kitty). Terminals without image support will show a placeholder message. +- **DoclingDocument storage**: Text-only documents (plain text, markdown added via `add`) don't have visual grounding available + +!!! tip + You can also view visual grounding from the command line with `haiku-rag visualize `. See [CLI documentation](cli.md#visualize-chunk) for details. diff --git a/docs/img/tui-qa.svg b/docs/img/tui-qa.svg new file mode 100644 index 00000000..4ebe8b61 --- /dev/null +++ b/docs/img/tui-qa.svg @@ -0,0 +1,306 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + haiku.rag Chat + + + + + + + + + + ⭘haiku.rag Chat + +█ +█You: +█ +█What did Guth propose about the inflationary era's effect on the Universe's flatness? +█ +█ +█✓Asking"What did Guth propose about the inflationary era's effect on the Universe's flatness?" +█ +█Assistant: +█ +█Alan Guth argued that a brief period of rapid, exponential expansion—inflation—would drive the Universe’s spatial curvature toward zero, +█effectively making the cosmos spatially flat. In his 1981 paper he showed that as the scale factor grows exponentially, the curvature term in +█the Friedmann equations falls off like the square of the scale factor, rapidly pushing the density parameter Ω toward 1. Thus inflation solves +█the flatness problem by flattening the geometry to an unobservable degree, leaving Ωtot extremely close to unity (≈ 1.0 ± 10⁻³²). +█ +█ + + +█Sources (2) + +▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ +█▼ [1] 2408.13427v2 (p.8) +█ +█The high spatial-resolution (0.5 deg) COBE results that revealed the amplitude and angular scale of the fluctuations would not be available +█until after ~2000. Nonetheless, the upper limits on fluctuation amplitudes and the large-scale isotropy of the CMB already imposed an +█initial condition for simulations of the present-day large-scale structure. The simulations suggested that including a cosmological +█constant or not were equally consistent with observed large-scale structure. +█ +█Semi-Empirica... +█ +█ +█Section: Semi-Empirical Evidence for a Flat Geometry +█ +█Source: file:///Users/ggozad/.cache/haiku.rag/evaluations/arxiv_pdfs/2408.13427v2.pdf +█ +█ +▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ +▶ [2] 2408.13427v2 (p.3, 4) + + + + + + + + + + + + + + + +▊▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▎ +▊Ask a question...▎ +▊▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▎ +▏^p palette + + + diff --git a/docs/img/tui-visual-grounding.png b/docs/img/tui-visual-grounding.png new file mode 100644 index 00000000..056b95d5 Binary files /dev/null and b/docs/img/tui-visual-grounding.png differ diff --git a/docs/index.md b/docs/index.md index fbfcb0b9..d3d90564 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,17 +5,19 @@ Agentic RAG built on [LanceDB](https://lancedb.com/), [Pydantic AI](https://ai.p ## Features - **Hybrid search** — Vector + full-text with Reciprocal Rank Fusion -- **Reranking** — MxBAI, Cohere, Zero Entropy, or vLLM - **Question answering** — QA agents with citations (page numbers, section headings) +- **Reranking** — MxBAI, Cohere, Zero Entropy, or vLLM - **Research agents** — Multi-agent workflows via pydantic-graph: plan, search, evaluate, synthesize - **Conversational RAG** — Chat TUI and web application for multi-turn conversations with session memory -- **Document structure** — Stores full [DoclingDocument](https://docling-project.github.io/docling/concepts/docling_document/), enabling structure-aware context expansion and visual grounding +- **Document structure** — Stores full [DoclingDocument](https://docling-project.github.io/docling/concepts/docling_document/), enabling structure-aware context expansion - **Multiple providers** — Embeddings: Ollama, OpenAI, VoyageAI, LM Studio, vLLM. QA/Research: any model supported by Pydantic AI - **Local-first** — Embedded LanceDB, no servers required. Also supports S3, GCS, Azure, and LanceDB Cloud -- **MCP server** — Expose as tools for AI assistants (Claude Desktop, etc.) -- **File monitoring** — Watch directories and auto-index on changes -- **Inspector** — TUI for browsing documents, chunks, and search results - **CLI & Python API** — Full functionality from command line or code +- **MCP server** — Expose as tools for AI assistants (Claude Desktop, etc.) +- **Visual grounding** — View chunks highlighted on original page images +- **File monitoring** — Watch directories and auto-index on changes +- **Time travel** — Query the database at any historical point with `--before` +- **Inspector** — TUI for browsing documents, chunks, and search results ## Quick Start diff --git a/docs/tutorial.md b/docs/tutorial.md index adaa08e8..c84312a8 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -86,21 +86,21 @@ Now you can view your [LanceDB](https://lancedb.com/) database, and the embeddin haiku-rag info ``` -You should see output like: +You should see output similar to: ``` haiku.rag database info path: /Users/moo/Library/Application Support/haiku.rag/haiku.rag.lancedb - haiku.rag version (db): 0.20.0 + haiku.rag version (db): x.y.z embeddings: openai/text-embedding-3-small (dim: 1536) documents: 3 (storage: 48.0 KB) chunks: 3 (storage: 52.0 KB) vector index: not created ────────────────────────────────────────────────────────────────────────────────── Versions - haiku.rag: 0.20.0 - lancedb: 0.25.2 - docling: 2.58.0 + haiku.rag: x.y.z + lancedb: ... + docling: ... ``` ## Asking questions and retrieving information