Add AsyncAPI spec for websocket (#613)

* AsyncAPI for websocket docs

* Delete old docs

* Update docs/README.md to point to docs site

* Add generated API docs

specs/README.md

@@ -0,0 +1,216 @@
+# TrustGraph API Specifications
+
+This directory contains formal specifications for the TrustGraph API Gateway.
+
+## Directory Structure
+
+```
+specs/
+├── api/              # OpenAPI 3.1.0 specification for REST API
+│   ├── openapi.yaml  # Main entry point
+│   ├── paths/        # Endpoint definitions
+│   ├── components/   # Reusable schemas, responses, parameters
+│   └── security/     # Security scheme definitions
+│
+├── websocket/        # AsyncAPI 3.0.0 specification for WebSocket API
+│   ├── asyncapi.yaml # Main entry point
+│   ├── channels/     # Channel definitions
+│   ├── components/   # Message and schema definitions
+│   └── STREAMING.md  # Streaming patterns documentation
+│
+└── README.md         # This file
+```
+
+## Specifications
+
+### REST API (OpenAPI 3.1.0)
+
+Location: `specs/api/openapi.yaml`
+
+The REST API specification documents:
+- **5 Global Services**: config, flow, librarian, knowledge, collection-management
+- **16 Flow-Hosted Services**: agent, RAG, embeddings, queries, loading, tools
+- **Import/Export**: Bulk data operations
+- **Metrics**: Prometheus monitoring
+
+**Features**:
+- Modular structure with $ref to external files
+- Comprehensive request/response schemas
+- Authentication via Bearer tokens
+- Field naming in kebab-case
+
+### WebSocket API (AsyncAPI 3.0.0)
+
+Location: `specs/websocket/asyncapi.yaml`
+
+The WebSocket API specification documents:
+- Multiplexed async communication protocol
+- Request/response message envelopes with ID correlation
+- All services accessible via single WebSocket connection
+- Streaming response patterns
+
+**Features**:
+- References REST API schemas (single source of truth)
+- Message-based routing (service + optional flow parameters)
+- Comprehensive streaming documentation
+- Full async/multiplexing behavior
+
+## Building Documentation
+
+### Prerequisites
+
+```bash
+npm install -g @redocly/cli @asyncapi/cli
+```
+
+Or use npx (no installation required).
+
+### Generate REST API Documentation
+
+**Using Redocly (HTML)**:
+```bash
+cd specs/api
+npx @redocly/cli build-docs openapi.yaml -o ../../docs/api.html
+```
+
+**Preview in browser**:
+```bash
+cd specs/api
+npx @redocly/cli preview-docs openapi.yaml
+```
+Opens interactive documentation at http://localhost:8080
+
+**Validate**:
+```bash
+cd specs/api
+npx @redocly/cli lint openapi.yaml
+```
+
+### Generate WebSocket API Documentation
+
+**Using AsyncAPI (HTML)**:
+```bash
+cd specs/websocket
+npx -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o /tmp/asyncapi-build -p singleFile=true --force-write
+mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
+rm -rf /tmp/asyncapi-build
+```
+
+Notes:
+- The generator must run from the `specs/websocket` directory to properly resolve relative `$ref` paths to OpenAPI schemas
+- `--use-new-generator` flag enables generator v2 compatibility
+- `-p singleFile=true` parameter generates a single standalone HTML file
+
+**Validate**:
+```bash
+cd specs/websocket
+npx @asyncapi/cli validate asyncapi.yaml
+```
+
+### Build All Documentation
+
+Use the provided build script:
+```bash
+./specs/build-docs.sh
+```
+
+This generates:
+- `docs/api.html` - REST API documentation
+- `docs/websocket.html` - WebSocket API documentation
+
+## Viewing Documentation
+
+After building:
+
+**REST API**:
+```bash
+xdg-open docs/api.html
+# or
+firefox docs/api.html
+```
+
+**WebSocket API**:
+```bash
+xdg-open docs/websocket.html
+# or
+firefox docs/websocket.html
+```
+
+## Schema Reuse
+
+The WebSocket API specification **references** the REST API schemas using relative paths:
+
+```yaml
+# In specs/websocket/components/messages/requests/AgentRequest.yaml
+request:
+  $ref: '../../../../api/components/schemas/agent/AgentRequest.yaml'
+```
+
+This ensures:
+- **Single source of truth** for all schemas
+- **Consistency** between REST and WebSocket APIs
+- **Easy maintenance** - update schemas in one place
+
+## Validation Status
+
+Both specifications are validated and error-free:
+
+- ✅ **OpenAPI**: Validated with Redocly CLI
+- ✅ **AsyncAPI**: Validated with AsyncAPI CLI
+
+## Maintenance
+
+### Adding a New Service
+
+1. **Create schemas** in `specs/api/components/schemas/{service-name}/`
+   - `{ServiceName}Request.yaml`
+   - `{ServiceName}Response.yaml`
+
+2. **Create path definition** in `specs/api/paths/` or `specs/api/paths/flow/`
+
+3. **Add path to main spec** in `specs/api/openapi.yaml`
+
+4. **Create WebSocket message** in `specs/websocket/components/messages/requests/`
+   - Reference the OpenAPI request schema
+
+5. **Add to ServiceRequest** message in `specs/websocket/components/messages/ServiceRequest.yaml`
+
+6. **Validate both specs**:
+   ```bash
+   cd specs/api && npx @redocly/cli lint openapi.yaml
+   cd specs/websocket && npx @asyncapi/cli validate asyncapi.yaml
+   ```
+
+### Modifying an Existing Service
+
+1. **Update schema** in `specs/api/components/schemas/{service-name}/`
+
+2. **Changes automatically apply** to WebSocket spec via $ref
+
+3. **Validate both specs** to ensure consistency
+
+## Tools and Resources
+
+**OpenAPI Tools**:
+- [Redocly CLI](https://redocly.com/docs/cli/) - Linting, docs generation
+- [Swagger Editor](https://editor.swagger.io/) - Online editor
+- [OpenAPI Generator](https://openapi-generator.tech/) - Client/server code generation
+
+**AsyncAPI Tools**:
+- [AsyncAPI CLI](https://www.asyncapi.com/tools/cli) - Validation, docs generation
+- [AsyncAPI Studio](https://studio.asyncapi.com/) - Online editor
+- [AsyncAPI Generator](https://www.asyncapi.com/tools/generator) - Template-based generation
+
+**Online Validators**:
+- OpenAPI: https://editor.swagger.io/
+- AsyncAPI: https://studio.asyncapi.com/
+
+## API Version
+
+Current version: **1.8.0**
+
+Version is specified in both:
+- `specs/api/openapi.yaml` → `info.version`
+- `specs/websocket/asyncapi.yaml` → `info.version`
+
+Update both when releasing a new API version.

specs/api/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: TrustGraph API Gateway
-  version: 1.8.0
+  version: "1.8"
   description: |
     REST API for TrustGraph - an AI-powered knowledge graph and RAG system.
 

specs/build-docs.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Build documentation from OpenAPI and AsyncAPI specifications
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "Building TrustGraph API Documentation..."
+echo
+
+# Create output directory
+mkdir -p ../docs
+
+# Build REST API documentation
+echo "Building REST API documentation (OpenAPI)..."
+cd api
+npx --yes @redocly/cli build-docs openapi.yaml -o ../../docs/api.html
+echo "✓ REST API docs generated: docs/api.html"
+echo
+
+# Build WebSocket API documentation
+echo "Building WebSocket API documentation (AsyncAPI)..."
+cd ../websocket
+npx --yes -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o /tmp/asyncapi-build -p singleFile=true --force-write
+mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
+rm -rf /tmp/asyncapi-build
+echo "✓ WebSocket API docs generated: docs/websocket.html"
+echo
+
+cd "$SCRIPT_DIR"
+echo "Documentation build complete!"
+echo
+echo "View documentation:"
+echo "  REST API:      file://$(realpath ../docs/api.html)"
+echo "  WebSocket API: file://$(realpath ../docs/websocket.html)"

specs/websocket/STREAMING.md

@@ -0,0 +1,357 @@
+# WebSocket Streaming Message Patterns
+
+This document describes streaming behavior for TrustGraph WebSocket services.
+
+## Overview
+
+Many TrustGraph services support streaming responses, where a single request results in multiple response messages sent progressively over time. This enables:
+- Real-time output as it's generated
+- Lower latency for first results
+- Progressive UI updates
+- Better user experience for long-running operations
+
+## Streaming Protocol
+
+### Request ID Correlation
+
+All streaming responses for a request share the same `id`:
+
+```json
+// Single request
+{"id": "req-1", "service": "agent", "flow": "my-flow", "request": {...}}
+
+// Multiple responses with same id
+{"id": "req-1", "response": {...}}  // First chunk
+{"id": "req-1", "response": {...}}  // Second chunk
+{"id": "req-1", "response": {...}}  // Final chunk
+```
+
+### Completion Indicators
+
+Services use different fields to indicate the final message:
+
+| Service | Completion Field | Final Value |
+|---------|-----------------|-------------|
+| agent | `end-of-dialog` | `true` |
+| document-rag | `end-of-stream` | `true` |
+| graph-rag | `end-of-stream` | `true` |
+| text-completion | `end-of-stream` | `true` |
+| prompt | `end-of-stream` | `true` |
+
+## Streaming Services
+
+### Agent Service
+
+Agent service streams thought processes, actions, observations, and answers:
+
+```json
+// Request
+{
+  "id": "agent-1",
+  "service": "agent",
+  "flow": "my-flow",
+  "request": {
+    "question": "What is quantum computing?",
+    "streaming": true
+  }
+}
+
+// Response stream
+{
+  "id": "agent-1",
+  "response": {
+    "chunk-type": "thought",
+    "content": "I need to explain quantum computing concepts",
+    "end-of-dialog": false
+  }
+}
+
+{
+  "id": "agent-1",
+  "response": {
+    "chunk-type": "answer",
+    "content": "Quantum computing is a type of computing that uses quantum mechanical phenomena...",
+    "end-of-dialog": false
+  }
+}
+
+{
+  "id": "agent-1",
+  "response": {
+    "chunk-type": "answer",
+    "content": "Key principles include superposition and entanglement.",
+    "end-of-dialog": true
+  }
+}
+```
+
+**Chunk Types**:
+- `thought`: Internal reasoning
+- `action`: Tool/action being invoked
+- `observation`: Result from tool/action
+- `answer`: Final answer content
+
+### Document RAG Service
+
+Document RAG streams answer chunks:
+
+```json
+// Request
+{
+  "id": "rag-1",
+  "service": "document-rag",
+  "flow": "my-flow",
+  "request": {
+    "query": "What are the main features?",
+    "streaming": true,
+    "doc-limit": 20
+  }
+}
+
+// Response stream
+{
+  "id": "rag-1",
+  "response": {
+    "content": "The main features include: 1) ",
+    "end-of-stream": false
+  }
+}
+
+{
+  "id": "rag-1",
+  "response": {
+    "content": "Knowledge graph storage, 2) Vector embeddings, ",
+    "end-of-stream": false
+  }
+}
+
+{
+  "id": "rag-1",
+  "response": {
+    "content": "3) RAG capabilities.",
+    "end-of-stream": true
+  }
+}
+```
+
+### Graph RAG Service
+
+Similar to Document RAG but retrieves from knowledge graph:
+
+```json
+{
+  "id": "graph-rag-1",
+  "service": "graph-rag",
+  "flow": "my-flow",
+  "request": {
+    "query": "What entities are related to quantum computing?",
+    "streaming": true,
+    "triple-limit": 100
+  }
+}
+```
+
+Response stream has same structure as Document RAG.
+
+### Text Completion Service
+
+Streams generated text:
+
+```json
+{
+  "id": "complete-1",
+  "service": "text-completion",
+  "flow": "my-flow",
+  "request": {
+    "prompt": "Once upon a time",
+    "streaming": true,
+    "max-output-tokens": 100
+  }
+}
+
+// Response stream
+{
+  "id": "complete-1",
+  "response": {
+    "content": " there was a ",
+    "end-of-stream": false
+  }
+}
+
+{
+  "id": "complete-1",
+  "response": {
+    "content": "kingdom far away...",
+    "end-of-stream": true
+  }
+}
+```
+
+### Prompt Service
+
+Streams prompt expansion/generation:
+
+```json
+{
+  "id": "prompt-1",
+  "service": "prompt",
+  "flow": "my-flow",
+  "request": {
+    "template": "default-template",
+    "variables": {"topic": "quantum"},
+    "streaming": true
+  }
+}
+```
+
+Response stream contains progressive prompt text.
+
+## Non-Streaming Services
+
+These services return a single response message:
+
+- **config**: Configuration operations
+- **flow**: Flow lifecycle management
+- **librarian**: Library operations
+- **knowledge**: Knowledge graph operations
+- **collection-management**: Collection metadata
+- **embeddings**: Generate embeddings
+- **mcp-tool**: Tool invocation
+- **triples**: Triple pattern queries
+- **objects**: GraphQL queries
+- **nlp-query**: NLP-based queries
+- **structured-query**: Structured queries
+- **structured-diag**: Diagnostics
+- **graph-embeddings**: Embedding-based graph search
+- **document-embeddings**: Embedding-based document search
+- **text-load**: Text loading (returns status)
+- **document-load**: Document loading (returns status)
+
+## Client Implementation Guide
+
+### Basic Streaming Handler
+
+```javascript
+const pendingRequests = new Map();
+
+// Send request
+const requestId = generateUniqueId();
+const request = {
+  id: requestId,
+  service: 'agent',
+  flow: 'my-flow',
+  request: {
+    question: 'What is quantum computing?',
+    streaming: true
+  }
+};
+
+pendingRequests.set(requestId, {
+  chunks: [],
+  complete: false
+});
+
+websocket.send(JSON.stringify(request));
+
+// Handle responses
+websocket.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+
+  if (message.error) {
+    // Handle error
+    console.error(`Request ${message.id} failed:`, message.error);
+    pendingRequests.delete(message.id);
+    return;
+  }
+
+  const pending = pendingRequests.get(message.id);
+  if (!pending) {
+    console.warn(`Unexpected response for ${message.id}`);
+    return;
+  }
+
+  // Accumulate chunk
+  pending.chunks.push(message.response);
+
+  // Check if complete
+  const isComplete =
+    message.response['end-of-stream'] === true ||
+    message.response['end-of-dialog'] === true;
+
+  if (isComplete) {
+    pending.complete = true;
+    console.log(`Request ${message.id} complete:`, pending.chunks);
+    pendingRequests.delete(message.id);
+  } else {
+    // Process intermediate chunk
+    console.log(`Chunk for ${message.id}:`, message.response);
+  }
+};
+```
+
+## Error Handling in Streaming
+
+Errors can occur at any point during streaming:
+
+```json
+// Mid-stream error
+{
+  "id": "req-1",
+  "response": {
+    "chunk-type": "thought",
+    "content": "Processing...",
+    "end-of-dialog": false
+  }
+}
+
+// Error interrupts stream
+{
+  "id": "req-1",
+  "error": {
+    "type": "service-error",
+    "message": "Backend timeout"
+  }
+}
+```
+
+When an error occurs, no further response messages will be sent for that request ID. The client should:
+1. Stop waiting for completion
+2. Handle the partial results appropriately
+3. Clean up request state
+
+## Performance Considerations
+
+### Multiplexing Streaming Requests
+
+Multiple streaming requests can be active simultaneously:
+
+```json
+{"id": "req-1", "service": "agent", ...}
+{"id": "req-2", "service": "document-rag", ...}
+{"id": "req-3", "service": "text-completion", ...}
+
+// Responses may interleave
+{"id": "req-2", "response": {...}}
+{"id": "req-1", "response": {...}}
+{"id": "req-3", "response": {...}}
+{"id": "req-1", "response": {...}}
+{"id": "req-2", "response": {...}}
+```
+
+### Backpressure
+
+If the client is slow to consume streaming responses, the WebSocket connection may experience:
+- Buffering on the server side
+- Increased latency
+- Potential connection issues
+
+Clients should process streaming chunks efficiently or implement flow control.
+
+## Best Practices
+
+1. **Always check completion flags**: Don't assume a fixed number of chunks
+2. **Handle partial results**: Be prepared for errors mid-stream
+3. **Unique request IDs**: Ensure IDs are unique across active requests
+4. **Timeout handling**: Implement client-side timeouts for streaming requests
+5. **Memory management**: Don't accumulate unbounded chunks; process incrementally
+6. **User feedback**: Show progressive results to users as chunks arrive

specs/websocket/asyncapi.yaml

@@ -0,0 +1,87 @@
+asyncapi: 3.0.0
+
+info:
+  title: TrustGraph WebSocket API
+  version: "1.8"
+  description: |
+    WebSocket API for TrustGraph - providing multiplexed, asynchronous access to all services.
+
+    ## Overview
+
+    The WebSocket API provides access to all TrustGraph services over a single persistent connection:
+    - **Multiplexed**: Multiple concurrent requests with ID-based correlation
+    - **Asynchronous**: Non-blocking request/response pattern
+    - **Efficient**: Lower overhead than HTTP REST
+    - **Streaming**: Real-time progressive responses
+
+    ## Protocol Summary
+
+    All messages are JSON with:
+    - `id`: Client-generated unique identifier for request/response correlation
+    - `service`: Service identifier (e.g., "config", "agent", "document-rag")
+    - `flow`: Optional flow ID for flow-hosted services
+    - `request`/`response`: Service-specific payload (identical to REST API schemas)
+    - `error`: Error information on failure
+
+    ## Service Types
+
+    **Global Services** (no `flow` parameter):
+    - config, flow, librarian, knowledge, collection-management
+
+    **Flow-Hosted Services** (require `flow` parameter):
+    - agent, text-completion, prompt, document-rag, graph-rag
+    - embeddings, graph-embeddings, document-embeddings
+    - triples, objects, nlp-query, structured-query, structured-diag
+    - text-load, document-load, mcp-tool
+
+    ## Schema Reuse
+
+    Request and response payloads use identical schemas to the REST API.
+    See OpenAPI specification for detailed schema documentation.
+
+  contact:
+    name: TrustGraph Project
+    url: https://trustgraph.ai
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  production:
+    host: localhost:8088
+    protocol: ws
+    description: Local development WebSocket server
+    security:
+      - $ref: '#/components/securitySchemes/bearerAuth'
+
+defaultContentType: application/json
+
+channels:
+  socket:
+    $ref: './channels/socket.yaml'
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: httpApiKey
+      name: token
+      in: query
+      description: |
+        Bearer token authentication when GATEWAY_SECRET is configured.
+        Include as query parameter: ws://localhost:8088/api/v1/socket?token=<token>
+
+  messages:
+    ServiceRequest:
+      $ref: './components/messages/ServiceRequest.yaml'
+    ServiceResponse:
+      $ref: './components/messages/ServiceResponse.yaml'
+    ServiceError:
+      $ref: './components/messages/ServiceError.yaml'
+
+  schemas:
+    RequestEnvelope:
+      $ref: './components/schemas/RequestEnvelope.yaml'
+    ResponseEnvelope:
+      $ref: './components/schemas/ResponseEnvelope.yaml'
+    ErrorEnvelope:
+      $ref: './components/schemas/ErrorEnvelope.yaml'

specs/websocket/channels/socket.yaml

@@ -0,0 +1,33 @@
+address: /api/v1/socket
+description: |
+  Primary WebSocket channel for all TrustGraph services.
+
+  This single channel provides multiplexed access to:
+  - All global services (config, flow, librarian, knowledge, collection-management)
+  - All flow-hosted services (agent, RAG, embeddings, queries, loading, etc.)
+
+  ## Multiplexing
+
+  Multiple requests can be sent concurrently over this channel. Each request includes
+  a unique `id` field that is echoed back in responses for correlation.
+
+  ## Message Flow
+
+  1. Client sends request with unique `id`, `service`, optional `flow`, and `request` payload
+  2. Server processes request asynchronously
+  3. Server sends response(s) with matching `id` and either `response` or `error`
+  4. For streaming services, multiple responses may be sent with the same `id`
+
+  ## Service Routing
+
+  Messages are routed to services based on:
+  - `service`: Service identifier (required)
+  - `flow`: Flow ID (required for flow-hosted services, omitted for global services)
+
+messages:
+  request:
+    $ref: '../components/messages/ServiceRequest.yaml'
+  response:
+    $ref: '../components/messages/ServiceResponse.yaml'
+  error:
+    $ref: '../components/messages/ServiceError.yaml'

specs/websocket/components/messages/ServiceError.yaml

@@ -0,0 +1,27 @@
+name: ServiceError
+title: Service Error Message
+summary: Error response from any TrustGraph service
+description: |
+  Error message sent when a service request fails.
+
+  Contains the request ID and error details.
+
+payload:
+  $ref: '../schemas/ErrorEnvelope.yaml'
+
+examples:
+  - name: Flow not found error
+    summary: Requested flow does not exist
+    payload:
+      id: req-2
+      error:
+        type: gateway-error
+        message: Flow 'my-flow' not found
+
+  - name: Service timeout error
+    summary: Service processing timeout
+    payload:
+      id: req-3
+      error:
+        type: timeout
+        message: Request exceeded 600s timeout

specs/websocket/components/messages/ServiceRequest.yaml

@@ -0,0 +1,55 @@
+name: ServiceRequest
+title: Service Request Message
+summary: Request message for any TrustGraph service
+description: |
+  Generic request message that can invoke any TrustGraph service.
+
+  The `request` field payload varies by service and matches the REST API request body schema.
+
+payload:
+  description: Service request envelope with id, service, optional flow, and service-specific request payload
+  oneOf:
+    # Global services (no flow parameter)
+    - $ref: './requests/ConfigRequest.yaml'
+    - $ref: './requests/FlowRequest.yaml'
+    - $ref: './requests/LibrarianRequest.yaml'
+    - $ref: './requests/KnowledgeRequest.yaml'
+    - $ref: './requests/CollectionManagementRequest.yaml'
+
+    # Flow-hosted services (require flow parameter)
+    - $ref: './requests/AgentRequest.yaml'
+    - $ref: './requests/DocumentRagRequest.yaml'
+    - $ref: './requests/GraphRagRequest.yaml'
+    - $ref: './requests/TextCompletionRequest.yaml'
+    - $ref: './requests/PromptRequest.yaml'
+    - $ref: './requests/EmbeddingsRequest.yaml'
+    - $ref: './requests/McpToolRequest.yaml'
+    - $ref: './requests/TriplesRequest.yaml'
+    - $ref: './requests/ObjectsRequest.yaml'
+    - $ref: './requests/NlpQueryRequest.yaml'
+    - $ref: './requests/StructuredQueryRequest.yaml'
+    - $ref: './requests/StructuredDiagRequest.yaml'
+    - $ref: './requests/GraphEmbeddingsRequest.yaml'
+    - $ref: './requests/DocumentEmbeddingsRequest.yaml'
+    - $ref: './requests/TextLoadRequest.yaml'
+    - $ref: './requests/DocumentLoadRequest.yaml'
+
+examples:
+  - name: Config service request
+    summary: List all flow configurations
+    payload:
+      id: req-1
+      service: config
+      request:
+        operation: list
+        type: flow
+
+  - name: Agent service request
+    summary: Ask question to agent
+    payload:
+      id: req-2
+      service: agent
+      flow: my-flow
+      request:
+        question: What is quantum computing?
+        streaming: true

specs/websocket/components/messages/ServiceResponse.yaml

@@ -0,0 +1,32 @@
+name: ServiceResponse
+title: Service Response Message
+summary: Successful response from any TrustGraph service
+description: |
+  Generic response message from any TrustGraph service.
+
+  The `response` field payload varies by service and matches the REST API response body schema.
+
+  For streaming services, multiple messages with the same `id` may be sent.
+
+payload:
+  $ref: '../schemas/ResponseEnvelope.yaml'
+
+examples:
+  - name: Config service response
+    summary: List of flow configurations
+    payload:
+      id: req-1
+      response:
+        type: flow
+        keys:
+          - my-flow
+          - production-flow
+
+  - name: Agent streaming response
+    summary: Agent answer chunk
+    payload:
+      id: req-2
+      response:
+        chunk-type: answer
+        content: Quantum computing uses quantum mechanical phenomena...
+        end-of-stream: false

specs/websocket/components/messages/requests/AgentRequest.yaml

@@ -0,0 +1,28 @@
+type: object
+description: WebSocket request for agent service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: agent
+    description: Service identifier for agent service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/agent/AgentRequest.yaml'
+examples:
+  - id: req-1
+    service: agent
+    flow: my-flow
+    request:
+      question: What is quantum computing?
+      streaming: true
+      system-prompt: You are a helpful assistant

specs/websocket/components/messages/requests/CollectionManagementRequest.yaml

@@ -0,0 +1,21 @@
+type: object
+description: WebSocket request for collection-management service (global service)
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: collection-management
+    description: Service identifier for collection-management service
+  request:
+    $ref: '../../../../api/components/schemas/collection/CollectionRequest.yaml'
+examples:
+  - id: req-1
+    service: collection-management
+    request:
+      operation: list

specs/websocket/components/messages/requests/ConfigRequest.yaml

@@ -0,0 +1,29 @@
+type: object
+description: WebSocket request for config service (global service)
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: config
+    description: Service identifier for config service
+  request:
+    $ref: '../../../../api/components/schemas/config/ConfigRequest.yaml'
+examples:
+  - id: req-1
+    service: config
+    request:
+      operation: list
+      type: flow
+  - id: req-2
+    service: config
+    request:
+      operation: get
+      keys:
+        - type: flow
+          key: my-flow

specs/websocket/components/messages/requests/DocumentEmbeddingsRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for document-embeddings service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: document-embeddings
+    description: Service identifier for document-embeddings service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/embeddings-query/DocumentEmbeddingsQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: document-embeddings
+    flow: my-flow
+    request:
+      text: quantum computing
+      limit: 10

specs/websocket/components/messages/requests/DocumentLoadRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for document-load service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: document-load
+    description: Service identifier for document-load service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/loading/DocumentLoadRequest.yaml'
+examples:
+  - id: req-1
+    service: document-load
+    flow: my-flow
+    request:
+      url: https://example.com/document.pdf
+      collection: default

specs/websocket/components/messages/requests/DocumentRagRequest.yaml

@@ -0,0 +1,28 @@
+type: object
+description: WebSocket request for document-rag service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: document-rag
+    description: Service identifier for document-rag service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/rag/DocumentRagRequest.yaml'
+examples:
+  - id: req-1
+    service: document-rag
+    flow: my-flow
+    request:
+      query: What are the main features?
+      streaming: true
+      doc-limit: 20

specs/websocket/components/messages/requests/EmbeddingsRequest.yaml

@@ -0,0 +1,26 @@
+type: object
+description: WebSocket request for embeddings service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: embeddings
+    description: Service identifier for embeddings service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/embeddings/EmbeddingsRequest.yaml'
+examples:
+  - id: req-1
+    service: embeddings
+    flow: my-flow
+    request:
+      text: What is quantum computing?

specs/websocket/components/messages/requests/FlowRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for flow service (global service)
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: flow
+    description: Service identifier for flow service
+  request:
+    $ref: '../../../../api/components/schemas/flow/FlowRequest.yaml'
+examples:
+  - id: req-1
+    service: flow
+    request:
+      operation: list
+  - id: req-2
+    service: flow
+    request:
+      operation: start
+      flow: my-flow
+      blueprint: default-blueprint

specs/websocket/components/messages/requests/GraphEmbeddingsRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for graph-embeddings service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: graph-embeddings
+    description: Service identifier for graph-embeddings service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/embeddings-query/GraphEmbeddingsQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: graph-embeddings
+    flow: my-flow
+    request:
+      text: quantum computing
+      limit: 10

specs/websocket/components/messages/requests/GraphRagRequest.yaml

@@ -0,0 +1,28 @@
+type: object
+description: WebSocket request for graph-rag service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: graph-rag
+    description: Service identifier for graph-rag service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/rag/GraphRagRequest.yaml'
+examples:
+  - id: req-1
+    service: graph-rag
+    flow: my-flow
+    request:
+      query: What entities are related to quantum computing?
+      streaming: true
+      triple-limit: 100

specs/websocket/components/messages/requests/KnowledgeRequest.yaml

@@ -0,0 +1,31 @@
+type: object
+description: WebSocket request for knowledge service (global service)
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: knowledge
+    description: Service identifier for knowledge service
+  request:
+    $ref: '../../../../api/components/schemas/knowledge/KnowledgeRequest.yaml'
+examples:
+  - id: req-1
+    service: knowledge
+    request:
+      operation: store
+      triples:
+        - s:
+            v: https://example.com/entity1
+            e: true
+          p:
+            v: https://example.com/relates-to
+            e: true
+          o:
+            v: https://example.com/entity2
+            e: true

specs/websocket/components/messages/requests/LibrarianRequest.yaml

@@ -0,0 +1,22 @@
+type: object
+description: WebSocket request for librarian service (global service)
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: librarian
+    description: Service identifier for librarian service
+  request:
+    $ref: '../../../../api/components/schemas/librarian/LibrarianRequest.yaml'
+examples:
+  - id: req-1
+    service: librarian
+    request:
+      operation: list
+      collection: default

specs/websocket/components/messages/requests/McpToolRequest.yaml

@@ -0,0 +1,30 @@
+type: object
+description: WebSocket request for mcp-tool service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: mcp-tool
+    description: Service identifier for mcp-tool service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/mcp-tool/McpToolRequest.yaml'
+examples:
+  - id: req-1
+    service: mcp-tool
+    flow: my-flow
+    request:
+      tool: calculator
+      arguments:
+        operation: add
+        a: 5
+        b: 3

specs/websocket/components/messages/requests/NlpQueryRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for nlp-query service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: nlp-query
+    description: Service identifier for nlp-query service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/query/NlpQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: nlp-query
+    flow: my-flow
+    request:
+      query: Show me all entities related to quantum computing
+      limit: 50

specs/websocket/components/messages/requests/ObjectsRequest.yaml

@@ -0,0 +1,26 @@
+type: object
+description: WebSocket request for objects service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: objects
+    description: Service identifier for objects service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/query/ObjectsQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: objects
+    flow: my-flow
+    request:
+      query: "{ entity(id: \"https://example.com/entity1\") { properties { key value } } }"

specs/websocket/components/messages/requests/PromptRequest.yaml

@@ -0,0 +1,29 @@
+type: object
+description: WebSocket request for prompt service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: prompt
+    description: Service identifier for prompt service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/prompt/PromptRequest.yaml'
+examples:
+  - id: req-1
+    service: prompt
+    flow: my-flow
+    request:
+      template: default-template
+      variables:
+        topic: quantum computing
+        style: technical

specs/websocket/components/messages/requests/StructuredDiagRequest.yaml

@@ -0,0 +1,26 @@
+type: object
+description: WebSocket request for structured-diag service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: structured-diag
+    description: Service identifier for structured-diag service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/diag/StructuredDiagRequest.yaml'
+examples:
+  - id: req-1
+    service: structured-diag
+    flow: my-flow
+    request:
+      operation: status

specs/websocket/components/messages/requests/StructuredQueryRequest.yaml

@@ -0,0 +1,30 @@
+type: object
+description: WebSocket request for structured-query service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: structured-query
+    description: Service identifier for structured-query service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/query/StructuredQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: structured-query
+    flow: my-flow
+    request:
+      query:
+        type: entity
+        filters:
+          - property: type
+            value: Person

specs/websocket/components/messages/requests/TextCompletionRequest.yaml

@@ -0,0 +1,28 @@
+type: object
+description: WebSocket request for text-completion service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: text-completion
+    description: Service identifier for text-completion service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/text-completion/TextCompletionRequest.yaml'
+examples:
+  - id: req-1
+    service: text-completion
+    flow: my-flow
+    request:
+      prompt: Once upon a time
+      streaming: true
+      max-output-tokens: 100

specs/websocket/components/messages/requests/TextLoadRequest.yaml

@@ -0,0 +1,27 @@
+type: object
+description: WebSocket request for text-load service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: text-load
+    description: Service identifier for text-load service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/loading/TextLoadRequest.yaml'
+examples:
+  - id: req-1
+    service: text-load
+    flow: my-flow
+    request:
+      text: This is the document content to be loaded into the knowledge graph.
+      collection: default

specs/websocket/components/messages/requests/TriplesRequest.yaml

@@ -0,0 +1,29 @@
+type: object
+description: WebSocket request for triples service (flow-hosted service)
+required:
+  - id
+  - service
+  - flow
+  - request
+properties:
+  id:
+    type: string
+    description: Unique request identifier
+  service:
+    type: string
+    const: triples
+    description: Service identifier for triples service
+  flow:
+    type: string
+    description: Flow ID
+  request:
+    $ref: '../../../../api/components/schemas/query/TriplesQueryRequest.yaml'
+examples:
+  - id: req-1
+    service: triples
+    flow: my-flow
+    request:
+      s:
+        v: https://example.com/entity1
+        e: true
+      limit: 100

specs/websocket/components/schemas/ErrorEnvelope.yaml

@@ -0,0 +1,37 @@
+type: object
+description: |
+  WebSocket error message envelope.
+
+  Sent when a request fails. Contains the request ID and error details.
+required:
+  - id
+  - error
+properties:
+  id:
+    type: string
+    description: |
+      Request identifier from the original request that failed.
+    examples:
+      - req-123
+      - request-abc-456
+  error:
+    type: object
+    description: Error information
+    required:
+      - type
+      - message
+    properties:
+      type:
+        type: string
+        description: Error type/category
+        examples:
+          - gateway-error
+          - service-error
+          - timeout
+      message:
+        type: string
+        description: Human-readable error message
+        examples:
+          - Flow not found
+          - Service timeout
+          - Invalid request format

specs/websocket/components/schemas/RequestEnvelope.yaml

@@ -0,0 +1,56 @@
+type: object
+description: |
+  WebSocket request message envelope.
+
+  Wraps service-specific request payloads with routing and correlation metadata.
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: |
+      Client-generated unique identifier for this request within the WebSocket session.
+      Used to correlate responses with requests in multiplexed async communication.
+      Can be any string, but must be unique per active request.
+    examples:
+      - req-123
+      - request-abc-456
+      - b5f8d9a2-4c3e-11ef-9c8a-0242ac120002
+  service:
+    type: string
+    description: |
+      Service identifier. Same as {kind} in REST API URLs.
+
+      Global services: config, flow, librarian, knowledge, collection-management
+      Flow-hosted services: agent, text-completion, prompt, document-rag, graph-rag,
+      embeddings, graph-embeddings, document-embeddings, triples, objects,
+      nlp-query, structured-query, structured-diag, text-load, document-load, mcp-tool
+    examples:
+      - config
+      - agent
+      - document-rag
+  flow:
+    type: string
+    description: |
+      Flow ID for flow-hosted services. Required for services accessed via
+      /api/v1/flow/{flow}/service/{kind} in REST API.
+
+      Omit this field for global services (config, flow, librarian, knowledge, collection-management).
+    examples:
+      - my-flow
+      - production-flow
+  request:
+    type: object
+    description: |
+      Service-specific request payload. Structure is identical to the request body
+      in the corresponding REST API endpoint.
+
+      See OpenAPI specification for detailed schemas per service.
+    examples:
+      - operation: list
+        type: flow
+      - question: What is quantum computing?
+        streaming: true
+        system-prompt: You are a helpful assistant

specs/websocket/components/schemas/ResponseEnvelope.yaml

@@ -0,0 +1,35 @@
+type: object
+description: |
+  WebSocket response message envelope for successful responses.
+
+  Contains the request ID for correlation and the service-specific response payload.
+required:
+  - id
+  - response
+properties:
+  id:
+    type: string
+    description: |
+      Request identifier from the original request. Client uses this to match
+      responses to requests in multiplexed communication.
+    examples:
+      - req-123
+      - request-abc-456
+  response:
+    type: object
+    description: |
+      Service-specific response payload. Structure is identical to the response body
+      in the corresponding REST API endpoint.
+
+      For streaming services, multiple response messages may be sent with the same `id`.
+      Look for `end-of-stream` or service-specific completion flags to detect the final message.
+
+      See OpenAPI specification for detailed schemas per service.
+    examples:
+      - type: flow
+        keys:
+          - my-flow
+          - production-flow
+      - chunk-type: answer
+        content: Quantum computing uses quantum bits...
+        end-of-stream: false