@bluefly/openstandardagents 0.3.5 → 0.4.0

package/examples/validation/error-codes-demo.ts

@@ -0,0 +1,254 @@
+/**
+ * OSSA Error Code Catalog - Demo
+ *
+ * Demonstrates how to use error codes for validation and debugging
+ */
+
+import {
+  EnhancedOSSAValidator,
+  OSSAErrorCode,
+  getErrorDetails,
+  searchErrorsByTag,
+  searchErrorsBySeverity,
+} from '../../src/validation';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+// Example 1: Validate with error codes
+function validateWithErrorCodes() {
+  console.log('=== Example 1: Validate with Error Codes ===\n');
+
+  const invalidManifest = {
+    kind: 'Agent', // Missing apiVersion (OSSA-001)
+    metadata: {
+      name: 'My_Agent', // Invalid DNS format (OSSA-800)
+      decentralized_identity: {
+        did: 'did:key:abc123', // Wrong DID method (OSSA-100)
+      },
+    },
+    // Missing spec (OSSA-005)
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(invalidManifest);
+
+  console.log('Valid:', result.valid);
+  console.log('Total Issues:', result.report.summary.total);
+  console.log('Errors:', result.report.summary.errorCount);
+  console.log('\nFormatted Output:\n');
+  console.log(result.formatted.text);
+  console.log('\n');
+}
+
+// Example 2: Handle specific error codes
+function handleSpecificErrors() {
+  console.log('=== Example 2: Handle Specific Errors ===\n');
+
+  const manifest = {
+    apiVersion: 'ossa/v0.3.6',
+    kind: 'Agent',
+    metadata: {
+      name: 'security-scanner',
+      decentralized_identity: {
+        did: 'did:ossa:INVALID_UPPERCASE', // Invalid (uppercase)
+      },
+      genetics: {
+        generation: 1,
+        // Missing parent_dids (OSSA-201)
+      },
+    },
+    spec: {
+      type: 'analyzer',
+    },
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(manifest);
+
+  if (!result.valid) {
+    result.report.errors.forEach((error) => {
+      console.log(`Error Code: ${error.code}`);
+      console.log(`Path: ${error.path}`);
+      console.log(`Message: ${error.message}`);
+
+      // Handle specific errors
+      switch (error.code) {
+        case OSSAErrorCode.OSSA_100:
+          console.log('🔧 Fix: Use lowercase in DID');
+          console.log('   did: "did:ossa:invalid_uppercase" → did: "did:ossa:invaliduppercase"');
+          break;
+        case OSSAErrorCode.OSSA_201:
+          console.log('🔧 Fix: Add parent DIDs for generation 1');
+          console.log('   Add: "parent_dids": ["did:ossa:parent1", "did:ossa:parent2"]');
+          break;
+        default:
+          console.log(`🔧 Fix: ${error.remediation}`);
+      }
+
+      console.log(`📚 Docs: ${error.docsUrl}`);
+      console.log('---\n');
+    });
+  }
+}
+
+// Example 3: Search and filter errors
+function searchAndFilter() {
+  console.log('=== Example 3: Search and Filter Errors ===\n');
+
+  // Find all DID-related errors
+  const didErrors = searchErrorsByTag('did');
+  console.log(`DID-related errors: ${didErrors.length}`);
+  didErrors.forEach((error) => {
+    console.log(`  - ${error.code}: ${error.message}`);
+  });
+  console.log('');
+
+  // Find all critical errors
+  const criticalErrors = searchErrorsBySeverity('error');
+  console.log(`Critical errors in catalog: ${criticalErrors.length}`);
+  console.log('');
+
+  // Find genetics errors
+  const geneticsErrors = searchErrorsByTag('genetics');
+  console.log(`Genetics errors: ${geneticsErrors.length}`);
+  geneticsErrors.slice(0, 5).forEach((error) => {
+    console.log(`  - ${error.code}: ${error.message}`);
+  });
+  console.log('');
+}
+
+// Example 4: Get error details
+function getErrorInfo() {
+  console.log('=== Example 4: Get Error Details ===\n');
+
+  const details = getErrorDetails(OSSAErrorCode.OSSA_001);
+
+  console.log(`Code: ${details!.code}`);
+  console.log(`Severity: ${details!.severity}`);
+  console.log(`Message: ${details!.message}`);
+  console.log(`Remediation: ${details!.remediation}`);
+  console.log(`Docs: ${details!.docsUrl}`);
+  console.log(`Tags: ${details!.tags?.join(', ')}`);
+
+  if (details!.examples && details!.examples.length > 0) {
+    console.log('\nExamples:');
+    details!.examples.forEach((example, i) => {
+      console.log(`\n  Example ${i + 1}: ${example.title}`);
+      console.log(`  Invalid: ${example.invalid}`);
+      console.log(`  Valid: ${example.valid}`);
+      console.log(`  Why: ${example.explanation}`);
+    });
+  }
+  console.log('');
+}
+
+// Example 5: Export multiple formats
+function exportFormats() {
+  console.log('=== Example 5: Export Multiple Formats ===\n');
+
+  const manifest = {
+    apiVersion: 'ossa/v0.3.6',
+    kind: 'Agent',
+    metadata: {
+      name: 'test-agent',
+    },
+    // Missing spec
+  };
+
+  const validator = new EnhancedOSSAValidator();
+  const result = validator.validate(manifest);
+
+  // Export JSON
+  const jsonPath = join(__dirname, 'validation-report.json');
+  writeFileSync(jsonPath, result.formatted.json);
+  console.log(`✅ Exported JSON: ${jsonPath}`);
+
+  // Export Markdown
+  const mdPath = join(__dirname, 'validation-report.md');
+  writeFileSync(mdPath, result.formatted.markdown);
+  console.log(`✅ Exported Markdown: ${mdPath}`);
+
+  // Export HTML
+  const htmlPath = join(__dirname, 'validation-report.html');
+  writeFileSync(htmlPath, result.formatted.html);
+  console.log(`✅ Exported HTML: ${htmlPath}`);
+
+  console.log('\n');
+}
+
+// Example 6: Validate file
+function validateFile() {
+  console.log('=== Example 6: Validate File ===\n');
+
+  const validator = new EnhancedOSSAValidator();
+
+  try {
+    // Create test manifest
+    const testManifest = {
+      apiVersion: 'ossa/v0.3.6',
+      kind: 'Agent',
+      metadata: {
+        name: 'file-test-agent',
+        taxonomy: {
+          domain: 'security',
+          subdomain: 'auth',
+        },
+        access_tier: {
+          tier: 'tier_1_read',
+          permissions: ['read_code', 'read_configs'],
+        },
+      },
+      spec: {
+        type: 'analyzer',
+        model: {
+          provider: 'anthropic',
+          name: 'claude-3-5-sonnet-20241022',
+        },
+      },
+    };
+
+    const testPath = join(__dirname, 'test-manifest.json');
+    writeFileSync(testPath, JSON.stringify(testManifest, null, 2));
+
+    // Validate
+    const result = validator.validateFile(testPath);
+
+    console.log(`File: ${testPath}`);
+    console.log(`Valid: ${result.valid}`);
+    console.log(`Issues: ${result.report.summary.total}`);
+
+    if (result.valid) {
+      console.log('✅ Manifest is valid!');
+    } else {
+      console.log('\nIssues found:');
+      console.log(result.formatted.text);
+    }
+  } catch (error) {
+    console.error('Error:', error);
+  }
+
+  console.log('');
+}
+
+// Run all examples
+async function main() {
+  console.clear();
+  console.log('╔═══════════════════════════════════════════════╗');
+  console.log('║  OSSA Error Code Catalog - Demo              ║');
+  console.log('║  Production-Quality Error Handling           ║');
+  console.log('╚═══════════════════════════════════════════════╝\n');
+
+  validateWithErrorCodes();
+  handleSpecificErrors();
+  searchAndFilter();
+  getErrorInfo();
+  exportFormats();
+  validateFile();
+
+  console.log('╔═══════════════════════════════════════════════╗');
+  console.log('║  Demo Complete                                ║');
+  console.log('║  Check generated files in examples/validation ║');
+  console.log('╚═══════════════════════════════════════════════╝');
+}
+
+main().catch(console.error);

package/examples/workflows/batch-email-campaign.yaml

@@ -1,6 +1,6 @@
 # Example: Batch Email Campaign Workflow
 # Demonstrates loops, parallel execution, and batch processing
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: batch-email-campaign

package/examples/workflows/content-review-publish.yaml

@@ -1,6 +1,6 @@
 # Example: Content Review and Publish Workflow
 # Demonstrates mixed Task + Agent composition
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: content-review-publish

package/examples/workflows/simple-etl.yaml

@@ -1,6 +1,6 @@
 # Example: Simple ETL Workflow
 # Demonstrates sequential Tasks with data transformation
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.3.6
 kind: Workflow
 metadata:
   name: simple-etl

package/openapi/agent-crud.yaml

@@ -719,9 +719,9 @@ components:
           type: string
 
     AgentType:
-      $ref: '../schemas/common/agent.yaml#/components/schemas/AgentType'
+      $ref: './schemas/common/agent.yaml#/components/schemas/AgentType'
     AgentStatus:
-      $ref: '../schemas/common/agent.yaml#/components/schemas/AgentStatus'
+      $ref: './schemas/common/agent.yaml#/components/schemas/AgentStatus'
 
     AgentMetrics:
       type: object
@@ -745,7 +745,7 @@ components:
 
     # Error Schemas (RFC7807) - Using shared schema
     Problem:
-      $ref: '../schemas/common/errors.yaml#/components/schemas/Problem'
+      $ref: './schemas/common/errors.yaml#/components/schemas/Problem'
 
   responses:
     BadRequest:

package/openapi/agent-taxonomy.yaml

@@ -0,0 +1,323 @@
+openapi: 3.1.0
+info:
+  title: OSSA Agent Taxonomy API
+  version: 0.3.6
+  description: |
+    Agent classification and taxonomy system for OSSA v0.3.x.
+    Provides hierarchical categorization of agents by:
+    - Primary role (analyzer, executor, coordinator, reviewer)
+    - Domain expertise (devops, security, data, ml, etc.)
+    - Capability level (tier_1_read, tier_2_write, tier_3_full, tier_4_policy)
+    - Runtime environment (kubernetes, docker, serverless, local)
+
+servers:
+  - url: http://localhost:3000/api/v1
+    description: Local development
+
+paths:
+  /taxonomy/categories:
+    get:
+      summary: List all taxonomy categories
+      operationId: listTaxonomyCategories
+      tags: [Taxonomy]
+      responses:
+        '200':
+          description: List of taxonomy categories
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  categories:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/TaxonomyCategory'
+                  total:
+                    type: integer
+
+  /taxonomy/categories/{categoryId}:
+    get:
+      summary: Get category by ID
+      operationId: getTaxonomyCategory
+      tags: [Taxonomy]
+      parameters:
+        - name: categoryId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Taxonomy category details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaxonomyCategory'
+        '404':
+          description: Category not found
+
+    put:
+      summary: Update category
+      operationId: updateTaxonomyCategory
+      tags: [Taxonomy]
+      parameters:
+        - name: categoryId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaxonomyCategoryInput'
+      responses:
+        '200':
+          description: Category updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaxonomyCategory'
+
+    delete:
+      summary: Delete category
+      operationId: deleteTaxonomyCategory
+      tags: [Taxonomy]
+      parameters:
+        - name: categoryId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Category deleted
+        '404':
+          description: Category not found
+
+  /taxonomy/categories:
+    post:
+      summary: Create new category
+      operationId: createTaxonomyCategory
+      tags: [Taxonomy]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaxonomyCategoryInput'
+      responses:
+        '201':
+          description: Category created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaxonomyCategory'
+
+  /taxonomy/classify:
+    post:
+      summary: Classify an agent manifest
+      operationId: classifyAgent
+      tags: [Taxonomy]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                manifest:
+                  type: object
+                  description: OSSA agent manifest to classify
+      responses:
+        '200':
+          description: Classification result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentClassification'
+
+  /taxonomy/validate:
+    post:
+      summary: Validate taxonomy assignment
+      operationId: validateTaxonomy
+      tags: [Taxonomy]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                categoryId:
+                  type: string
+                manifest:
+                  type: object
+      responses:
+        '200':
+          description: Validation result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationResult'
+
+components:
+  schemas:
+    TaxonomyCategory:
+      type: object
+      required:
+        - id
+        - name
+        - type
+        - level
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique category identifier
+        name:
+          type: string
+          description: Category name (e.g., "DevOps Automation", "Security Analysis")
+        description:
+          type: string
+          description: Category description
+        type:
+          type: string
+          enum: [role, domain, capability, runtime, custom]
+          description: Category type
+        level:
+          type: integer
+          minimum: 1
+          maximum: 5
+          description: Hierarchy level (1=top, 5=most specific)
+        parent_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: Parent category ID for hierarchical taxonomy
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Additional category metadata
+        tags:
+          type: array
+          items:
+            type: string
+          description: Category tags for search/filter
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    TaxonomyCategoryInput:
+      type: object
+      required:
+        - name
+        - type
+        - level
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        type:
+          type: string
+          enum: [role, domain, capability, runtime, custom]
+        level:
+          type: integer
+          minimum: 1
+          maximum: 5
+        parent_id:
+          type: string
+          format: uuid
+          nullable: true
+        metadata:
+          type: object
+          additionalProperties: true
+        tags:
+          type: array
+          items:
+            type: string
+
+    AgentClassification:
+      type: object
+      required:
+        - agent_id
+        - classifications
+        - confidence
+      properties:
+        agent_id:
+          type: string
+          description: Agent identifier
+        classifications:
+          type: array
+          items:
+            type: object
+            properties:
+              category_id:
+                type: string
+                format: uuid
+              category_name:
+                type: string
+              confidence:
+                type: number
+                format: float
+                minimum: 0
+                maximum: 1
+              reason:
+                type: string
+        confidence:
+          type: number
+          format: float
+          minimum: 0
+          maximum: 1
+          description: Overall classification confidence
+        suggested_categories:
+          type: array
+          items:
+            type: string
+          description: Suggested categories based on manifest analysis
+
+    ValidationResult:
+      type: object
+      required:
+        - valid
+        - category_id
+      properties:
+        valid:
+          type: boolean
+          description: Whether taxonomy assignment is valid
+        category_id:
+          type: string
+          format: uuid
+        errors:
+          type: array
+          items:
+            type: object
+            properties:
+              field:
+                type: string
+              message:
+                type: string
+              severity:
+                type: string
+                enum: [error, warning, info]
+        warnings:
+          type: array
+          items:
+            type: object
+            properties:
+              field:
+                type: string
+              message:
+                type: string
+        recommendations:
+          type: array
+          items:
+            type: string
+          description: Recommendations for improving taxonomy fit