@bluefly/openstandardagents 0.2.7 → 0.2.9

package/website/content/docs/openapi-extensions/root-extensions.md

@@ -1,410 +0,0 @@
-# Root-Level Extensions
-
-Extensions that can be added at the root level of an OpenAPI 3.1 specification.
-
----
-
-## x-ossa-metadata
-
-Embeds comprehensive OSSA agent metadata in OpenAPI spec root. Provides governance, compliance, security, and observability metadata.
-
-### Location
-
-Root level of OpenAPI spec
-
-### Schema
-
-```yaml
-x-ossa-metadata:
-  version: string              # OSSA specification version (e.g., "0.2.2", "1.0.0")
-  compliance:
-    level: string              # "basic" | "standard" | "advanced" | "enterprise"
-    frameworks: string[]       # List of compliance frameworks
-  governance:
-    approved: boolean          # Whether specification has been approved
-    approvedBy: string         # Entity that approved (optional)
-    approvalDate: string       # Date of approval in YYYY-MM-DD format (optional)
-  security:
-    classification: string     # "public" | "internal" | "confidential" | "restricted"
-    authentication: string     # "required" | "optional" | "none"
-    encryption: string         # Encryption requirements (e.g., "tls1.3")
-  observability:
-    tracing: boolean           # Enable distributed tracing
-    metrics: boolean           # Enable metrics collection
-    logging: boolean           # Enable structured logging
-```
-
-**Schema Reference Table:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `version` | string | OSSA specification version (e.g., "0.2.2", "1.0.0") |
-| `compliance.level` | string | Compliance level: "basic" \| "standard" \| "advanced" \| "enterprise" |
-| `compliance.frameworks` | string[] | List of compliance frameworks (e.g., ["OSSA", "OpenAPI 3.1"]) |
-| `governance.approved` | boolean | Whether specification has been approved |
-| `governance.approvedBy` | string | Entity that approved (optional) |
-| `governance.approvalDate` | string | Date of approval in YYYY-MM-DD format (optional) |
-| `security.classification` | string | Security level: "public" \| "internal" \| "confidential" \| "restricted" |
-| `security.authentication` | string | Auth requirement: "required" \| "optional" \| "none" |
-| `security.encryption` | string | Encryption requirements (e.g., "tls1.3") |
-| `observability.tracing` | boolean | Enable distributed tracing |
-| `observability.metrics` | boolean | Enable metrics collection |
-| `observability.logging` | boolean | Enable structured logging |
-
-### Example (YAML)
-
-```yaml
-openapi: 3.1.0
-info:
-  title: Kubernetes Troubleshooter Agent API
-  version: 1.0.0
-
-x-ossa-metadata:
-  version: 0.2.x
-  compliance:
-    level: enterprise
-    frameworks:
-      - OSSA
-      - OpenAPI 3.1
-      - RFC7807
-  governance:
-    approved: true
-    approvedBy: Platform Team
-    approvalDate: 2024-01-15
-  security:
-    classification: internal
-    authentication: required
-    encryption: tls1.3
-  observability:
-    tracing: true
-    metrics: true
-    logging: true
-
-paths:
-  # ... paths ...
-```
-
-### Example (JSON)
-
-```json
-{
-  "openapi": "3.1.0",
-  "info": {
-    "title": "Kubernetes Troubleshooter Agent API",
-    "version": "1.0.0"
-  },
-  "x-ossa-metadata": {
-    "version": "0.2.2",
-    "compliance": {
-      "level": "enterprise",
-      "frameworks": ["OSSA", "OpenAPI 3.1", "RFC7807"]
-    },
-    "governance": {
-      "approved": true,
-      "approvedBy": "Platform Team",
-      "approvalDate": "2024-01-15"
-    },
-    "security": {
-      "classification": "internal",
-      "authentication": "required",
-      "encryption": "tls1.3"
-    },
-    "observability": {
-      "tracing": true,
-      "metrics": true,
-      "logging": true
-    }
-  }
-}
-```
-
-### Use Cases
-
-- **Enterprise compliance** - Document governance and approval workflows
-- **Security audits** - Declare security classification and requirements
-- **Observability** - Enable tracing, metrics, and logging at spec level
-- **Multi-framework compliance** - Track compliance with multiple standards
-
----
-
-## x-ossa
-
-Core OSSA compliance information with agent identification and validation metadata.
-
-### Location
-
-Root level or `info` section of OpenAPI spec
-
-### Schema
-
-```yaml
-x-ossa:
-  version: string              # OSSA specification version (e.g., "0.2.2")
-  agent:
-    id: string                 # Unique agent identifier (DNS subdomain format)
-    type: string               # Agent type (see table below)
-    compliance:
-      standards: string[]      # Architectural standards (e.g., ["openapi-first", "dry", "solid"])
-      validated: boolean       # Whether agent has been validated
-      validatedAt: string      # ISO 8601 timestamp of validation
-```
-
-**Schema Reference Table:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `version` | string | OSSA specification version (e.g., "0.2.2") |
-| `agent.id` | string | Unique agent identifier (DNS subdomain format) |
-| `agent.type` | string | Agent type (see table below) |
-| `agent.compliance.standards` | string[] | Architectural standards (e.g., ["openapi-first", "dry", "solid"]) |
-| `agent.compliance.validated` | boolean | Whether agent has been validated |
-| `agent.compliance.validatedAt` | string | ISO 8601 timestamp of validation |
-
-### Agent Types
-
-| Type | Description |
-|------|-------------|
-| `orchestrator` | Coordinates multiple agents and workflows |
-| `worker` | Performs specific tasks and operations |
-| `specialist` | Specialized domain expertise |
-| `critic` | Reviews and validates agent outputs |
-| `judge` | Makes decisions and evaluates outcomes |
-| `monitor` | Observes and reports on system state |
-| `gateway` | Entry point for agent communication |
-| `governor` | Enforces policies and compliance |
-| `integrator` | Connects systems and protocols |
-| `voice` | Handles audio/speech interactions |
-
-### Example
-
-```yaml
-openapi: 3.1.0
-info:
-  title: My Agent API
-  version: 1.0.0
-
-x-ossa:
-  version: 0.2.x
-  agent:
-    id: k8s-troubleshooter
-    type: worker
-    compliance:
-      standards:
-        - openapi-first
-        - dry
-        - crud
-        - solid
-        - type-safe
-      validated: true
-      validatedAt: "2024-01-15T10:30:00Z"
-
-paths:
-  # ... paths ...
-```
-
-### Use Cases
-
-- **Agent registry** - Unique ID enables agent discovery and registration
-- **Type-based routing** - Route requests based on agent type
-- **Validation tracking** - Track when agent spec was last validated
-- **Standards compliance** - Document architectural standards followed
-
----
-
-## x-agent
-
-Agent-specific capabilities, tools, environment, and rules configuration.
-
-### Location
-
-Root level or `info` section of OpenAPI spec
-
-### Schema
-
-```yaml
-x-agent:
-  capabilities: string[]       # List of agent capability names
-  tools: string[]             # List of tools/MCP servers available
-  environment: object         # Environment-specific configuration (key-value pairs)
-  rules: string[]             # List of rules or policies the agent follows
-```
-
-**Schema Reference Table:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `capabilities` | string[] | List of agent capability names |
-| `tools` | string[] | List of tools/MCP servers available |
-| `environment` | object | Environment-specific configuration (key-value pairs) |
-| `rules` | string[] | List of rules or policies the agent follows |
-
-### Example
-
-```yaml
-openapi: 3.1.0
-info:
-  title: Data Processing Agent API
-  version: 1.0.0
-
-x-agent:
-  capabilities:
-    - data-transformation
-    - csv-parsing
-    - json-validation
-  tools:
-    - postgres-mcp
-    - redis-mcp
-    - file-system-mcp
-  environment:
-    processingTimeout: 300
-    maxFileSize: "100MB"
-    enableCaching: true
-  rules:
-    - no-external-api-calls
-    - validate-all-inputs
-    - encrypt-sensitive-data
-
-paths:
-  # ... paths ...
-```
-
-### Use Cases
-
-- **Capability discovery** - List all capabilities agent provides
-- **Tool requirements** - Document MCP servers and tools needed
-- **Environment config** - Define environment-specific settings
-- **Policy enforcement** - Declare rules and constraints agent follows
-
----
-
-## Parameter Extensions
-
-Standard parameters for agent-to-agent communication.
-
-### x-ossa-agent-id
-
-Standard header parameter for agent identification.
-
-**Location**: Parameter definition in `components.parameters` or operation-level `parameters`
-
-**Example**:
-
-```yaml
-components:
-  parameters:
-    X-Ossa-Agent-Id:
-      name: X-OSSA-Agent-ID
-      in: header
-      description: Unique identifier of the agent making the request
-      required: false
-      schema:
-        type: string
-        pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
-      example: "k8s-troubleshooter"
-
-paths:
-  /api/v1/capabilities:
-    get:
-      summary: Get agent capabilities
-      parameters:
-        - $ref: '#/components/parameters/X-Ossa-Agent-Id'
-```
-
-### x-ossa-version
-
-Standard header parameter for OSSA specification version.
-
-**Location**: Parameter definition in `components.parameters` or operation-level `parameters`
-
-**Example**:
-
-```yaml
-components:
-  parameters:
-    X-Ossa-Version:
-      name: X-OSSA-Version
-      in: header
-      description: OSSA specification version the agent supports
-      required: false
-      schema:
-        type: string
-        pattern: "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
-      example: "0.2.2"
-
-paths:
-  /api/v1/execute:
-    post:
-      summary: Execute agent capability
-      parameters:
-        - $ref: '#/components/parameters/X-Ossa-Version'
-```
-
----
-
-## Schema Extensions
-
-### x-ossa-capability-schema
-
-Extends schema definition with capability metadata, linking OpenAPI schemas to OSSA capabilities.
-
-**Location**: Schema definition in `components.schemas`
-
-**Schema**:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `capabilityName` | string | Name of the capability this schema represents |
-| `input` | boolean | Whether this is an input schema (default: false) |
-| `output` | boolean | Whether this is an output schema (default: false) |
-| `validation.required` | boolean | Whether validation is required (optional) |
-| `validation.strict` | boolean | Whether to use strict validation (optional) |
-
-**Example**:
-
-```yaml
-components:
-  schemas:
-    DataProcessingInput:
-      type: object
-      required: [csvData]
-      properties:
-        csvData:
-          type: string
-          description: CSV content to process
-      x-ossa-capability-schema:
-        capabilityName: data-transformation
-        input: true
-        validation:
-          required: true
-          strict: true
-
-    DataProcessingOutput:
-      type: object
-      properties:
-        jsonData:
-          type: array
-          items:
-            type: object
-      x-ossa-capability-schema:
-        capabilityName: data-transformation
-        output: true
-```
-
----
-
-## Best Practices
-
-1. **Use x-ossa-metadata for enterprise deployments** - Document compliance, governance, and security
-2. **Always include x-ossa at root** - Provides core agent identification
-3. **Use x-agent for capability listing** - Makes agent discoverable
-4. **Define standard parameters once** - Reference X-OSSA-Agent-ID and X-OSSA-Version from components
-5. **Link schemas to capabilities** - Use x-ossa-capability-schema for validation
-
----
-
-## References
-
-- [Operation-Level Extensions](operation-extensions)
-- [Examples & Patterns](examples)
-- [OSSA Specification](/docs/specification)
-- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)

package/website/content/docs/ossa-compliant-badge.md

@@ -1,251 +0,0 @@
----
-title: "OSSA COMPLIANT BADGE"
----
-
-# OSSA Compliant Badge
-
-Display the **OSSA Compliant** badge in your project to show that your AI agent follows the Open Standard for AI Agents (OSSA) specification.
-
----
-
-## Badge Options
-
-### Markdown
-
-```markdown
-[![OSSA Compliant](https://img.shields.io/badge/OSSA-Compliant-00B8D4.svg)](https://github.com/blueflyio/openstandardagents)
-```
-
-**Result**:
-[![OSSA Compliant](https://img.shields.io/badge/OSSA-Compliant-00B8D4.svg)](https://github.com/blueflyio/openstandardagents)
-
-### HTML
-
-```html
-<a href="https://github.com/blueflyio/openstandardagents">
-  <img src="https://img.shields.io/badge/OSSA-Compliant-00B8D4.svg" alt="OSSA Compliant">
-</a>
-```
-
-### reStructuredText
-
-```rst
-.. image:: https://img.shields.io/badge/OSSA-Compliant-00B8D4.svg
-   :target: https://github.com/blueflyio/openstandardagents
-   :alt: OSSA Compliant
-```
-
----
-
-## Compliance Requirements
-
-To display the OSSA Compliant badge, your project must:
-
-### Required
-
-1. **Valid OSSA Manifest** - Your agent must have a valid `.ossa.yaml` manifest
-2. **Schema Validation** - Manifest must pass `ossa validate` without errors
-3. **Semantic Versioning** - Agent version follows semver (e.g., `1.0.0`)
-4. **Required Fields** - All required OSSA fields must be present
-
-### Recommended
-
-1. **Examples** - Provide example manifests showing usage
-2. **Documentation** - Document your agent's capabilities and usage
-3. **Testing** - Include tests that validate your OSSA manifest
-4. **CI/CD** - Automate OSSA validation in your pipeline
-
----
-
-## Verification
-
-### Manual Verification
-
-```bash
-# Install OSSA CLI
-npm install -g @bluefly/openstandardagents
-
-# Validate your manifest
-ossa validate path/to/your-agent.ossa.yaml
-```
-
-### Automated Verification (CI/CD)
-
-#### GitLab CI
-
-```yaml
-ossa-validation:
-  stage: test
-  image: node:20-alpine
-  script:
-    - npm install -g @bluefly/openstandardagents
-    - ossa validate agents/*.ossa.yaml
-```
-
-#### GitHub Actions
-
-```yaml
-name: OSSA Validation
-on: [push, pull_request]
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '20'
-      - run: npm install -g @bluefly/openstandardagents
-      - run: ossa validate agents/*.ossa.yaml
-```
-
----
-
-## Compliance Levels
-
-### Level 1: Basic Compliance
-
-- Valid OSSA manifest
-- Required fields present
-- Passes schema validation
-
-### Level 2: Standard Compliance
-
-- Level 1 requirements
-- Best practices followed (descriptions, examples)
-- Semantic versioning
-- At least one capability defined
-
-### Level 3: Advanced Compliance
-
-- Level 2 requirements
-- Platform extensions configured
-- Observability enabled
-- Resource constraints defined
-- Security considerations documented
-
----
-
-## OSSA Certified Projects
-
-Projects that have achieved OSSA compliance:
-
-| Project | Level | Version | Link |
-|---------|-------|---------|------|
-| Agent Buildkit | Advanced | v0.2.3 | [GitHub](https://github.com/blueflyio/openstandardagents) |
-| Agent Studio | Advanced | v0.2.3 | [GitHub](https://github.com/blueflyio/openstandardagents) |
-| KAgent | Advanced | v0.2.3 | [GitHub](https://github.com/blueflyio/openstandardagents) |
-
-**Add your project**: Submit a merge request to update this table!
-
----
-
-## Example Implementation
-
-### Minimal OSSA Manifest
-
-```yaml
-apiVersion: ossa/v0.2.3
-kind: Agent
-
-metadata:
-  name: my-agent
-  version: 1.0.0
-  description: A simple OSSA-compliant agent
-
-spec:
-  role: |
-    You are a helpful assistant that processes data.
-
-  llm:
-    provider: openai
-    model: gpt-4
-
-  tools:
-    - type: function
-      name: process_data
-      description: Process incoming data
-```
-
-### With Platform Extensions
-
-```yaml
-apiVersion: ossa/v0.2.3
-kind: Agent
-
-metadata:
-  name: my-agent
-  version: 1.0.0
-  description: An advanced OSSA-compliant agent
-  labels:
-    environment: production
-    team: ai-engineering
-
-spec:
-  role: |
-    You are a production-ready agent with observability.
-
-  llm:
-    provider: openai
-    model: gpt-4
-    temperature: 0.7
-
-  tools:
-    - type: function
-      name: analyze_data
-      description: Analyze data and generate insights
-
-  observability:
-    tracing:
-      enabled: true
-      exporter: otlp
-    metrics:
-      enabled: true
-      exporter: prometheus
-
-extensions:
-  buildkit:
-    deployment:
-      replicas: 3
-      autoscaling: true
-```
-
----
-
-## FAQ
-
-### Q: Can I use the badge if my agent partially implements OSSA?
-
-**A**: The badge should only be used if your agent has a **valid, complete OSSA manifest** that passes validation. Partial implementations should work toward full compliance before displaying the badge.
-
-### Q: Do I need to register my project?
-
-**A**: No registration required! OSSA is an open standard. Simply ensure your manifest validates and add the badge.
-
-### Q: What if my agent uses a custom runtime?
-
-**A**: OSSA supports custom runtimes! Use platform extensions to define your custom runtime while maintaining OSSA compliance.
-
-### Q: Can I modify the badge design?
-
-**A**: The official badge design helps maintain consistency across the ecosystem. However, you can customize colors for your specific needs while keeping the "OSSA Compliant" text visible.
-
----
-
-## Resources
-
-- **OSSA Specification**: [spec/v0.2.6/](Specification/v0.2.3/)
-- **Examples**: [examples/](Examples/)
-- **CLI Documentation**: [docs/cli/](./cli/)
-- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md)
-- **GitHub Repository**: https://github.com/blueflyio/openstandardagents
-
----
-
-**Questions?** Open an issue on [GitHub](https://github.com/blueflyio/openstandardagents/issues)
-
-**Want to contribute?** See [CONTRIBUTING.md](../CONTRIBUTING.md)
-
----
-
-*OSSA: The OpenAPI for AI Agents*