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 with human-in-the-loop control.

Watch demo video

Features

• Human-in-the-loop research: Review and modify questions at decision points, then continue searching or generate report
• Multi-iteration research graph: Automated question decomposition and parallel search
• Live state synchronization: Real-time delta updates of research progress via AG-UI protocol
• 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

   haiku-rag init --db data/haiku_rag.lancedb
   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. Pull the base image

   docker pull ghcr.io/ggozad/haiku.rag-slim:latest
   

5. Start the application

   docker compose up --build
   

6. 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 decomposes your question into targeted sub-questions
3. Decision point: Review the proposed questions in the right panel
   • Add new questions using the input field
   • Remove questions you don't need
   • Click Search to execute searches for pending questions
   • Click Generate Report to skip to synthesis (when you have enough answers)
4. Research iterations: After each search cycle, you return to a decision point where you can:
   • Review collected answers
   • Add follow-up questions based on findings
   • Continue searching or generate the final report
5. 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 with AG-UI client-side tool calls:

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

2. Interactive Research Graph (haiku.rag):

   • Multi-step research workflow invoked by the agent's tool
   • At decision points, emits AG-UI TOOL_CALL_START/ARGS/END events for human_decision
   • Waits for tool result via async queue before continuing

3. Client-Side Tool Handling (AG-UI pattern):

   • Frontend listens for human_decision tool calls via AG-UI events
   • Renders decision UI inline in chat when tool call is received
   • User decision sent directly to backend /v1/research/stream endpoint
   • Backend extracts tool result from messages and routes to waiting graph via async queue

4. Shared Event Stream:

   • AGUIEmitter is shared between agent and graph
   • Events from both flow through a single stream to the frontend
   • STATE_DELTA events sync research state to frontend in real-time

Components

• Backend (Python):

  • Uses published ghcr.io/ggozad/haiku.rag:latest Docker image as base
  • agent.py: Pydantic AI agent with run_research tool, manages ActiveResearch registry
  • main.py: Custom AG-UI streaming endpoint, extracts tool results from messages
  • Real-time event forwarding from emitter to SSE stream

• Frontend (Next.js/React):

  • AG-UI protocol integration for real-time streaming
  • Handles human_decision tool calls with inline decision UI
  • Split-pane UI: chat on left, live research state on right
  • Tool results sent directly to backend endpoint

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.