@bluefly/openstandardagents 0.3.1 → 0.3.3

package/examples/getting-started/05-workflow-composition.ossa.yaml

@@ -1,25 +1,4 @@
-# =============================================================================
-# OSSA Getting Started: 05 - Workflow Composition
-# =============================================================================
-#
-# Workflows compose multiple Tasks and Agents into executable pipelines.
-# This is OSSA's power feature - orchestrate complex processes declaratively.
-#
-# Workflow vs Agent:
-# - Agent: LLM-powered, can reason and decide
-# - Task: Deterministic, no LLM (batch jobs, transformations)
-# - Workflow: Composes Agents and Tasks with control flow
-#
-# Features:
-# - Triggers: webhook, cron, events
-# - Steps: sequential, parallel, conditional
-# - Error handling: retry, rollback, compensation
-# - Data flow: pass outputs between steps
-#
-# Run:   ossa validate 05-workflow-composition.ossa.yaml
-# =============================================================================
-
-apiVersion: ossa/v0.3.0
+apiVersion: ossa/v0.3.3
 kind: Workflow
 metadata:
   name: code-review-pipeline
@@ -27,34 +6,28 @@ metadata:
   description: Automated code review pipeline with security scanning
   labels:
     difficulty: advanced
-    tutorial: "05"
+    tutorial: '05'
     use-case: ci-cd
-
 spec:
-  # Triggers that start the workflow
   triggers:
-    # Webhook trigger - receives HTTP POST
-    - type: webhook
-      path: /api/review
-      method: POST
-      authentication:
-        type: bearer
-        secret_ref: ${WEBHOOK_SECRET}
-
-    # Event trigger - GitLab merge request events
-    - type: event
-      source: gitlab
-      events:
-        - merge_request.opened
-        - merge_request.updated
-      filter:
-        # Only trigger for specific branches
-        expression: "${{ event.target_branch in ['main', 'develop'] }}"
-
-  # Input schema - validates incoming data
+  - type: webhook
+    path: /api/review
+    method: POST
+    authentication:
+      type: bearer
+      secret_ref: ${WEBHOOK_SECRET}
+  - type: event
+    source: gitlab
+    events:
+    - merge_request.opened
+    - merge_request.updated
+    filter:
+      expression: ${{ event.target_branch in ['main', 'develop'] }}
   inputs:
     type: object
-    required: [repository_url, branch]
+    required:
+    - repository_url
+    - branch
     properties:
       repository_url:
         type: string
@@ -66,14 +39,15 @@ spec:
       pr_number:
         type: integer
         description: Pull request number (if applicable)
-
-  # Output schema - what the workflow produces
   outputs:
     type: object
     properties:
       review_status:
         type: string
-        enum: [approved, changes_requested, blocked]
+        enum:
+        - approved
+        - changes_requested
+        - blocked
       findings:
         type: array
         items:
@@ -82,123 +56,93 @@ spec:
         type: number
         minimum: 0
         maximum: 100
-
-  # Workflow steps - the main logic
   steps:
-    # Step 1: Validate the PR (deterministic Task - no LLM)
-    - id: validate
-      name: Validate PR Structure
-      kind: Task
-      ref: ./tasks/validate-pr.ossa.yaml
-      input:
-        repository: "${{ workflow.input.repository_url }}"
-        branch: "${{ workflow.input.branch }}"
-      # Step outputs are available to subsequent steps
-      output:
-        files_changed: array
-        is_valid: boolean
-
-    # Step 2: Security scan (Agent - uses LLM)
-    # Only runs if PR is valid
-    - id: security-scan
-      name: Security Analysis
-      kind: Agent
-      ref: ./agents/security-scanner.ossa.yaml
-      condition: "${{ steps.validate.output.is_valid == true }}"
-      input:
-        files: "${{ steps.validate.output.files_changed }}"
-        scan_type: full
-      output:
-        vulnerabilities: array
-        security_score: number
-
-    # Step 3: Code review (Agent - uses LLM)
-    # Runs in parallel with security scan
-    - id: code-review
-      name: Code Quality Review
-      kind: Agent
-      ref: ./agents/code-reviewer.ossa.yaml
-      condition: "${{ steps.validate.output.is_valid == true }}"
-      parallel_with: security-scan  # Run simultaneously with security scan
-      input:
-        files: "${{ steps.validate.output.files_changed }}"
-        review_type: comprehensive
-      output:
-        suggestions: array
-        quality_score: number
-
-    # Step 4: Aggregate results (Task - no LLM)
-    # Waits for both security-scan and code-review
-    - id: aggregate
-      name: Aggregate Review Results
-      kind: Task
-      depends_on:
-        - security-scan
-        - code-review
-      ref: ./tasks/aggregate-results.ossa.yaml
-      input:
-        security_findings: "${{ steps.security-scan.output.vulnerabilities }}"
-        security_score: "${{ steps.security-scan.output.security_score }}"
-        code_suggestions: "${{ steps.code-review.output.suggestions }}"
-        quality_score: "${{ steps.code-review.output.quality_score }}"
-      output:
-        final_status: string
-        combined_findings: array
-
-    # Step 5: Post comment to PR (Task - no LLM)
-    - id: post-comment
-      name: Post Review Comment
-      kind: Task
-      ref: ./tasks/post-pr-comment.ossa.yaml
-      input:
-        pr_number: "${{ workflow.input.pr_number }}"
-        status: "${{ steps.aggregate.output.final_status }}"
-        findings: "${{ steps.aggregate.output.combined_findings }}"
-
-    # Conditional step: Block if critical issues
-    - id: block-merge
-      name: Block Merge on Critical Issues
-      kind: Task
-      condition: "${{ steps.aggregate.output.final_status == 'blocked' }}"
-      ref: ./tasks/block-merge.ossa.yaml
-      input:
-        pr_number: "${{ workflow.input.pr_number }}"
-        reason: "Critical security vulnerabilities found"
-
-  # Shared context available to all steps
+  - id: validate
+    name: Validate PR Structure
+    kind: Task
+    ref: ./tasks/validate-pr.ossa.yaml
+    input:
+      repository: ${{ workflow.input.repository_url }}
+      branch: ${{ workflow.input.branch }}
+    output:
+      files_changed: array
+      is_valid: boolean
+  - id: security-scan
+    name: Security Analysis
+    kind: Agent
+    ref: ./agents/security-scanner.ossa.yaml
+    condition: ${{ steps.validate.output.is_valid == true }}
+    input:
+      files: ${{ steps.validate.output.files_changed }}
+      scan_type: full
+    output:
+      vulnerabilities: array
+      security_score: number
+  - id: code-review
+    name: Code Quality Review
+    kind: Agent
+    ref: ./agents/code-reviewer.ossa.yaml
+    condition: ${{ steps.validate.output.is_valid == true }}
+    parallel_with: security-scan
+    input:
+      files: ${{ steps.validate.output.files_changed }}
+      review_type: comprehensive
+    output:
+      suggestions: array
+      quality_score: number
+  - id: aggregate
+    name: Aggregate Review Results
+    kind: Task
+    depends_on:
+    - security-scan
+    - code-review
+    ref: ./tasks/aggregate-results.ossa.yaml
+    input:
+      security_findings: ${{ steps.security-scan.output.vulnerabilities }}
+      security_score: ${{ steps.security-scan.output.security_score }}
+      code_suggestions: ${{ steps.code-review.output.suggestions }}
+      quality_score: ${{ steps.code-review.output.quality_score }}
+    output:
+      final_status: string
+      combined_findings: array
+  - id: post-comment
+    name: Post Review Comment
+    kind: Task
+    ref: ./tasks/post-pr-comment.ossa.yaml
+    input:
+      pr_number: ${{ workflow.input.pr_number }}
+      status: ${{ steps.aggregate.output.final_status }}
+      findings: ${{ steps.aggregate.output.combined_findings }}
+  - id: block-merge
+    name: Block Merge on Critical Issues
+    kind: Task
+    condition: ${{ steps.aggregate.output.final_status == 'blocked' }}
+    ref: ./tasks/block-merge.ossa.yaml
+    input:
+      pr_number: ${{ workflow.input.pr_number }}
+      reason: Critical security vulnerabilities found
   context:
     variables:
-      organization: "${{ env.GITHUB_ORG }}"
+      organization: ${{ env.GITHUB_ORG }}
       default_reviewers:
-        - "@security-team"
-        - "@code-review-team"
-
-  # Error handling configuration
+      - '@security-team'
+      - '@code-review-team'
   error_handling:
-    # What to do when a step fails
-    on_failure: compensation  # Options: fail_fast, continue, compensation, rollback
-
-    # Compensation steps - undo partial work
+    on_failure: compensation
     compensation_steps:
-      - id: cleanup
-        name: Cleanup Failed Review
-        kind: Task
-        ref: ./tasks/cleanup-review.ossa.yaml
-        input:
-          pr_number: "${{ workflow.input.pr_number }}"
-
-    # Retry configuration for transient failures
+    - id: cleanup
+      name: Cleanup Failed Review
+      kind: Task
+      ref: ./tasks/cleanup-review.ossa.yaml
+      input:
+        pr_number: ${{ workflow.input.pr_number }}
     retry:
       max_attempts: 3
       backoff: exponential
       initial_delay_seconds: 5
-
-  # Timeouts
   timeouts:
-    workflow: 30m      # Total workflow timeout
-    step_default: 5m   # Default per-step timeout
-
-  # Observability
+    workflow: 30m
+    step_default: 5m
   observability:
     tracing:
       enabled: true

package/examples/getting-started/hello-world-complete.ossa.yaml

@@ -1,266 +1,111 @@
-# ============================================================================
-# OSSA v0.2.x - Complete "Hello World" Agent Example
-# ============================================================================
-# 
-# PURPOSE:
-#   This is a minimal, fully-compliant OSSA agent manifest demonstrating
-#   all required fields and best practices. Use this as a starting point
-#   for your first agent.
-#
-# LEARNING OBJECTIVES:
-#   1. Understand OSSA manifest structure (apiVersion, kind, metadata, spec)
-#   2. Learn required vs optional fields
-#   3. See how to define agent capabilities (tools)
-#   4. Understand LLM configuration
-#   5. Learn basic observability setup
-#
-# VALIDATION:
-#   ossa validate examples/getting-started/hello-world-complete.ossa.yaml
-#
-# DEPLOYMENT:
-#   This agent can be deployed to any OSSA-compatible runtime:
-#   - Kubernetes (via agent-buildkit)
-#   - Docker Compose
-#   - Serverless (AWS Lambda, Google Cloud Functions)
-#   - Local development
-#
-# INTEGRATION PATTERNS:
-#   - Standalone agent (no dependencies)
-#   - Can be called via HTTP/gRPC
-#   - Can participate in multi-agent workflows
-#   - Compatible with MCP (Model Context Protocol)
-#
-# ============================================================================
-
-apiVersion: ossa/v0.3.0
+apiVersion: ossa/v0.3.3
 kind: Agent
-
 metadata:
-  # REQUIRED: Agent identifier (DNS-1123 format for Kubernetes compatibility)
-  # Must be lowercase alphanumeric with hyphens, max 253 chars
   name: hello-world-agent
-  
-  # REQUIRED: Semantic version (semver 2.0.0)
-  # Format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
   version: 1.0.0
-  
-  # REQUIRED: Human-readable description
-  # Should explain what the agent does, its purpose, and key capabilities
-  description: |
-    A minimal OSSA-compliant agent that demonstrates basic capabilities.
+  description: 'A minimal OSSA-compliant agent that demonstrates basic capabilities.
+
     This agent can greet users, echo messages, and report its status.
+
     Perfect for learning OSSA fundamentals and testing deployments.
-  
-  # OPTIONAL: Key-value labels for organization and filtering
-  # Common labels: environment, team, domain, classification
+
+    '
   labels:
     environment: development
     team: platform-engineering
     domain: examples
     complexity: minimal
-  
-  # OPTIONAL: Arbitrary metadata for tooling (not used for filtering)
-  # Common annotations: documentation URL, support contact, runbooks
   annotations:
     documentation: https://docs.ossa.io/examples/hello-world
     support: support@example.com
     runbook: https://runbooks.example.com/hello-world-agent
-
 spec:
-  # REQUIRED: Agent role/system prompt describing behavior and capabilities
-  # This is the "personality" and instructions for the LLM
-  # Should be clear, specific, and aligned with the agent's purpose
-  role: |
-    You are a helpful assistant agent that can:
+  role: 'You are a helpful assistant agent that can:
+
     1. Greet users with personalized messages
+
     2. Echo back messages sent to you
+
     3. Report your current status and health
-    
+
+
     Always be friendly, concise, and helpful. If you receive a request
+
     you cannot handle, politely explain your limitations.
-  
-  # REQUIRED: LLM configuration
-  # Defines which language model powers this agent
+
+    '
   llm:
-    # REQUIRED: LLM provider (openai, anthropic, google, azure, ollama, custom)
     provider: openai
-    
-    # REQUIRED: Model identifier (specific to provider)
-    # OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
-    # Anthropic: claude-3-opus-20240229, claude-3-sonnet-20240229
-    # Google: gemini-pro, gemini-pro-vision
     model: gpt-3.5-turbo
-    
-    # OPTIONAL: Temperature (0.0-2.0) - Controls randomness
-    # 0.0 = deterministic, 1.0 = balanced, 2.0 = very creative
-    # Lower values better for structured tasks, higher for creative tasks
     temperature: 0.7
-    
-    # OPTIONAL: Maximum tokens per request
-    # Limits response length. Set based on expected output size
     maxTokens: 1000
-    
-    # OPTIONAL: Top-p (nucleus sampling) - 0.0-1.0
-    # Alternative to temperature. 0.9 = consider top 90% probability mass
     topP: 0.9
-  
-  # REQUIRED: Available tools/capabilities for the agent
-  # Each tool represents a capability the agent can use
-  # Must have at least one tool
   tools:
-    # Tool 1: Greeting capability
-    - type: function
-      name: greet_user
-      description: |
-        Generate a personalized greeting message for a user.
-        Takes a user name and optional context, returns a friendly greeting.
-      # Tool-specific configuration
-      config:
-        # Example: This could reference a function, API endpoint, or MCP server
-        handler: greet_handler
-        timeout: 5
-      
-      # OPTIONAL: Authentication for tool access
-      auth:
-        type: none  # Options: bearer, oauth2, mtls, apikey, none
-    
-    # Tool 2: Echo capability
-    - type: function
-      name: echo_message
-      description: |
-        Echo back a message sent to the agent.
-        Useful for testing and demonstrating basic agent communication.
-      config:
-        handler: echo_handler
-        timeout: 2
-    
-    # Tool 3: Status reporting
-    - type: http
-      name: get_status
-      description: |
-        Get the current status and health of the agent.
-        Returns agent metadata, uptime, and capability status.
-      endpoint: http://localhost:8080/status
-      config:
-        method: GET
-        timeout: 3
-      auth:
-        type: none
-  
-  # OPTIONAL: Autonomy configuration
-  # Controls how independently the agent can operate
+  - type: function
+    name: greet_user
+    description: 'Generate a personalized greeting message for a user.
+
+      Takes a user name and optional context, returns a friendly greeting.
+
+      '
+    config:
+      handler: greet_handler
+      timeout: 5
+    auth:
+      type: none
+  - type: function
+    name: echo_message
+    description: 'Echo back a message sent to the agent.
+
+      Useful for testing and demonstrating basic agent communication.
+
+      '
+    config:
+      handler: echo_handler
+      timeout: 2
+  - type: http
+    name: get_status
+    description: 'Get the current status and health of the agent.
+
+      Returns agent metadata, uptime, and capability status.
+
+      '
+    endpoint: http://localhost:8080/status
+    config:
+      method: GET
+      timeout: 3
+    auth:
+      type: none
   autonomy:
-    # Level of autonomy: supervised, autonomous, fully_autonomous
-    # supervised = requires human approval for actions
-    # autonomous = can act independently within constraints
-    # fully_autonomous = complete independence (use with caution)
     level: supervised
-    
-    # Whether human approval is required before executing actions
     approval_required: true
-    
-    # Whitelist of permitted actions (if specified, only these are allowed)
     allowed_actions:
-      - greet_user
-      - echo_message
-      - get_status
-    
-    # Blacklist of forbidden actions
+    - greet_user
+    - echo_message
+    - get_status
     blocked_actions: []
-  
-  # OPTIONAL: Constraints and limits
   constraints:
-    # Cost constraints (prevent runaway spending)
     cost:
-      # Maximum tokens per day (prevents excessive API usage)
       maxTokensPerDay: 100000
-      
-      # Maximum tokens per request
       maxTokensPerRequest: 2000
-      
-      # Maximum cost per day (in specified currency)
-      maxCostPerDay: 10.00
-      
-      # Currency code (ISO 4217, 3-letter code)
+      maxCostPerDay: 10.0
       currency: USD
-    
-    # Performance constraints
     performance:
-      # Maximum latency in seconds
       maxLatencySeconds: 5.0
-      
-      # Maximum concurrent requests
       maxConcurrentRequests: 10
-      
-      # Request timeout in seconds
       timeoutSeconds: 30
-    
-    # Resource constraints (for Kubernetes deployments)
     resources:
-      cpu: "100m"      # 0.1 CPU cores (Kubernetes format)
-      memory: "256Mi"  # 256 megabytes (Kubernetes format)
-      # gpu: "1"       # Optional GPU requirement
-  
-  # OPTIONAL: Observability configuration
-  # Enables monitoring, tracing, and logging
+      cpu: 100m
+      memory: 256Mi
   observability:
-    # Distributed tracing (OpenTelemetry, Jaeger, Zipkin)
     tracing:
       enabled: true
-      exporter: otlp  # Options: otlp, jaeger, zipkin, custom
-      endpoint: http://localhost:4318  # OTLP collector endpoint
-    
-    # Metrics collection (Prometheus, OTLP)
+      exporter: otlp
+      endpoint: http://localhost:4318
     metrics:
       enabled: true
-      exporter: prometheus  # Options: prometheus, otlp, custom
+      exporter: prometheus
       endpoint: http://localhost:9090/metrics
-    
-    # Logging configuration
     logging:
-      level: info  # Options: debug, info, warn, error
-      format: json  # Options: json, text
-
-# ============================================================================
-# USAGE EXAMPLES
-# ============================================================================
-#
-# 1. VALIDATE THIS MANIFEST:
-#    $ ossa validate examples/getting-started/hello-world-complete.ossa.yaml
-#
-# 2. DEPLOY TO KUBERNETES (via agent-buildkit):
-#    $ buildkit agents deploy examples/getting-started/hello-world-complete.ossa.yaml
-#
-# 3. TEST LOCALLY:
-#    $ ossa validate examples/getting-started/hello-world-complete.ossa.yaml --verbose
-#
-# 4. INTEGRATE WITH MCP:
-#    This agent can be exposed via MCP (Model Context Protocol) for use
-#    with Claude Desktop, Cursor, or other MCP-compatible tools.
-#
-# 5. USE IN MULTI-AGENT WORKFLOW:
-#    This agent can be orchestrated alongside other agents using
-#    agent-buildkit's workflow engine.
-#
-# ============================================================================
-# NEXT STEPS
-# ============================================================================
-#
-# After understanding this example:
-# 1. Review examples/intermediate/ for more complex patterns
-# 2. Check examples/advanced/ for enterprise patterns
-# 3. Read the full OSSA specification at spec/v0.2.x/ossa-0.2.x.schema.json
-# 4. Explore integration examples in examples/bridges/
-# 5. See migration guides in examples/migration-guides/
-#
-# ============================================================================
-# RELATED DOCUMENTATION
-# ============================================================================
-#
-# - OSSA Specification: spec/v0.2.x/ossa-0.2.x.schema.json
-# - Schema Reference: docs/schemas/
-# - API Reference: openapi/
-# - GitHub Repository: https://github.com/blueflyio/openstandardagents
-#
-# ============================================================================
-
+      level: info
+      format: json