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

```bash
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 |
|---------|-------------|
| Filter documents | Select documents to restrict searches |
| Show context | View current session context |
| 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
- Clearing chat resets session state but preserves document filter

## 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
- Session context that summarizes conversation history
- Settings panel for background context configuration

### Quick Start

```bash
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:

```bash
# 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:

```yaml
# 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:

```bash
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

```bash
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.