248 lines
7 KiB
Markdown
248 lines
7 KiB
Markdown
# Server Mode
|
|
|
|
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, AG-UI server, or any combination:
|
|
|
|
### MCP Server Only
|
|
|
|
```bash
|
|
haiku-rag serve --mcp
|
|
```
|
|
|
|
Transport options:
|
|
- Default - Streamable HTTP transport on port 8001
|
|
- `--stdio` - Standard input/output transport
|
|
- `--mcp-port` - Custom port (default: 8001)
|
|
|
|
### File Monitoring Only
|
|
|
|
```bash
|
|
haiku-rag serve --monitor
|
|
```
|
|
|
|
### Both Services
|
|
|
|
```bash
|
|
haiku-rag serve --monitor --mcp
|
|
```
|
|
|
|
This will start file monitoring and MCP server on port 8001.
|
|
|
|
## File Monitoring
|
|
|
|
Configure directories to monitor in your `haiku.rag.yaml` (see [Document Processing](configuration/processing.md#file-monitoring) for all options):
|
|
|
|
```yaml
|
|
monitor:
|
|
directories:
|
|
- /path/to/documents
|
|
- /another/path
|
|
```
|
|
|
|
Then start the server:
|
|
|
|
```bash
|
|
haiku-rag serve --monitor
|
|
```
|
|
|
|
### Monitoring Features
|
|
|
|
- **Startup**: Scans all monitored directories and adds new files
|
|
- **File Added/Modified**: Automatically parses and updates documents
|
|
- **File Deleted**: Removes corresponding documents from database
|
|
|
|
### Filtering Files
|
|
|
|
You can filter which files to monitor using gitignore-style patterns:
|
|
|
|
```yaml
|
|
monitor:
|
|
directories:
|
|
- /path/to/documents
|
|
|
|
# Ignore patterns (exclude files)
|
|
ignore_patterns:
|
|
- "*draft*" # Ignore draft files
|
|
- "temp/" # Ignore temp directory
|
|
- "**/archive/**" # Ignore archive directories
|
|
|
|
# Include patterns (whitelist files)
|
|
include_patterns:
|
|
- "*.md" # Only markdown files
|
|
- "**/docs/**" # Files in docs directories
|
|
```
|
|
|
|
**Pattern behavior:**
|
|
- Extension filtering is applied first (only supported file types)
|
|
- Include patterns create a whitelist (if specified)
|
|
- Ignore patterns exclude files
|
|
- Both can be combined for fine-grained control
|
|
|
|
### Supported Formats
|
|
|
|
The file monitor processes documents using [Docling](https://github.com/DS4SD/docling), which supports:
|
|
|
|
**Documents:**
|
|
- PDF (`.pdf`) - with OCR support for scanned documents
|
|
- Microsoft Word (`.docx`)
|
|
- Microsoft Excel (`.xlsx`)
|
|
- Microsoft PowerPoint (`.pptx`)
|
|
- HTML (`.html`, `.htm`)
|
|
- Markdown (`.md`)
|
|
- AsciiDoc (`.adoc`, `.asciidoc`)
|
|
|
|
**Data formats:**
|
|
- CSV (`.csv`)
|
|
- JSON (`.json`)
|
|
- XML (`.xml`)
|
|
|
|
**Images (via OCR):**
|
|
- PNG (`.png`)
|
|
- JPEG (`.jpg`, `.jpeg`)
|
|
- TIFF (`.tiff`, `.tif`)
|
|
- BMP (`.bmp`)
|
|
|
|
**Code files:**
|
|
- Python (`.py`)
|
|
- JavaScript (`.js`)
|
|
- TypeScript (`.ts`)
|
|
- And other text-based code files
|
|
|
|
**Plain text:**
|
|
- Text files (`.txt`)
|
|
- 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
|
|
```
|