1
2
3
4
5
6
7
8
9

# Install AIMatrix CLI
npm install -g @aimatrix/cli

# Install Capsule Development Kit (CDK)
npm install -g @aimatrix/capsule-cdk

# Verify installation
aimatrix version
capsule-cdk version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// aimatrix.config.ts
export default {
  capsule: {
    development: {
      runtime: 'node18',
      environment: 'sandbox',
      debugging: true,
      hotReload: true,
      testDatabase: 'postgresql://localhost:5432/capsule_dev',
      vectorStore: 'local', // or 'supabase' for remote development
    },
    build: {
      outputDir: './dist',
      minify: true,
      treeshaking: true,
      sourceMap: true,
      bundleAnalysis: true
    },
    deployment: {
      registry: 'https://marketplace.aimatrix.com',
      organization: 'your-org',
      visibility: 'private' // or 'public'
    }
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Create a new capsule project
capsule-cdk init my-knowledge-capsule --template=typescript

# Available templates
capsule-cdk list-templates
# - typescript (default)
# - python
# - javascript
# - mixed-language

cd my-knowledge-capsule

# Install dependencies
npm install

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

{
  "id": "com.example.my-knowledge-capsule",
  "name": "My Knowledge Capsule",
  "version": "1.0.0",
  "description": "A comprehensive knowledge capsule for domain-specific tasks",
  "author": {
    "name": "Developer Name",
    "email": "developer@example.com",
    "organization": "Example Corp",
    "website": "https://example.com"
  },
  "license": "MIT",
  "keywords": ["knowledge", "ai", "domain-specific"],
  
  "aimatrixVersion": "^2.0.0",
  "nodeVersion": ">=18.0.0",
  
  "dependencies": {
    "com.aimatrix.core.nlp": "^1.2.0",
    "com.aimatrix.data.postgres": "^2.1.0"
  },
  
  "peerDependencies": {
    "com.aimatrix.vector.embeddings": "^1.0.0"
  },
  
  "resources": {
    "memory": {
      "min": "128MB",
      "recommended": "256MB",
      "max": "512MB"
    },
    "cpu": {
      "min": 0.1,
      "recommended": 0.5
    },
    "storage": {
      "persistent": "1GB",
      "temporary": "500MB"
    }
  },
  
  "permissions": [
    {
      "resource": "supabase.table.knowledge_base",
      "actions": ["read", "write"],
      "conditions": [
        {
          "field": "organization_id",
          "operator": "equals",
          "value": "${organization.id}"
        }
      ]
    },
    {
      "resource": "aimatrix.vector.search",
      "actions": ["query", "embed"]
    }
  ],
  
  "endpoints": [
    {
      "path": "/api/v1/process",
      "method": "POST",
      "handler": "src/handlers/process.ts",
      "description": "Process knowledge queries"
    }
  ],
  
  "eventHandlers": [
    {
      "event": "knowledge.updated",
      "handler": "src/handlers/knowledge-updated.ts"
    }
  ],
  
  "hooks": {
    "preInstall": "src/hooks/pre-install.ts",
    "postInstall": "src/hooks/post-install.ts",
    "preUpdate": "src/hooks/pre-update.ts",
    "postUpdate": "src/hooks/post-update.ts",
    "preRemove": "src/hooks/pre-remove.ts"
  },
  
  "knowledgeAssets": {
    "schemas": ["knowledge/schemas/*.json"],
    "rules": ["knowledge/rules/*.yaml"],
    "workflows": ["knowledge/workflows/*.bpmn"],
    "embeddings": ["knowledge/embeddings/*.jsonl"]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// src/index.ts
import { CapsuleRuntime, CapsuleContext } from '@aimatrix/capsule-runtime';
import { KnowledgeService } from './services/knowledge';
import { APIService } from './services/api';
import { DataService } from './services/data';

export class MyKnowledgeCapsule {
  private knowledgeService: KnowledgeService;
  private apiService: APIService;
  private dataService: DataService;
  
  constructor(private context: CapsuleContext) {
    this.initializeServices();
  }
  
  async initialize(): Promise<void> {
    // Initialize services in dependency order
    await this.dataService.initialize();
    await this.knowledgeService.initialize();
    await this.apiService.initialize();
    
    // Register event handlers
    this.registerEventHandlers();
    
    // Setup monitoring
    this.setupMonitoring();
    
    console.log(`${this.context.capsule.name} v${this.context.capsule.version} initialized`);
  }
  
  async shutdown(): Promise<void> {
    // Graceful shutdown sequence
    await this.apiService.shutdown();
    await this.knowledgeService.shutdown();
    await this.dataService.shutdown();
    
    console.log('Capsule shutdown complete');
  }
  
  private initializeServices(): void {
    this.dataService = new DataService(this.context);
    this.knowledgeService = new KnowledgeService(this.context, this.dataService);
    this.apiService = new APIService(this.context, this.knowledgeService);
  }
  
  private registerEventHandlers(): void {
    this.context.events.on('knowledge.updated', async (event) => {
      await this.knowledgeService.handleKnowledgeUpdate(event);
    });
    
    this.context.events.on('organization.settings.changed', async (event) => {
      await this.handleOrganizationSettingsChange(event);
    });
  }
  
  private setupMonitoring(): void {
    // Performance monitoring
    this.context.metrics.gauge('capsule.memory_usage', () => process.memoryUsage().heapUsed);
    this.context.metrics.gauge('capsule.active_requests', () => this.apiService.getActiveRequestCount());
    
    // Health checks
    this.context.health.register('database', () => this.dataService.healthCheck());
    this.context.health.register('knowledge_base', () => this.knowledgeService.healthCheck());
  }
}

// Export the capsule class for runtime loading
export default MyKnowledgeCapsule;

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

// src/services/knowledge.ts
import { CapsuleContext } from '@aimatrix/capsule-runtime';
import { VectorSearch, Embedding } from '@aimatrix/vector-search';
import { RuleEngine } from '@aimatrix/rule-engine';
import { DataService } from './data';

export class KnowledgeService {
  private vectorSearch: VectorSearch;
  private ruleEngine: RuleEngine;
  private embeddings: Map<string, Embedding>;
  
  constructor(
    private context: CapsuleContext,
    private dataService: DataService
  ) {
    this.vectorSearch = new VectorSearch(context.supabase);
    this.ruleEngine = new RuleEngine();
    this.embeddings = new Map();
  }
  
  async initialize(): Promise<void> {
    // Load knowledge rules
    await this.loadKnowledgeRules();
    
    // Load embeddings
    await this.loadEmbeddings();
    
    // Initialize vector search
    await this.vectorSearch.initialize();
    
    // Subscribe to knowledge updates
    this.subscribeToUpdates();
  }
  
  async processQuery(query: string, context?: Record<string, any>): Promise<KnowledgeResponse> {
    const startTime = Date.now();
    
    try {
      // 1. Generate query embedding
      const queryEmbedding = await this.context.ai.generateEmbedding(query);
      
      // 2. Vector search for relevant knowledge
      const searchResults = await this.vectorSearch.search(queryEmbedding, {
        limit: 10,
        threshold: 0.7,
        filter: {
          capsule_id: this.context.capsule.id,
          organization_id: this.context.organization.id
        }
      });
      
      // 3. Apply business rules
      const ruleContext = {
        query,
        searchResults,
        userContext: context,
        organization: this.context.organization
      };
      
      const ruleResults = await this.ruleEngine.evaluate(ruleContext);
      
      // 4. Generate response
      const response = await this.generateResponse(query, searchResults, ruleResults);
      
      // 5. Log metrics
      this.context.metrics.histogram('knowledge.query_duration', Date.now() - startTime);
      this.context.metrics.counter('knowledge.queries_processed').inc();
      
      return response;
      
    } catch (error) {
      this.context.metrics.counter('knowledge.query_errors').inc();
      this.context.logger.error('Knowledge query processing failed', { query, error });
      throw error;
    }
  }
  
  private async loadKnowledgeRules(): Promise<void> {
    const ruleFiles = await this.context.assets.glob('knowledge/rules/*.yaml');
    
    for (const ruleFile of ruleFiles) {
      const ruleContent = await this.context.assets.readText(ruleFile);
      const rules = this.parseRuleFile(ruleContent);
      
      for (const rule of rules) {
        this.ruleEngine.addRule(rule);
      }
    }
    
    this.context.logger.info(`Loaded ${this.ruleEngine.getRuleCount()} knowledge rules`);
  }
  
  private async loadEmbeddings(): Promise<void> {
    const embeddingFiles = await this.context.assets.glob('knowledge/embeddings/*.jsonl');
    
    for (const embeddingFile of embeddingFiles) {
      const lines = await this.context.assets.readLines(embeddingFile);
      
      for (const line of lines) {
        const embedding = JSON.parse(line) as Embedding;
        this.embeddings.set(embedding.id, embedding);
        
        // Store in vector database
        await this.vectorSearch.upsert({
          id: embedding.id,
          vector: embedding.vector,
          metadata: {
            capsule_id: this.context.capsule.id,
            content: embedding.content,
            tags: embedding.tags
          }
        });
      }
    }
    
    this.context.logger.info(`Loaded ${this.embeddings.size} embeddings`);
  }
  
  async updateKnowledge(updates: KnowledgeUpdate[]): Promise<void> {
    const transaction = await this.dataService.beginTransaction();
    
    try {
      for (const update of updates) {
        switch (update.type) {
          case 'rule':
            await this.updateRule(update, transaction);
            break;
          case 'embedding':
            await this.updateEmbedding(update, transaction);
            break;
          case 'schema':
            await this.updateSchema(update, transaction);
            break;
        }
      }
      
      await transaction.commit();
      
      // Emit update event
      this.context.events.emit('knowledge.updated', {
        capsuleId: this.context.capsule.id,
        updates: updates.length
      });
      
    } catch (error) {
      await transaction.rollback();
      throw error;
    }
  }
  
  async healthCheck(): Promise<boolean> {
    try {
      // Check vector search connectivity
      await this.vectorSearch.healthCheck();
      
      // Check rule engine status
      const ruleCount = this.ruleEngine.getRuleCount();
      if (ruleCount === 0) {
        throw new Error('No rules loaded');
      }
      
      // Check embedding availability
      if (this.embeddings.size === 0) {
        throw new Error('No embeddings loaded');
      }
      
      return true;
    } catch (error) {
      this.context.logger.error('Knowledge service health check failed', { error });
      return false;
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

// tests/unit/knowledge.service.test.ts
import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
import { createMockContext } from '@aimatrix/capsule-testing';
import { KnowledgeService } from '../../src/services/knowledge';
import { DataService } from '../../src/services/data';

describe('KnowledgeService', () => {
  let knowledgeService: KnowledgeService;
  let mockContext: any;
  let mockDataService: DataService;
  
  beforeEach(async () => {
    mockContext = createMockContext({
      capsule: {
        id: 'test-capsule',
        name: 'Test Capsule',
        version: '1.0.0'
      }
    });
    
    mockDataService = new DataService(mockContext);
    knowledgeService = new KnowledgeService(mockContext, mockDataService);
    
    await knowledgeService.initialize();
  });
  
  afterEach(async () => {
    await knowledgeService.shutdown();
  });
  
  test('should process simple queries', async () => {
    const query = 'What is the refund policy?';
    const response = await knowledgeService.processQuery(query);
    
    expect(response).toBeDefined();
    expect(response.confidence).toBeGreaterThan(0.5);
    expect(response.sources).toHaveLength.toBeGreaterThan(0);
  });
  
  test('should handle knowledge updates', async () => {
    const updates = [
      {
        type: 'rule',
        id: 'new-rule',
        content: 'IF customer_tier = "premium" THEN priority = "high"'
      }
    ];
    
    await expect(knowledgeService.updateKnowledge(updates)).resolves.not.toThrow();
  });
  
  test('should pass health checks', async () => {
    const isHealthy = await knowledgeService.healthCheck();
    expect(isHealthy).toBe(true);
  });
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// tests/integration/capsule.integration.test.ts
import { describe, test, expect, beforeAll, afterAll } from '@jest/globals';
import { CapsuleTestRunner } from '@aimatrix/capsule-testing';
import MyKnowledgeCapsule from '../../src/index';

describe('Capsule Integration Tests', () => {
  let testRunner: CapsuleTestRunner;
  let capsule: MyKnowledgeCapsule;
  
  beforeAll(async () => {
    testRunner = new CapsuleTestRunner({
      capsuleClass: MyKnowledgeCapsule,
      testDatabase: process.env.TEST_DATABASE_URL,
      supabaseUrl: process.env.TEST_SUPABASE_URL,
      supabaseKey: process.env.TEST_SUPABASE_ANON_KEY
    });
    
    await testRunner.setup();
    capsule = await testRunner.createCapsule();
  });
  
  afterAll(async () => {
    await testRunner.teardown();
  });
  
  test('should install successfully', async () => {
    const result = await testRunner.install(capsule);
    expect(result.success).toBe(true);
  });
  
  test('should handle API requests', async () => {
    const response = await testRunner.request('/api/v1/process', {
      method: 'POST',
      body: {
        query: 'Test query',
        context: { user_id: 'test-user' }
      }
    });
    
    expect(response.status).toBe(200);
    expect(response.data).toHaveProperty('result');
  });
  
  test('should process knowledge queries end-to-end', async () => {
    const query = 'What are the business hours?';
    
    const response = await testRunner.processKnowledgeQuery(query);
    
    expect(response.confidence).toBeGreaterThan(0.7);
    expect(response.result).toContain('hours');
  });
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// .eslintrc.js
module.exports = {
  extends: ['@aimatrix/eslint-config-capsule'],
  rules: {
    // Security rules
    'security/detect-object-injection': 'error',
    'security/detect-non-literal-require': 'error',
    
    // Performance rules
    'unicorn/no-abusive-eslint-disable': 'error',
    'sonarjs/cognitive-complexity': ['error', 15],
    
    // Code quality rules
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/explicit-function-return-type': 'warn',
    
    // AIMatrix specific rules
    'aimatrix/no-direct-database-access': 'error',
    'aimatrix/require-permission-checks': 'error',
    'aimatrix/validate-knowledge-assets': 'error'
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# .github/workflows/security-scan.yml
name: Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run security audit
        run: |
          npm audit --audit-level high
          
      - name: Snyk security scan
        run: |
          npx snyk test --severity-threshold=medium
          
      - name: CodeQL analysis
        uses: github/codeql-action/analyze@v2
        with:
          languages: typescript
          
      - name: AIMatrix security validation
        run: |
          capsule-cdk validate --security

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Performance benchmarks that must be met
const PERFORMANCE_REQUIREMENTS = {
  // Response time requirements (95th percentile)
  api: {
    simpleQuery: 100, // ms
    complexQuery: 500, // ms
    knowledgeUpdate: 1000 // ms
  },
  
  // Resource usage limits
  memory: {
    idle: 50 * 1024 * 1024, // 50MB
    peak: 256 * 1024 * 1024 // 256MB
  },
  
  // Throughput requirements
  throughput: {
    queries_per_second: 100,
    concurrent_users: 50
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Certification requirements checklist
interface CertificationRequirements {
  basic: {
    functionality: boolean;     // All tests pass
    security: boolean;          // Security scan passes
    documentation: boolean;     // Complete documentation
    manifest: boolean;          // Valid manifest
  };
  
  advanced: {
    performance: boolean;       // Meets performance benchmarks
    integration: boolean;       // Integration tests pass
    monitoring: boolean;        // Proper monitoring setup
    errorHandling: boolean;     // Comprehensive error handling
  };
  
  enterprise: {
    scalability: boolean;       // Load testing passes
    reliability: boolean;       // High availability design
    observability: boolean;     // Full observability stack
    compliance: boolean;        // Regulatory compliance
  };
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Run certification process
capsule-cdk certify --level=basic

# Output example:
✓ Functionality tests: PASSED (127/127 tests)
✓ Security scan: PASSED (0 high, 2 medium, 5 low issues)
✓ Documentation: PASSED (95% coverage)
✓ Manifest validation: PASSED
✓ Performance benchmarks: PASSED (avg: 45ms, p95: 120ms)
✓ Integration tests: PASSED (23/23 tests)

🎉 Certification PASSED - Ready for Basic certification

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#!/bin/bash
# pre-publish.sh

set -e

echo "🔍 Running pre-publication checks..."

# 1. Version validation
echo "📋 Validating version..."
capsule-cdk validate-version

# 2. Build and test
echo "🔧 Building capsule..."
npm run build

echo "🧪 Running tests..."
npm test

# 3. Security scan
echo "🔒 Security scanning..."
capsule-cdk security-scan

# 4. Performance testing
echo "⚡ Performance testing..."
npm run test:performance

# 5. Integration testing
echo "🔗 Integration testing..."
npm run test:integration

# 6. Documentation validation
echo "📚 Documentation validation..."
capsule-cdk validate-docs

# 7. License check
echo "⚖️ License validation..."
capsule-cdk validate-license

echo "✅ All pre-publication checks passed!"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Build production package
npm run build:production

# Package for distribution
capsule-cdk package

# Upload to marketplace (requires authentication)
capsule-cdk publish --registry=https://marketplace.aimatrix.com

# Example output:
📦 Packaging capsule...
   ✓ Manifest validation
   ✓ Asset compression
   ✓ Dependency resolution
   ✓ Security signing

🚀 Publishing to AIMatrix Marketplace...
   ✓ Authentication verified
   ✓ Package uploaded (2.4MB)
   ✓ Automated testing initiated
   ✓ Security review queued

🎉 Publication successful!
   Package ID: pkg_abc123def456
   Review status: https://marketplace.aimatrix.com/review/pkg_abc123def456
   Expected approval: 2-5 business days

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Revenue model configuration
interface RevenueModel {
  type: 'free' | 'freemium' | 'subscription' | 'usage' | 'enterprise';
  pricing?: {
    free_tier?: {
      requests_per_month: number;
      features: string[];
    };
    paid_tiers?: Array<{
      name: string;
      price_monthly: number;
      price_yearly: number;
      requests_per_month: number;
      features: string[];
    }>;
    usage_pricing?: {
      per_request: number;
      per_gb_storage: number;
      per_cpu_hour: number;
    };
  };
  revenue_share: number; // AIMatrix platform fee (typically 20-30%)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// Built-in revenue tracking
export class RevenueTracker {
  async trackUsage(
    capsuleId: string,
    organizationId: string,
    event: UsageEvent
  ): Promise<void> {
    await this.context.billing.recordUsage({
      capsule_id: capsuleId,
      organization_id: organizationId,
      event_type: event.type,
      quantity: event.quantity,
      unit_price: this.getPricing(event.type),
      timestamp: new Date()
    });
  }
  
  async generateInvoice(
    period: BillingPeriod
  ): Promise<Invoice> {
    return await this.context.billing.generateInvoice({
      capsule_id: this.context.capsule.id,
      period,
      line_items: await this.calculateLineItems(period)
    });
  }
}