Update docs

2025-11-11 13:11:31 +02:00 · 2025-11-11 13:11:31 +02:00 · ed27acc1a2
commit ed27acc1a2
parent d5b6ad544d
5 changed files with 210 additions and 37 deletions
--- a/README.md
+++ b/README.md
@ -84,6 +84,7 @@ To customize settings, create a `haiku.rag.yaml` config file (see [Configuration
 ## Python Usage

 ```python
+from haiku.rag.agui.stream import stream_graph
 from haiku.rag.client import HaikuRAG
 from haiku.rag.config import Config
 from haiku.rag.research import (
@ -91,7 +92,6 @@ from haiku.rag.research import (
    ResearchDeps,
    ResearchState,
    build_research_graph,
-    stream_research_graph,
 )

 async with HaikuRAG("database.lancedb") as client:
@ -126,15 +126,17 @@ async with HaikuRAG("database.lancedb") as client:
    report = await graph.run(state=state, deps=deps)
    print(report.title)

-    # Streaming progress (log/report/error events)
-    async for event in stream_research_graph(graph, state, deps):
-        if event.type == "log":
-            iteration = event.state.iterations if event.state else state.iterations
-            print(f"[{iteration}] {event.message}")
-        elif event.type == "report":
+    # Streaming progress (AG-UI events)
+    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":
+            print(f"  {event['content']}")
+        elif event["type"] == "RUN_FINISHED":
            print("\nResearch complete!\n")
-            print(event.report.title)
-            print(event.report.executive_summary)
+            result = event["result"]
+            print(result["title"])
+            print(result["executive_summary"])
 ```

 ## MCP Server
--- a/docs/agents.md
+++ b/docs/agents.md
@ -250,15 +250,15 @@ deps = ResearchDeps(client=client)
 result = await graph.run(state=state, deps=deps)
 ```

-Python usage (streamed events):
+Python usage (streamed AG-UI events):

 ```python
+from haiku.rag.agui.stream import stream_graph
 from haiku.rag.client import HaikuRAG
 from haiku.rag.config import Config
 from haiku.rag.research.dependencies import ResearchContext
 from haiku.rag.research.graph import build_research_graph
 from haiku.rag.research.state import ResearchDeps, ResearchState
-from haiku.rag.research.stream import stream_research_graph

 async with HaikuRAG(path_to_db) as client:
    graph = build_research_graph(config=Config)
@ -267,16 +267,14 @@ async with HaikuRAG(path_to_db) as client:
    state = ResearchState.from_config(context=context, config=Config)
    deps = ResearchDeps(client=client)

-    async for event in stream_research_graph(
-        graph,
-        state,
-        deps,
-    ):
-        if event.type == "log":
-            iteration = event.state.iterations if event.state else state.iterations
-            print(f"[{iteration}] {event.message}")
-        elif event.type == "report":
+    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":
+            print(f"  {event['content']}")
+        elif event["type"] == "RUN_FINISHED":
            print("\nResearch complete!\n")
-            print(event.report.title)
-            print(event.report.executive_summary)
+            result = event["result"]
+            print(result["title"])
+            print(result["executive_summary"])
 ```
--- a/docs/cli.md
+++ b/docs/cli.md
@ -146,20 +146,23 @@ When available, citations use the document title; otherwise they fall back to th
 Run the multi-step research graph:

 ```bash
-haiku-rag research "How does haiku.rag organize and query documents?" \
-  --max-iterations 2 \
-  --confidence-threshold 0.8 \
-  --max-concurrency 3 \
-  --verbose
+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
 ```

 Flags:
- `--max-iterations, -n`: maximum search/evaluate cycles (default: 3)
- `--confidence-threshold`: stop once evaluation confidence meets/exceeds this (default: 0.8)
- `--max-concurrency`: number of sub-questions searched in parallel each iteration (default: 3)
- `--verbose`: show planning, searching previews, evaluation summary, and stop reason
+- `--verbose`: Show planning, searching previews, evaluation summary, and stop reason

-When `--verbose` is set the CLI also consumes the internal research stream, printing every `log` event as agents progress through planning, search, evaluation, and synthesis. If you build your own integration, call `stream_research_graph` to access the same `log`, `report`, and `error` events and render them however you like while the graph is running.
+Research parameters like `max_iterations`, `confidence_threshold`, and `max_concurrency` are configured in your [configuration file](configuration.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.agui.stream` 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

@ -174,10 +177,18 @@ haiku-rag serve --mcp --stdio
 # File monitoring only
 haiku-rag serve --monitor

-# Both services
-haiku-rag serve --monitor --mcp
+# AG-UI server only
+haiku-rag serve --agui

-# Custom port
+# Multiple 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
 ```

--- a/docs/configuration.md
+++ b/docs/configuration.md
@ -83,6 +83,17 @@ qa:
 research:
  provider: ""  # Empty to use qa settings
  model: ""
+  max_iterations: 3
+  confidence_threshold: 0.8
+  max_concurrency: 1
+
+agui:
+  host: "0.0.0.0"
+  port: 8000
+  cors_origins: ["*"]
+  cors_credentials: true
+  cors_methods: ["GET", "POST", "OPTIONS"]
+  cors_headers: ["*"]

 processing:
  chunk_size: 256
@ -460,6 +471,52 @@ providers:

 **Note:** vLLM reranking uses the `/rerank` API endpoint. You need to run a vLLM server separately with a reranking model loaded. Consult the specific model's documentation for proper vLLM serving configuration.

+## Research Configuration
+
+Configure the multi-agent research workflow:
+
+```yaml
+research:
+  provider: ""  # Empty to use qa settings
+  model: ""     # Empty to use qa model
+  max_iterations: 3           # Maximum search/evaluate cycles
+  confidence_threshold: 0.8   # Stop when confidence meets/exceeds this
+  max_concurrency: 1          # Sub-questions searched in parallel per iteration
+```
+
+- **provider/model**: LLM provider and model for research. Leave empty to use the same settings as `qa`.
+- **max_iterations**: Maximum number of search/evaluate cycles before stopping (default: 3)
+- **confidence_threshold**: Stop research when evaluation confidence score meets or exceeds this threshold (default: 0.8)
+- **max_concurrency**: Number of sub-questions to search in parallel during each iteration (default: 1)
+
+The research workflow plans sub-questions, searches in parallel batches, evaluates findings, and iterates until reaching the confidence threshold or max iterations.
+
+## AG-UI Server Configuration
+
+Configure the AG-UI HTTP server for streaming graph execution events:
+
+```yaml
+agui:
+  host: "0.0.0.0"
+  port: 8000
+  cors_origins: ["*"]
+  cors_credentials: true
+  cors_methods: ["GET", "POST", "OPTIONS"]
+  cors_headers: ["*"]
+```
+
+Start the AG-UI server with:
+
+```bash
+haiku-rag serve --agui
+```
+
+The server exposes:
+- `GET /health` - Health check endpoint
+- `POST /v1/agent/stream` - Research graph streaming endpoint (Server-Sent Events)
+
+See [Server Mode](server.md) for more details.
+
 ## Other Settings

 ### Database and Storage
--- a/docs/server.md
+++ b/docs/server.md
@ -1,10 +1,10 @@
 # Server Mode

-The server provides automatic file monitoring and MCP functionality.
+The server provides automatic file monitoring, MCP functionality, and AG-UI graph streaming.

 ## Starting the Server

-The `serve` command requires at least one service flag. You can enable file monitoring, MCP server, or both:
+The `serve` command requires at least one service flag. You can enable file monitoring, MCP server, AG-UI server, or any combination:

 ### MCP Server Only

@ -93,3 +93,108 @@ The server can parse 40+ file formats including:
 - And more...

 URLs are also supported for web content.
+
+## 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/agent/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
+```
+
+See [Configuration](configuration.md#ag-ui-server-configuration) for all available options.
+
+### Using the Streaming Endpoint
+
+The `/v1/agent/stream` endpoint accepts POST requests with research parameters and streams AG-UI events:
+
+**Request format:**
+```json
+{
+  "threadId": "optional-thread-id",
+  "runId": "optional-run-id",
+  "state": {
+    "context": {
+      "original_question": "What are the key features of haiku.rag?"
+    }
+  },
+  "messages": [],
+  "config": {}
+}
+```
+
+**Example with curl:**
+```bash
+curl -X POST http://localhost:8000/v1/agent/stream \
+  -H "Content-Type: application/json" \
+  -d '{
+    "state": {
+      "context": {
+        "original_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.
+
+**Response:** Server-Sent Events stream with AG-UI protocol events:
+- `RUN_STARTED` - Graph execution started
+- `STATE_SNAPSHOT` - Current state snapshot
+- `STEP_STARTED` - Node execution started
+- `STEP_FINISHED` - Node execution completed
+- `ACTIVITY_SNAPSHOT` - Progress update
+- `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","content":"Creating research plan"}
+
+data: {"type":"STEP_FINISHED","stepName":"plan"}
+
+data: {"type":"RUN_FINISHED","threadId":"abc123","runId":"xyz789","result":{"title":"Research Report","executive_summary":"..."}}
+```
+
+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
+```