haiku.rag/docs/apps.md

Applications

Three interactive applications for working with your knowledge base.

Chat TUI

Conversational RAG from the terminal with streaming responses and session memory.

!!! note Requires the tui extra: pip install haiku.rag-slim[tui] (included in full haiku.rag package)

Usage

haiku-rag chat
haiku-rag chat --db /path/to/database.lancedb

Interface

The chat interface provides:

• Streaming responses with real-time tool execution indicators
• Expandable citations showing source document, pages, and headings
• Session memory for context-aware follow-up questions
• Visual grounding to inspect chunk source locations

Command Palette

Press Ctrl+P to open the command palette:

Command	Description
Memory	Edit initial context (before first message) or view session context (after)
Filter documents	Select documents to restrict searches
Show database info	View document/chunk counts and storage info
Visual grounding	View chunk source location in document
Clear chat	Clear chat history and reset session

Session Management

• Conversation history is maintained in memory for the session
• Previous Q/A pairs are used as context for follow-up questions
• Citations are tracked per response and can be inspected
• Document filter restricts all searches to selected documents
• Initial context can be set via CLI (--initial-context) or command palette
• Initial context is editable until the first message is sent, then becomes read-only
• Clearing chat resets session state, restores CLI-provided context, and unlocks editing

Web Application

Browser-based conversational RAG with a CopilotKit frontend.

Features

• Streaming chat with real-time tool execution visibility
• Expandable citations with source documents, pages, and headings
• Visual grounding to view chunk source locations in documents
• Document filter to restrict searches to selected documents
• Memory panel: set initial context before first message, view session context after

Quick Start

cd app
docker compose -f docker-compose.dev.yml up -d --build

• Frontend: http://localhost:3000
• Backend: http://localhost:8001

Architecture

• Backend: Starlette server with pydantic-ai AGUIAdapter
• Frontend: Next.js with CopilotKit
• Protocol: AG-UI for streaming chat

Configuration

Create a .env file in the app/ directory:

# API Keys (at least one required)
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key

# Database path
DB_PATH=/path/to/your/haiku.rag.lancedb

# Optional: Ollama base URL (if using local models)
OLLAMA_BASE_URL=http://localhost:11434

# Optional: Logfire for observability
LOGFIRE_TOKEN=your-logfire-token

For full configuration, mount a haiku.rag.yaml file:

# app/haiku.rag.yaml
qa:
  model:
    provider: anthropic
    name: claude-sonnet-4-20250514

API Endpoints

Endpoint	Method	Description
/v1/chat/stream	POST	AG-UI chat streaming
/api/documents	GET	List all documents
/api/info	GET	Database statistics
/api/visualize/{chunk_id}	GET	Visual grounding images (base64)
/health	GET	Health check

Development

Hot reload: The backend reloads automatically on file changes. For frontend changes:

docker compose -f docker-compose.dev.yml up -d --build frontend

Logfire debugging: If LOGFIRE_TOKEN is set, LLM calls are traced and available in the Logfire dashboard.

Inspector

TUI for browsing documents, chunks, and search results.

!!! note Requires the tui extra: pip install haiku.rag-slim[tui] (included in full haiku.rag package)

Usage

haiku-rag inspect
haiku-rag inspect --db /path/to/database.lancedb

Interface

Three panels display your data:

• Documents (left) - All documents in the database
• Chunks (top right) - Chunks for the selected document
• Detail View (bottom right) - Full content and metadata

Navigation

Key	Action
Tab	Cycle between panels
↑ / ↓	Navigate lists
/	Open search modal
c	Context expansion modal (when viewing a chunk)
v	Visual grounding modal (when viewing a chunk)
q	Quit

Mouse: Click to select, scroll to view content.

Search

Press / to open the full-screen search modal:

• Enter your query and press Enter to search
• Left panel: Search results with relevance scores [0.95] content preview
• Right panel: Full chunk content and metadata
• Use ↑ / ↓ to navigate results
• Press Enter on a result to navigate to that document/chunk
• Press Esc to close search

Search uses hybrid (vector + full-text) search across all chunks.

Context Expansion

Press c while viewing a chunk to see the expanded context that would be provided to the QA agent:

• Type-aware expansion: tables, code blocks, and lists expand to their complete structures
• Text content expands based on search.context_radius setting
• Includes metadata like source document, content type, and relevance score

Visual Grounding

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

!!! note Visual grounding requires documents with a stored DoclingDocument that includes page images. Text-only documents won't have visual grounding available.