@bluefly/openstandardagents 0.3.2 → 0.3.3

package/examples/drupal/gitlab-ml-recommender.ossa.yaml

@@ -1,64 +1,8 @@
-# ============================================================================
-# OSSA Drupal Integration Example: GitLab ML Recommendation Engine
-# ============================================================================
-#
-# PURPOSE:
-#   Demonstrates OSSA integration with Drupal's AI Agent Orchestra module.
-#   Showcases a real-world RAG (Retrieval-Augmented Generation) pipeline for
-#   customer success recommendations using semantic search and LLM generation.
-#
-# KEY FEATURES:
-#   - RAG pipeline with Qdrant vector database for semantic search
-#   - GPT-4 powered recommendation generation
-#   - TimescaleDB aggregation for customer health metrics
-#   - Agent-to-Agent (A2A) communication via JSON-RPC
-#   - Event-driven architecture with Redis pub/sub
-#   - Enterprise-grade monitoring, caching, and compliance
-#
-# ARCHITECTURE:
-#   Drupal Module (ai_agent_orchestra)
-#     ↓ (service call)
-#   GitLabMlRecommendationsService
-#     ↓ (semantic search)
-#   Qdrant Vector DB
-#     ↓ (context retrieval)
-#   GPT-4 via Agent Router
-#     → AI Recommendations
-#
-# USE CASE:
-#   Customer Success teams get AI-powered, data-driven recommendations for
-#   proactive customer engagement based on historical successful interventions
-#   and current customer health signals.
-#
-# RELATED DOCUMENTATION:
-#   - OSSA Drupal Extensions: spec/OSSA_Drupal_Extensions.md
-#   - RAG Pipeline Guide: docs/patterns/rag-patterns.md
-#   - A2A Protocol: spec/OSSA_A2A_Protocol.md
-# ============================================================================
-
-# OSSA specification version - defines which features are available
-apiVersion: ossa/v0.3.2
-ossaVersion: "1.0"
-
-# Agent metadata and configuration
-agent:
-  # Unique identifier for this agent (must be DNS-compatible: lowercase, hyphens)
-  id: gitlab-ml-recommender
-
-  # Human-readable name displayed in UIs
-  name: "GitLab ML Recommendation Engine"
-
-  # Semantic version for agent deployment tracking
-  version: "1.0.0"
-
-  # Agent role determines lifecycle and communication patterns:
-  # - "integration": Long-running service that connects external systems
-  # - "chat": Interactive conversational agent
-  # - "worker": Task-based processor (fire-and-forget or queued)
-  # - "orchestrator": Coordinates multiple agents
-  role: "integration"
-
-  # Detailed agent description (supports Markdown for rich documentation)
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: gitlab-ml-recommender
+  version: 1.0.0
   description: |
     AI-powered customer success recommendation agent using RAG (Retrieval-Augmented Generation).
 
@@ -71,540 +15,55 @@ agent:
     - GitLabMlRecommendationsService (RAG generation)
     - GitLabMlDashboardService (health metrics)
     - QdrantVectorService (semantic search)
-
-  # Runtime configuration - defines how the agent is deployed and executed
-  runtime:
-    # Execution environment type:
-    # - "docker": Containerized deployment with image specification
-    # - "serverless": FaaS deployment (AWS Lambda, Google Cloud Functions, etc.)
-    # - "kubernetes": Native k8s deployment with CRD
-    # - "local": Direct process execution (dev/testing only)
-    type: "docker"
-
-    # Docker image reference (registry/name:tag)
-    # Should follow semantic versioning and be immutable (no "latest" tag)
-    image: "llm-platform/ml-recommender:1.0.0"
-
-    # Language and dependency requirements (enforced at build time)
-    requirements:
-      # PHP version constraint (Drupal requirement)
-      php: ">=8.1"
-
-      # Node.js version for build tools and frontend assets
-      node: ">=20.0.0"
-
-      # Composer packages required for Drupal integration
-      packages:
-        - "guzzlehttp/guzzle"      # HTTP client for external API calls
-        - "symfony/http-client"     # Alternative HTTP client with retry logic
-
-    # Resource limits (Kubernetes-style requests/limits)
-    # These prevent resource exhaustion and enable autoscaling decisions
-    resources:
-      cpu: "1000m"      # 1 CPU core (1000 millicores)
-      memory: "2Gi"     # 2 gigabytes RAM
-
-    # Health check configuration for container orchestration
-    # Used by Kubernetes liveness/readiness probes and load balancers
-    health_check:
-      type: "http"          # HTTP GET request for health status
-      endpoint: "/health"   # Health check endpoint path
-      port: 8080            # Container port to check
-
-  # Capabilities define what the agent can do (contract-first design)
-  # Each capability is a discrete, testable unit of functionality with:
-  # - Type-safe input/output schemas (JSON Schema)
-  # - Usage examples for documentation and testing
-  # - Timeout and retry policies for reliability
-  capabilities:
-    # ========================================================================
-    # Capability 1: Generate Recommendations (RAG Pipeline)
-    # ========================================================================
-    # This is the core capability demonstrating OSSA's RAG pattern:
-    # 1. Semantic search in Qdrant for similar successful customer cases
-    # 2. Context injection into GPT-4 prompt
-    # 3. AI-generated recommendations with rationale
-    # 4. Priority ranking based on customer health signals
-    #
-    # FLOW:
-    #   Drupal Request → Service Layer → Qdrant Search → GPT-4 Generation
-    #   → Priority Ranking → Structured Response
-    # ========================================================================
-    - name: generate_recommendations
-
-      # Capability description (appears in API docs and UI)
-      description: "Generate AI recommendations using RAG pipeline (Qdrant semantic search + GPT-4)"
-
-      # Input schema using JSON Schema (OpenAPI-compatible)
-      # This defines the contract for calling this capability
-      input_schema:
-        type: object
-
-        # Required fields - validation will fail if missing
-        required: [customer_id]
-
-        properties:
-          # Customer UUID from GitLab (primary identifier)
-          customer_id:
-            type: string
-            format: uuid  # Validates UUID format (RFC 4122)
-            description: "Customer UUID from GitLab"
-
-          # Context filter for targeted recommendations
-          # Different contexts use different embedding collections
-          context:
-            type: string
-            enum: [health, churn, engagement, technical]
-            description: "Recommendation context filter"
-
-          # Result limit for controlling response size and cost
-          limit:
-            type: integer
-            default: 10       # Default if not provided
-            minimum: 1        # At least 1 recommendation
-            maximum: 50       # Max to prevent token exhaustion
-            description: "Maximum number of recommendations"
-
-
-      # Output schema defines the structure of the response
-      # This ensures consistent data contracts across all agents
-      output_schema:
-        type: object
-
-        # Required response fields (must always be present)
-        required: [customerId, recommendations, generatedAt]
-
-        properties:
-          # Echo back the customer ID for request correlation
-          customerId:
-            type: string
-            format: uuid
-
-          # Array of AI-generated recommendations
-          recommendations:
-            type: array
-            items:
-              type: object
-
-              # Each recommendation must have these core fields
-              required: [id, title, priority, category]
-
-              properties:
-                # Unique recommendation ID for tracking and analytics
-                id:
-                  type: string
-                  format: uuid
-
-                # Short, actionable title (shown in UI cards)
-                title:
-                  type: string
-                  maxLength: 255  # Database column constraint
-
-                # Detailed explanation of the recommendation
-                description:
-                  type: string
-
-                # Priority level for sorting and alerting
-                priority:
-                  type: string
-                  enum: [critical, high, medium, low]
-
-                # Recommendation category for filtering and routing
-                category:
-                  type: string
-                  enum: [engagement, technical, health, success]
-
-                # Concrete action steps (Drupal renders as checklist)
-                actionItems:
-                  type: array
-                  items:
-                    type: string
-
-                # AI-generated rationale explaining "why" this recommendation
-                # This is the key value from RAG - evidence from similar cases
-                rationale:
-                  type: string
-
-                # References to similar customer cases from vector search
-                # Provides transparency and builds trust in AI recommendations
-                similarCases:
-                  type: array
-                  items:
-                    type: object
-
-          # ISO 8601 timestamp for audit trail
-          generatedAt:
-            type: string
-            format: date-time
-
-
-      # Examples for documentation, testing, and contract validation
-      # Used by OSSA validators and API documentation generators
-      examples:
-        - name: "Health context recommendations"
-          input:
-            customer_id: "123e4567-e89b-12d3-a456-426614174000"
-            context: "health"
-            limit: 5
-          output:
-            customerId: "123e4567-e89b-12d3-a456-426614174000"
-            recommendations:
-              - id: "rec-001"
-                title: "Schedule health check meeting"
-                description: "Conduct comprehensive health review with technical team"
-                priority: "high"
-                category: "engagement"
-                actionItems:
-                  - "Send meeting invitation for next week"
-                  - "Prepare health check questionnaire"
-                  - "Review usage metrics before meeting"
-                rationale: "Early issue identification strengthens customer relationships"
-            generatedAt: "2025-10-24T12:00:00Z"
-
-      # Timeout prevents hung requests and enables circuit breaker patterns
-      timeout_seconds: 30
-
-      # Retry policy for transient failures (network issues, rate limits)
-      retry_policy:
-        max_attempts: 3           # Total attempts (initial + 2 retries)
-        backoff: "exponential"    # 1s, 2s, 4s, 8s... (prevents thundering herd)
-
-    # ========================================================================
-    # Capability 2: Get Dashboard Overview
-    # ========================================================================
-    # Provides aggregated customer health metrics from TimescaleDB.
-    # This is a read-only, fast query capability for dashboard UIs.
-    # ========================================================================
-    - name: get_dashboard_overview
-
-      description: "Retrieve customer health dashboard data aggregated from TimescaleDB"
-
-
-      # Minimal input - just a time range selector
-      input_schema:
-        type: object
-        required: [time_range]
-        properties:
-          # Time range for metric aggregation (TimescaleDB time bucket)
-          time_range:
-            type: string
-            enum: ["24h", "7d", "30d", "90d"]
-            description: "Time range for dashboard data"
-
-      # Dashboard metrics output (all pre-aggregated in TimescaleDB)
-      output_schema:
-        type: object
-        required: [totalCustomers, healthDistribution, churnRisks]
-        properties:
-          totalCustomers:
-            type: integer
-          healthDistribution:
-            type: object
-            properties:
-              healthy:
-                type: integer
-              warning:
-                type: integer
-              critical:
-                type: integer
-          churnRisks:
-            type: object
-            properties:
-              low:
-                type: integer
-              medium:
-                type: integer
-              high:
-                type: integer
-              critical:
-                type: integer
-          activeAlerts:
-            type: integer
-          recommendations:
-            type: integer
-          trends:
-            type: object
-            properties:
-              healthChange:
-                type: number
-              churnChange:
-                type: number
-              engagementChange:
-                type: number
-
-
-      # Fast timeout for dashboard queries (should be cached)
-      timeout_seconds: 10
-
-    # ========================================================================
-    # Capability 3: Get Active Alerts
-    # ========================================================================
-    # Returns active health alerts for customer success team triage.
-    # Supports filtering by severity and status for alert management workflows.
-    # ========================================================================
-    - name: get_active_alerts
-
-      description: "Retrieve active customer health alerts"
-      
-      input_schema:
-        type: object
-        properties:
-          severity:
-            type: string
-            enum: [critical, high, medium, low]
-          status:
-            type: string
-            enum: [active, acknowledged, resolved]
-            default: "active"
-      
-      output_schema:
-        type: object
-        required: [alerts, total]
-        properties:
-          alerts:
-            type: array
-            items:
-              type: object
-              properties:
-                id:
-                  type: string
-                customerId:
-                  type: string
-                customerName:
-                  type: string
-                severity:
-                  type: string
-                type:
-                  type: string
-                message:
-                  type: string
-                status:
-                  type: string
-                createdAt:
-                  type: string
-                  format: date-time
-          total:
-            type: integer
-
-  # ========================================================================
-  # LLM Configuration
-  # ========================================================================
-  # Defines the language model used for generation tasks.
-  # For RAG pipelines, choose models with good reasoning and context handling.
-  # ========================================================================
+  labels:
+    ossa-version: v0.3.3
+  annotations:
+    ossa.io/migration: legacy-v1.0-to-ossa/v0.3.3
+    ossa.io/migrated-date: 2026-01-10
+spec:
+  role: integration
+  taxonomy:
+    domain: data
+    subdomain: general
+    capability: general
   llm:
-    # Provider name (openai, anthropic, azure-openai, etc.)
-    provider: "openai"
-
-    # Model identifier - GPT-4 for high-quality reasoning over retrieved context
-    model: "gpt-4"
-
-    # Temperature controls randomness (0.0=deterministic, 1.0=creative)
-    # 0.7 balances consistency with natural variation
+    provider: openai
+    model: gpt-4
     temperature: 0.7
-
-    # Maximum tokens per generation (controls cost and latency)
     maxTokens: 2000
-
-  # ========================================================================
-  # Tools Configuration (MCP and HTTP endpoints)
-  # ========================================================================
-  # Defines external tools the agent can invoke during execution.
-  # MCP (Model Context Protocol) provides standardized tool interfaces.
-  # ========================================================================
   tools:
-    # Qdrant vector database for semantic search (RAG retrieval step)
-    - type: "mcp"
-      server: "qdrant-mcp"              # MCP server name (from config)
-      namespace: "default"               # Kubernetes namespace
-      capabilities:
-        - semantic_search                # Find similar customer cases
-        - vector_retrieval               # Fetch embeddings by ID
-        - get_point                      # Get specific vector point
-        - search_points                  # Batch vector search
-
-    # Agent Router for LLM and embedding generation
-    - type: "http"
-      server: "agent-router"
-      endpoint: "http://agent-router:4000"
-      capabilities:
-        - llm_generation                 # GPT-4 text generation
-        - embedding_generation           # text-embedding-ada-002
-
-  # ========================================================================
-  # Communication Protocols
-  # ========================================================================
-  # Defines how external systems can interact with this agent.
-  # Multiple protocols enable different integration patterns.
-  # ========================================================================
-  protocols:
-    # RESTful HTTP API for traditional request/response (most common)
-    - type: "http"
-      version: "1.1"
-      endpoint: "/api/v1/recommendations"
-
-    # Server-Sent Events for real-time streaming (dashboards, live updates)
-    - type: "sse"
-      version: "1.0"
-      endpoint: "/api/v1/stream"
-
-    # JSON-RPC for agent-to-agent communication (A2A protocol)
-    - type: "json-rpc"
-      version: "2.0"
-      endpoint: "/api/v1/rpc"
-
-  # ========================================================================
-  # Compliance and Governance
-  # ========================================================================
-  # Defines regulatory frameworks and data handling requirements.
-  # Used for audit trails, data retention, and access control.
-  # ========================================================================
-  compliance:
-    # Regulatory frameworks this agent complies with
-    frameworks: ["SOC2", "HIPAA"]
-
-    # Data sensitivity level (public, internal, confidential, restricted)
-    dataClassification: "confidential"
-
-    # Data retention policy for audit and compliance
-    retentionPolicy: "7years"
-
-# ============================================================================
-# OSSA Drupal Extensions
-# ============================================================================
-# Drupal-specific configuration for integration with ai_agent_orchestra module.
-# This section is OSSA's extension mechanism for framework-specific features.
-# ============================================================================
-extensions:
-  drupal:
-    # Drupal module that implements this agent
-    module: "ai_agent_orchestra"
-
-    # Drupal service ID for dependency injection
-    # Registered in ai_agent_orchestra.services.yml
-    service: "ai_agent_orchestra.gitlab_ml_recommendations"
-
-    # Drupal module dependencies (must be enabled)
-    dependencies:
-      - "ai_agents"                  # Core AI agent framework
-      - "ai_provider_langchain"      # LangChain integration
-      - "ai_provider_openai"         # OpenAI provider
-
-    # Database tables created by this agent's schema
-    database:
-      tables:
-        - "gitlab_ml_metrics"           # Customer health metrics (TimescaleDB)
-        - "gitlab_ml_alerts"            # Active health alerts
-        - "gitlab_ml_recommendations"   # Generated recommendations
-      schema_version: "1.0.0"           # For schema migrations
-
-    # ======================================================================
-    # RAG Pipeline Configuration
-    # ======================================================================
-    # Retrieval-Augmented Generation settings for semantic search and LLM.
-    # This is the core of the recommendation engine.
-    # ======================================================================
-    rag_pipeline:
-      vector_db: "qdrant"                              # Vector database type
-      collection: "gitlab_customer_embeddings"         # Qdrant collection name
-      embedding_model: "text-embedding-ada-002"        # OpenAI embedding model
-      similarity_limit: 5                              # Top-K results from search
-      similarity_threshold: 0.7                        # Minimum cosine similarity
-      llm_service: "http://agent-router:4000"          # LLM generation endpoint
-
-    # ======================================================================
-    # Observability Configuration (OpenTelemetry)
-    # ======================================================================
-    # Distributed tracing, metrics, and structured logging for production.
-    # ======================================================================
-    monitoring:
-      metrics: true           # Prometheus metrics
-      tracing: true           # OpenTelemetry traces
-      logging: true           # Structured JSON logs
-      opentelemetry:
-        endpoint: "http://agent-tracer:4318"     # OTLP collector endpoint
-        service_name: "gitlab-ml-recommender"    # Service identifier in traces
-        headers:
-          "x-service-version": "1.0.0"           # Custom trace metadata
-
-    # ======================================================================
-    # Drupal Cache Integration
-    # ======================================================================
-    # Caches recommendation results to reduce LLM costs and latency.
-    # ======================================================================
-    caching:
-      enabled: true
-      backend: "redis"        # Drupal cache backend (redis, database, memcache)
-      ttl: 3600               # Cache TTL in seconds (1 hour)
-      tags:                   # Cache tags for invalidation
-        - "gitlab_ml"
-        - "recommendations"
-
-    # Drupal permissions required to use this agent
-    permissions:
-      - "administer ai agents"       # Full agent management
-      - "execute ai agents"           # Execute agent capabilities
-      - "view ai agent results"       # View recommendation history
-
-    # ======================================================================
-    # Agent-to-Agent (A2A) Communication
-    # ======================================================================
-    # Enables this agent to call other agents for compliance checks,
-    # cost optimization, and orchestration workflows.
-    # ======================================================================
-    a2a_config:
-      enabled: true
-      protocol: "json-rpc"              # JSON-RPC 2.0 for A2A calls
-      endpoints:
-        # Compliance validator ensures recommendations meet policies
-        - "http://compliance-validator:8080/a2a"
-        # Cost optimizer prevents budget overruns
-        - "http://cost-optimizer:8080/a2a"
-      authentication:
-        type: "bearer"                  # Bearer token authentication
-        secretRef:                      # Kubernetes secret reference
-          name: "drupal-a2a-credentials"
-          key: "bearer-token"
-
-    # ======================================================================
-    # Event Bus Integration (Redis Pub/Sub)
-    # ======================================================================
-    # Publishes events for real-time dashboards and workflow automation.
-    # ======================================================================
-    event_bus:
-      enabled: true
-      # Event topics this agent publishes to
-      topics:
-        - "customer.health.changed"      # Health score updates
-        - "recommendations.generated"    # New recommendations available
-        - "alerts.created"               # New health alerts
-        - "metrics.updated"              # Metric aggregation complete
-      redis:
-        host: "redis://buildkit-redis:16379"
-        db: 0
-
-# ============================================================================
-# End of OSSA Drupal Integration Example
-# ============================================================================
-#
-# VALIDATION:
-#   ossa validate examples/drupal/gitlab-ml-recommender.ossa.yaml
-#
-# DEPLOYMENT:
-#   1. Enable required Drupal modules: drush en ai_agent_orchestra
-#   2. Import agent manifest: drush ossa:import gitlab-ml-recommender.ossa.yaml
-#   3. Clear Drupal cache: drush cr
-#   4. Test capabilities: drush ossa:test gitlab-ml-recommender
-#
-# INTEGRATION POINTS:
-#   - Drupal Service: ai_agent_orchestra.gitlab_ml_recommendations
-#   - Database Tables: gitlab_ml_* (see schema in module)
-#   - Cache Tags: gitlab_ml, recommendations
-#   - Permissions: administer/execute/view ai agents
-#   - Events: customer.health.changed, recommendations.generated
-#
-# RELATED EXAMPLES:
-#   - examples/bridges/aiflow-bridge-example.yml (social agent bridge)
-#   - examples/openapi-extensions/worker-agent-api.openapi.yml (OpenAPI)
-#   - spec/OSSA_Drupal_Extensions.md (full Drupal spec)
-# ============================================================================
+    - type: mcp
+      name: generate_recommendations
+      server: gitlab-ml-recommender
+    - type: mcp
+      name: get_dashboard_overview
+      server: gitlab-ml-recommender
+    - type: mcp
+      name: get_active_alerts
+      server: gitlab-ml-recommender
+  extensions:
+    buildkit:
+      deployment:
+        replicas:
+          min: 1
+          max: 4
+      container:
+        image: llm-platform/ml-recommender:1.0.0
+        runtime: docker
+        resources: &a1
+          cpu: 1000m
+          memory: 2Gi
+    runtime:
+      type: docker
+      image: llm-platform/ml-recommender:1.0.0
+      requirements:
+        php: ">=8.1"
+        node: ">=20.0.0"
+        packages:
+          - guzzlehttp/guzzle
+          - symfony/http-client
+      resources: *a1
+      health_check:
+        type: http
+        endpoint: /health
+        port: 8080

package/examples/extensions/agents-md-advanced.yml

@@ -1,7 +1,7 @@
 # OSSA agents.md Extension - Advanced Example
 # Demonstrates advanced features including Cursor integration and custom sections
 
-apiVersion: ossa/v0.3.2
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: fullstack-dev-agent

package/examples/extensions/agents-md-basic.yml

@@ -1,7 +1,7 @@
 # OSSA agents.md Extension - Basic Example
 # Demonstrates basic agents.md generation from OSSA manifest
 
-apiVersion: ossa/v0.3.2
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: code-review-agent

package/examples/extensions/agents-md-sync.yml

@@ -1,7 +1,7 @@
 # OSSA agents.md Extension - Sync Example
 # Demonstrates automatic synchronization configuration
 
-apiVersion: ossa/v0.3.2
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: docs-agent