danvics/haiku.rag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update docs

Browse source
This commit is contained in:
Yiorgis Gozadinos 2026-01-09 19:03:19 +02:00
parent bb61e8fab6
commit fc29b0c3f7
No known key found for this signature in database
6 changed files with 6 additions and 255 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
docs/agents.md
View file

@ -5,8 +5,6 @@ Two agentic flows are provided by haiku.rag:
- **Simple QA Agent** — a focused question answering agent
- **Research Graph** — a multi-step research workflow with question decomposition
For an interactive example using Pydantic AI and AG-UI, see the [Interactive Research Assistant](https://github.com/ggozad/haiku.rag/tree/main/examples/ag-ui-research) example ([demo video](https://vimeo.com/1128874386)).
See [QA and Research Configuration](configuration/qa-research.md) for configuring model, iterations, concurrency, and other settings.
## Simple QA Agent
@ -96,9 +94,6 @@ stateDiagram-v2
# Basic usage
haiku-rag research "How does haiku.rag organize and query documents?"
# With verbose output (shows progress)
haiku-rag research "How does haiku.rag organize and query documents?" --verbose
# With document filter
haiku-rag research "What are the key findings?" --filter "uri LIKE '%report%'"
```
@ -154,35 +149,6 @@ async with HaikuRAG(path_to_db) as client:
report = await graph.run(state=state, deps=deps)
```
**Streaming AG-UI events:**
```python
from haiku.rag.client import HaikuRAG
from haiku.rag.config import Config
from haiku.rag.graph.agui import stream_graph
from haiku.rag.graph.research.dependencies import ResearchContext
from haiku.rag.graph.research.graph import build_research_graph
from haiku.rag.graph.research.state import ResearchDeps, ResearchState
async with HaikuRAG(path_to_db) as client:
graph = build_research_graph(config=Config)
context = ResearchContext(original_question="What are the main features?")
state = ResearchState.from_config(context=context, config=Config)
deps = ResearchDeps(client=client)
async for event in stream_graph(graph, state, deps):
if event["type"] == "STEP_STARTED":
print(f"Starting step: {event['stepName']}")
elif event["type"] == "ACTIVITY_SNAPSHOT":
content = event["content"]
print(f" {content['message']}")
if "confidence" in content:
print(f" Confidence: {content['confidence']:.0%}")
elif event["type"] == "RUN_FINISHED":
report = event["result"]
print(report["executive_summary"])
```
### Filtering Documents
Restrict searches to specific documents via the `search_filter` parameter:
@ -196,35 +162,3 @@ report = await graph.run(state=state, deps=deps)
```
The filter applies to all search operations in the graph. See [Filtering Search Results](python.md#filtering-search-results) for available filter columns and syntax.
### Interactive Research Mode
Interactive mode provides human-in-the-loop control over the research process through a conversational interface.
**CLI usage:**
```bash
# Start interactive research mode
haiku-rag research --interactive
# Start with a specific question
haiku-rag research --interactive "How does X work?"
# With document filter
haiku-rag research --interactive --filter "uri LIKE '%report%'"
```
In interactive mode, you can:
- Chat with the assistant before starting research
- Review the generated sub-questions after planning
- Add, remove, or modify questions through natural conversation
- Execute searches and review collected answers
- Continue researching or synthesize when ready
For a web-based interactive experience, see the [AG-UI Research Example](https://github.com/ggozad/haiku.rag/tree/main/examples/ag-ui-research). The example demonstrates AG-UI client-side tool calling:
- Frontend handles `human_decision` tool calls via AG-UI `TOOL_CALL_*` events
- Decision UI rendered inline in the chat at each decision point
- Question editing (add/remove) and action buttons (Search, Generate Report)
- Tool results sent directly to the backend endpoint which queues decisions and continues the graph

41
docs/cli.md
View file

@ -148,11 +148,6 @@ Use deep QA for complex questions (multi-agent decomposition):
haiku-rag ask "What are the main features and architecture of haiku.rag?" --deep --cite
```
Show verbose output with deep QA:
```bash
haiku-rag ask "What are the main features and architecture of haiku.rag?" --deep --verbose
```
Filter to specific documents:
```bash
haiku-rag ask "What are the main findings?" --filter "uri LIKE '%paper%'"
@ -164,7 +159,6 @@ Flags:
- `--cite`: Include citations showing which documents were used
- `--deep`: Decompose the question into sub-questions answered in parallel before synthesizing a final answer
- `--verbose`: Show planning, searching, evaluation, and synthesis steps (only with `--deep`)
- `--filter`: Restrict searches to documents matching the filter (see [Filtering Search Results](python.md#filtering-search-results))
## Research
@ -175,43 +169,18 @@ Run the multi-step research graph:
haiku-rag research "How does haiku.rag organize and query documents?"
```
With verbose output to see progress:
```bash
haiku-rag research "How does haiku.rag organize and query documents?" --verbose
```
Filter to specific documents:
```bash
haiku-rag research "What are the key findings?" --filter "uri LIKE '%paper%'"
```
Interactive mode with human-in-the-loop:
```bash
# Start interactive research mode
haiku-rag research --interactive
# Start with a specific question
haiku-rag research --interactive "How does haiku.rag work?"
# With document filter
haiku-rag research --interactive --filter "uri LIKE '%docs%'"
```
Flags:
- `--verbose`: Show planning, searching previews, evaluation summary, and stop reason
- `--filter`: SQL WHERE clause to filter documents (see [Filtering Search Results](python.md#filtering-search-results))
- `--interactive` / `-i`: Start interactive research mode with human-in-the-loop decision points
Research parameters like `max_iterations`, `confidence_threshold`, and `max_concurrency` are configured in your [configuration file](configuration/index.md) under the `research` section.
When `--verbose` is set, the CLI consumes the research graph's AG-UI event stream, displaying step events and activity snapshots as agents progress through planning, search, evaluation, and synthesis. Without `--verbose`, only the final research report is displayed.
If you build your own integration, import `stream_graph` from `haiku.rag.graph.agui` to access AG-UI events (`STEP_STARTED`, `ACTIVITY_SNAPSHOT`, `STATE_SNAPSHOT`, `RUN_FINISHED`, etc.) and render them however you like while the graph is running.
## Server
Start services (requires at least one flag):
@ -225,16 +194,8 @@ haiku-rag serve --mcp --stdio
# File monitoring only
haiku-rag serve --monitor
# AG-UI server only
haiku-rag serve --agui
# Multiple services
# Both services
haiku-rag serve --monitor --mcp
haiku-rag serve --monitor --agui
haiku-rag serve --mcp --agui
# All services
haiku-rag serve --monitor --mcp --agui
# Custom MCP port
haiku-rag serve --mcp --mcp-port 9000

8
docs/configuration/index.md
View file

@ -106,14 +106,6 @@ search:
vector_index_metric: cosine # cosine, l2, or dot
vector_refine_factor: 30
agui:
host: "0.0.0.0"
port: 8000
cors_origins: ["*"]
cors_credentials: true
cors_methods: ["GET", "POST", "OPTIONS"]
cors_headers: ["*"]
prompts:
domain_preamble: "" # Prepended to all agent prompts
qa: null # Custom QA agent prompt (null = use default)

10
docs/mcp.md
View file

@ -102,17 +102,11 @@ After restarting Claude Desktop, you can ask Claude to search your documents, ad
## Running with Other Services
Combine MCP with file monitoring or AG-UI:
Combine MCP with file monitoring:
```bash
# MCP + file monitoring
haiku-rag serve --mcp --monitor
# MCP + AG-UI streaming
haiku-rag serve --mcp --agui
# All services
haiku-rag serve --mcp --monitor --agui
```
See [Server Mode](server.md) for details on file monitoring and AG-UI.
See [Server Mode](server.md) for details on file monitoring.

134
docs/server.md
View file

@ -1,10 +1,10 @@
# Server Mode
The server provides automatic file monitoring, MCP functionality, and AG-UI graph streaming.
The server provides automatic file monitoring and MCP functionality.
## Starting the Server
The `serve` command requires at least one service flag. You can enable file monitoring, MCP server, AG-UI server, or any combination:
The `serve` command requires at least one service flag. You can enable file monitoring, MCP server, or both:
### MCP Server Only
@ -116,133 +116,3 @@ The file monitor processes documents using [Docling](https://github.com/DS4SD/do
- RST (`.rst`)
URLs are also supported - the content is fetched and converted to markdown.
## AG-UI Server
The AG-UI server provides HTTP streaming of research graph execution using Server-Sent Events (SSE).
### Starting the AG-UI Server
```bash
haiku-rag serve --agui
```
This starts an HTTP server (default: http://0.0.0.0:8000) that exposes:
- `GET /health` - Health check endpoint
- `POST /v1/research/stream` - Research graph streaming endpoint
### Configuration
Configure the AG-UI server in your `haiku.rag.yaml`:
```yaml
agui:
host: "0.0.0.0"
port: 8000
cors_origins: ["*"]
cors_credentials: true
cors_methods: ["GET", "POST", "OPTIONS"]
cors_headers: ["*"]
```
- **host**: Bind address (default: `0.0.0.0`)
- **port**: Server port (default: `8000`)
- **cors_origins**: Allowed CORS origins (default: `["*"]`)
- **cors_credentials**: Allow credentials in CORS requests (default: `true`)
- **cors_methods**: Allowed HTTP methods (default: `["GET", "POST", "OPTIONS"]`)
- **cors_headers**: Allowed headers (default: `["*"]`)
### Using the Streaming Endpoint
The endpoint accepts POST requests with AG-UI RunAgentInput format and streams AG-UI events.
**Request format:**
```json
{
"threadId": "optional-thread-id",
"runId": "optional-run-id",
"state": {
"question": "What are the key features of haiku.rag?"
},
"messages": [],
"config": {}
}
```
**Example:**
```bash
curl -X POST http://localhost:8000/v1/research/stream \
-H "Content-Type: application/json" \
-d '{
"state": {
"question": "What are the key features of haiku.rag?"
}
}' \
--no-buffer
```
The `--no-buffer` flag ensures curl displays events as they arrive instead of buffering them.
**Note:** The `state` object can include:
- `question`: The question to answer (required)
- `max_iterations`: Maximum research iterations (optional, defaults to config)
- `confidence_threshold`: Confidence threshold for early termination (optional, defaults to config)
**Response:** Server-Sent Events stream with AG-UI protocol events:
- `RUN_STARTED` - Graph execution started
- `STATE_SNAPSHOT` - Current state snapshot
- `STATE_DELTA` - Incremental state changes (JSON Patch format)
- `STEP_STARTED` - Node execution started
- `STEP_FINISHED` - Node execution completed
- `ACTIVITY_SNAPSHOT` - Progress update with structured data
- `RUN_FINISHED` - Graph execution completed with result
- `RUN_ERROR` - Error during execution
Example event output:
```
data: {"type":"RUN_STARTED","threadId":"abc123","runId":"xyz789"}
data: {"type":"STATE_SNAPSHOT","snapshot":{"context":{"original_question":"What are the key features of haiku.rag?"},"iterations":0}}
data: {"type":"STEP_STARTED","stepName":"plan"}
data: {"type":"ACTIVITY_SNAPSHOT","messageId":"msg-1","activityType":"planning","stepName":"plan","content":{"message":"Created plan with 3 sub-questions","sub_questions":["What is X?","How does Y work?","Why is Z important?"]}}
data: {"type":"STEP_FINISHED","stepName":"plan"}
data: {"type":"STATE_DELTA","delta":[{"op":"replace","path":"/iterations","value":1}]}
data: {"type":"ACTIVITY_SNAPSHOT","messageId":"msg-2","activityType":"evaluating","stepName":"decide","content":{"message":"Confidence: 85%, Sufficient: Yes","confidence":0.85,"is_sufficient":true}}
data: {"type":"RUN_FINISHED","threadId":"abc123","runId":"xyz789","result":{"title":"Research Report","executive_summary":"..."}}
```
**Activity Event Structure:**
`ACTIVITY_SNAPSHOT` events include a `content` object with:
- `message` - Human-readable progress message (always present)
- `stepName` - The graph step emitting this activity (when available)
- Additional structured fields depending on the activity type:
- **Planning**: `sub_questions` (list of strings)
- **Searching**: `query` (string), `confidence` (float, on completion), `error` (string, on failure)
- **Evaluating**: `confidence` (float), `is_sufficient` (boolean), `new_questions` (list of strings)
The `message` field is always present for simple rendering, while structured fields enable richer UI features like displaying lists, charts, and detailed status information.
The endpoint follows the [AG-UI protocol](https://docs.ag-ui.com/concepts/events) for event streaming.
### Running Multiple Services
You can run any combination of services:
```bash
# File monitoring + AG-UI
haiku-rag serve --monitor --agui
# MCP + AG-UI
haiku-rag serve --mcp --agui
# All services
haiku-rag serve --monitor --mcp --agui
```

2
docs/tutorial.md
View file

@ -207,4 +207,4 @@ The following people are presenting talks at PyCon Finland 2025:
- **[Python API](python.md)** - Use haiku.rag in your Python applications
- **[Agents](agents.md)** - Deep QA and multi-agent research workflows
- **[Configuration](configuration/index.md)** - Complete YAML configuration reference
- **[Server Mode](server.md)** - File monitoring, MCP server, and AG-UI streaming
- **[Server Mode](server.md)** - File monitoring and MCP server