haiku.rag/examples/ag-ui-research/README.md

Interactive Research Assistant

Research assistant powered by haiku.rag, Pydantic Graph, and AG-UI. Ask complex questions and watch the research process unfold in real-time.

Watch demo video

Features

• Multi-iteration research graph: Automated question decomposition, search, insight extraction, and gap analysis
• Intelligent evaluation: Confidence-based decision making with automatic iteration until sufficient information is gathered
• Live state synchronization: Real-time delta updates of research progress via AG-UI protocol
• Insight & gap tracking: Structured insights with provenance and automatic gap identification
• Rich reporting: Generates comprehensive research reports with findings, conclusions, and sources

Quick Start

Prerequisites

• Docker and Docker Compose
• A haiku.rag database with indexed documents
• Ollama (or configure another LLM provider)

Setup

1. Prepare your knowledge base

   Option A: Create a new database

   mkdir -p data
   haiku-rag add "Your documents here" --db data/haiku_rag.lancedb
   # Or add from files
   haiku-rag add-src document.pdf --db data/haiku_rag.lancedb
   

   Option B: Use an existing database

   Set the DB_PATH environment variable to point to your existing haiku.rag database:

   # In .env file
   DB_PATH=/path/to/your/existing/haiku_rag.lancedb
   

   Or export it before running docker compose:

   export DB_PATH=/path/to/your/existing/haiku_rag.lancedb
   docker compose up --build
   

   The database will be mounted as read-write, so the research assistant can access all documents in your existing knowledge base.

2. Configure haiku.rag

   cp haiku.rag.yaml.example haiku.rag.yaml
   # Edit haiku.rag.yaml to customize provider/model
   

   See haiku.rag configuration for details.

3. Set API keys (if using non-Ollama providers)

   cp .env.example .env
   # Edit .env to set your API keys
   OPENAI_API_KEY=your-key-here
   ANTHROPIC_API_KEY=your-key-here
   DB_PATH=/path/to/your/existing/haiku_rag.lancedb # If using an existing db.
   

4. Start the application

   docker compose up --build
   

5. Access the interface

   • Frontend: http://localhost:3000
   • Backend health: http://localhost:8000/health

How It Works

1. Ask a question: Type your research question in the chat
2. Plan phase: The research graph automatically:
   • Decomposes your question into targeted sub-questions
   • Gathers initial context about the topic
3. Research iterations: The graph autonomously:
   • Searches the knowledge base for each sub-question in parallel
   • Extracts structured insights with source provenance
   • Identifies information gaps and assesses confidence
   • Generates new follow-up questions for gaps
   • Iterates until confidence threshold is met or max iterations reached
4. Synthesis: Generates a comprehensive research report with:
   • Executive summary
   • Main findings with supporting evidence
   • Conclusions and recommendations
   • Source citations

Architecture

Agent + Graph Pattern

This example demonstrates the agent+graph architecture pattern:

1. Conversational Agent (agent.py):

   • Pydantic AI agent handles user conversations
   • Decides when to invoke the research tool based on user intent
   • Responds directly to greetings/casual chat without tools
   • Formats research results for the user

2. Research Graph (haiku.rag):

   • Multi-step research workflow invoked by the agent's tool
   • Autonomous execution with plan → search → analyze → decide → synthesize flow
   • Emits AG-UI events for real-time progress tracking

3. Shared Event Stream:

   • AGUIEmitter is shared between agent and graph
   • Events from both flow through a single stream to the frontend
   • Custom streaming endpoint (main.py) uses anyio memory streams for proper async handling

Components

• Backend (Python):

  • Uses published ghcr.io/ggozad/haiku.rag:latest Docker image as base
  • agent.py: Pydantic AI agent with run_research tool
  • main.py: Custom AG-UI streaming endpoint with anyio memory object streams
  • Real-time event forwarding from emitter to SSE stream
  • Filters out ACTIVITY_SNAPSHOT events (not yet supported by CopilotKit)

• Frontend (Next.js/React):

  • CopilotKit for AG-UI protocol integration
  • Split-pane UI: chat on left, live research state on right
  • Real-time state synchronization via Server-Sent Events (SSE)
  • StateDisplay component with collapsible sections for questions, insights, and gaps

Configuration

Configuration is done through haiku.rag.yaml (see haiku.rag.yaml.example):

• research.provider: LLM provider (default: ollama)
• research.model: Model name (default: gpt-oss:latest)
• research.max_iterations: Maximum research iterations (default: 3)
• research.confidence_threshold: Confidence threshold for completion (default: 0.8)
• research.max_concurrency: Parallel sub-question processing (default: 1)
• providers.ollama.base_url: Ollama endpoint (default: http://host.docker.internal:11434)

Environment variables (see .env.example):

• DB_PATH: Path to haiku.rag database (default: haiku_rag.lancedb)
• OPENAI_API_KEY, ANTHROPIC_API_KEY: API keys for cloud providers

For full configuration options, see haiku.rag configuration docs.