@bluefly/openstandardagents 0.1.9

package/dist/spec/v0.2.3/ossa-0.2.3.yaml

@@ -0,0 +1,448 @@
+ossaVersion: '1.0'
+
+# OSSA (Open Standard for Smart & Scalable Agents) - Version 1.0
+# The OpenAPI for AI Agents
+#
+# This specification defines a standard format for AI agent definition,
+# deployment, and orchestration across heterogeneous environments.
+#
+# Design Principles:
+# 1. OpenAPI-First: OSSA manifests are to agents what OpenAPI specs are to APIs
+# 2. Cloud-Agnostic: Run anywhere (Docker, K8s, local, serverless)
+# 3. Compliance-First: Built-in support for FedRAMP, SOC2, HIPAA, GDPR
+# 4. Type-Safe: JSON Schema validation with auto-generated types
+# 5. Discoverable: Agents can be searched, versioned, and shared
+
+spec:
+  title: OSSA 1.0 Specification
+  description: Open Standard for Smart & Scalable Agents
+  version: '1.0.0'
+  license: Apache-2.0
+  maintainer: OSSA Working Group
+  website: https://openstandardagents.org
+  repository: https://github.com/ossa-standard/specification
+
+schema:
+  # Top-level structure
+  root:
+    ossaVersion: '1.0' # Required
+    agent: # Required
+      # Core Identity
+      id: string # DNS-1123 subdomain format (a-z0-9-)
+      name: string # Human-readable name
+      version: semver # Semantic versioning (1.0.0)
+      description: string
+      role: enum # compliance|chat|orchestration|audit|workflow|monitoring|data_sync|search|custom
+      tags: string[] # Searchable tags
+
+      # Runtime Configuration
+      runtime:
+        type: enum # docker|k8s|local|serverless|edge
+        image: string # Container image (for docker/k8s)
+        command: string[] # Entrypoint (for local)
+        requirements: # Dependencies
+          python: string
+          node: string
+          packages: string[]
+        resources: # Resource requests
+          cpu: string # "500m", "1", "2"
+          memory: string # "256Mi", "512Mi", "1Gi"
+          gpu: boolean
+        health_check: # Health monitoring
+          type: enum # http|tcp|exec
+          endpoint: string
+          port: integer
+          command: string[]
+          initial_delay_seconds: integer
+          period_seconds: integer
+          timeout_seconds: integer
+          failure_threshold: integer
+
+      # Capabilities (Like OpenAPI operations)
+      capabilities:
+        - name: string
+          description: string
+          input_schema: # JSON Schema OR OpenAPI ref
+            type: object|uri
+          output_schema: # JSON Schema OR OpenAPI ref
+            type: object|uri
+          examples:
+            - name: string
+              input: object
+              output: object
+          timeout_seconds: integer
+          retry_policy:
+            max_attempts: integer
+            backoff: linear|exponential
+
+      # Policies & Compliance
+      policies:
+        compliance: enum[] # fedramp-low|moderate|high, iso27001, soc2, hipaa, gdpr, etc.
+        data_residency: string[] # ["US", "CA", "EU"]
+        encryption: boolean
+        audit: boolean
+        pii_handling: enum # none|anonymize|encrypt|prohibit
+
+      # Integration & Communication
+      integration:
+        protocol: enum # http|grpc|mcp|websocket
+        endpoints:
+          base_url: uri
+          health: string
+          metrics: string
+          openapi: string # Path to OpenAPI spec
+        auth:
+          type: enum # none|api_key|jwt|oauth2|mtls
+          config: object
+        rate_limits:
+          requests_per_second: integer
+          requests_per_minute: integer
+          burst: integer
+
+      # Monitoring & Observability
+      monitoring:
+        traces: boolean # OpenTelemetry tracing
+        metrics: boolean # Prometheus metrics
+        logs: boolean # Structured logging
+        health_check: uri
+        phoenix_arise: # Phoenix Arise integration
+          enabled: boolean
+          project: string
+          export_interval_seconds: integer
+
+      # Dependencies
+      dependencies:
+        required: # Hard dependencies
+          - agent_id: string
+            min_version: semver
+            max_version: semver
+        optional: # Soft dependencies
+          - agent_id: string
+            fallback: string
+
+      # Metadata
+      metadata:
+        author: string
+        maintainer: string
+        homepage: uri
+        repository: uri
+        documentation: uri
+        license: string
+        keywords: string[]
+
+      # Bridge Configuration (Protocol Interoperability)
+      bridge:
+        # Model Context Protocol Bridge
+        mcp:
+          enabled: boolean
+          server_type: enum # stdio|sse|websocket
+          tools: # MCP tools exposed by the agent
+            - name: string
+              description: string
+              input_schema: object # JSON Schema
+              output_schema: object # JSON Schema
+              capability: string # Maps to OSSA capability
+          resources: # MCP resources provided
+            - uri: string # e.g., "ossa://agents"
+              name: string
+              description: string
+              mimeType: string
+              readonly: boolean
+          prompts: # MCP prompts available
+            - name: string
+              description: string
+              template: string # Template with {{variables}}
+              arguments:
+                - name: string
+                  type: string
+                  required: boolean
+          config:
+            max_message_size: integer # bytes
+            timeout_ms: integer # milliseconds
+            retry_count: integer
+
+        # kagent.dev Bridge (CNCF Kubernetes-native agents)
+        kagent:
+          enabled: boolean
+          api_version: string # kagent.dev/v1alpha2
+          agent_type: enum # declarative|imperative
+          deployment: # Kubernetes deployment config
+            replicas: integer
+            resources:
+              requests:
+                cpu: string
+                memory: string
+              limits:
+                cpu: string
+                memory: string
+          model_config: string # Reference to ModelConfig CRD
+          system_message: string # System prompt
+          tools: # kagent.dev tool servers
+            - type: enum # McpServer|ToolServer|HttpTool
+              mcpServer:
+                toolServer: string # Name of MCP server
+                toolNames: string[] # Specific tools to use
+              httpTool:
+                url: uri
+                method: enum # GET|POST|PUT|DELETE
+          a2a_config: # Agent-to-Agent for kagent
+            skills:
+              - id: string
+                name: string
+                description: string
+                examples: string[]
+                tags: string[]
+
+        # AIFlow-Agent Bridge (Social/Character agents on BNB Chain)
+        aiflow:
+          enabled: boolean
+          character: # Character definition
+            name: string
+            username: string # Twitter/social username
+            personality_traits: string[]
+            bio: string
+            lore: string[] # Background story elements
+            message_examples: # Conversation examples
+              - - user: string
+                  content:
+                    text: string
+                - character: string
+                  content:
+                    text: string
+            post_examples: string[] # Social media post examples
+            topics: string[] # Topics of interest
+            style: # Communication style
+              all: string[]
+              chat: string[]
+              post: string[]
+            adjectives: string[] # Personality adjectives
+          blockchain: # BNB Chain integration
+            enabled: boolean
+            network: enum # mainnet|testnet
+            wallet_address: string
+          social_platforms: # Social media integrations
+            twitter:
+              enabled: boolean
+              username: string
+              auto_post: boolean
+            telegram:
+              enabled: boolean
+              bot_token: string
+            discord:
+              enabled: boolean
+              bot_token: string
+
+        # Agent-to-Agent Protocol Bridge
+        a2a:
+          enabled: boolean
+          card_url: uri
+          schema_version: string
+          capabilities_mapping: object # Map OSSA caps to A2A actions
+          metadata:
+            '@context': string
+            '@type': string
+
+        # OpenAPI Bridge
+        openapi:
+          enabled: boolean
+          spec_url: uri
+          spec_version: enum # 3.0|3.1
+          auto_generate: boolean
+          servers:
+            - url: uri
+              description: string
+          security: object[]
+
+        # LangChain Bridge
+        langchain:
+          enabled: boolean
+          tool_class: string
+          chain_type: enum # llm|retrieval|agent|sequential|custom
+          memory:
+            type: enum # buffer|summary|conversation|vector
+            max_tokens: integer
+          callbacks: string[]
+          export:
+            as_tool: boolean
+            as_chain: boolean
+            as_agent: boolean
+
+        # CrewAI Bridge
+        crewai:
+          enabled: boolean
+          agent_type: enum # worker|manager|researcher|analyst|custom
+          role: string
+          goal: string
+          backstory: string
+          tools: string[]
+          llm:
+            model: string
+            temperature: float
+          max_iter: integer
+          allow_delegation: boolean
+
+        # AutoGen Bridge
+        autogen:
+          enabled: boolean
+          agent_type: enum # assistant|user_proxy|groupchat|custom
+          system_message: string
+          human_input_mode: enum # ALWAYS|NEVER|TERMINATE
+          code_execution:
+            enabled: boolean
+            work_dir: string
+            use_docker: boolean
+          llm_config:
+            model: string
+            temperature: float
+            max_tokens: integer
+            functions: object[]
+          max_consecutive_auto_reply: integer
+
+        # Custom Bridges
+        custom: object # Arbitrary custom bridge configurations
+
+# Validation Rules
+validation:
+  - id: must match DNS-1123 subdomain format
+  - version: must be valid semver 2.0.0
+  - capabilities: at least one capability required
+  - runtime.type: must specify runtime type
+  - policies.compliance: if specified, encryption must be true
+  - dependencies.required: all required deps must be resolvable
+
+# Extension Points
+extensions:
+  # Custom annotations (like Kubernetes)
+  annotations:
+    'openstandardagents.org/*': reserved for OSSA standard
+    'vendor.io/*': vendor-specific extensions
+    '*': custom extensions
+
+  # Custom fields allowed at root level
+  # Prefix with "x-" to avoid conflicts
+  custom_fields:
+    pattern: '^x-[a-z0-9-]+$'
+
+# Compatibility
+compatibility:
+  openapi: 'Can reference OpenAPI specs for capability schemas'
+  kubernetes: 'Agent manifest maps directly to K8s Agent CRD (kagent)'
+  mcp: 'Integration.protocol = mcp enables MCP tool server support'
+  docker: 'runtime.image maps to Docker image'
+  helm: 'Can be packaged as Helm chart values'
+
+# Reserved Roles
+roles:
+  - compliance: Security scanning, policy enforcement, audit
+  - chat: Customer support, Q&A, conversational interfaces
+  - orchestration: Workflow coordination, multi-agent management
+  - audit: Security auditing, compliance verification
+  - workflow: Task execution, process automation
+  - monitoring: System health, performance tracking, alerting
+  - data_processing: ETL, data transformation, analytics
+  - integration: API bridging, system integration
+  - development: Code generation, testing, CI/CD
+  - custom: Custom/specialized agents
+
+# Protocol Support Matrix
+protocols:
+  http:
+    use_case: 'RESTful APIs, local-first development'
+    required_fields: ['integration.endpoints.base_url']
+  grpc:
+    use_case: 'High-performance inter-agent communication'
+    required_fields: ['integration.endpoints.base_url', 'proto file']
+  mcp:
+    use_case: 'MCP tool server integration, Claude Desktop'
+    required_fields: ['integration.protocol = mcp']
+  websocket:
+    use_case: 'Real-time streaming, bi-directional communication'
+    required_fields: ['integration.endpoints.base_url']
+
+# Compliance Framework Mapping
+compliance_frameworks:
+  fedramp-low:
+    encryption: required
+    audit: required
+    data_residency: ['US']
+  fedramp-moderate:
+    encryption: required
+    audit: required
+    data_residency: ['US-GOV']
+    pii_handling: 'encrypt'
+  fedramp-high:
+    encryption: required
+    audit: required
+    data_residency: ['US-GOV']
+    pii_handling: 'encrypt'
+    auth.type: 'mtls'
+  soc2-type2:
+    encryption: required
+    audit: required
+  hipaa:
+    encryption: required
+    audit: required
+    pii_handling: 'encrypt'
+  gdpr:
+    encryption: required
+    audit: required
+    pii_handling: 'anonymize'
+    data_residency: ['EU']
+
+# Versioning Strategy
+versioning:
+  semver: 'OSSA agents MUST use semantic versioning'
+  breaking_changes: 'Major version bump required for breaking changes'
+  deprecation: 'Deprecate in N, remove in N+1'
+  compatibility_matrix:
+    - ossa_version: '1.0'
+      agent_versions: '1.x.x'
+    - ossa_version: '1.1'
+      agent_versions: '1.x.x || 2.x.x'
+
+# Bridge Use Cases
+bridge_use_cases:
+  mcp:
+    description: 'Model Context Protocol - Claude Desktop, Langflow integration'
+    when_to_use: 'Expose agent as MCP tool server for AI assistants'
+    transport_types:
+      stdio: 'Local execution, Claude Desktop'
+      sse: 'Server-sent events for web integration'
+      websocket: 'Real-time bidirectional communication'
+
+  a2a:
+    description: 'Agent-to-Agent Protocol - Multi-agent coordination'
+    when_to_use: 'Enable agent discovery and inter-agent communication'
+
+  openapi:
+    description: 'REST API bridge - Standard HTTP/REST integration'
+    when_to_use: 'Expose agent capabilities as REST API'
+
+  langchain:
+    description: 'LangChain framework integration'
+    when_to_use: 'Use agent within LangChain workflows'
+
+  crewai:
+    description: 'CrewAI framework integration'
+    when_to_use: 'Agent as part of CrewAI multi-agent system'
+
+  autogen:
+    description: 'AutoGen framework integration'
+    when_to_use: 'Multi-agent conversations with AutoGen'
+
+# Best Practices
+best_practices:
+  - Always specify health_check endpoint
+  - Use semantic versioning
+  - Document all capabilities with examples
+  - Enable monitoring (traces, metrics, logs)
+  - Specify compliance requirements upfront
+  - Use resource limits for K8s deployments
+  - Implement retry policies for resilience
+  - Tag agents for discovery
+  - Reference OpenAPI specs for complex schemas
+  - Use dependency declarations for agent coordination
+  - Enable bridge protocols for interoperability
+  - Map MCP tools to OSSA capabilities for consistency
+  - Use stdio transport for local/desktop integration
+  - Use websocket transport for production deployments

package/dist/spec/v0.2.4-dev/README.md

@@ -0,0 +1,61 @@
+# OSSA v0.2.4-dev Specification
+
+**Status:** Development  
+**Release Date:** TBD  
+**Previous Version:** [v0.2.3](../v0.2.3/README.md)
+
+## Overview
+
+OSSA v0.2.4 focuses on **Transport & Security** enhancements, providing foundational features for secure, stateful agent communication and enterprise integrations.
+
+## Key Features
+
+### Transport Metadata
+- Protocol specification per capability (http, grpc, a2a, mcp, websocket, custom)
+- Streaming modes (none, request, response, bidirectional)
+- Binding paths and content types
+
+### State Management
+- Stateless, session, and long-running agent modes
+- Storage backends (memory, vector-db, kv, rdbms, custom)
+- Context window strategies (sliding_window, summarization, importance_weighted)
+
+### Security & Compliance
+- OAuth2-like scopes for fine-grained permissions
+- Compliance tags (pii, hipaa, gdpr, fedramp, soc2, pci-dss)
+- Per-capability scope overrides
+
+### Capability Versioning
+- Independent capability versioning (semantic versioning)
+- Deprecation support with removal versions
+- Migration guide templates
+
+### Framework Extensions
+- Google ADK integration (llm_agent, sequential_agent, parallel_agent, loop_agent)
+- Microsoft Agent Framework adapter examples
+
+## Schema Files
+
+- **JSON Schema:** [`ossa-0.2.4-dev.schema.json`](./ossa-0.2.4-dev.schema.json)
+- **YAML Schema:** [`ossa-0.2.4-dev.yaml`](./ossa-0.2.4-dev.yaml)
+
+## Migration Guide
+
+See [`migrations/v0.2.3-to-v0.2.4.md`](./migrations/v0.2.3-to-v0.2.4.md) for migration instructions from v0.2.3.
+
+## Changelog
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for detailed changes.
+
+## Examples
+
+- CI/CD Agents: [`.gitlab/agents/`](../../.gitlab/agents/)
+- Getting Started: [`examples/getting-started/`](../../examples/getting-started/)
+- Framework Integrations: [`examples/`](../../examples/)
+
+## Related Documentation
+
+- [OSSA Website](https://openstandardagents.org)
+- [GitHub Repository](https://github.com/blueflyio/openstandardagents)
+- [NPM Package](https://www.npmjs.com/package/@bluefly/openstandardagents)
+

package/dist/spec/v0.2.4-dev/RELEASE-PROCESS.md

@@ -0,0 +1,130 @@
+# v0.2.4 Release Process
+
+## Current Status: Development (v0.2.4-dev)
+
+We are currently in **development** phase for v0.2.4. The `spec/v0.2.4-dev/` directory contains the development version of the specification.
+
+## Folder Naming Convention
+
+### Development Versions
+- **Format**: `spec/v0.2.X-dev/`
+- **Example**: `spec/v0.2.4-dev/`
+- **Purpose**: Active development, schema may change
+- **Status**: Not stable, APIs may change
+
+### Stable Releases
+- **Format**: `spec/v0.2.X/`
+- **Example**: `spec/v0.2.4/`
+- **Purpose**: Stable, released specification
+- **Status**: Frozen, no breaking changes
+
+## Release Process (When Ready)
+
+When v0.2.4 is ready for release:
+
+### Step 1: Create Stable Directory
+```bash
+mkdir -p spec/v0.2.4
+```
+
+### Step 2: Copy and Prepare Files
+```bash
+# Copy all files from dev to stable
+cp -r spec/v0.2.4-dev/* spec/v0.2.4/
+
+# Rename schema files (remove -dev suffix)
+cd spec/v0.2.4
+mv ossa-0.2.4-dev.schema.json ossa-0.2.4.schema.json
+mv ossa-0.2.4-dev.yaml ossa-0.2.4.yaml
+
+# Update schema file contents
+# - Change apiVersion pattern to accept ossa/v0.2.4 (without -dev)
+# - Update $id and title to remove -dev
+# - Update CHANGELOG.md to mark as stable release
+```
+
+### Step 3: Update References
+- Update `package.json` exports to reference `spec/v0.2.4/ossa-0.2.4.schema.json`
+- Update website version files
+- Update documentation references
+- Update examples to use `ossa/v0.2.4` (without -dev)
+
+### Step 4: Handle Development Directory
+**Option A: Keep for ongoing development**
+- Keep `spec/v0.2.4-dev/` for patch development
+- Create `spec/v0.2.5-dev/` for next minor version
+
+**Option B: Rename for next version**
+- Rename `spec/v0.2.4-dev/` to `spec/v0.2.5-dev/`
+- Update all references to v0.2.5-dev
+
+### Step 5: Update Schema Version Pattern
+In `ossa-0.2.4.schema.json`, update apiVersion pattern:
+```json
+"pattern": "^ossa/v(0\\.2\\.[2-4]|1)(\\.[0-9]+)?(-[a-zA-Z0-9]+)?$"
+```
+Remove `-dev` from accepted versions for stable release.
+
+## Current Structure
+
+```
+spec/
+├── v0.2.3/              # Stable release
+│   ├── ossa-0.2.3.schema.json
+│   ├── ossa-0.2.3.yaml
+│   ├── README.md
+│   ├── CHANGELOG.md
+│   └── migrations/
+│
+├── v0.2.4-dev/          # Development (current)
+│   ├── ossa-0.2.4-dev.schema.json
+│   ├── ossa-0.2.4-dev.yaml
+│   ├── README.md
+│   ├── CHANGELOG.md
+│   ├── migrations/
+│   └── openapi/          # OpenAPI documentation
+│       ├── README-0.2.4.md
+│       ├── CHANGELOG-0.2.4.md
+│       └── VERIFICATION-0.2.4.md
+│
+└── v0.2.5-dev/           # Future development
+```
+
+## After Release Structure
+
+```
+spec/
+├── v0.2.3/              # Stable release
+├── v0.2.4/              # NEW: Stable release (after release)
+│   ├── ossa-0.2.4.schema.json  # No -dev suffix
+│   ├── ossa-0.2.4.yaml
+│   ├── README.md
+│   ├── CHANGELOG.md
+│   ├── migrations/
+│   └── openapi/
+│
+└── v0.2.4-dev/          # Keep for patches OR rename to v0.2.5-dev
+```
+
+## Decision: When to Create Stable Directory
+
+**Create `spec/v0.2.4/` when:**
+- ✅ All v0.2.4 milestone issues are complete
+- ✅ All tests pass
+- ✅ Schema is validated
+- ✅ Documentation is complete
+- ✅ Ready to tag and release
+
+**Keep `spec/v0.2.4-dev/` for:**
+- Ongoing development
+- Patch releases (v0.2.4.1, v0.2.4.2, etc.)
+- Or rename to v0.2.5-dev for next minor version
+
+## OpenAPI Documentation
+
+OpenAPI-related documentation for v0.2.4 is stored in:
+- `spec/v0.2.4-dev/openapi/` (development)
+- Will move to `spec/v0.2.4/openapi/` when released
+
+This keeps all v0.2.4-related documentation together in the spec directory.
+