@bluefly/openstandardagents 0.2.4

package/docs/schemas/openapi-extensions.schema.json

@@ -0,0 +1,486 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ossa.io/schemas/openapi-extensions.json",
+  "title": "OSSA OpenAPI/Swagger Specification Extensions Schema",
+  "description": "JSON Schema for OSSA-specific OpenAPI 3.1 extensions that enable AI agent metadata, capabilities, and configuration within OpenAPI specifications.",
+  "type": "object",
+  "properties": {
+    "rootLevelExtensions": {
+      "type": "object",
+      "description": "Extensions that can be added at the root level of an OpenAPI specification",
+      "properties": {
+        "x-ossa-metadata": {
+          "$ref": "#/definitions/XOssaMetadata"
+        },
+        "x-ossa": {
+          "$ref": "#/definitions/XOssa"
+        },
+        "x-agent": {
+          "$ref": "#/definitions/XAgent"
+        }
+      }
+    },
+    "operationLevelExtensions": {
+      "type": "object",
+      "description": "Extensions that can be added to individual OpenAPI operations (GET, POST, etc.)",
+      "properties": {
+        "x-ossa-capability": {
+          "$ref": "#/definitions/XOssaCapability"
+        },
+        "x-ossa-autonomy": {
+          "$ref": "#/definitions/XOssaAutonomy"
+        },
+        "x-ossa-constraints": {
+          "$ref": "#/definitions/XOssaConstraints"
+        },
+        "x-ossa-tools": {
+          "$ref": "#/definitions/XOssaTools"
+        },
+        "x-ossa-llm": {
+          "$ref": "#/definitions/XOssaLlm"
+        }
+      }
+    },
+    "parameterExtensions": {
+      "type": "object",
+      "description": "Extensions for OpenAPI parameters (headers, query params, etc.)",
+      "properties": {
+        "x-ossa-agent-id": {
+          "$ref": "#/definitions/XOssaAgentId"
+        },
+        "x-ossa-version": {
+          "$ref": "#/definitions/XOssaVersion"
+        }
+      }
+    },
+    "schemaExtensions": {
+      "type": "object",
+      "description": "Extensions for OpenAPI schema definitions",
+      "properties": {
+        "x-ossa-capability-schema": {
+          "$ref": "#/definitions/XOssaCapabilitySchema"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "XOssaMetadata": {
+      "type": "object",
+      "description": "Embeds comprehensive OSSA agent metadata in OpenAPI spec root",
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "OSSA specification version",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$",
+          "examples": ["0.2.2", "1.0.0", "0.1.9"]
+        },
+        "compliance": {
+          "type": "object",
+          "properties": {
+            "level": {
+              "type": "string",
+              "enum": ["basic", "standard", "advanced", "enterprise"],
+              "description": "Compliance level"
+            },
+            "frameworks": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of compliance frameworks (e.g., OSSA, OpenAPI 3.1, RFC7807)",
+              "examples": [["OSSA", "OpenAPI 3.1", "RFC7807"]]
+            }
+          },
+          "required": ["level", "frameworks"]
+        },
+        "governance": {
+          "type": "object",
+          "properties": {
+            "approved": {
+              "type": "boolean",
+              "description": "Whether the specification has been approved"
+            },
+            "approvedBy": {
+              "type": "string",
+              "description": "Entity that approved the specification"
+            },
+            "approvalDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Date of approval (YYYY-MM-DD format)"
+            }
+          }
+        },
+        "security": {
+          "type": "object",
+          "properties": {
+            "classification": {
+              "type": "string",
+              "enum": ["public", "internal", "confidential", "restricted"],
+              "description": "Security classification level"
+            },
+            "authentication": {
+              "type": "string",
+              "enum": ["required", "optional", "none"],
+              "description": "Authentication requirements"
+            },
+            "encryption": {
+              "type": "string",
+              "description": "Encryption requirements (e.g., tls1.3, tls1.2)",
+              "examples": ["tls1.3", "tls1.2"]
+            }
+          }
+        },
+        "observability": {
+          "type": "object",
+          "properties": {
+            "tracing": {
+              "type": "boolean",
+              "description": "Enable distributed tracing"
+            },
+            "metrics": {
+              "type": "boolean",
+              "description": "Enable metrics collection"
+            },
+            "logging": {
+              "type": "boolean",
+              "description": "Enable structured logging"
+            }
+          }
+        }
+      },
+      "required": ["version"]
+    },
+    "XOssa": {
+      "type": "object",
+      "description": "Core OSSA compliance information",
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "OSSA specification version",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
+        },
+        "agent": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Unique agent identifier",
+              "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+            },
+            "type": {
+              "type": "string",
+              "enum": ["orchestrator", "worker", "specialist", "critic", "judge", "monitor", "gateway", "governor", "integrator", "voice"],
+              "description": "Agent type"
+            },
+            "compliance": {
+              "type": "object",
+              "properties": {
+                "standards": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "List of architectural standards",
+                  "examples": [["openapi-first", "dry", "crud", "solid", "type-safe"]]
+                },
+                "validated": {
+                  "type": "boolean",
+                  "description": "Whether the agent has been validated"
+                },
+                "validatedAt": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "ISO 8601 timestamp of validation"
+                }
+              }
+            }
+          },
+          "required": ["id", "type"]
+        }
+      },
+      "required": ["version", "agent"]
+    },
+    "XAgent": {
+      "type": "object",
+      "description": "Agent-specific capabilities and configuration",
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of agent capability names"
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of tools/MCP servers available to the agent"
+        },
+        "environment": {
+          "type": "object",
+          "description": "Environment-specific configuration",
+          "additionalProperties": true
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of rules or policies the agent follows"
+        }
+      }
+    },
+    "XOssaCapability": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Simple capability name reference"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Capability name"
+            },
+            "description": {
+              "type": "string",
+              "description": "Capability description"
+            },
+            "inputSchema": {
+              "type": "object",
+              "description": "JSON Schema for capability input"
+            },
+            "outputSchema": {
+              "type": "object",
+              "description": "JSON Schema for capability output"
+            }
+          },
+          "required": ["name"]
+        }
+      ],
+      "description": "Links OpenAPI operation to OSSA agent capability"
+    },
+    "XOssaAutonomy": {
+      "type": "object",
+      "description": "Defines autonomy level for operation execution",
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["supervised", "autonomous", "semi-autonomous"],
+          "description": "Autonomy level"
+        },
+        "approval_required": {
+          "type": "boolean",
+          "description": "Whether human approval is required before execution"
+        },
+        "allowed_actions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of allowed actions for this operation"
+        },
+        "blocked_actions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of blocked actions for this operation"
+        }
+      },
+      "required": ["level"]
+    },
+    "XOssaConstraints": {
+      "type": "object",
+      "description": "Defines cost, token, and resource constraints for operation",
+      "properties": {
+        "cost": {
+          "type": "object",
+          "properties": {
+            "maxTokensPerDay": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Maximum tokens allowed per day"
+            },
+            "maxTokensPerRequest": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Maximum tokens allowed per request"
+            },
+            "maxCostPerDay": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Maximum cost in USD per day"
+            },
+            "currency": {
+              "type": "string",
+              "default": "USD",
+              "description": "Currency code (ISO 4217)"
+            }
+          }
+        },
+        "performance": {
+          "type": "object",
+          "properties": {
+            "maxLatencySeconds": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Maximum acceptable latency in seconds"
+            },
+            "maxConcurrentRequests": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum concurrent requests"
+            }
+          }
+        },
+        "time": {
+          "type": "object",
+          "properties": {
+            "maxExecutionTime": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Maximum execution time in seconds"
+            }
+          }
+        }
+      }
+    },
+    "XOssaTools": {
+      "type": "array",
+      "description": "Specifies MCP servers or tools required for operation",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["mcp", "http", "custom"],
+            "description": "Tool type"
+          },
+          "server": {
+            "type": "string",
+            "description": "Tool server identifier or URL"
+          },
+          "namespace": {
+            "type": "string",
+            "description": "Namespace for the tool (for MCP servers)"
+          },
+          "capabilities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "List of tool capabilities"
+          }
+        },
+        "required": ["type", "server"]
+      }
+    },
+    "XOssaLlm": {
+      "type": "object",
+      "description": "Overrides LLM configuration for specific operation",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["openai", "anthropic", "google", "azure", "custom"],
+          "description": "LLM provider"
+        },
+        "model": {
+          "type": "string",
+          "description": "Model identifier (e.g., gpt-4, claude-3-opus)",
+          "examples": ["gpt-4", "claude-3-opus", "gemini-pro"]
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Sampling temperature (0-2)"
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum tokens in response"
+        }
+      },
+      "required": ["provider", "model"]
+    },
+    "XOssaAgentId": {
+      "type": "object",
+      "description": "Header parameter extension for agent identification",
+      "properties": {
+        "name": {
+          "type": "string",
+          "default": "X-OSSA-Agent-ID",
+          "description": "Header parameter name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Parameter description"
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the header is required"
+        }
+      }
+    },
+    "XOssaVersion": {
+      "type": "object",
+      "description": "Header parameter extension for OSSA version",
+      "properties": {
+        "name": {
+          "type": "string",
+          "default": "X-OSSA-Version",
+          "description": "Header parameter name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Parameter description"
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the header is required"
+        }
+      }
+    },
+    "XOssaCapabilitySchema": {
+      "type": "object",
+      "description": "Extends schema definition with capability metadata",
+      "properties": {
+        "capabilityName": {
+          "type": "string",
+          "description": "Name of the capability this schema represents"
+        },
+        "input": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this is an input schema"
+        },
+        "output": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this is an output schema"
+        },
+        "validation": {
+          "type": "object",
+          "properties": {
+            "required": {
+              "type": "boolean",
+              "description": "Whether validation is required"
+            },
+            "strict": {
+              "type": "boolean",
+              "description": "Whether to use strict validation"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+

package/examples/adk-integration/code-review-workflow.yml

@@ -0,0 +1,136 @@
+# Example: ADK Code Review Workflow with OSSA Agents
+# This demonstrates how OSSA agents work with ADK orchestration patterns
+
+apiVersion: '@ossa/v0.1.9'
+kind: Workflow
+metadata:
+  name: code-review-workflow
+  description: 'Multi-agent code review using ADK patterns'
+
+spec:
+  # ADK orchestration pattern
+  adk_pattern: sequential
+
+  # Agents involved in workflow
+  agents:
+    - name: code-analyzer
+      type: LlmAgent
+      ossa_type: worker
+      capabilities:
+        - code-analysis
+        - static-analysis
+      instruction: |
+        Analyze the provided code for:
+        - Code quality issues
+        - Potential bugs
+        - Performance concerns
+        - Security vulnerabilities
+        Store findings in {analysis_results}
+      output_key: analysis_results
+
+    - name: style-checker
+      type: LlmAgent
+      ossa_type: critic
+      capabilities:
+        - style-checking
+        - formatting
+      instruction: |
+        Check code style based on {analysis_results}:
+        - Naming conventions
+        - Code formatting
+        - Documentation completeness
+        Store style issues in {style_report}
+      output_key: style_report
+
+    - name: security-auditor
+      type: CustomAgent
+      custom_type: governor
+      ossa_type: governor
+      capabilities:
+        - security-scanning
+        - vulnerability-detection
+      policies:
+        - name: owasp-top-10
+          severity: high
+        - name: cwe-sans-25
+          severity: critical
+      instruction: |
+        Audit code for security issues using {analysis_results}
+        Apply OWASP and CWE policies
+        Store violations in {security_audit}
+      output_key: security_audit
+
+    - name: review-aggregator
+      type: WorkflowAgent
+      workflow_type: parallel
+      ossa_type: orchestrator
+      sub_agents:
+        - code-analyzer
+        - style-checker
+        - security-auditor
+      instruction: |
+        Aggregate all review results:
+        - {analysis_results}
+        - {style_report}  
+        - {security_audit}
+        Generate comprehensive review report
+      output_key: final_review
+
+  # Execution configuration
+  execution:
+    # Use ADK state management
+    state_management: adk_session
+
+    # Tool delegation
+    tool_delegation:
+      type: explicit
+      tools:
+        - name: git_operations
+          capabilities: [version-control]
+        - name: issue_tracker
+          capabilities: [issue-management]
+
+    # Conditional execution based on findings
+    conditions:
+      - agent: security-auditor
+        condition: "session.state.analysis_results.severity > 'medium'"
+      - agent: style-checker
+        condition: 'session.state.analysis_results.lines_of_code > 100'
+
+    # Loop configuration for iterative review
+    loop_options:
+      max_iterations: 3
+      break_condition: 'session.state.security_audit.violations.length == 0'
+
+  # ADK integration settings
+  adk_config:
+    # Model configuration
+    models:
+      default: gemini-2.0-flash
+      specialized:
+        security-auditor: gemini-2.0-pro
+
+    # Performance settings
+    performance:
+      parallel_execution: true
+      cache_session_state: true
+      state_persistence: redis
+
+    # Error handling
+    error_handling:
+      retry_count: 3
+      fallback_pattern: sequential
+# Example usage with ADK adapter:
+#
+# const adapter = new OSSAADKAdapter();
+# await adapter.loadAgent('.agents/code-analyzer');
+# await adapter.loadAgent('.agents/style-checker');
+# await adapter.loadAgent('.agents/security-auditor');
+# await adapter.loadAgent('.agents/review-aggregator');
+#
+# const result = await adapter.executeOrchestration(
+#   'sequential',
+#   ['code-analyzer', 'style-checker', 'security-auditor', 'review-aggregator'],
+#   { code: sourceCode },
+#   { conditions: [...], loop_options: {...} }
+# );