@bluefly/openstandardagents 0.1.9

package/specs/acdl-specification.yml

@@ -0,0 +1,531 @@
+# Agent Capability Description Language (ACDL) v0.1.9
+# OSSA Platform Standard for Agent Capability Declaration
+
+openapi: 3.1.0
+info:
+  title: Agent Capability Description Language (ACDL)
+  version: 0.1.9
+  description: |
+    ACDL is the standardized language for agents to declare their capabilities,
+    requirements, and integration points within the OSSA ecosystem.
+    
+    This specification defines how agents:
+    - Declare their capabilities and domains
+    - Specify protocol support and endpoints
+    - Define performance characteristics
+    - Register with the OSSA platform
+    - Discover and match with other agents
+
+paths:
+  /acdl/register:
+    post:
+      summary: Register agent capabilities
+      operationId: registerAgent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ACDLManifest'
+      responses:
+        '201':
+          description: Agent registered successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RegistrationResponse'
+
+  /acdl/discover:
+    post:
+      summary: Discover agents by capability
+      operationId: discoverAgents
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DiscoveryQuery'
+      responses:
+        '200':
+          description: Matching agents found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DiscoveryResponse'
+
+  /acdl/match:
+    post:
+      summary: Match agents for task requirements
+      operationId: matchAgents
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MatchRequest'
+      responses:
+        '200':
+          description: Compatible agents matched
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MatchResponse'
+
+components:
+  schemas:
+    ACDLManifest:
+      type: object
+      required:
+        - agentId
+        - agentType
+        - agentSubType
+        - version
+        - capabilities
+        - protocols
+        - performance
+      properties:
+        agentId:
+          type: string
+          pattern: '^[a-z0-9]+-[a-z0-9]+-v\d+\.\d+\.\d+$'
+          example: 'worker-openapi-v1.2.0'
+          description: Unique agent identifier following naming convention
+        
+        agentType:
+          type: string
+          enum:
+            - orchestrator
+            - worker
+            - critic
+            - judge
+            - trainer
+            - governor
+            - monitor
+            - integrator
+          description: Primary agent classification
+        
+        agentSubType:
+          type: string
+          pattern: '^[a-z]+\.[a-z]+$'
+          example: 'worker.openapi'
+          description: Detailed agent specialization
+        
+        version:
+          type: string
+          pattern: '^\d+\.\d+\.\d+(-[a-z]+(\.\d+)?)?$'
+          example: '1.2.0-alpha.1'
+          description: Semantic version of the agent
+        
+        capabilities:
+          $ref: '#/components/schemas/Capabilities'
+        
+        protocols:
+          $ref: '#/components/schemas/Protocols'
+        
+        performance:
+          $ref: '#/components/schemas/Performance'
+        
+        requirements:
+          $ref: '#/components/schemas/Requirements'
+        
+        metadata:
+          $ref: '#/components/schemas/Metadata'
+
+    Capabilities:
+      type: object
+      required:
+        - domains
+        - operations
+      properties:
+        domains:
+          type: array
+          items:
+            type: string
+            enum:
+              - nlp
+              - vision
+              - reasoning
+              - data
+              - documentation
+              - api-design
+              - validation
+              - orchestration
+              - monitoring
+              - security
+          description: Supported capability domains
+          example: ['documentation', 'api-design', 'validation']
+        
+        operations:
+          type: array
+          items:
+            type: object
+            required:
+              - name
+              - description
+            properties:
+              name:
+                type: string
+                example: 'validate'
+              description:
+                type: string
+                example: 'Validate OpenAPI specifications'
+              inputSchema:
+                type: object
+                description: JSON Schema for operation input
+              outputSchema:
+                type: object
+                description: JSON Schema for operation output
+        
+        specializations:
+          type: object
+          additionalProperties:
+            type: object
+            properties:
+              versions:
+                type: array
+                items:
+                  type: string
+              features:
+                type: array
+                items:
+                  type: string
+          example:
+            openapi:
+              versions: ['3.0.3', '3.1.0']
+              features: ['validate', 'generate', 'diff', 'merge']
+
+    Protocols:
+      type: object
+      required:
+        - supported
+      properties:
+        supported:
+          type: array
+          items:
+            type: object
+            required:
+              - name
+              - version
+              - endpoint
+            properties:
+              name:
+                type: string
+                enum:
+                  - rest
+                  - grpc
+                  - websocket
+                  - mcp
+                  - graphql
+              version:
+                type: string
+              endpoint:
+                type: string
+                format: uri
+              authentication:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    enum: [none, api-key, oauth2, jwt, mtls]
+                  details:
+                    type: object
+        
+        preferred:
+          type: string
+          description: Preferred protocol for communication
+
+    Performance:
+      type: object
+      required:
+        - throughput
+        - latency
+      properties:
+        throughput:
+          type: object
+          properties:
+            requestsPerSecond:
+              type: integer
+              minimum: 1
+              example: 100
+            concurrentRequests:
+              type: integer
+              minimum: 1
+              example: 10
+        
+        latency:
+          type: object
+          properties:
+            p50:
+              type: integer
+              description: 50th percentile latency in ms
+              example: 50
+            p95:
+              type: integer
+              description: 95th percentile latency in ms
+              example: 150
+            p99:
+              type: integer
+              description: 99th percentile latency in ms
+              example: 250
+        
+        limits:
+          type: object
+          properties:
+            maxRequestSize:
+              type: integer
+              description: Maximum request size in bytes
+              example: 10485760
+            maxResponseSize:
+              type: integer
+              description: Maximum response size in bytes
+            timeout:
+              type: integer
+              description: Request timeout in milliseconds
+              example: 30000
+            rateLimits:
+              type: object
+              properties:
+                requestsPerMinute:
+                  type: integer
+                requestsPerHour:
+                  type: integer
+
+    Requirements:
+      type: object
+      properties:
+        resources:
+          type: object
+          properties:
+            cpu:
+              type: object
+              properties:
+                requests:
+                  type: string
+                  example: '100m'
+                limits:
+                  type: string
+                  example: '500m'
+            memory:
+              type: object
+              properties:
+                requests:
+                  type: string
+                  example: '256Mi'
+                limits:
+                  type: string
+                  example: '1Gi'
+            storage:
+              type: string
+              example: '10Gi'
+        
+        dependencies:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              version:
+                type: string
+              type:
+                type: string
+                enum: [service, library, model, database]
+        
+        environment:
+          type: object
+          properties:
+            runtime:
+              type: string
+              example: 'node:20'
+            platform:
+              type: string
+              enum: [kubernetes, docker, serverless, bare-metal]
+
+    Metadata:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Human-readable agent name
+        description:
+          type: string
+          description: Detailed agent description
+        author:
+          type: string
+        organization:
+          type: string
+        license:
+          type: string
+        repository:
+          type: string
+          format: uri
+        documentation:
+          type: string
+          format: uri
+        tags:
+          type: array
+          items:
+            type: string
+        created:
+          type: string
+          format: date-time
+        updated:
+          type: string
+          format: date-time
+        deprecated:
+          type: boolean
+          default: false
+        deprecationNotice:
+          type: string
+
+    DiscoveryQuery:
+      type: object
+      properties:
+        domains:
+          type: array
+          items:
+            type: string
+          description: Required capability domains
+        operations:
+          type: array
+          items:
+            type: string
+          description: Required operations
+        agentType:
+          type: string
+          description: Filter by agent type
+        protocols:
+          type: array
+          items:
+            type: string
+          description: Required protocol support
+        performance:
+          type: object
+          properties:
+            minThroughput:
+              type: integer
+            maxLatencyP99:
+              type: integer
+
+    DiscoveryResponse:
+      type: object
+      properties:
+        agents:
+          type: array
+          items:
+            type: object
+            properties:
+              agentId:
+                type: string
+              score:
+                type: number
+                minimum: 0
+                maximum: 1
+                description: Match score (0-1)
+              manifest:
+                $ref: '#/components/schemas/ACDLManifest'
+        totalFound:
+          type: integer
+        queryTime:
+          type: integer
+          description: Query execution time in ms
+
+    MatchRequest:
+      type: object
+      required:
+        - task
+        - requirements
+      properties:
+        task:
+          type: object
+          properties:
+            type:
+              type: string
+            description:
+              type: string
+            expectedDuration:
+              type: integer
+              description: Expected duration in ms
+        requirements:
+          type: object
+          properties:
+            capabilities:
+              $ref: '#/components/schemas/Capabilities'
+            performance:
+              $ref: '#/components/schemas/Performance'
+            constraints:
+              type: object
+              properties:
+                budget:
+                  type: integer
+                  description: Token budget
+                deadline:
+                  type: string
+                  format: date-time
+
+    MatchResponse:
+      type: object
+      properties:
+        matches:
+          type: array
+          items:
+            type: object
+            properties:
+              agentId:
+                type: string
+              compatibility:
+                type: number
+                minimum: 0
+                maximum: 1
+              reasons:
+                type: array
+                items:
+                  type: string
+              warnings:
+                type: array
+                items:
+                  type: string
+        recommendation:
+          type: object
+          properties:
+            primaryAgent:
+              type: string
+            alternativeAgents:
+              type: array
+              items:
+                type: string
+            ensemble:
+              type: array
+              items:
+                type: object
+                properties:
+                  agentId:
+                    type: string
+                  role:
+                    type: string
+
+    RegistrationResponse:
+      type: object
+      properties:
+        registrationId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [registered, pending, rejected]
+        validationResults:
+          type: array
+          items:
+            type: object
+            properties:
+              check:
+                type: string
+              passed:
+                type: boolean
+              message:
+                type: string
+        registeredAt:
+          type: string
+          format: date-time
+        expiresAt:
+          type: string
+          format: date-time