From fc29b0c3f73c26662014bf5159e6f70c27848a41 Mon Sep 17 00:00:00 2001 From: Yiorgis Gozadinos Date: Fri, 9 Jan 2026 19:03:19 +0200 Subject: [PATCH] Update docs --- docs/agents.md | 66 ------------------ docs/cli.md | 41 +---------- docs/configuration/index.md | 8 --- docs/mcp.md | 10 +-- docs/server.md | 134 +----------------------------------- docs/tutorial.md | 2 +- 6 files changed, 6 insertions(+), 255 deletions(-) diff --git a/docs/agents.md b/docs/agents.md index ff11b1bf..25f3aa2c 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -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 diff --git a/docs/cli.md b/docs/cli.md index db1ced53..13a6d8b3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -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 diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 5bf63ecf..2261b103 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -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) diff --git a/docs/mcp.md b/docs/mcp.md index 7aa5bc10..b1e10976 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -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. diff --git a/docs/server.md b/docs/server.md index 33109877..3f6ba3ef 100644 --- a/docs/server.md +++ b/docs/server.md @@ -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 -``` diff --git a/docs/tutorial.md b/docs/tutorial.md index b920b018..cae572d8 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -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