@bluefly/openstandardagents 0.3.3 → 0.3.5

package/spec/v0.3/examples/forward-thinking-agent.ossa.yaml

@@ -0,0 +1,294 @@
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: forward-thinking-reviewer
+  version: 1.0.0
+  description: "Next-generation MR reviewer with MoE, completion signals, and checkpointing"
+spec:
+  # Core Agent Configuration
+  identity:
+    id: "@forward-thinking-reviewer"
+    display_name: "Forward Thinking MR Reviewer"
+    tier: worker
+  
+  # LLM Configuration with MoE
+  llm:
+    provider: ${LLM_PROVIDER:-anthropic}
+    model: ${LLM_MODEL:-claude-sonnet}
+    profile: balanced
+    fallback_models:
+      - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
+        model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
+
+  # Completion Signals
+  completion:
+    default_signal: complete
+    signals:
+      - signal: continue
+        condition: "iteration_count < max_iterations"
+        priority: 1
+      - signal: blocked
+        condition: "confidence < 0.5"
+        priority: 2
+      - signal: escalate
+        condition: "error_count > 3"
+        priority: 3
+      - signal: checkpoint
+        condition: "iteration_count % 5 == 0"
+        priority: 4
+    max_iterations: 20
+    timeout_seconds: 600
+
+  # Session Checkpointing
+  checkpointing:
+    enabled: true
+    interval: iteration
+    interval_value: 5
+    retention:
+      days: 30
+      max_checkpoints: 100
+    storage:
+      backend: agent-brain
+      location: s3://checkpoints/@forward-thinking-reviewer/{session_id}
+
+  # Mixture of Experts
+  extensions:
+    experts:
+      registry:
+        - id: reasoning-expert
+          name: "Complex Reasoning Expert"
+          model:
+            provider: anthropic
+            model: claude-opus-4-5-20251101
+          specializations:
+            - complex_reasoning
+            - planning
+            - multi_step_analysis
+          cost_tier: premium
+          capabilities:
+            extended_thinking: true
+            max_tokens: 200000
+            reasoning_depth: deep
+          availability:
+            regions: [us-east-1, eu-west-1]
+            fallback: code-expert
+
+        - id: code-expert
+          name: "Code Generation Expert"
+          model:
+            provider: anthropic
+            model: claude-sonnet-4-20250514
+          specializations:
+            - code_generation
+            - code_review
+            - debugging
+          cost_tier: standard
+          capabilities:
+            max_tokens: 16384
+            reasoning_depth: balanced
+
+        - id: speed-expert
+          name: "High-Volume Expert"
+          model:
+            provider: google
+            model: gemini-2.0-flash
+          specializations:
+            - quick_responses
+            - high_volume
+            - cost_sensitive
+          cost_tier: economy
+          capabilities:
+            max_tokens: 8192
+            reasoning_depth: fast
+
+      selection_strategy: agent_controlled
+
+      tools:
+        - name: list_experts
+          description: "Discover available expert models and their capabilities"
+        - name: invoke_expert
+          description: "Delegate task to specialized expert model"
+        - name: get_expert_history
+          description: "Review past expert invocations for learning"
+
+    # BAT Framework
+    bat:
+      selection_criteria:
+        - dimension: reasoning_depth
+          required: true
+          options:
+            - value: deep
+              technologies: [claude-opus, gpt-4-turbo]
+              cost_tier: premium
+            - value: balanced
+              technologies: [claude-sonnet, gpt-4o]
+              cost_tier: standard
+            - value: fast
+              technologies: [gemini-flash, claude-haiku]
+              cost_tier: economy
+
+        - dimension: cost_sensitivity
+          required: true
+          options:
+            - value: high
+              prefer: [gemini-flash, claude-haiku]
+              max_cost_per_task: 0.10
+            - value: medium
+              prefer: [claude-sonnet, gpt-4o]
+              max_cost_per_task: 0.50
+            - value: low
+              prefer: [claude-opus, gpt-4-turbo]
+              max_cost_per_task: 2.00
+
+      tools:
+        - name: select_technology
+          description: "Select best available technology for a task"
+
+    # MOE Metrics
+    moe:
+      primary:
+        metric: review_accuracy
+        description: "Core review accuracy metric"
+        target: 0.95
+        measurement:
+          type: ratio
+          numerator: approved_reviews_without_issues
+          denominator: total_reviews
+        collection:
+          source: agent-tracer
+          interval: real_time
+
+      secondary:
+        - metric: review_latency_p95
+          description: "95th percentile review latency"
+          target: 600
+          unit: seconds
+          measurement:
+            type: percentile
+            value: 95
+            field: duration_ms
+
+        - metric: user_satisfaction
+          description: "User satisfaction score"
+          target: 4.5
+          unit: rating
+          scale: [1, 5]
+
+      operational:
+        - metric: uptime
+          description: "Agent availability"
+          target: 0.999
+          unit: ratio
+
+        - metric: cost_per_review
+          description: "Average cost per review"
+          target: 0.25
+          unit: usd
+
+      tracking:
+        enabled: true
+        collection_interval: 60s
+        retention_days: 90
+        dashboards:
+          - gitlab_observability
+          - agent_studio_ui
+        alerts:
+          - condition: "primary_metric < target * 0.9"
+            severity: warning
+          - condition: "primary_metric < target * 0.8"
+            severity: critical
+
+    # Capability Discovery
+    capabilities:
+      discovery:
+        enabled: true
+        registry: agent-mesh
+        refresh_interval: 60s
+
+      tools:
+        - name: list_capabilities
+          description: "Discover available capabilities in the environment"
+        - name: register_capability
+          description: "Register a new capability for discovery"
+
+    # Feedback Loops
+    feedback:
+      tools:
+        - name: record_feedback
+          description: "Record feedback on action or result"
+        - name: get_feedback_summary
+          description: "Get aggregate feedback for analysis"
+        - name: suggest_improvements
+          description: "Get improvement suggestions based on feedback"
+
+      learning:
+        enabled: true
+        strategy: reinforcement
+        data_sources:
+          - feedback_ratings
+          - completion_signals
+          - expert_selection_outcomes
+        model_fine_tuning:
+          enabled: true
+          schedule: monthly
+          target_model: models/orchestration
+
+  # Tools with checkpoint support
+  tools:
+    - name: checkpoint_session
+      description: "Save current session state for resumption"
+      parameters:
+        type: object
+        properties:
+          reason:
+            type: string
+
+    - name: resume_session
+      description: "Resume from a previous checkpoint"
+      parameters:
+        type: object
+        required: [checkpoint_id]
+        properties:
+          checkpoint_id:
+            type: string
+            format: uuid
+
+    - name: review_merge_request
+      description: "Review a GitLab merge request"
+      parameters:
+        type: object
+        required: [project_id, mr_iid]
+        properties:
+          project_id:
+            type: integer
+          mr_iid:
+            type: integer
+          use_expert:
+            type: string
+            description: "Expert ID to use (optional)"
+
+  # Access Tier
+  access_tier:
+    tier: tier_2_write_limited
+    permissions:
+      - gitlab:read
+      - gitlab:write_comments
+      - gitlab:read_code
+
+  # A2A Communication
+  communication:
+    a2a:
+      enabled: true
+      mesh_endpoint: mesh.blueflyagents.com:3005
+      completion_signals: true
+      checkpoint_sync: true
+
+  # Infrastructure Awareness
+  infrastructure:
+    - type: synology_nas
+      hostname: blueflynas.tailcf98b3.ts.net
+      capabilities:
+        - store_artifact
+        - manage_checkpoints
+      access:
+        tier: tier_2_write_limited

package/spec/v0.3/examples/moe-example.ossa.yaml

@@ -0,0 +1,120 @@
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: moe-powered-agent
+  version: 1.0.0
+  description: "Agent demonstrating Mixture of Experts (MoE) for cost optimization"
+spec:
+  identity:
+    id: "@moe-powered-agent"
+    display_name: "MoE Powered Agent"
+    tier: worker
+
+  llm:
+    provider: ${LLM_PROVIDER:-anthropic}
+    model: ${LLM_MODEL:-claude-sonnet}
+    profile: balanced
+
+  # Completion signals
+  completion:
+    default_signal: complete
+    signals:
+      - signal: continue
+        condition: "iteration_count < max_iterations"
+      - signal: escalate
+        condition: "confidence < 0.3"
+    max_iterations: 15
+
+extensions:
+  # Mixture of Experts
+  experts:
+    registry:
+      - id: reasoning-expert
+        name: "Complex Reasoning Expert"
+        model:
+          provider: anthropic
+          model: claude-opus-4-5-20251101
+        specializations:
+          - complex_reasoning
+          - planning
+          - multi_step_analysis
+        cost_tier: premium
+        capabilities:
+          extended_thinking: true
+          max_tokens: 200000
+          reasoning_depth: deep
+        availability:
+          regions: [us-east-1, eu-west-1]
+          fallback: code-expert
+
+      - id: code-expert
+        name: "Code Generation Expert"
+        model:
+          provider: anthropic
+          model: claude-sonnet-4-20250514
+        specializations:
+          - code_generation
+          - code_review
+          - debugging
+        cost_tier: standard
+        capabilities:
+          max_tokens: 16384
+          reasoning_depth: balanced
+
+      - id: speed-expert
+        name: "High-Volume Expert"
+        model:
+          provider: google
+          model: gemini-2.0-flash
+        specializations:
+          - quick_responses
+          - high_volume
+          - cost_sensitive
+        cost_tier: economy
+        capabilities:
+          max_tokens: 8192
+          reasoning_depth: fast
+
+    selection_strategy: agent_controlled
+
+    tools:
+      - name: list_experts
+        description: "Discover available expert models and their capabilities"
+      - name: invoke_expert
+        description: "Delegate task to specialized expert model"
+      - name: get_expert_history
+        description: "Review past expert invocations for learning"
+
+  # MOE Metrics
+  moe:
+    primary:
+      metric: expert_selection_accuracy
+      target: 0.90
+      measurement:
+        type: ratio
+        numerator: optimal_expert_selections
+        denominator: total_expert_invocations
+    secondary:
+      - metric: cost_per_task
+        target: 0.15
+        unit: usd
+    operational:
+      - metric: expert_availability
+        target: 0.95
+        unit: ratio
+
+tools:
+  - name: select_expert_for_task
+    description: "Select optimal expert for a given task"
+    parameters:
+      type: object
+      required: [task_description]
+      properties:
+        task_description:
+          type: string
+        cost_sensitivity:
+          type: string
+          enum: [high, medium, low]
+        reasoning_requirement:
+          type: string
+          enum: [fast, balanced, deep]

package/spec/v0.3/extensions/a2a/README.md

@@ -0,0 +1,193 @@
+# A2A (Agent-to-Agent) Communication Extension
+
+**Version**: 0.3.5
+**Status**: Stable
+**Protocol**: Production-Ready A2A
+
+## Overview
+
+The A2A extension enables production-ready agent-to-agent communication with service discovery, message routing, task delegation, completion signals, and checkpoint synchronization.
+
+## Features
+
+- **Service Discovery**: DNS, Consul, Kubernetes, Registry-based discovery
+- **Message Routing**: Direct, broadcast, round-robin, capability-based routing
+- **Task Delegation**: Multi-level delegation with handoff support
+- **Completion Signals**: Standardized task completion signaling
+- **Checkpoint Sync**: Distributed checkpoint synchronization
+- **Authentication**: mTLS, OAuth2, API Key, JWT support
+- **Resilience**: Retry policies, circuit breakers, health checks
+- **Observability**: Distributed tracing, metrics, logging
+
+## Schema Reference
+
+### Basic A2A Configuration
+
+```yaml
+extensions:
+  a2a:
+    enabled: true
+    protocol:
+      type: json-rpc
+      version: "2.0"
+      messageFormat: json
+      timeout: 30
+    endpoints:
+      - agentId: "@security-scanner"
+        url: "http://security-scanner:8080/a2a"
+        capabilities: ["security-scan", "vulnerability-check"]
+        priority: 10
+```
+
+### Service Discovery
+
+```yaml
+extensions:
+  a2a:
+    discovery:
+      enabled: true
+      mechanism: registry
+      registryUrl: "https://registry.example.com/agents"
+      refreshInterval: 60
+      healthCheck:
+        enabled: true
+        interval: 30
+        timeout: 5
+        endpoint: "/health"
+```
+
+### Routing Configuration
+
+```yaml
+extensions:
+  a2a:
+    routing:
+      strategy: capability-based
+      defaultAgent: "@fallback-agent"
+      routingRules:
+        - name: "security-routing"
+          condition: "message.type == 'security-scan'"
+          target: "@security-scanner"
+          priority: 10
+        - name: "code-review-routing"
+          condition: "message.type == 'code-review'"
+          target: "@mr-reviewer"
+          priority: 5
+```
+
+### Task Delegation
+
+```yaml
+extensions:
+  a2a:
+    delegation:
+      enabled: true
+      maxDepth: 3
+      timeout: 300
+      handoff:
+        enabled: true
+        preserveContext: true
+        handoffRules:
+          - name: "escalation"
+            condition: "signal == 'escalate'"
+            target: "@senior-reviewer"
+            message: "Escalating to senior reviewer"
+```
+
+### Completion Signals
+
+```yaml
+extensions:
+  a2a:
+    completionSignals:
+      enabled: true
+      signals: ["continue", "complete", "blocked", "escalate", "checkpoint"]
+      handlers:
+        - signal: escalate
+          action: handoff
+          target: "@senior-agent"
+        - signal: checkpoint
+          action: checkpoint
+          config:
+            storage: agent-brain
+```
+
+### Authentication
+
+```yaml
+extensions:
+  a2a:
+    authentication:
+      type: mtls
+      mtls:
+        certPath: "/certs/client.crt"
+        keyPath: "/certs/client.key"
+        caPath: "/certs/ca.crt"
+        verifyPeer: true
+```
+
+## Use Cases
+
+### 1. Multi-Agent Code Review System
+
+```yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: mr-coordinator
+spec:
+  extensions:
+    a2a:
+      enabled: true
+      protocol:
+        type: json-rpc
+        version: "2.0"
+      endpoints:
+        - agentId: "@security-scanner"
+          url: "http://security-scanner:8080/a2a"
+          capabilities: ["security-scan"]
+        - agentId: "@performance-analyzer"
+          url: "http://performance-analyzer:8080/a2a"
+          capabilities: ["performance-analysis"]
+      routing:
+        strategy: capability-based
+      delegation:
+        enabled: true
+        maxDepth: 2
+```
+
+### 2. Service Discovery with Kubernetes
+
+```yaml
+apiVersion: ossa/v0.3.5
+kind: Agent
+metadata:
+  name: distributed-agent
+spec:
+  extensions:
+    a2a:
+      enabled: true
+      discovery:
+        enabled: true
+        mechanism: kubernetes
+        refreshInterval: 60
+      protocol:
+        type: grpc
+        version: "1.0"
+```
+
+## Best Practices
+
+1. **Service Discovery**: Use registry or Kubernetes for dynamic environments
+2. **Authentication**: Always use mTLS or OAuth2 in production
+3. **Circuit Breakers**: Enable to prevent cascading failures
+4. **Health Checks**: Configure for automatic unhealthy agent removal
+5. **Delegation Depth**: Keep maxDepth <= 3 to avoid deep chains
+6. **Timeouts**: Set appropriate timeouts for agent response times
+7. **Observability**: Enable tracing for debugging distributed workflows
+
+## References
+
+- [OSSA v0.3.5 Specification](../../README.md)
+- [MCP Extension](../mcp/README.md)
+- [Kagent Extension](../kagent/README.md)

package/spec/v0.3/extensions/a2a/a2a.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.5/extensions/a2a.json",
+  "title": "A2A Extension Schema",
+  "description": "Agent-to-Agent communication extension for OSSA",
+  "type": "object",
+  "properties": {
+    "service_discovery": {
+      "type": "object",
+      "description": "Service discovery configuration",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "registry_url": { "type": "string", "format": "uri" },
+        "health_check_interval": { "type": "integer", "minimum": 0 },
+        "timeout": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "agent_card": {
+      "type": "object",
+      "description": "Agent identity card for A2A",
+      "properties": {
+        "agent_uri": { "type": "string", "pattern": "^agent://" },
+        "capabilities": { "type": "array", "items": { "type": "string" } },
+        "protocols": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["json-rpc", "grpc", "http", "websocket"]
+          }
+        },
+        "endpoints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "url": { "type": "string", "format": "uri" },
+              "protocol": { "type": "string" },
+              "auth_required": { "type": "boolean" }
+            }
+          }
+        }
+      },
+      "required": ["agent_uri", "capabilities"]
+    },
+    "handoff_protocol": {
+      "type": "object",
+      "description": "Task handoff configuration",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["capability_match", "load_balance", "round_robin", "custom"]
+        },
+        "timeout": { "type": "integer" },
+        "retry_policy": {
+          "type": "object",
+          "properties": {
+            "max_retries": { "type": "integer" },
+            "backoff_ms": { "type": "integer" }
+          }
+        }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "description": "Authentication configuration",
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["jwt", "oauth2", "api_key", "mtls"]
+        },
+        "issuer": { "type": "string" },
+        "audience": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": false
+}