From 83d3ad05df440796fa1b7947d6146b82f63197ab Mon Sep 17 00:00:00 2001
From: Cyber MacGeddon <cybermaggedon@gmail.com>
Date: Thu, 15 Jan 2026 10:00:20 +0000
Subject: [PATCH] Config and flow services

---
 .../schemas/config/ConfigRequest.yaml         |  67 ++++++
 .../schemas/config/ConfigResponse.yaml        |  49 +++++
 .../components/schemas/flow/FlowRequest.yaml  |  76 +++++++
 .../components/schemas/flow/FlowResponse.yaml |  82 ++++++++
 specs/api/openapi.yaml                        |  11 +-
 specs/api/paths/config.yaml                   | 165 +++++++++++++++
 specs/api/paths/flow.yaml                     | 194 ++++++++++++++++++
 7 files changed, 638 insertions(+), 6 deletions(-)
 create mode 100644 specs/api/components/schemas/config/ConfigRequest.yaml
 create mode 100644 specs/api/components/schemas/config/ConfigResponse.yaml
 create mode 100644 specs/api/components/schemas/flow/FlowRequest.yaml
 create mode 100644 specs/api/components/schemas/flow/FlowResponse.yaml
 create mode 100644 specs/api/paths/config.yaml
 create mode 100644 specs/api/paths/flow.yaml

diff --git a/specs/api/components/schemas/config/ConfigRequest.yaml b/specs/api/components/schemas/config/ConfigRequest.yaml
new file mode 100644
index 00000000..aa39e519
--- /dev/null
+++ b/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
diff --git a/specs/api/components/schemas/config/ConfigResponse.yaml b/specs/api/components/schemas/config/ConfigResponse.yaml
new file mode 100644
index 00000000..9815c51e
--- /dev/null
+++ b/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
diff --git a/specs/api/components/schemas/flow/FlowRequest.yaml b/specs/api/components/schemas/flow/FlowRequest.yaml
new file mode 100644
index 00000000..8cff7955
--- /dev/null
+++ b/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"
diff --git a/specs/api/components/schemas/flow/FlowResponse.yaml b/specs/api/components/schemas/flow/FlowResponse.yaml
new file mode 100644
index 00000000..c93ae42c
--- /dev/null
+++ b/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
diff --git a/specs/api/openapi.yaml b/specs/api/openapi.yaml
index cb5997fc..4398665c 100644
--- a/specs/api/openapi.yaml
+++ b/specs/api/openapi.yaml
@@ -95,12 +95,11 @@ tags:
     description: System metrics and monitoring
 
 paths:
-  # Global services will be added here as we build them
-  # /api/v1/config:
-  #   $ref: './paths/config.yaml'
-  # /api/v1/flow:
-  #   $ref: './paths/flow.yaml'
-  # etc.
+  /api/v1/config:
+    $ref: './paths/config.yaml'
+  /api/v1/flow:
+    $ref: './paths/flow.yaml'
+  # More services will be added here as we build them
 
 components:
   securitySchemes:
diff --git a/specs/api/paths/config.yaml b/specs/api/paths/config.yaml
new file mode 100644
index 00000000..ef95498b
--- /dev/null
+++ b/specs/api/paths/config.yaml
@@ -0,0 +1,165 @@
+post:
+  tags:
+    - Config
+  summary: Configuration service
+  description: |
+    Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.
+
+    ## Operations
+
+    ### config
+    Get the complete system configuration including all flows, prompts, token costs, etc.
+
+    ### list
+    List all configuration items of a specific type (e.g., all flows, all prompts).
+
+    ### get
+    Retrieve specific configuration items by type and key.
+
+    ### put
+    Create or update configuration values.
+
+    ### delete
+    Delete configuration items.
+
+    ## Configuration Types
+
+    - `flow` - Flow instance definitions
+    - `flow-blueprint` - Flow blueprint definitions (stored separately from flow instances)
+    - `prompt` - Prompt templates
+    - `token-cost` - Model token pricing
+    - `parameter-type` - Parameter type definitions
+    - `interface-description` - Interface descriptions
+    - Custom types as needed
+
+    ## Important Distinction
+
+    The **config service** manages *stored configuration*.
+    The **flow service** (`/api/v1/flow`) manages *running flow instances*.
+
+    - Use config service to store/retrieve flow definitions
+    - Use flow service to start/stop/manage running flows
+
+  operationId: configService
+  security:
+    - bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/config/ConfigRequest.yaml'
+        examples:
+          getCompleteConfig:
+            summary: Get complete configuration
+            value:
+              operation: config
+          listFlows:
+            summary: List all stored flow definitions
+            value:
+              operation: list
+              type: flow
+          listPrompts:
+            summary: List all prompts
+            value:
+              operation: list
+              type: prompt
+          getFlow:
+            summary: Get specific flow definition
+            value:
+              operation: get
+              keys:
+                - type: flow
+                  key: default
+          putFlow:
+            summary: Create/update flow definition
+            value:
+              operation: put
+              values:
+                - type: flow
+                  key: my-flow
+                  value:
+                    blueprint-name: document-rag
+                    description: My RAG flow
+                    parameters:
+                      model: gpt-4
+          putPrompt:
+            summary: Set system prompt
+            value:
+              operation: put
+              values:
+                - type: prompt
+                  key: system
+                  value: You are a helpful AI assistant specialized in data analysis
+          putTokenCost:
+            summary: Set token costs for a model
+            value:
+              operation: put
+              values:
+                - type: token-cost
+                  key: gpt-4
+                  value:
+                    prompt: 0.03
+                    completion: 0.06
+          deleteFlow:
+            summary: Delete flow definition
+            value:
+              operation: delete
+              keys:
+                - type: flow
+                  key: my-flow
+  responses:
+    '200':
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/config/ConfigResponse.yaml'
+          examples:
+            completeConfig:
+              summary: Complete configuration
+              value:
+                version: 42
+                config:
+                  flow:
+                    default:
+                      blueprint-name: document-rag+graph-rag
+                      description: Default flow
+                      interfaces:
+                        agent:
+                          request: non-persistent://tg/request/agent:default
+                          response: non-persistent://tg/response/agent:default
+                  prompt:
+                    system: You are a helpful AI assistant
+                  token-cost:
+                    gpt-4:
+                      prompt: 0.03
+                      completion: 0.06
+            listFlows:
+              summary: List of flow definition keys
+              value:
+                directory:
+                  - default
+                  - production
+                  - my-flow
+            getFlow:
+              summary: Retrieved flow definition
+              value:
+                values:
+                  - type: flow
+                    key: default
+                    value:
+                      blueprint-name: document-rag+graph-rag
+                      description: Default flow
+            putSuccess:
+              summary: Put operation success
+              value:
+                version: 43
+            deleteSuccess:
+              summary: Delete operation success
+              value:
+                version: 44
+    '401':
+      $ref: '../components/responses/Unauthorized.yaml'
+    '500':
+      $ref: '../components/responses/Error.yaml'
diff --git a/specs/api/paths/flow.yaml b/specs/api/paths/flow.yaml
new file mode 100644
index 00000000..181e03bf
--- /dev/null
+++ b/specs/api/paths/flow.yaml
@@ -0,0 +1,194 @@
+post:
+  tags:
+    - Flow
+  summary: Flow lifecycle and blueprint management
+  description: |
+    Manage flow instances and blueprints.
+
+    ## Important Distinction
+
+    The **flow service** manages *running flow instances*.
+    The **config service** (`/api/v1/config`) manages *stored configuration*.
+
+    - Use flow service to start/stop/manage running flows
+    - Use config service to store/retrieve flow definitions
+
+    ## Flow Instance Operations
+
+    ### start-flow
+    Start a new flow instance from a blueprint. The blueprint must exist (either built-in or created via put-blueprint).
+
+    Parameters are resolved from:
+    1. User-provided values (--param)
+    2. Default values from parameter type definitions
+    3. Controlled-by relationships
+
+    ### stop-flow
+    Stop a running flow instance. This terminates all processors and releases resources.
+
+    ### list-flows
+    List all currently running flow instances.
+
+    ### get-flow
+    Get details of a running flow including its configuration, parameters, and interface queue names.
+
+    ## Blueprint Operations
+
+    ### list-blueprints
+    List all available flow blueprints (built-in and custom).
+
+    ### get-blueprint
+    Retrieve a blueprint definition showing its structure, parameters, processors, and interfaces.
+
+    ### put-blueprint
+    Create or update a flow blueprint definition.
+
+    Blueprints define:
+    - **Class processors**: Shared across all instances of this blueprint
+    - **Flow processors**: Unique to each flow instance
+    - **Interfaces**: Entry points for external systems
+    - **Parameters**: Configurable values for customization
+
+    ### delete-blueprint
+    Delete a custom blueprint definition. Built-in blueprints cannot be deleted.
+
+  operationId: flowService
+  security:
+    - bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/flow/FlowRequest.yaml'
+        examples:
+          startFlow:
+            summary: Start a flow instance
+            value:
+              operation: start-flow
+              flow-id: my-flow
+              blueprint-name: document-rag
+              description: My document processing flow
+              parameters:
+                model: gpt-4
+                temperature: "0.7"
+          startFlowMinimal:
+            summary: Start flow with defaults
+            value:
+              operation: start-flow
+              flow-id: my-flow
+              blueprint-name: document-rag
+          stopFlow:
+            summary: Stop a flow instance
+            value:
+              operation: stop-flow
+              flow-id: my-flow
+          listFlows:
+            summary: List running flows
+            value:
+              operation: list-flows
+          getFlow:
+            summary: Get flow details
+            value:
+              operation: get-flow
+              flow-id: my-flow
+          listBlueprints:
+            summary: List available blueprints
+            value:
+              operation: list-blueprints
+          getBlueprint:
+            summary: Get blueprint definition
+            value:
+              operation: get-blueprint
+              blueprint-name: document-rag
+          putBlueprint:
+            summary: Create/update blueprint
+            value:
+              operation: put-blueprint
+              blueprint-name: my-custom-rag
+              blueprint-definition:
+                description: Custom RAG pipeline
+                parameters:
+                  model:
+                    type: llm-model
+                    description: 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}
+          deleteBlueprint:
+            summary: Delete blueprint
+            value:
+              operation: delete-blueprint
+              blueprint-name: my-custom-rag
+  responses:
+    '200':
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/flow/FlowResponse.yaml'
+          examples:
+            startFlow:
+              summary: Flow started
+              value:
+                flow-id: my-flow
+            listFlows:
+              summary: Running flows
+              value:
+                flow-ids:
+                  - default
+                  - production
+                  - my-flow
+            getFlow:
+              summary: Flow details
+              value:
+                flow:
+                  blueprint-name: document-rag
+                  description: My document processing flow
+                  parameters:
+                    model: gpt-4
+                    temperature: "0.7"
+                  interfaces:
+                    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
+            listBlueprints:
+              summary: Available blueprints
+              value:
+                blueprint-names:
+                  - document-rag
+                  - graph-rag
+                  - document-rag+graph-rag
+                  - my-custom-rag
+            getBlueprint:
+              summary: Blueprint definition
+              value:
+                blueprint-definition:
+                  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}
+                  interfaces:
+                    agent:
+                      request: non-persistent://tg/request/agent:{id}
+                      response: non-persistent://tg/response/agent:{id}
+    '401':
+      $ref: '../components/responses/Unauthorized.yaml'
+    '500':
+      $ref: '../components/responses/Error.yaml'