History

Yiorgis Gozadinos 771ac9c96c Register the optional capabilities where agents are composed The README feature list and the overview stopped at the analysis capability. Both examples and the app backend composed agents without the capabilities the documentation recommends alongside an evidence capability. custom_agent.py ran each input as an independent agent run, so it needed a state dict and a carried history before compaction could mean anything there: without state the evidence record is empty, and earlier evidence would reduce to receipts retaining nothing.		2026-08-13 15:04:05 +03:00
..
backend	Register the optional capabilities where agents are composed	2026-08-13 15:04:05 +03:00
frontend	Update dependencies for security advisories	2026-08-13 12:44:07 +03:00
.env.example	Update docs for app	2026-01-13 12:18:13 +02:00
docker-compose.dev.yml	Bind app example backend to loopback and document its lack of auth	2026-07-08 11:37:03 +03:00
docker-compose.yml	Bind app example backend to loopback and document its lack of auth	2026-07-08 11:37:03 +03:00
haiku.rag.yaml.example	replace fixed-radius expansion with section-bounded algorithm	2026-04-16 12:11:53 +03:00
README.md	Bind app example backend to loopback and document its lack of auth	2026-07-08 11:37:03 +03:00

README.md

haiku.rag Chat App

A conversational RAG interface built with CopilotKit and pydantic-ai's AG-UI protocol.

Note: An illustrative example meant as a starting point, with no authentication. The compose files bind the backend to 127.0.0.1; don't expose it to an untrusted network.

Prerequisites

Docker and Docker Compose
A haiku.rag database (created via the haiku-rag CLI)
An LLM API key (Anthropic, OpenAI, or local Ollama)

Quick Start

Set up environment variables:

cp .env.example .env
# Edit .env with your API keys and database path

Configure the LLM and embedding models:

cp haiku.rag.yaml.example haiku.rag.yaml
# Edit haiku.rag.yaml to configure your models

Start the app:
```
docker compose up -d
```
Open the chat interface: http://localhost:3000

Configuration

Environment Variables

Variable	Description	Required
`DB_PATH`	Path to your haiku.rag LanceDB database	Yes
`ANTHROPIC_API_KEY`	Anthropic API key	One LLM key required
`OPENAI_API_KEY`	OpenAI API key	One LLM key required
`OLLAMA_BASE_URL`	Ollama server URL (default: `http://host.docker.internal:11434`)	For local models
`LOGFIRE_TOKEN`	Pydantic Logfire token for debugging	No

haiku.rag.yaml

Configure the LLM, embeddings, and search settings:

qa:
  model:
    provider: anthropic  # or openai, ollama
    name: claude-sonnet-4-20250514

embeddings:
  model:
    provider: ollama
    name: nomic-embed-text

search:
  limit: 10

See haiku.rag.yaml.example for all options.

Development

For local development with hot reloading:

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

Backend code changes reload automatically
Frontend available at http://localhost:3000
Backend API at http://localhost:8001

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Frontend     │────▶│     Backend     │────▶│   haiku.rag     │
│  (CopilotKit)   │     │  (pydantic-ai)  │     │   (LanceDB)     │
│  localhost:3000 │     │  localhost:8001 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Backend Endpoints

Endpoint	Method	Description
`/v1/chat/stream`	POST	AG-UI chat streaming
`/api/documents`	GET	List documents in database
`/api/info`	GET	Database statistics
`/api/visualize/{chunk_id}`	GET	Visual grounding for chunks
`/health`	GET	Health check

Chat Capabilities

The chat can:

Search your documents with hybrid vector + full-text search
Answer questions with citations from your knowledge base
Filter by document when you ask about specific files
Show visual grounding for PDF/image sources