@bluefly/openstandardagents 0.5.0 → 0.5.3

package/examples/production/agent.yml

@@ -1,713 +0,0 @@
-# ============================================================================
-# OSSA Production Worker Agent Example
-# ============================================================================
-# Purpose: Production-ready worker agent for document analysis with NLP
-#
-# Key Concepts:
-# - Worker Agent: Executes tasks delegated by orchestrator agents
-# - Capability-Based: Registers capabilities for discovery and routing
-# - Production-Grade: Full observability, health checks, and resource limits
-# - Multi-Protocol: Exposes both OpenAPI and MCP bridges for integration
-#
-# Conformance Level: Silver
-# - Production-ready with comprehensive monitoring
-# - Health checks for dependencies (database, Redis)
-# - Structured logging with redaction
-# - Metrics and distributed tracing
-# - Performance optimization (caching, batching)
-#
-# Related Examples:
-# - examples/openapi-extensions/orchestrator-agent-api.openapi.yml (Orchestrator)
-# - examples/openapi-extensions/worker-agent-api.openapi.yml (Worker API)
-# - examples/agent-manifests/orchestrators/orchestrator-agent.yaml (Orchestrator manifest)
-#
-# Integration Pattern:
-# 1. Worker agent registers capabilities in agent-mesh
-# 2. Orchestrator discovers worker via agent-router
-# 3. Orchestrator delegates workflow step to worker
-# 4. Worker executes capability and returns result
-# 5. Orchestrator aggregates results from all workers
-#
-# OSSA Version: 1.0 (Worker profile)
-# ============================================================================
-
-# OSSA specification version - defines schema and features
-ossaVersion: "1.0"
-
-# ============================================================================
-# AGENT: Core identity, capabilities, and runtime configuration
-# ============================================================================
-agent:
-  # Unique identifier for service discovery and routing
-  # - Used by agent-router to route requests to this agent
-  # - Must be unique within the agent ecosystem
-  id: document-analyzer
-
-  # Human-readable name for UI and documentation
-  name: Document Analyzer
-
-  # Semantic version for compatibility tracking
-  # - Breaking changes: Increment major version
-  # - New capabilities: Increment minor version
-  # - Bug fixes: Increment patch version
-  version: 2.1.0
-
-  # Description for service discovery and documentation
-  description: Production document analysis agent with NLP capabilities
-
-  # Role defines the agent's purpose in multi-agent workflows
-  # - data_processing: Transforms or analyzes data
-  # - code_generation: Generates or modifies code
-  # - quality_assurance: Validates outputs
-  # - orchestration: Coordinates other agents
-  role: data_processing
-
-  # Tags enable filtering and discovery
-  # - Used by orchestrators to find agents with specific traits
-  # - Example: Find all NLP agents, all production agents, etc.
-  tags:
-    - nlp          # Natural Language Processing capability
-    - documents    # Document processing specialization
-    - analysis     # Analytical capabilities
-    - production   # Production-ready deployment
-
-  # Metadata for governance and compliance
-  metadata:
-    author: Bluefly.io    # Team or organization maintaining this agent
-    license: MIT          # License for usage and distribution
-
-  # ============================================================================
-  # RUNTIME: Kubernetes deployment configuration
-  # ============================================================================
-  runtime:
-    # Deployment type: k8s (Kubernetes), docker, serverless, etc.
-    type: k8s
-
-    # Container image with version tag
-    # - Use semantic versioning for image tags
-    # - Avoid 'latest' tag in production
-    image: ossa/document-analyzer:2.1.0
-
-    # Resource requests and limits for Kubernetes
-    resources:
-      # CPU allocation: 1000m = 1 CPU core
-      # - Request: Guaranteed allocation
-      # - Limit: Maximum allowed (set in k8s manifest)
-      cpu: "1000m"
-
-      # Memory allocation: 1Gi = 1 gibibyte
-      # - Request: Guaranteed allocation
-      # - Limit: Maximum allowed (OOM kill if exceeded)
-      memory: "1Gi"
-
-    # Health check configuration for Kubernetes liveness/readiness probes
-    health_check:
-      # HTTP health check endpoint
-      type: http
-
-      # Health check endpoint path
-      # - Should return 200 OK when healthy
-      # - Should check all critical dependencies (DB, Redis, etc.)
-      endpoint: /health
-
-      # Port for health check requests
-      port: 3000
-
-  # ============================================================================
-  # CAPABILITIES: Functions this worker agent can perform
-  # ============================================================================
-  # Capabilities are registered in agent-mesh for discovery by orchestrators
-  # Each capability defines input/output schemas and timeout constraints
-  capabilities:
-    # ------------------------------------------------------------------------
-    # Capability: analyze_document - Comprehensive NLP analysis
-    # ------------------------------------------------------------------------
-    - name: analyze_document
-      # Description used for capability matching and documentation
-      description: Comprehensive document analysis with sentiment and entities
-
-      # Input schema: JSON Schema for request validation
-      input_schema:
-        type: object
-        required: ["document"]    # Document text is required
-        properties:
-          # Document text to analyze
-          document:
-            type: string
-            description: Document text to analyze
-
-          # Optional: Include entity extraction in analysis
-          # - Named entities: People, organizations, locations, dates
-          includeEntities:
-            type: boolean
-            default: true
-
-          # Optional: Include sentiment analysis in analysis
-          # - Sentiment: Positive, negative, neutral with confidence scores
-          includeSentiment:
-            type: boolean
-            default: true
-
-      # Output schema: JSON Schema for response validation
-      output_schema:
-        type: object
-        properties:
-          # Sentiment analysis results
-          # - score: -1.0 (negative) to 1.0 (positive)
-          # - label: positive, negative, neutral
-          # - confidence: 0.0 to 1.0
-          sentiment:
-            type: object
-
-          # Named entities extracted from document
-          # - type: PERSON, ORG, GPE, DATE, etc.
-          # - text: Entity mention in document
-          # - start/end: Character offsets
-          entities:
-            type: array
-
-          # Generated summary of document (if requested)
-          summary:
-            type: string
-
-      # Maximum execution time: 300 seconds (5 minutes)
-      # - Includes NLP model inference time
-      # - Should handle large documents (up to 100KB)
-      timeout_seconds: 300
-
-    # ------------------------------------------------------------------------
-    # Capability: extract_text - Extract text from binary documents
-    # ------------------------------------------------------------------------
-    - name: extract_text
-      # Extract text from PDF, Word, images (OCR), etc.
-      description: Extract text from various document formats
-
-      input_schema:
-        type: object
-        required: ["document"]
-        properties:
-          # Binary document data (base64 encoded)
-          # - Supports: PDF, DOCX, PPTX, images (OCR)
-          document:
-            type: string
-            format: binary
-
-      output_schema:
-        type: object
-        properties:
-          # Extracted plain text from document
-          text:
-            type: string
-
-      # Shorter timeout: Text extraction is faster than analysis
-      # - 60 seconds should handle most documents
-      timeout_seconds: 60
-
-    # ------------------------------------------------------------------------
-    # Capability: summarize_document - Generate document summary
-    # ------------------------------------------------------------------------
-    - name: summarize_document
-      # Generate abstractive or extractive summary
-      description: Generate concise document summary
-
-      input_schema:
-        type: object
-        required: ["text"]
-        properties:
-          # Document text to summarize
-          text:
-            type: string
-
-          # Maximum summary length in characters
-          # - Default: 500 characters (2-3 sentences)
-          maxLength:
-            type: integer
-            default: 500
-
-      output_schema:
-        type: object
-        properties:
-          # Generated summary
-          # - Abstractive: Paraphrased summary
-          # - Extractive: Key sentences from original
-          summary:
-            type: string
-
-      # Medium timeout: Summarization is moderately expensive
-      # - 120 seconds for documents up to 50KB
-      timeout_seconds: 120
-
-    # ------------------------------------------------------------------------
-    # Capability: classify_document - Categorize document by type
-    # ------------------------------------------------------------------------
-    - name: classify_document
-      # Classify into predefined categories (e.g., invoice, contract, email)
-      description: Classify document into categories
-
-      input_schema:
-        type: object
-        required: ["text"]
-        properties:
-          # Document text to classify
-          text:
-            type: string
-
-      output_schema:
-        type: object
-        properties:
-          # Predicted category label
-          # - Examples: invoice, contract, email, report, memo
-          category:
-            type: string
-
-          # Confidence score for prediction (0.0 to 1.0)
-          # - Use threshold (e.g., 0.8) for high-confidence predictions
-          confidence:
-            type: number
-
-      # Fast timeout: Classification is quick (single model inference)
-      timeout_seconds: 60
-
-  # ============================================================================
-  # INTEGRATION: How orchestrators communicate with this worker agent
-  # ============================================================================
-  integration:
-    # Protocol: HTTP REST API
-    # - Alternatives: gRPC, WebSocket, message queue
-    protocol: http
-
-    # Endpoint configuration
-    endpoints:
-      # Base URL for all API requests
-      # - Uses Kubernetes service DNS: <service-name>:<port>
-      base_url: "http://document-analyzer:3000"
-
-      # Health check endpoint (Kubernetes liveness/readiness)
-      health: /health
-
-      # Prometheus metrics endpoint
-      metrics: /metrics
-
-      # OpenAPI specification for capabilities
-      # - Auto-generated from capability definitions
-      # - Used by clients for request/response validation
-      openapi: /api/openapi.json
-
-    # Authentication: JWT tokens
-    # - Orchestrators include JWT in Authorization header
-    # - Worker validates token signature and expiration
-    auth:
-      type: jwt
-
-# ============================================================================
-# MONITORING: Observability configuration for production operations
-# ============================================================================
-monitoring:
-  # IO-aware monitoring: Track input/output for each capability invocation
-  # - Enables debugging of request/response payloads
-  # - Supports compliance auditing and traceability
-  io_aware: true
-
-  # ============================================================================
-  # LOGS: Structured logging configuration
-  # ============================================================================
-  logs:
-    # JSON Lines format for structured logging
-    # - Each log entry is a single JSON object
-    # - Easy to parse by log aggregation tools (ELK, Loki, CloudWatch)
-    format: jsonl
-
-    # Log level: trace, debug, info, warn, error, fatal
-    # - info: Standard production level (business events)
-    # - debug: Troubleshooting (more verbose)
-    # - trace: Full request/response payloads (development only)
-    level: info
-
-    # Enable distributed tracing correlation IDs in logs
-    # - Links logs to distributed traces (Jaeger, Zipkin)
-    # - trace_id and span_id fields in every log entry
-    trace: true
-
-    # Log retention period: 30 days
-    # - Comply with data retention policies
-    # - Balance storage costs with debugging needs
-    retention: 30d
-
-    # Log outputs: Where to send logs
-    outputs:
-      # Console output for Kubernetes log collection
-      # - Kubernetes captures stdout/stderr
-      # - Forwarded to log aggregation system
-      - type: console
-
-      # File output for local debugging and backup
-      - type: file
-        config:
-          # Log file path (persistent volume in Kubernetes)
-          path: /var/log/ossa/document-analyzer.log
-
-          # Daily log rotation to prevent large files
-          rotation: daily
-
-          # Keep last 7 days of logs (7 * 24h = 168h retention)
-          max_files: 7
-
-  # ============================================================================
-  # METRICS: Prometheus metrics configuration
-  # ============================================================================
-  metrics:
-    # Enable metrics collection
-    enabled: true
-
-    # Metrics endpoint for Prometheus scraping
-    # - Kubernetes ServiceMonitor targets this endpoint
-    endpoint: /metrics
-
-    # Prometheus exposition format
-    # - Standard text-based format for Prometheus
-    format: prometheus
-
-    # Scrape interval: 60 seconds
-    # - Balance between metric granularity and overhead
-    # - Kubernetes typically scrapes every 30-60 seconds
-    interval: 60
-
-    # Custom business metrics (in addition to standard runtime metrics)
-    custom_metrics:
-      # Counter: Total documents processed
-      # - Monotonically increasing count
-      # - Labels enable filtering by document type and status
-      - name: documents_processed_total
-        type: counter
-        description: Total documents processed
-        labels: [document_type, status]
-
-      # Histogram: Document analysis duration
-      # - Distribution of processing times
-      # - Buckets define SLO boundaries (e.g., p50, p95, p99)
-      - name: analysis_duration_seconds
-        type: histogram
-        description: Document analysis duration
-        buckets: [0.1, 0.5, 1, 2, 5, 10]
-
-  # ============================================================================
-  # TRACES: Distributed tracing configuration
-  # ============================================================================
-  traces:
-    # Enable distributed tracing
-    enabled: true
-
-    # OpenTelemetry Protocol (OTLP) format
-    # - Standard protocol for traces, metrics, and logs
-    # - Compatible with Jaeger, Zipkin, Tempo, etc.
-    format: otlp
-
-    # Jaeger collector endpoint
-    # - Receives trace spans from agent
-    # - Stores traces for querying and visualization
-    endpoint: http://jaeger:4317
-
-    # Sampling configuration: Don't trace every request
-    sampling:
-      # Probabilistic sampling: Randomly sample requests
-      # - Alternatives: always_on, always_off, parent_based
-      type: probabilistic
-
-      # Sample 10% of requests
-      # - Reduces overhead while preserving statistical accuracy
-      # - Increase rate (e.g., 1.0) for debugging
-      rate: 0.1
-
-  # ============================================================================
-  # HEALTH: Health check configuration
-  # ============================================================================
-  health:
-    # Enable health checks
-    enabled: true
-
-    # Health check endpoint
-    # - Used by Kubernetes liveness and readiness probes
-    # - Should return 200 OK when healthy, 5xx when unhealthy
-    endpoint: /health
-
-    # Health check interval: 30 seconds
-    # - Kubernetes probes typically run every 10-30 seconds
-    interval: 30
-
-    # Dependency health checks
-    # - Agent is only healthy if all dependencies are reachable
-    # - Prevents routing traffic to unhealthy instances
-    checks:
-      # PostgreSQL database health
-      - name: database
-        type: tcp          # TCP connection test
-        config:
-          port: 5432       # PostgreSQL default port
-          timeout: 5       # Fail after 5 seconds
-
-      # Redis cache health
-      - name: redis
-        type: tcp          # TCP connection test
-        config:
-          port: 6379       # Redis default port
-          timeout: 5       # Fail after 5 seconds
-
-  # ============================================================================
-  # REDACTION: PII/sensitive data redaction in logs and traces
-  # ============================================================================
-  redaction:
-    # Enable automatic redaction of sensitive data
-    # - Prevents PII leaks in logs, traces, and metrics
-    # - Required for GDPR, HIPAA, PCI-DSS compliance
-    enabled: true
-
-    # Regex patterns for sensitive data detection
-    patterns:
-      # Credit card numbers (Luhn algorithm format)
-      # - Matches: 4532 1234 5678 9010, GB12 3456 7890 1234 5678
-      - pattern: "\\b[A-Z]{2}\\d{2}\\s?\\d{4}\\s?\\d{4}\\s?\\d{4}\\s?\\d{4}\\b"
-        name: credit_card
-
-      # US Social Security Numbers (SSN)
-      # - Matches: 123-45-6789
-      - pattern: "\\b\\d{3}-\\d{2}-\\d{4}\\b"
-        name: ssn
-
-      # Email addresses
-      # - Matches: user@example.com
-      - pattern: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"
-        name: email
-
-    # Replacement text for redacted data
-    # - All matches replaced with this string
-    # - Preserves log structure while hiding sensitive data
-    replacement: '[REDACTED]'
-
-# ============================================================================
-# PERFORMANCE: Optimization strategies for cost and latency
-# ============================================================================
-performance:
-  # ============================================================================
-  # TOKEN OPTIMIZATION: Reduce LLM token usage (if using LLM for NLP)
-  # ============================================================================
-  token_optimization:
-    # Enable token optimization strategies
-    enabled: true
-
-    # Optimization strategies
-    strategies:
-      # Sliding window: Process long documents in chunks
-      # - Prevents exceeding context window limits
-      # - Maintains context across chunks via overlap
-      - type: sliding_window
-        config:
-          # Window size: 4096 tokens (~16KB text)
-          # - Fits within most LLM context windows
-          # - Allows for overlap between windows
-          window_size: 4096
-
-    # Maximum context length: 32000 tokens
-    # - Total context available for processing
-    # - Includes prompt, document, and response
-    max_context: 32000
-
-  # ============================================================================
-  # CACHE: Multi-layer caching for repeated requests
-  # ============================================================================
-  cache:
-    # Enable caching for performance and cost savings
-    # - Reduces redundant NLP processing
-    # - Lowers LLM API costs
-    enabled: true
-
-    # Cache layers: L1 (memory) -> L2 (Redis)
-    layers:
-      # L1 Cache: In-memory cache (fastest, limited capacity)
-      - name: memory_cache
-        type: memory
-        # Cache size: 100MB
-        # - Stores ~10,000 document analysis results
-        size: 100MB
-        # TTL: 300 seconds (5 minutes)
-        # - Short TTL for frequently accessed data
-        # - Falls through to L2 if expired
-        ttl: 300
-
-      # L2 Cache: Redis cache (slower, larger capacity)
-      - name: redis_cache
-        type: redis
-        # TTL: 3600 seconds (1 hour)
-        # - Longer TTL for less frequently accessed data
-        # - Persists across agent restarts
-        ttl: 3600
-        config:
-          # Redis connection details
-          host: redis
-          port: 6379
-          db: 0
-
-    # Cache key strategy: semantic
-    # - Keys based on semantic similarity of input
-    # - Similar documents share cache entries
-    # - Alternatives: exact (exact text match), hash (SHA-256)
-    key_strategy: semantic
-
-  # ============================================================================
-  # BATCHING: Batch multiple requests for throughput
-  # ============================================================================
-  batching:
-    # Enable request batching
-    # - Processes multiple documents in a single batch
-    # - Improves GPU utilization for NLP models
-    enabled: true
-
-    # Dynamic batching: Adjust batch size based on load
-    # - Small batches under light load (low latency)
-    # - Large batches under heavy load (high throughput)
-    dynamic: true
-
-    # Maximum batch size: 32 documents
-    # - Balance between throughput and latency
-    # - Larger batches increase latency but improve throughput
-    max_batch_size: 32
-
-    # Batch timeout: 100ms
-    # - Maximum time to wait for batch to fill
-    # - Prevents indefinite waiting under light load
-    timeout_ms: 100
-
-# ============================================================================
-# BRIDGE: Protocol bridges for multi-protocol support
-# ============================================================================
-bridge:
-  # ============================================================================
-  # OPENAPI BRIDGE: REST API for standard HTTP clients
-  # ============================================================================
-  openapi:
-    # Enable OpenAPI bridge
-    # - Exposes capabilities as REST endpoints
-    # - Auto-generates API from capability definitions
-    enabled: true
-
-    # OpenAPI specification file
-    # - Can be manually authored or auto-generated
-    # - Used by clients for request/response validation
-    spec_url: ./openapi.yaml
-
-    # Auto-generate OpenAPI spec from capabilities
-    # - false: Use manually authored spec (this example)
-    # - true: Generate spec from capability definitions
-    auto_generate: false
-
-  # ============================================================================
-  # MCP BRIDGE: Model Context Protocol for LLM integration
-  # ============================================================================
-  # MCP enables LLMs to invoke agent capabilities as tools
-  # - LLMs can call analyzeDocument, extractEntities, etc.
-  # - Agent capabilities become LLM function calls
-  mcp:
-    # Enable MCP bridge
-    # - Exposes capabilities as MCP tools
-    # - Allows LLMs to orchestrate this agent
-    enabled: true
-
-    # Server type: stdio (standard input/output)
-    # - Communication via stdin/stdout
-    # - Alternative: http (REST API for MCP)
-    server_type: stdio
-
-    # MCP tools: Capabilities exposed to LLMs
-    tools:
-      # MCP Tool: analyzeDocument
-      # - Maps to capability: analyze_document
-      # - Simplified interface for LLM consumption
-      - name: analyzeDocument
-        description: Analyze document with NLP
-        input_schema:
-          type: object
-          required: [document]
-          properties:
-            # Document text to analyze
-            document:
-              type: string
-            # Optional analysis options
-            options:
-              type: object
-        # Capability this tool invokes
-        # - Maps MCP tool call to OSSA capability
-        capability: sentiment_analysis
-
-      # MCP Tool: extractEntities
-      # - Maps to capability: analyze_document (with entity extraction)
-      # - Focused interface for entity extraction only
-      - name: extractEntities
-        description: Extract named entities
-        input_schema:
-          type: object
-          required: [text]
-          properties:
-            # Text to extract entities from
-            text:
-              type: string
-        # Capability this tool invokes
-        capability: entity_recognition
-
-# ============================================================================
-# END OF MANIFEST
-# ============================================================================
-# Deployment Instructions:
-#
-# 1. Build container image:
-#    docker build -t ossa/document-analyzer:2.1.0 .
-#
-# 2. Push to registry:
-#    docker push ossa/document-analyzer:2.1.0
-#
-# 3. Deploy to Kubernetes:
-#    kubectl apply -f k8s/deployment.yaml
-#    kubectl apply -f k8s/service.yaml
-#
-# 4. Register with agent-mesh:
-#    curl -X POST http://agent-mesh/api/v1/agents \
-#      -H "Content-Type: application/json" \
-#      -d @agent.yml
-#
-# 5. Verify registration:
-#    curl http://agent-mesh/api/v1/agents/document-analyzer
-#
-# 6. Test capability:
-#    curl -X POST http://document-analyzer:3000/api/v1/analyze \
-#      -H "Content-Type: application/json" \
-#      -d '{"document": "This is a test document."}'
-#
-# Monitoring:
-# - Logs: kubectl logs -f deployment/document-analyzer
-# - Metrics: http://document-analyzer:3000/metrics
-# - Traces: https://jaeger.example.com/search?service=document-analyzer
-# - Health: curl http://document-analyzer:3000/health
-#
-# Related Documentation:
-# - OSSA Spec: https://ossa.ai/spec
-# - Worker Agent Pattern: https://ossa.ai/docs/worker-agents
-# - Capability Registration: https://ossa.ai/docs/capabilities
-# - MCP Integration: https://modelcontextprotocol.io
-#
-# Multi-Agent Workflow:
-# 1. Orchestrator receives workflow request
-# 2. Uses agent-router to discover this worker (by capability)
-# 3. Delegates document analysis task to this worker
-# 4. Worker processes document and returns results
-# 5. Orchestrator aggregates results with other workers
-#
-# Example Workflow Step:
-# {
-#   "stepId": "analyze-sentiment",
-#   "agentType": "worker",
-#   "capability": "sentiment_analysis",
-#   "input": {
-#     "document": "Customer feedback text...",
-#     "includeEntities": true,
-#     "includeSentiment": true
-#   }
-# }
-# ============================================================================