From ed27acc1a207f1c9f62faf8aebaf5e5d13664a02 Mon Sep 17 00:00:00 2001 From: Yiorgis Gozadinos Date: Tue, 11 Nov 2025 13:11:31 +0200 Subject: [PATCH] Update docs --- README.md | 20 ++++---- docs/agents.md | 24 +++++----- docs/cli.md | 37 +++++++++----- docs/configuration.md | 57 ++++++++++++++++++++++ docs/server.md | 109 +++++++++++++++++++++++++++++++++++++++++- 5 files changed, 210 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 78173afc..e374b79c 100644 --- 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 diff --git a/docs/agents.md b/docs/agents.md index e9fb688a..73355100 100644 --- 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"]) ``` diff --git a/docs/cli.md b/docs/cli.md index 11e2a5b0..9f433cd7 100644 --- 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 ``` diff --git a/docs/configuration.md b/docs/configuration.md index db0571d4..3f8da060 100644 --- 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 diff --git a/docs/server.md b/docs/server.md index 23a74f98..e53232df 100644 --- 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 +```