openapi.yaml

openapi: 3.1.0
info:
  title: Network-AI Swarm Orchestrator
  description: >
    Multi-agent swarm orchestration API. Provides task delegation, shared
    blackboard coordination, parallel agent spawning, and permission gating
    via AuthGuardian. Requires the companion MCP server:
    `npm install -g network-ai && npx network-ai-server --port 3001`
  version: 4.11.2
  license:
    name: MIT
    url: https://github.com/Jovancoding/Network-AI/blob/main/LICENSE

servers:
  - url: http://localhost:3001
    description: Local MCP server (default port)

paths:
  /swarm/delegate:
    post:
      operationId: delegateTask
      summary: Delegate a task to a sub-agent
      description: >
        Route a task to a specialized sub-agent within the swarm. Common agent
        types: data_analyst, strategy_advisor, risk_assessor, orchestrator.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegateTaskRequest'
      responses:
        '200':
          description: Task accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegateTaskResponse'

  /swarm/state:
    get:
      operationId: querySwarmState
      summary: Query current swarm state
      description: >
        Returns active tasks, blackboard contents, agent availability, and
        permission grants.
      parameters:
        - name: scope
          in: query
          schema:
            type: string
            enum: [all, agents, tasks, blackboard, permissions]
            default: all
          description: Scope of state information to retrieve
        - name: agentFilter
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter results to specific agent IDs
        - name: includeHistory
          in: query
          schema:
            type: boolean
            default: false
          description: Include historical task execution data
      responses:
        '200':
          description: Current swarm state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwarmStateResponse'

  /swarm/parallel:
    post:
      operationId: spawnParallelAgents
      summary: Spawn multiple agents in parallel
      description: >
        Execute multiple sub-tasks simultaneously and synthesize results.
        Useful for multi-perspective analysis.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParallelAgentsRequest'
      responses:
        '200':
          description: Synthesized results from all parallel agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParallelAgentsResponse'

  /auth/permission:
    post:
      operationId: requestPermission
      summary: Request AuthGuardian permission
      description: >
        Gate access to protected resource types. Always call before DATABASE,
        PAYMENTS, EMAIL, or FILE_EXPORT operations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionRequest'
      responses:
        '200':
          description: Permission decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionResponse'

  /context/inject:
    get:
      operationId: injectContext
      summary: Get project context for agent injection
      description: >
        Returns the persistent project context (Layer 3 memory) as a formatted
        markdown block. Prepend this to any agent's system prompt so all agents
        share the same long-term project awareness: goals, tech stack,
        architecture decisions, milestones, and banned approaches.
      responses:
        '200':
          description: Formatted project context block
          content:
            application/json:
              schema:
                type: object
                properties:
                  contextMarkdown:
                    type: string
                    description: Markdown block ready to inject into system prompt
                  updatedAt:
                    type: string
                    description: ISO timestamp of last context update

  /context/update:
    post:
      operationId: updateContext
      summary: Update persistent project context
      description: >
        Persist a decision, milestone, stack entry, goal, or banned approach
        to the project context file (Layer 3 memory). Changes survive across
        all agent sessions — every future agent that calls injectContext will
        see them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContextRequest'
      responses:
        '200':
          description: Context section updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  section:
                    type: string

  /blackboard/{key}:
      operationId: readBlackboard
      summary: Read a blackboard entry
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
          description: Blackboard key (e.g. task:001:data_analyst)
      responses:
        '200':
          description: Blackboard entry value (null if expired or not found)
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                  value: {}
                  expiresAt:
                    type: string
                    nullable: true
    put:
      operationId: updateBlackboard
      summary: Write or update a blackboard entry
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlackboardWriteRequest'
      responses:
        '200':
          description: Write confirmed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  previousValue: {}

  /qa/harness:
    post:
      operationId: runQAHarness
      summary: Run QA test harness
      description: >
        Run a batch of blackboard entries through the quality gate and return
        aggregate results including pass rate, contradictions, and a regression snapshot.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QAHarnessRequest'
      responses:
        '200':
          description: QA harness results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QAHarnessResponse'

components:
  schemas:
    DelegateTaskRequest:
      type: object
      required: [targetAgent, taskPayload]
      properties:
        targetAgent:
          type: string
          description: Agent identifier (e.g. data_analyst, strategy_advisor)
        taskPayload:
          type: object
          description: Task context, instructions, and required data
        priority:
          type: string
          enum: [low, normal, high, critical]
          default: normal
        timeout:
          type: number
          default: 30000
          description: Max execution time in milliseconds
        requiresAuth:
          type: boolean
          default: false

    DelegateTaskResponse:
      type: object
      properties:
        taskId:
          type: string
        status:
          type: string
        result: {}
        agentTrace:
          type: array
          items:
            type: object

    SwarmStateResponse:
      type: object
      properties:
        timestamp:
          type: string
        activeAgents:
          type: array
          items:
            type: object
        pendingTasks:
          type: array
          items:
            type: object
        blackboardSnapshot:
          type: object
        permissionGrants:
          type: array
          items:
            type: object

    ParallelAgentsRequest:
      type: object
      required: [tasks]
      properties:
        tasks:
          type: array
          items:
            type: object
            required: [agentType, taskPayload]
            properties:
              agentType:
                type: string
              taskPayload:
                type: object
        synthesisStrategy:
          type: string
          enum: [merge, vote, chain, first-success]
          default: merge

    ParallelAgentsResponse:
      type: object
      properties:
        synthesizedResult: {}
        individualResults:
          type: array
          items:
            type: object
        executionMetrics:
          type: object

    PermissionRequest:
      type: object
      required: [resourceType, justification]
      properties:
        resourceType:
          type: string
          enum: [DATABASE, PAYMENTS, EMAIL, FILE_EXPORT]
        justification:
          type: string
          description: Specific reason for access — must relate to the current task
        scope:
          type: string
          description: Specific access scope (e.g. read:invoices)

    PermissionResponse:
      type: object
      properties:
        granted:
          type: boolean
        grantToken:
          type: string
          nullable: true
        expiresAt:
          type: string
          nullable: true
        restrictions:
          type: array
          items:
            type: string

    BlackboardWriteRequest:
      type: object
      required: [value]
      properties:
        value: {}
        ttl:
          type: number
          description: Time-to-live in seconds (optional)

    UpdateContextRequest:
      type: object
      required: [section]
      properties:
        section:
          type: string
          enum: [decisions, milestones, stack, goals, banned, project]
          description: The context section to update
        add:
          description: Item to append (JSON object or plain string depending on section)
        set:
          type: object
          description: Key-value pairs to merge (used for stack and project sections)
        complete:
          type: string
          description: Milestone name to mark completed (milestones section only)

    QAHarnessRequest:
      type: object
      required: [scenarios]
      properties:
        scenarios:
          type: array
          items:
            type: object
            required: [id, key, value, sourceAgent]
            properties:
              id:
                type: string
              key:
                type: string
              value: {}
              sourceAgent:
                type: string
              minScore:
                type: number
        qualityThreshold:
          type: number
          description: Global minimum quality score (0-1). Defaults to 0.7.

    QAHarnessResponse:
      type: object
      properties:
        total:
          type: integer
        passed:
          type: integer
        failed:
          type: integer
        passRate:
          type: number
        contradictions:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              agentA:
                type: string
              agentB:
                type: string
        snapshot:
          type: object
          properties:
            timestamp:
              type: string
            scenariosRun:
              type: integer
            scenarioPassRate:
              type: number