@bluefly/openstandardagents 0.2.4

package/openapi/unified-agent-gateway.openapi.yaml

@@ -0,0 +1,833 @@
+openapi: 3.1.0
+info:
+  title: Unified Agent Gateway
+  version: 1.0.0
+  description: |
+    **Single Entry Point for All LLM Platform Agents**
+    
+    This gateway provides a unified OpenAPI interface for:
+    - OSSA-compliant agents (validation, deployment, orchestration)
+    - Drupal llm-platform (content, users, sites, data management)
+    - Agent Studio (Mac/iOS/CarPlay/VSCode/IDE)
+    - Agent Chat (Claude Code replacement)
+    - Langflow/LangChain/K-Agent workflows
+    - BuildKit (agent lifecycle management)
+    - GitLab CI/CD orchestration
+    
+    **Architecture**:
+    - Protocol: HTTP/REST + gRPC (agent-mesh)
+    - Auth: API Key + JWT (GitLab SSO)
+    - Registry: agent-router (service discovery)
+    - Tracing: Phoenix (all requests)
+    - Metrics: Prometheus
+    - Storage: Drupal llm-platform (single source of truth)
+
+  contact:
+    name: LLM Platform Team
+    url: https://gitlab.bluefly.io/llm
+  
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://gateway.agent-buildkit.orb.local/api/v1
+    description: Production
+  - url: http://localhost:8080/api/v1
+    description: Local development (Orbstack)
+
+security:
+  - ApiKeyAuth: []
+  - GitLabJWT: []
+
+tags:
+  - name: agents
+    description: Agent lifecycle management (create, deploy, scale, delete)
+  - name: drupal
+    description: Drupal llm-platform integration (content, users, sites)
+  - name: workflows
+    description: Langflow/LangChain workflow orchestration
+  - name: studio
+    description: Agent Studio mobile API (iOS/CarPlay remote coding)
+  - name: gitlab
+    description: GitLab CI/CD orchestration
+  - name: registry
+    description: Service discovery and health monitoring
+
+paths:
+  # =================================================================
+  # AGENTS - Unified Agent Management
+  # =================================================================
+  
+  /agents:
+    post:
+      tags: [agents]
+      summary: Create and deploy new agent
+      description: |
+        Creates an OSSA-compliant agent and deploys to K8s via Helm.
+        Registers with agent-router, starts Phoenix tracing.
+      operationId: createAgent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateAgentRequest'
+      responses:
+        '201':
+          description: Agent created and deployed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentResponse'
+    
+    get:
+      tags: [agents]
+      summary: List all agents
+      operationId: listAgents
+      parameters:
+        - $ref: '#/components/parameters/Namespace'
+        - $ref: '#/components/parameters/Status'
+        - $ref: '#/components/parameters/Framework'
+      responses:
+        '200':
+          description: List of agents
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentList'
+
+  /agents/{agentId}:
+    get:
+      tags: [agents]
+      summary: Get agent details
+      operationId: getAgent
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      responses:
+        '200':
+          description: Agent details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentDetails'
+    
+    put:
+      tags: [agents]
+      summary: Update agent
+      operationId: updateAgent
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateAgentRequest'
+      responses:
+        '200':
+          description: Agent updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentResponse'
+    
+    delete:
+      tags: [agents]
+      summary: Delete agent
+      operationId: deleteAgent
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      responses:
+        '204':
+          description: Agent deleted
+
+  /agents/{agentId}/execute:
+    post:
+      tags: [agents]
+      summary: Execute agent task
+      description: Send task to agent and get response
+      operationId: executeAgentTask
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AgentTaskRequest'
+      responses:
+        '200':
+          description: Task executed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentTaskResponse'
+
+  # =================================================================
+  # DRUPAL - Single Source of Truth
+  # =================================================================
+  
+  /drupal/content:
+    post:
+      tags: [drupal]
+      summary: Create Drupal content
+      description: Create content node via llm-platform API
+      operationId: createDrupalContent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DrupalContentRequest'
+      responses:
+        '201':
+          description: Content created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DrupalContentResponse'
+    
+    get:
+      tags: [drupal]
+      summary: Query Drupal content
+      operationId: queryDrupalContent
+      parameters:
+        - name: type
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [published, draft, archived]
+      responses:
+        '200':
+          description: Content list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/DrupalContentResponse'
+
+  /drupal/users:
+    post:
+      tags: [drupal]
+      summary: Create Drupal user
+      operationId: createDrupalUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DrupalUserRequest'
+      responses:
+        '201':
+          description: User created
+    
+    get:
+      tags: [drupal]
+      summary: List users
+      operationId: listDrupalUsers
+      responses:
+        '200':
+          description: User list
+
+  /drupal/sites:
+    post:
+      tags: [drupal]
+      summary: Build new Drupal site
+      description: Agent creates complete Drupal site with modules/config
+      operationId: buildDrupalSite
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DrupalSiteRequest'
+      responses:
+        '202':
+          description: Site creation started
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DrupalJobResponse'
+
+  # =================================================================
+  # WORKFLOWS - Langflow/LangChain/K-Agent
+  # =================================================================
+  
+  /workflows:
+    post:
+      tags: [workflows]
+      summary: Create workflow
+      description: Create Langflow or LangChain workflow
+      operationId: createWorkflow
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WorkflowRequest'
+      responses:
+        '201':
+          description: Workflow created
+    
+    get:
+      tags: [workflows]
+      summary: List workflows
+      operationId: listWorkflows
+      parameters:
+        - name: framework
+          in: query
+          schema:
+            type: string
+            enum: [langflow, langchain, kagent]
+      responses:
+        '200':
+          description: Workflow list
+
+  /workflows/{workflowId}/execute:
+    post:
+      tags: [workflows]
+      summary: Execute workflow
+      operationId: executeWorkflow
+      parameters:
+        - name: workflowId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                inputs:
+                  type: object
+                  additionalProperties: true
+      responses:
+        '200':
+          description: Workflow executed
+
+  # =================================================================
+  # STUDIO - Mobile API for Remote Coding
+  # =================================================================
+  
+  /studio/sessions:
+    post:
+      tags: [studio]
+      summary: Create remote coding session
+      description: |
+        Creates coding session accessible from iOS/CarPlay.
+        Agent continues work when you're away from computer.
+      operationId: createStudioSession
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StudioSessionRequest'
+      responses:
+        '201':
+          description: Session created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StudioSessionResponse'
+    
+    get:
+      tags: [studio]
+      summary: List active sessions
+      operationId: listStudioSessions
+      responses:
+        '200':
+          description: Active sessions
+
+  /studio/sessions/{sessionId}/tasks:
+    post:
+      tags: [studio]
+      summary: Queue task for agent
+      description: Queue coding task to run while you're mobile
+      operationId: queueStudioTask
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StudioTaskRequest'
+      responses:
+        '202':
+          description: Task queued
+
+  # =================================================================
+  # GITLAB - CI/CD Orchestration
+  # =================================================================
+  
+  /gitlab/pipelines:
+    post:
+      tags: [gitlab]
+      summary: Trigger pipeline for project
+      operationId: triggerPipeline
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GitLabPipelineRequest'
+      responses:
+        '202':
+          description: Pipeline triggered
+    
+    get:
+      tags: [gitlab]
+      summary: List pipelines
+      operationId: listPipelines
+      responses:
+        '200':
+          description: Pipeline list
+
+  /gitlab/packages:
+    get:
+      tags: [gitlab]
+      summary: List available packages
+      description: Query gitlab.bluefly.io package registry
+      operationId: listGitLabPackages
+      parameters:
+        - name: scope
+          in: query
+          schema:
+            type: string
+            example: "@llm"
+      responses:
+        '200':
+          description: Package list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/GitLabPackage'
+
+  # =================================================================
+  # REGISTRY - Service Discovery
+  # =================================================================
+  
+  /registry/discover:
+    get:
+      tags: [registry]
+      summary: Discover services
+      description: Query agent-router for available services/agents
+      operationId: discoverServices
+      parameters:
+        - name: capability
+          in: query
+          schema:
+            type: string
+        - name: framework
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Discovered services
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ServiceEndpoint'
+
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+    
+    GitLabJWT:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  parameters:
+    AgentId:
+      name: agentId
+      in: path
+      required: true
+      schema:
+        type: string
+    
+    Namespace:
+      name: namespace
+      in: query
+      schema:
+        type: string
+        default: agents
+    
+    Status:
+      name: status
+      in: query
+      schema:
+        type: string
+        enum: [running, stopped, error]
+    
+    Framework:
+      name: framework
+      in: query
+      schema:
+        type: string
+        enum: [ossa, langflow, langchain, kagent, drupal]
+
+  schemas:
+    CreateAgentRequest:
+      type: object
+      required:
+        - ossa_manifest
+        - deployment_target
+      properties:
+        ossa_manifest:
+          type: string
+          format: uri
+          description: URL to OSSA manifest in GitLab
+          example: "https://gitlab.bluefly.io/llm/agents/my-agent/-/raw/main/agent.ossa.yaml"
+        deployment_target:
+          type: string
+          enum: [kubernetes, docker, serverless]
+        namespace:
+          type: string
+          default: agents
+        helm_values:
+          type: object
+          description: Override Helm chart values
+        gitlab_package:
+          type: string
+          description: GitLab package to use (if available)
+          example: "@llm/my-agent@1.0.0"
+
+    AgentResponse:
+      type: object
+      properties:
+        agent_id:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          enum: [deploying, running, error]
+        endpoints:
+          type: object
+          properties:
+            api:
+              type: string
+              format: uri
+            health:
+              type: string
+              format: uri
+            metrics:
+              type: string
+              format: uri
+        phoenix_traces:
+          type: string
+          format: uri
+        helm_release:
+          type: string
+
+    AgentList:
+      type: object
+      properties:
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentSummary'
+        total:
+          type: integer
+
+    AgentSummary:
+      type: object
+      properties:
+        agent_id:
+          type: string
+        name:
+          type: string
+        framework:
+          type: string
+        status:
+          type: string
+        namespace:
+          type: string
+
+    AgentDetails:
+      allOf:
+        - $ref: '#/components/schemas/AgentResponse'
+        - type: object
+          properties:
+            ossa_manifest:
+              type: object
+            metrics:
+              type: object
+            recent_tasks:
+              type: array
+              items:
+                type: object
+
+    UpdateAgentRequest:
+      type: object
+      properties:
+        replicas:
+          type: integer
+        image_tag:
+          type: string
+        helm_values:
+          type: object
+
+    AgentTaskRequest:
+      type: object
+      required:
+        - capability
+        - input
+      properties:
+        capability:
+          type: string
+          description: Agent capability to invoke
+        input:
+          type: object
+          additionalProperties: true
+        async:
+          type: boolean
+          default: false
+
+    AgentTaskResponse:
+      type: object
+      properties:
+        task_id:
+          type: string
+        status:
+          type: string
+          enum: [queued, running, completed, failed]
+        output:
+          type: object
+          additionalProperties: true
+        traces:
+          type: array
+          items:
+            type: object
+
+    # Drupal Schemas
+    DrupalContentRequest:
+      type: object
+      required:
+        - type
+        - title
+      properties:
+        type:
+          type: string
+          description: Content type machine name
+        title:
+          type: string
+        body:
+          type: string
+        fields:
+          type: object
+          additionalProperties: true
+        status:
+          type: string
+          enum: [published, draft]
+          default: draft
+
+    DrupalContentResponse:
+      type: object
+      properties:
+        nid:
+          type: integer
+        uuid:
+          type: string
+        type:
+          type: string
+        title:
+          type: string
+        url:
+          type: string
+          format: uri
+        created:
+          type: string
+          format: date-time
+
+    DrupalUserRequest:
+      type: object
+      required:
+        - username
+        - email
+      properties:
+        username:
+          type: string
+        email:
+          type: string
+          format: email
+        roles:
+          type: array
+          items:
+            type: string
+
+    DrupalSiteRequest:
+      type: object
+      required:
+        - site_name
+        - modules
+      properties:
+        site_name:
+          type: string
+        modules:
+          type: array
+          items:
+            type: string
+        theme:
+          type: string
+        config:
+          type: object
+
+    DrupalJobResponse:
+      type: object
+      properties:
+        job_id:
+          type: string
+        status:
+          type: string
+        gitlab_pipeline:
+          type: string
+          format: uri
+
+    # Workflow Schemas
+    WorkflowRequest:
+      type: object
+      required:
+        - framework
+        - definition
+      properties:
+        framework:
+          type: string
+          enum: [langflow, langchain, kagent]
+        definition:
+          type: object
+          additionalProperties: true
+        agents:
+          type: array
+          items:
+            type: string
+          description: Agent IDs to include in workflow
+
+    # Studio Mobile API Schemas
+    StudioSessionRequest:
+      type: object
+      required:
+        - device_type
+        - repository
+      properties:
+        device_type:
+          type: string
+          enum: [ios, ipad, carplay, watch]
+        repository:
+          type: string
+          description: GitLab repository URL
+        branch:
+          type: string
+          default: development
+
+    StudioSessionResponse:
+      type: object
+      properties:
+        session_id:
+          type: string
+        websocket_url:
+          type: string
+          format: uri
+          description: WebSocket for real-time updates
+        api_endpoint:
+          type: string
+          format: uri
+        expires_at:
+          type: string
+          format: date-time
+
+    StudioTaskRequest:
+      type: object
+      required:
+        - task_type
+        - description
+      properties:
+        task_type:
+          type: string
+          enum: [code, test, deploy, review]
+        description:
+          type: string
+        files:
+          type: array
+          items:
+            type: string
+        agent_id:
+          type: string
+          description: Specific agent to use (optional)
+
+    # GitLab Schemas
+    GitLabPipelineRequest:
+      type: object
+      required:
+        - project
+        - ref
+      properties:
+        project:
+          type: string
+          description: GitLab project path
+        ref:
+          type: string
+          description: Git ref (branch/tag)
+        variables:
+          type: object
+          additionalProperties:
+            type: string
+
+    GitLabPackage:
+      type: object
+      properties:
+        name:
+          type: string
+        version:
+          type: string
+        package_type:
+          type: string
+          enum: [npm, python, generic]
+        url:
+          type: string
+          format: uri
+
+    # Registry Schemas
+    ServiceEndpoint:
+      type: object
+      properties:
+        service_id:
+          type: string
+        name:
+          type: string
+        url:
+          type: string
+          format: uri
+        capabilities:
+          type: array
+          items:
+            type: string
+        health:
+          type: string
+          enum: [healthy, degraded, unhealthy]
+        framework:
+          type: string
+