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/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