REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/components/schemas/agent/AgentRequest.yaml

@@ -0,0 +1,59 @@
+type: object
+description: |
+  Agent service request - conversational AI agent that can reason and take actions.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: User question or prompt for the agent
+    example: What is the capital of France?
+  state:
+    type: string
+    description: Agent state for continuation (optional, for multi-turn)
+    example: agent-state-12345
+  group:
+    type: array
+    description: Group identifiers for collaborative agents (optional)
+    items:
+      type: string
+    example: ["research-team"]
+  history:
+    type: array
+    description: Conversation history (optional, list of previous agent steps)
+    items:
+      type: object
+      properties:
+        thought:
+          type: string
+          description: Agent's reasoning
+          example: I need to search for information about Paris
+        action:
+          type: string
+          description: Action taken
+          example: search
+        arguments:
+          type: object
+          description: Action arguments
+          additionalProperties:
+            type: string
+          example:
+            query: "capital of France"
+        observation:
+          type: string
+          description: Result of the action
+          example: "Paris is the capital of France"
+        user:
+          type: string
+          description: User context for this step
+          example: alice
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/agent/AgentResponse.yaml

@@ -0,0 +1,51 @@
+type: object
+description: Agent service response (streaming or legacy format)
+properties:
+  chunk-type:
+    type: string
+    description: Type of streaming chunk (streaming mode only)
+    enum:
+      - thought
+      - action
+      - observation
+      - answer
+      - error
+    example: answer
+  content:
+    type: string
+    description: Chunk content (streaming mode only)
+    example: Paris is the capital of France.
+  end-of-message:
+    type: boolean
+    description: Current chunk type is complete (streaming mode)
+    default: false
+    example: true
+  end-of-dialog:
+    type: boolean
+    description: Entire agent dialog is complete (streaming mode)
+    default: false
+    example: true
+  answer:
+    type: string
+    description: Final answer (legacy non-streaming format)
+    example: Paris is the capital of France.
+  thought:
+    type: string
+    description: Agent reasoning (legacy format)
+    example: I should search for information about the capital of France.
+  observation:
+    type: string
+    description: Observation from actions (legacy format)
+    example: Found information about Paris being the capital.
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to process agent request
+      code:
+        type: string
+        description: Error code
+        example: AGENT_ERROR

specs/api/components/schemas/collection/CollectionRequest.yaml

@@ -0,0 +1,58 @@
+type: object
+description: |
+  Collection management request.
+
+  Operations: list-collections, update-collection, delete-collection
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum:
+      - list-collections
+      - update-collection
+      - delete-collection
+    description: |
+      Collection operation:
+      - `list-collections`: List collections for user
+      - `update-collection`: Create or update collection metadata
+      - `delete-collection`: Delete collection
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection identifier (for update, delete)
+    example: research
+  timestamp:
+    type: string
+    description: ISO timestamp
+    format: date-time
+    example: "2024-01-15T10:30:00Z"
+  name:
+    type: string
+    description: Human-readable collection name (for update)
+    example: Research Papers
+  description:
+    type: string
+    description: Collection description (for update)
+    example: Academic research papers on AI and ML
+  tags:
+    type: array
+    description: Collection tags for organization (for update)
+    items:
+      type: string
+    example: ["research", "AI", "academic"]
+  tag-filter:
+    type: array
+    description: Filter collections by tags (for list)
+    items:
+      type: string
+    example: ["research"]
+  limit:
+    type: integer
+    description: Maximum number of results (for list)
+    default: 0
+    example: 100

specs/api/components/schemas/collection/CollectionResponse.yaml

@@ -0,0 +1,39 @@
+type: object
+description: Collection management response
+properties:
+  timestamp:
+    type: string
+    description: ISO timestamp
+    format: date-time
+    example: "2024-01-15T10:30:00Z"
+  collections:
+    type: array
+    description: List of collections (returned by list-collections)
+    items:
+      type: object
+      required:
+        - user
+        - collection
+      properties:
+        user:
+          type: string
+          description: User identifier
+          example: alice
+        collection:
+          type: string
+          description: Collection identifier
+          example: research
+        name:
+          type: string
+          description: Human-readable collection name
+          example: Research Papers
+        description:
+          type: string
+          description: Collection description
+          example: Academic research papers on AI and ML
+        tags:
+          type: array
+          description: Collection tags
+          items:
+            type: string
+          example: ["research", "AI", "academic"]

specs/api/components/schemas/common/DocumentMetadata.yaml

@@ -0,0 +1,26 @@
+type: object
+description: Document metadata for library management
+properties:
+  url:
+    type: string
+    description: Document URL or identifier
+    example: https://example.com/document.pdf
+  title:
+    type: string
+    description: Document title
+    example: Example Document
+  author:
+    type: string
+    description: Document author
+    example: John Doe
+  date:
+    type: string
+    description: Document date
+    example: "2024-01-15"
+  metadata:
+    type: object
+    description: Additional metadata fields
+    additionalProperties: true
+    example:
+      department: Engineering
+      category: Technical

specs/api/components/schemas/common/ProcessingMetadata.yaml

@@ -0,0 +1,25 @@
+type: object
+description: Processing metadata for library document processing
+properties:
+  flow:
+    type: string
+    description: Flow ID
+    example: my-flow
+  collection:
+    type: string
+    description: Collection identifier
+    example: default
+  status:
+    type: string
+    description: Processing status
+    enum: [pending, processing, completed, failed]
+    example: completed
+  timestamp:
+    type: string
+    format: date-time
+    description: Processing timestamp
+    example: "2024-01-15T10:30:00Z"
+  error:
+    type: string
+    description: Error message if processing failed
+    example: Failed to extract text from PDF

specs/api/components/schemas/common/RdfValue.yaml

@@ -0,0 +1,21 @@
+type: object
+description: |
+  RDF value - represents either a URI/entity or a literal value.
+
+  When `e` is true, `v` must be a full URI (e.g., http://schema.org/name).
+  When `e` is false, `v` is a literal value (string, number, etc.).
+properties:
+  v:
+    type: string
+    description: The value - full URI when e=true, literal when e=false
+    example: http://example.com/Person1
+  e:
+    type: boolean
+    description: True if entity/URI, false if literal value
+    example: true
+required:
+  - v
+  - e
+example:
+  v: http://schema.org/name
+  e: true

specs/api/components/schemas/common/Triple.yaml

@@ -0,0 +1,29 @@
+type: object
+description: |
+  RDF triple representing a subject-predicate-object statement in the knowledge graph.
+
+  Example: (Person1) -[has name]-> ("John Doe")
+properties:
+  s:
+    $ref: './RdfValue.yaml'
+    description: Subject - the entity the statement is about
+  p:
+    $ref: './RdfValue.yaml'
+    description: Predicate - the property or relationship
+  o:
+    $ref: './RdfValue.yaml'
+    description: Object - the value or target entity
+required:
+  - s
+  - p
+  - o
+example:
+  s:
+    v: http://example.com/Person1
+    e: true
+  p:
+    v: http://schema.org/name
+    e: true
+  o:
+    v: John Doe
+    e: false

specs/api/components/schemas/config/ConfigRequest.yaml

@@ -0,0 +1,67 @@
+type: object
+description: |
+  Configuration service request.
+
+  Supports operations: config, list, get, put, delete
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum: [config, list, get, put, delete]
+    description: |
+      Operation to perform:
+      - `config`: Get complete configuration
+      - `list`: List all items of a specific type
+      - `get`: Get specific configuration items
+      - `put`: Set/update configuration values
+      - `delete`: Delete configuration items
+    example: config
+  type:
+    type: string
+    description: |
+      Configuration type (required for list, get, put, delete operations).
+      Common types: flow, prompt, token-cost, parameter-type, interface-description
+    example: flow
+  keys:
+    type: array
+    description: Keys to retrieve (for get operation) or delete (for delete operation)
+    items:
+      type: object
+      required:
+        - type
+        - key
+      properties:
+        type:
+          type: string
+          description: Configuration type
+          example: flow
+        key:
+          type: string
+          description: Configuration key
+          example: my-flow
+  values:
+    type: array
+    description: Values to set/update (for put operation)
+    items:
+      type: object
+      required:
+        - type
+        - key
+        - value
+      properties:
+        type:
+          type: string
+          description: Configuration type
+          example: flow
+        key:
+          type: string
+          description: Configuration key
+          example: my-flow
+        value:
+          type: object
+          description: Configuration value (structure depends on type)
+          additionalProperties: true
+          example:
+            blueprint-name: document-rag
+            description: My RAG flow

specs/api/components/schemas/config/ConfigResponse.yaml

@@ -0,0 +1,49 @@
+type: object
+description: Configuration service response
+properties:
+  version:
+    type: integer
+    description: Configuration version number
+    example: 42
+  config:
+    type: object
+    description: Complete configuration (returned by 'config' operation)
+    additionalProperties: true
+    example:
+      flow:
+        default:
+          blueprint-name: document-rag+graph-rag
+          description: Default flow
+      prompt:
+        system: You are a helpful AI assistant
+      token-cost:
+        gpt-4:
+          prompt: 0.03
+          completion: 0.06
+  directory:
+    type: array
+    description: List of keys (returned by 'list' operation)
+    items:
+      type: string
+    example:
+      - default
+      - production
+      - my-flow
+  values:
+    type: array
+    description: Retrieved configuration values (returned by 'get' operation)
+    items:
+      type: object
+      properties:
+        type:
+          type: string
+          example: flow
+        key:
+          type: string
+          example: default
+        value:
+          type: object
+          additionalProperties: true
+          example:
+            blueprint-name: document-rag+graph-rag
+            description: Default flow

specs/api/components/schemas/diag/StructuredDiagRequest.yaml

@@ -0,0 +1,46 @@
+type: object
+description: |
+  Structured data diagnosis request - analyze and understand structured data formats.
+
+  Operations: detect-type, generate-descriptor, diagnose, schema-selection
+required:
+  - operation
+  - sample
+properties:
+  operation:
+    type: string
+    enum:
+      - detect-type
+      - generate-descriptor
+      - diagnose
+      - schema-selection
+    description: |
+      Diagnosis operation:
+      - `detect-type`: Identify data format (CSV, JSON, XML)
+      - `generate-descriptor`: Create schema descriptor for data
+      - `diagnose`: Full analysis (detect + generate descriptor)
+      - `schema-selection`: Find matching schemas for data
+  sample:
+    type: string
+    description: Data sample to analyze (text content)
+    example: |
+      name,age,email
+      Alice,30,alice@example.com
+      Bob,25,bob@example.com
+  type:
+    type: string
+    description: Data type (required for generate-descriptor)
+    enum: [csv, json, xml]
+    example: csv
+  schema-name:
+    type: string
+    description: Target schema name for descriptor generation (optional)
+    example: person-records
+  options:
+    type: object
+    description: Format-specific options (e.g., CSV delimiter)
+    additionalProperties:
+      type: string
+    example:
+      delimiter: ","
+      has_header: "true"

specs/api/components/schemas/diag/StructuredDiagResponse.yaml

@@ -0,0 +1,49 @@
+type: object
+description: Structured data diagnosis response
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    description: Operation that was performed
+    example: diagnose
+  detected-type:
+    type: string
+    description: Detected data format (for detect-type/diagnose)
+    enum: [csv, json, xml]
+    example: csv
+  confidence:
+    type: number
+    description: Detection confidence score (0.0-1.0)
+    minimum: 0.0
+    maximum: 1.0
+    example: 0.95
+  descriptor:
+    type: object
+    description: Generated schema descriptor (for generate-descriptor/diagnose)
+    additionalProperties: {}
+    example:
+      schema_name: person-records
+      type: csv
+      fields:
+        - name: name
+          type: string
+        - name: age
+          type: integer
+        - name: email
+          type: string
+  metadata:
+    type: object
+    description: Additional analysis metadata
+    additionalProperties:
+      type: string
+    example:
+      field_count: "3"
+      record_count: "2"
+      has_header: "true"
+  schema-matches:
+    type: array
+    description: Matching schema IDs (for schema-selection)
+    items:
+      type: string
+    example: ["person-schema-v1", "contact-schema-v2"]

specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryRequest.yaml

@@ -0,0 +1,29 @@
+type: object
+description: |
+  Document embeddings query request - find similar documents by vector similarity.
+required:
+  - vectors
+properties:
+  vectors:
+    type: array
+    description: Query embedding vector
+    items:
+      type: number
+    example: [0.023, -0.142, 0.089, 0.234, -0.067, 0.156]
+  limit:
+    type: integer
+    description: Maximum number of document chunks to return
+    default: 10
+    minimum: 1
+    maximum: 1000
+    example: 20
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search
+    default: default
+    example: research

specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryResponse.yaml

@@ -0,0 +1,12 @@
+type: object
+description: Document embeddings query response
+properties:
+  chunks:
+    type: array
+    description: Similar document chunks (text strings)
+    items:
+      type: string
+    example:
+      - "Quantum computing uses quantum mechanics principles for computation..."
+      - "Neural networks are computing systems inspired by biological neurons..."
+      - "Machine learning algorithms learn patterns from data..."

specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryRequest.yaml

@@ -0,0 +1,29 @@
+type: object
+description: |
+  Graph embeddings query request - find similar entities by vector similarity.
+required:
+  - vectors
+properties:
+  vectors:
+    type: array
+    description: Query embedding vector
+    items:
+      type: number
+    example: [0.023, -0.142, 0.089, 0.234, -0.067, 0.156]
+  limit:
+    type: integer
+    description: Maximum number of entities to return
+    default: 10
+    minimum: 1
+    maximum: 1000
+    example: 20
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search
+    default: default
+    example: research

specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryResponse.yaml

@@ -0,0 +1,12 @@
+type: object
+description: Graph embeddings query response
+properties:
+  entities:
+    type: array
+    description: Similar entities (RDF values)
+    items:
+      $ref: '../../common/RdfValue.yaml'
+    example:
+      - {v: "https://example.com/person/alice", e: true}
+      - {v: "https://example.com/person/bob", e: true}
+      - {v: "https://example.com/concept/quantum", e: true}

specs/api/components/schemas/embeddings/EmbeddingsRequest.yaml

@@ -0,0 +1,10 @@
+type: object
+description: |
+  Embeddings request - convert text to vector embedding.
+required:
+  - text
+properties:
+  text:
+    type: string
+    description: Text to convert to embedding vector
+    example: Quantum computing uses quantum mechanics principles for computation.

specs/api/components/schemas/embeddings/EmbeddingsResponse.yaml

@@ -0,0 +1,11 @@
+type: object
+description: Embeddings response
+required:
+  - vectors
+properties:
+  vectors:
+    type: array
+    description: Embedding vector (array of floats)
+    items:
+      type: number
+    example: [0.023, -0.142, 0.089, 0.234, -0.067, 0.156]

specs/api/components/schemas/errors/ErrorObject.yaml

@@ -0,0 +1,14 @@
+type: object
+description: Structured error response with type and message
+properties:
+  type:
+    type: string
+    description: Error type identifier
+    example: gateway-error
+  message:
+    type: string
+    description: Human-readable error message
+    example: Timeout
+required:
+  - type
+  - message

specs/api/components/schemas/flow/FlowRequest.yaml

@@ -0,0 +1,76 @@
+type: object
+description: |
+  Flow service request for managing flow instances and blueprints.
+
+  Operations: start-flow, stop-flow, list-flows, get-flow,
+  list-blueprints, get-blueprint, put-blueprint, delete-blueprint
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum:
+      - start-flow
+      - stop-flow
+      - list-flows
+      - get-flow
+      - list-blueprints
+      - get-blueprint
+      - put-blueprint
+      - delete-blueprint
+    description: |
+      Flow operation:
+      - `start-flow`: Start a new flow instance from a blueprint
+      - `stop-flow`: Stop a running flow instance
+      - `list-flows`: List all running flow instances
+      - `get-flow`: Get details of a running flow
+      - `list-blueprints`: List available flow blueprints
+      - `get-blueprint`: Get blueprint definition
+      - `put-blueprint`: Create/update blueprint definition
+      - `delete-blueprint`: Delete blueprint definition
+  flow-id:
+    type: string
+    description: Flow instance ID (required for start-flow, stop-flow, get-flow)
+    example: my-flow
+  blueprint-name:
+    type: string
+    description: Flow blueprint name (required for start-flow, get-blueprint, put-blueprint, delete-blueprint)
+    example: document-rag
+  blueprint-definition:
+    type: object
+    description: Flow blueprint definition (required for put-blueprint)
+    additionalProperties: true
+    example:
+      description: Custom RAG pipeline
+      parameters:
+        model:
+          type: llm-model
+          description: LLM model for processing
+          order: 1
+      class:
+        text-completion:{class}:
+          request: non-persistent://tg/request/text-completion:{class}
+          response: non-persistent://tg/response/text-completion:{class}
+      flow:
+        chunker:{id}:
+          input: persistent://tg/flow/chunk:{id}
+          output: persistent://tg/flow/chunk-load:{id}
+      interfaces:
+        agent:
+          request: non-persistent://tg/request/agent:{id}
+          response: non-persistent://tg/response/agent:{id}
+  description:
+    type: string
+    description: Flow description (optional for start-flow)
+    example: My document processing flow
+  parameters:
+    type: object
+    description: |
+      Flow parameters (for start-flow).
+      All values are stored as strings, regardless of input type.
+    additionalProperties:
+      type: string
+    example:
+      model: gpt-4
+      temperature: "0.7"
+      chunk-size: "1000"

specs/api/components/schemas/flow/FlowResponse.yaml

@@ -0,0 +1,82 @@
+type: object
+description: Flow service response
+properties:
+  flow-id:
+    type: string
+    description: Flow instance ID (returned by start-flow)
+    example: my-flow
+  flow-ids:
+    type: array
+    description: List of running flow IDs (returned by list-flows)
+    items:
+      type: string
+    example:
+      - default
+      - production
+      - my-flow
+  blueprint-names:
+    type: array
+    description: List of available blueprint names (returned by list-blueprints)
+    items:
+      type: string
+    example:
+      - document-rag
+      - graph-rag
+      - document-rag+graph-rag
+  blueprint-definition:
+    type: object
+    description: Blueprint definition (returned by get-blueprint)
+    additionalProperties: true
+    example:
+      description: Standard RAG pipeline
+      parameters:
+        model:
+          type: llm-model
+          order: 1
+      class:
+        text-completion:{class}:
+          request: non-persistent://tg/request/text-completion:{class}
+          response: non-persistent://tg/response/text-completion:{class}
+      flow:
+        chunker:{id}:
+          input: persistent://tg/flow/chunk:{id}
+          output: persistent://tg/flow/chunk-load:{id}
+      interfaces:
+        agent:
+          request: non-persistent://tg/request/agent:{id}
+          response: non-persistent://tg/response/agent:{id}
+  flow:
+    type: object
+    description: Flow instance details (returned by get-flow)
+    properties:
+      blueprint-name:
+        type: string
+        example: document-rag
+      description:
+        type: string
+        example: My document processing flow
+      parameters:
+        type: object
+        description: Flow parameters (all values are strings)
+        additionalProperties:
+          type: string
+        example:
+          model: gpt-4
+          temperature: "0.7"
+      interfaces:
+        type: object
+        description: Service interfaces with resolved queue names
+        additionalProperties: true
+        example:
+          agent:
+            request: non-persistent://tg/request/agent:my-flow
+            response: non-persistent://tg/response/agent:my-flow
+          text-load: persistent://tg/flow/text-document-load:my-flow
+  description:
+    type: string
+    description: Description
+  parameters:
+    type: object
+    description: Parameters
+    additionalProperties:
+      type: string

specs/api/components/schemas/knowledge/KnowledgeRequest.yaml

@@ -0,0 +1,128 @@
+type: object
+description: |
+  Knowledge graph core management request.
+
+  Operations: list-kg-cores, get-kg-core, put-kg-core, delete-kg-core,
+  load-kg-core, unload-kg-core
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum:
+      - list-kg-cores
+      - get-kg-core
+      - put-kg-core
+      - delete-kg-core
+      - load-kg-core
+      - unload-kg-core
+    description: |
+      Knowledge core operation:
+      - `list-kg-cores`: List knowledge cores for user
+      - `get-kg-core`: Get knowledge core by ID
+      - `put-kg-core`: Store triples and/or embeddings
+      - `delete-kg-core`: Delete knowledge core by ID
+      - `load-kg-core`: Load knowledge core into flow
+      - `unload-kg-core`: Unload knowledge core from flow
+  user:
+    type: string
+    description: User identifier (for list-kg-cores, put-kg-core, delete-kg-core)
+    default: trustgraph
+    example: alice
+  id:
+    type: string
+    description: Knowledge core ID (for get, put, delete, load, unload)
+    example: core-123
+  flow:
+    type: string
+    description: Flow ID (for load-kg-core)
+    example: my-flow
+  collection:
+    type: string
+    description: Collection identifier (for load-kg-core)
+    default: default
+    example: default
+  triples:
+    type: object
+    description: Triples to store (for put-kg-core)
+    required:
+      - metadata
+      - triples
+    properties:
+      metadata:
+        type: object
+        required:
+          - id
+          - user
+          - collection
+        properties:
+          id:
+            type: string
+            description: Knowledge core ID
+            example: core-123
+          user:
+            type: string
+            description: User identifier
+            example: alice
+          collection:
+            type: string
+            description: Collection identifier
+            example: default
+          metadata:
+            type: array
+            description: Metadata triples
+            items:
+              $ref: '../../common/Triple.yaml'
+      triples:
+        type: array
+        description: Knowledge triples
+        items:
+          $ref: '../../common/Triple.yaml'
+  graph-embeddings:
+    type: object
+    description: Graph embeddings to store (for put-kg-core)
+    required:
+      - metadata
+      - entities
+    properties:
+      metadata:
+        type: object
+        required:
+          - id
+          - user
+          - collection
+        properties:
+          id:
+            type: string
+            description: Knowledge core ID
+            example: core-123
+          user:
+            type: string
+            description: User identifier
+            example: alice
+          collection:
+            type: string
+            description: Collection identifier
+            example: default
+          metadata:
+            type: array
+            description: Metadata triples
+            items:
+              $ref: '../../common/Triple.yaml'
+      entities:
+        type: array
+        description: Entity embeddings
+        items:
+          type: object
+          required:
+            - entity
+            - vectors
+          properties:
+            entity:
+              $ref: '../../common/RdfValue.yaml'
+            vectors:
+              type: array
+              description: Embedding vectors
+              items:
+                type: number
+              example: [0.1, 0.2, 0.3]

specs/api/components/schemas/knowledge/KnowledgeResponse.yaml

@@ -0,0 +1,91 @@
+type: object
+description: Knowledge service response
+properties:
+  ids:
+    type: array
+    description: List of knowledge core IDs (returned by list-kg-cores)
+    items:
+      type: string
+    example: ["core-123", "core-456"]
+  triples:
+    type: object
+    description: Triples data (returned by get-kg-core, streamed)
+    properties:
+      metadata:
+        type: object
+        required:
+          - id
+          - user
+          - collection
+        properties:
+          id:
+            type: string
+            description: Knowledge core ID
+            example: core-123
+          user:
+            type: string
+            description: User identifier
+            example: alice
+          collection:
+            type: string
+            description: Collection identifier
+            example: default
+          metadata:
+            type: array
+            description: Metadata triples
+            items:
+              $ref: '../../common/Triple.yaml'
+      triples:
+        type: array
+        description: Knowledge triples
+        items:
+          $ref: '../../common/Triple.yaml'
+  graph-embeddings:
+    type: object
+    description: Graph embeddings data (returned by get-kg-core, streamed)
+    properties:
+      metadata:
+        type: object
+        required:
+          - id
+          - user
+          - collection
+        properties:
+          id:
+            type: string
+            description: Knowledge core ID
+            example: core-123
+          user:
+            type: string
+            description: User identifier
+            example: alice
+          collection:
+            type: string
+            description: Collection identifier
+            example: default
+          metadata:
+            type: array
+            description: Metadata triples
+            items:
+              $ref: '../../common/Triple.yaml'
+      entities:
+        type: array
+        description: Entity embeddings
+        items:
+          type: object
+          required:
+            - entity
+            - vectors
+          properties:
+            entity:
+              $ref: '../../common/RdfValue.yaml'
+            vectors:
+              type: array
+              description: Embedding vectors
+              items:
+                type: number
+              example: [0.1, 0.2, 0.3]
+  eos:
+    type: boolean
+    description: End of stream marker (for streaming responses)
+    example: true

specs/api/components/schemas/librarian/LibrarianRequest.yaml

@@ -0,0 +1,79 @@
+type: object
+description: |
+  Librarian service request for document library management.
+
+  Operations: add-document, remove-document, list-documents,
+  start-processing, stop-processing, list-processing
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum:
+      - add-document
+      - remove-document
+      - list-documents
+      - start-processing
+      - stop-processing
+      - list-processing
+    description: |
+      Library operation:
+      - `add-document`: Add document to library
+      - `remove-document`: Remove document from library
+      - `list-documents`: List documents in library
+      - `start-processing`: Start processing library documents
+      - `stop-processing`: Stop library processing
+      - `list-processing`: List processing status
+  flow:
+    type: string
+    description: Flow ID
+    example: my-flow
+  collection:
+    type: string
+    description: Collection identifier
+    default: default
+    example: default
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  document-id:
+    type: string
+    description: Document identifier
+    example: doc-123
+  processing-id:
+    type: string
+    description: Processing task identifier
+    example: proc-456
+  document-metadata:
+    $ref: '../common/DocumentMetadata.yaml'
+  processing-metadata:
+    $ref: '../common/ProcessingMetadata.yaml'
+  content:
+    type: string
+    description: Document content (for add-document with inline content)
+    example: This is the document content...
+  criteria:
+    type: array
+    description: Search criteria for filtering documents
+    items:
+      type: object
+      required:
+        - key
+        - value
+        - operator
+      properties:
+        key:
+          type: string
+          description: Metadata field name
+          example: author
+        value:
+          type: string
+          description: Value to match
+          example: John Doe
+        operator:
+          type: string
+          enum: [eq, ne, gt, lt, contains]
+          description: Comparison operator
+          example: eq

specs/api/components/schemas/librarian/LibrarianResponse.yaml

@@ -0,0 +1,18 @@
+type: object
+description: Librarian service response
+properties:
+  document-metadata:
+    $ref: '../common/DocumentMetadata.yaml'
+  content:
+    type: string
+    description: Document content
+  document-metadatas:
+    type: array
+    description: List of documents (returned by list-documents)
+    items:
+      $ref: '../common/DocumentMetadata.yaml'
+  processing-metadatas:
+    type: array
+    description: List of processing tasks (returned by list-processing)
+    items:
+      $ref: '../common/ProcessingMetadata.yaml'

specs/api/components/schemas/loading/DocumentLoadRequest.yaml

@@ -0,0 +1,32 @@
+type: object
+description: |
+  Document load request - load binary document (PDF, etc.) into processing pipeline.
+
+  Fire-and-forget operation (no response).
+required:
+  - data
+properties:
+  data:
+    type: string
+    description: Document data (base64 encoded)
+    format: byte
+    example: JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL...
+  id:
+    type: string
+    description: Document identifier
+    example: doc-456
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection for document
+    default: default
+    example: research
+  metadata:
+    type: array
+    description: Document metadata as RDF triples
+    items:
+      $ref: '../../common/Triple.yaml'

specs/api/components/schemas/loading/TextLoadRequest.yaml

@@ -0,0 +1,37 @@
+type: object
+description: |
+  Text load request - load text document into processing pipeline.
+
+  Fire-and-forget operation (no response).
+required:
+  - text
+properties:
+  text:
+    type: string
+    description: Text content (base64 encoded)
+    format: byte
+    example: VGhpcyBpcyB0aGUgZG9jdW1lbnQgdGV4dC4uLg==
+  id:
+    type: string
+    description: Document identifier
+    example: doc-123
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection for document
+    default: default
+    example: research
+  charset:
+    type: string
+    description: Text character encoding
+    default: utf-8
+    example: utf-8
+  metadata:
+    type: array
+    description: Document metadata as RDF triples
+    items:
+      $ref: '../../common/Triple.yaml'

specs/api/components/schemas/mcp-tool/McpToolRequest.yaml

@@ -0,0 +1,17 @@
+type: object
+description: |
+  MCP tool request - execute Model Context Protocol tool.
+required:
+  - name
+properties:
+  name:
+    type: string
+    description: Tool name to execute
+    example: search
+  parameters:
+    type: object
+    description: Tool parameters (JSON object, auto-converted to string internally)
+    additionalProperties: {}
+    example:
+      query: quantum computing
+      limit: 10

specs/api/components/schemas/mcp-tool/McpToolResponse.yaml

@@ -0,0 +1,15 @@
+type: object
+description: MCP tool response
+properties:
+  text:
+    type: string
+    description: Text response from tool
+    example: Found 10 results for quantum computing...
+  object:
+    type: object
+    description: Structured response from tool (JSON object)
+    additionalProperties: {}
+    example:
+      results:
+        - title: Introduction to Quantum Computing
+          url: https://example.com/qc-intro

specs/api/components/schemas/prompt/PromptRequest.yaml

@@ -0,0 +1,32 @@
+type: object
+description: |
+  Prompt service request - template-based text generation.
+
+  Execute a stored prompt template with variable substitution.
+required:
+  - id
+properties:
+  id:
+    type: string
+    description: Prompt template ID (stored in config)
+    example: summarize-document
+  terms:
+    type: object
+    description: Template variables as key-value pairs (values are JSON strings)
+    additionalProperties:
+      type: string
+    example:
+      document: '"This is the document text to summarize..."'
+      max_length: '"200"'
+  variables:
+    type: object
+    description: Alternative to terms - variables as native JSON values (auto-converted)
+    additionalProperties: {}
+    example:
+      document: This is the document text to summarize...
+      max_length: 200
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/prompt/PromptResponse.yaml

@@ -0,0 +1,16 @@
+type: object
+description: Prompt service response
+properties:
+  text:
+    type: string
+    description: Generated text response
+    example: This document discusses quantum computing and its applications...
+  object:
+    type: string
+    description: Structured response (JSON string) if prompt produces objects
+    example: '{"summary": "Quantum computing overview", "key_points": [...]}'
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true

specs/api/components/schemas/query/NlpQueryRequest.yaml

@@ -0,0 +1,17 @@
+type: object
+description: |
+  NLP query request - convert natural language question to structured query.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: Natural language question
+    example: Who does Alice know that works in engineering?
+  max-results:
+    type: integer
+    description: Maximum results to return when query is executed
+    default: 100
+    minimum: 1
+    maximum: 10000
+    example: 50

specs/api/components/schemas/query/NlpQueryResponse.yaml

@@ -0,0 +1,47 @@
+type: object
+description: NLP query response
+required:
+  - graphql-query
+  - variables
+properties:
+  graphql-query:
+    type: string
+    description: Generated GraphQL query
+    example: |
+      query GetConnections($person: ID!) {
+        person(id: $person) {
+          knows {
+            name
+            worksFor { department }
+          }
+        }
+      }
+  variables:
+    type: object
+    description: Query variables
+    additionalProperties:
+      type: string
+    example:
+      person: "https://example.com/person/alice"
+  detected-schemas:
+    type: array
+    description: Detected schema types used in query
+    items:
+      type: string
+    example: ["Person", "Organization"]
+  confidence:
+    type: number
+    description: Confidence score for query generation (0.0-1.0)
+    minimum: 0.0
+    maximum: 1.0
+    example: 0.87
+  error:
+    type: object
+    description: Error if query generation failed
+    properties:
+      type:
+        type: string
+        example: PARSE_ERROR
+      message:
+        type: string
+        example: Could not understand question structure

specs/api/components/schemas/query/ObjectsQueryRequest.yaml

@@ -0,0 +1,40 @@
+type: object
+description: |
+  Objects query request - GraphQL query over knowledge graph.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: GraphQL query string
+    example: |
+      query GetPerson($id: ID!) {
+        person(id: $id) {
+          name
+          email
+          knows {
+            name
+          }
+        }
+      }
+  variables:
+    type: object
+    description: GraphQL query variables
+    additionalProperties:
+      type: string
+    example:
+      id: "https://example.com/person/alice"
+  operation-name:
+    type: string
+    description: Operation name (for multi-operation documents)
+    example: GetPerson
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/ObjectsQueryResponse.yaml

@@ -0,0 +1,54 @@
+type: object
+description: Objects query response (GraphQL format)
+properties:
+  data:
+    description: GraphQL response data (JSON object or null)
+    oneOf:
+      - type: object
+        additionalProperties: {}
+      - type: "null"
+    example:
+      person:
+        name: Alice
+        email: alice@example.com
+        knows:
+          - name: Bob
+          - name: Carol
+  errors:
+    type: array
+    description: GraphQL field-level errors
+    items:
+      type: object
+      properties:
+        message:
+          type: string
+          description: Error message
+          example: Cannot query field 'age' on type 'Person'
+        path:
+          type: array
+          description: Path to error location
+          items:
+            type: string
+          example: ["person", "age"]
+        extensions:
+          type: object
+          description: Additional error metadata
+          additionalProperties:
+            type: string
+  extensions:
+    type: object
+    description: Query metadata (execution time, etc.)
+    additionalProperties:
+      type: string
+    example:
+      execution_time_ms: "42"
+  error:
+    type: object
+    description: System-level error (connection, timeout, etc.)
+    properties:
+      type:
+        type: string
+        example: TIMEOUT_ERROR
+      message:
+        type: string
+        example: Query execution timeout

specs/api/components/schemas/query/StructuredQueryRequest.yaml

@@ -0,0 +1,22 @@
+type: object
+description: |
+  Structured query request - natural language question with automatic execution.
+
+  Combines NLP query generation and execution in one call.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: Natural language question
+    example: Who does Alice know that works in engineering?
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/StructuredQueryResponse.yaml

@@ -0,0 +1,34 @@
+type: object
+description: Structured query response
+properties:
+  data:
+    description: Query results (JSON object or null)
+    oneOf:
+      - type: object
+        additionalProperties: {}
+      - type: "null"
+    example:
+      person:
+        name: Alice
+        knows:
+          - name: Bob
+            worksFor: {name: Acme Corp, department: Engineering}
+          - name: Carol
+            worksFor: {name: Tech Inc, department: Engineering}
+  errors:
+    type: array
+    description: Query errors (array of error strings)
+    items:
+      type: string
+    example:
+      - Could not resolve field 'age' on type 'Person'
+  error:
+    type: object
+    description: System-level error
+    properties:
+      type:
+        type: string
+        example: QUERY_GENERATION_ERROR
+      message:
+        type: string
+        example: Failed to generate query from question

specs/api/components/schemas/query/TriplesQueryRequest.yaml

@@ -0,0 +1,30 @@
+type: object
+description: |
+  Triples query request - query knowledge graph by subject/predicate/object pattern.
+properties:
+  s:
+    $ref: '../../common/RdfValue.yaml'
+    description: Subject filter (optional)
+  p:
+    $ref: '../../common/RdfValue.yaml'
+    description: Predicate filter (optional)
+  o:
+    $ref: '../../common/RdfValue.yaml'
+    description: Object filter (optional)
+  limit:
+    type: integer
+    description: Maximum number of triples to return
+    default: 10000
+    minimum: 1
+    maximum: 100000
+    example: 100
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/TriplesQueryResponse.yaml

@@ -0,0 +1,10 @@
+type: object
+description: Triples query response
+required:
+  - response
+properties:
+  response:
+    type: array
+    description: Matching triples
+    items:
+      $ref: '../../common/Triple.yaml'

specs/api/components/schemas/rag/DocumentRagRequest.yaml

@@ -0,0 +1,33 @@
+type: object
+description: |
+  Document RAG (Retrieval-Augmented Generation) query request.
+  Searches document embeddings and generates answer using retrieved context.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: User query or question
+    example: What are the key findings in the research papers?
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search within
+    default: default
+    example: research
+  doc-limit:
+    type: integer
+    description: Maximum number of documents to retrieve
+    default: 20
+    minimum: 1
+    maximum: 100
+    example: 10
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/rag/DocumentRagResponse.yaml

@@ -0,0 +1,24 @@
+type: object
+description: Document RAG response
+properties:
+  response:
+    type: string
+    description: Generated response based on retrieved documents
+    example: The research papers found three key findings...
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to retrieve documents
+      type:
+        type: string
+        description: Error type
+        example: RETRIEVAL_ERROR

specs/api/components/schemas/rag/GraphRagRequest.yaml

@@ -0,0 +1,54 @@
+type: object
+description: |
+  Graph RAG (Retrieval-Augmented Generation) query request.
+  Searches knowledge graph and generates answer using retrieved subgraph.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: User query or question
+    example: What connections exist between quantum physics and computer science?
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search within
+    default: default
+    example: research
+  entity-limit:
+    type: integer
+    description: Maximum number of entities to retrieve
+    default: 50
+    minimum: 1
+    maximum: 200
+    example: 30
+  triple-limit:
+    type: integer
+    description: Maximum number of triples to retrieve per entity
+    default: 30
+    minimum: 1
+    maximum: 100
+    example: 20
+  max-subgraph-size:
+    type: integer
+    description: Maximum total subgraph size (triples)
+    default: 1000
+    minimum: 10
+    maximum: 5000
+    example: 500
+  max-path-length:
+    type: integer
+    description: Maximum path length for graph traversal
+    default: 2
+    minimum: 1
+    maximum: 5
+    example: 3
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/rag/GraphRagResponse.yaml

@@ -0,0 +1,24 @@
+type: object
+description: Graph RAG response
+properties:
+  response:
+    type: string
+    description: Generated response based on retrieved knowledge graph
+    example: Quantum physics and computer science intersect in quantum computing...
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to retrieve graph data
+      type:
+        type: string
+        description: Error type
+        example: GRAPH_ERROR

specs/api/components/schemas/text-completion/TextCompletionRequest.yaml

@@ -0,0 +1,20 @@
+type: object
+description: |
+  Text completion request - direct LLM completion without RAG.
+required:
+  - system
+  - prompt
+properties:
+  system:
+    type: string
+    description: System prompt that sets behavior and context for the LLM
+    example: You are a helpful assistant that provides concise answers.
+  prompt:
+    type: string
+    description: User prompt or question
+    example: Explain the concept of recursion in programming.
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/text-completion/TextCompletionResponse.yaml

@@ -0,0 +1,26 @@
+type: object
+description: Text completion response
+required:
+  - response
+properties:
+  response:
+    type: string
+    description: Generated text response
+    example: Recursion is a programming technique where a function calls itself...
+  in-token:
+    type: integer
+    description: Number of input tokens consumed
+    example: 45
+  out-token:
+    type: integer
+    description: Number of output tokens generated
+    example: 128
+  model:
+    type: string
+    description: Model used for completion
+    example: gpt-4
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true