ACS Basic Implementation Guide

Practical implementation of ACS (Adaptive Context Scaling) core functionality for v0. Focus on provider selection, basic scoring, and execution without advanced optimization features.

Implementation Goals (v0)

✅ In Scope:

• Basic provider selection based on simple scoring
• Execute requests with timeout and retry logic
• Simple benefit/cost calculation
• Basic error handling and fallback

❌ Out of Scope (v1):

• Complex optimization algorithms
• Machine learning-based scoring
• Advanced cognitive load management
• Multi-objective optimization

45-Minute Implementation

Step 1: Core Types (10 minutes)

// types/acs.ts
export interface ProviderCapability {
  provider_id: string;
  name: string;
  type: 'llm' | 'search' | 'code' | 'docs';
  domains: string[]; // ['code', 'documentation', 'research']
  capabilities: string[]; // ['completion', 'embeddings', 'search']
  
  // Performance characteristics
  avg_latency_ms: number;
  cost_per_request_cents: number;
  quality_score: number; // 0.0-1.0
  reliability_score: number; // 0.0-1.0
  
  // Configuration
  endpoint: string;
  api_key?: string;
  timeout_ms: number;
  max_retries: number;
}

export interface ACSRequest {
  request_id: string;
  intent: ParsedIntent; // From CEO
  budget: ResourceBudget; // From CEO
  timestamp: Date;
}

export interface ProviderScore {
  provider_id: string;
  benefit_score: number; // 0.0-1.0
  cost_score: number; // 0.0-1.0
  combined_score: number; // benefit/cost ratio
  reasoning: string;
}

export interface ExecutionPlan {
  selected_providers: ProviderCapability[];
  fallback_providers: ProviderCapability[];
  total_estimated_cost: number;
  total_estimated_latency: number;
}

export interface ACSResponse {
  request_id: string;
  results: any[];
  execution_metadata: {
    providers_used: string[];
    total_cost_cents: number;
    total_latency_ms: number;
    quality_achieved: number;
  };
  errors?: string[];
}

Step 2: Provider Registry (10 minutes)

// services/provider-registry.ts
export class BasicProviderRegistry {
  private providers: Map<string, ProviderCapability> = new Map();

  constructor() {
    this.initializeDefaultProviders();
  }

  private initializeDefaultProviders(): void {
    const defaultProviders: ProviderCapability[] = [
      {
        provider_id: 'openai_gpt4',
        name: 'OpenAI GPT-4',
        type: 'llm',
        domains: ['code', 'documentation', 'research', 'general'],
        capabilities: ['completion', 'analysis'],
        avg_latency_ms: 2000,
        cost_per_request_cents: 10,
        quality_score: 0.9,
        reliability_score: 0.95,
        endpoint: 'https://api.openai.com/v1/chat/completions',
        timeout_ms: 10000,
        max_retries: 2
      },
      {
        provider_id: 'anthropic_claude',
        name: 'Anthropic Claude',
        type: 'llm',
        domains: ['code', 'documentation', 'research', 'general'],
        capabilities: ['completion', 'analysis'],
        avg_latency_ms: 1500,
        cost_per_request_cents: 8,
        quality_score: 0.88,
        reliability_score: 0.93,
        endpoint: 'https://api.anthropic.com/v1/messages',
        timeout_ms: 8000,
        max_retries: 2
      },
      {
        provider_id: 'local_search',
        name: 'Local Vector Search',
        type: 'search',
        domains: ['code', 'documentation'],
        capabilities: ['search', 'embeddings'],
        avg_latency_ms: 200,
        cost_per_request_cents: 1,
        quality_score: 0.75,
        reliability_score: 0.98,
        endpoint: 'http://localhost:8000/search',
        timeout_ms: 5000,
        max_retries: 1
      }
    ];

    for (const provider of defaultProviders) {
      this.providers.set(provider.provider_id, provider);
    }
  }

  getProvider(providerId: string): ProviderCapability | undefined {
    return this.providers.get(providerId);
  }

  getAllProviders(): ProviderCapability[] {
    return Array.from(this.providers.values());
  }

  getProvidersByDomain(domain: string): ProviderCapability[] {
    return this.getAllProviders().filter(p => p.domains.includes(domain));
  }

  getProvidersByCapability(capability: string): ProviderCapability[] {
    return this.getAllProviders().filter(p => p.capabilities.includes(capability));
  }

  addProvider(provider: ProviderCapability): void {
    this.providers.set(provider.provider_id, provider);
  }

  removeProvider(providerId: string): boolean {
    return this.providers.delete(providerId);
  }
}

Step 3: Provider Scorer (10 minutes)

// services/provider-scorer.ts
export class BasicProviderScorer {
  scoreProviders(
    providers: ProviderCapability[],
    intent: ParsedIntent,
    budget: ResourceBudget
  ): ProviderScore[] {
    const scores = providers.map(provider => this.scoreProvider(provider, intent, budget));
    
    // Sort by combined score (descending)
    return scores.sort((a, b) => b.combined_score - a.combined_score);
  }

  private scoreProvider(
    provider: ProviderCapability,
    intent: ParsedIntent,
    budget: ResourceBudget
  ): ProviderScore {
    const benefitScore = this.calculateBenefitScore(provider, intent);
    const costScore = this.calculateCostScore(provider, budget);
    const combinedScore = this.calculateCombinedScore(benefitScore, costScore);

    return {
      provider_id: provider.provider_id,
      benefit_score: benefitScore,
      cost_score: costScore,
      combined_score: combinedScore,
      reasoning: this.generateReasoning(provider, intent, benefitScore, costScore)
    };
  }

  private calculateBenefitScore(provider: ProviderCapability, intent: ParsedIntent): number {
    let score = 0;

    // Domain match bonus
    if (provider.domains.includes(intent.domain)) {
      score += 0.4;
    }

    // Quality score contribution
    score += provider.quality_score * 0.3;

    // Reliability contribution
    score += provider.reliability_score * 0.2;

    // Complexity match
    const complexityMatch = this.getComplexityMatch(provider, intent.complexity);
    score += complexityMatch * 0.1;

    return Math.min(1.0, score);
  }

  private calculateCostScore(provider: ProviderCapability, budget: ResourceBudget): number {
    // Lower cost = higher cost score
    const costRatio = provider.cost_per_request_cents / budget.max_cost_cents;
    const latencyRatio = provider.avg_latency_ms / budget.max_latency_ms;

    // If provider exceeds budget, penalize heavily
    if (costRatio > 1.0 || latencyRatio > 1.0) {
      return Math.max(0.1, 1.0 - Math.max(costRatio, latencyRatio));
    }

    // Otherwise, higher score for lower cost/latency
    return Math.max(0.1, 1.0 - (costRatio * 0.6 + latencyRatio * 0.4));
  }

  private calculateCombinedScore(benefitScore: number, costScore: number): number {
    // Simple benefit/cost ratio with floor to avoid division by zero
    return benefitScore / Math.max(0.1, (1.0 - costScore + 0.1));
  }

  private getComplexityMatch(provider: ProviderCapability, complexity: string): number {
    // Simple heuristic: higher quality providers better for complex tasks
    const complexityWeights = { simple: 0.5, medium: 0.7, complex: 1.0 };
    const weight = complexityWeights[complexity] || 0.5;
    
    return provider.quality_score * weight;
  }

  private generateReasoning(
    provider: ProviderCapability,
    intent: ParsedIntent,
    benefitScore: number,
    costScore: number
  ): string {
    const reasons = [];

    if (provider.domains.includes(intent.domain)) {
      reasons.push(`domain match (${intent.domain})`);
    }

    if (provider.quality_score > 0.85) {
      reasons.push('high quality');
    }

    if (provider.cost_per_request_cents <= 5) {
      reasons.push('low cost');
    }

    if (provider.avg_latency_ms <= 1000) {
      reasons.push('fast response');
    }

    return reasons.join(', ') || 'basic scoring';
  }
}

Step 4: Execution Engine (10 minutes)

// services/execution-engine.ts
export class BasicExecutionEngine {
  private httpClient: any; // Axios or fetch wrapper

  constructor() {
    // Initialize HTTP client with default configuration
    this.initializeHttpClient();
  }

  async executeRequest(
    provider: ProviderCapability,
    query: string,
    options: Record<string, any> = {}
  ): Promise<any> {
    const startTime = Date.now();

    try {
      const response = await this.makeProviderRequest(provider, query, options);
      const latency = Date.now() - startTime;

      return {
        success: true,
        data: response,
        metadata: {
          provider_id: provider.provider_id,
          latency_ms: latency,
          cost_cents: provider.cost_per_request_cents
        }
      };

    } catch (error) {
      const latency = Date.now() - startTime;
      
      return {
        success: false,
        error: error.message,
        metadata: {
          provider_id: provider.provider_id,
          latency_ms: latency,
          cost_cents: 0 // No cost for failed requests
        }
      };
    }
  }

  async executeWithFallback(
    providers: ProviderCapability[],
    query: string,
    options: Record<string, any> = {}
  ): Promise<any> {
    let lastError: Error;

    for (const provider of providers) {
      try {
        console.log(`Trying provider: ${provider.name}`);
        const result = await this.executeRequest(provider, query, options);
        
        if (result.success) {
          return result;
        } else {
          lastError = new Error(result.error);
          console.warn(`Provider ${provider.name} failed: ${result.error}`);
        }
        
      } catch (error) {
        lastError = error;
        console.warn(`Provider ${provider.name} failed: ${error.message}`);
      }
    }

    throw new Error(`All providers failed. Last error: ${lastError?.message}`);
  }

  private async makeProviderRequest(
    provider: ProviderCapability,
    query: string,
    options: Record<string, any>
  ): Promise<any> {
    // Simplified provider request - customize per provider type
    const requestPayload = this.buildRequestPayload(provider, query, options);
    
    const response = await this.httpClient({
      method: 'POST',
      url: provider.endpoint,
      data: requestPayload,
      timeout: provider.timeout_ms,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${provider.api_key || process.env.DEFAULT_API_KEY}`,
        ...options.headers
      }
    });

    return this.parseProviderResponse(provider, response.data);
  }

  private buildRequestPayload(
    provider: ProviderCapability,
    query: string,
    options: Record<string, any>
  ): any {
    // Basic payload - customize per provider
    switch (provider.type) {
      case 'llm':
        return {
          messages: [{ role: 'user', content: query }],
          max_tokens: options.max_tokens || 1000,
          temperature: options.temperature || 0.7
        };
      
      case 'search':
        return {
          query: query,
          limit: options.limit || 10,
          threshold: options.threshold || 0.7
        };
        
      default:
        return { query, ...options };
    }
  }

  private parseProviderResponse(provider: ProviderCapability, responseData: any): any {
    // Basic response parsing - customize per provider
    switch (provider.type) {
      case 'llm':
        return responseData.choices?.[0]?.message?.content || responseData.content;
      
      case 'search':
        return responseData.results || responseData;
        
      default:
        return responseData;
    }
  }

  private initializeHttpClient(): void {
    // Initialize your preferred HTTP client (axios, fetch, etc.)
    // This is a placeholder - implement based on your environment
    this.httpClient = async (config: any) => {
      // Simplified HTTP client implementation
      throw new Error('HTTP client not implemented - use axios or fetch');
    };
  }
}

Step 5: Main ACS Service (5 minutes)

// services/acs.ts
export class BasicACS {
  private providerRegistry: BasicProviderRegistry;
  private providerScorer: BasicProviderScorer;
  private executionEngine: BasicExecutionEngine;

  constructor() {
    this.providerRegistry = new BasicProviderRegistry();
    this.providerScorer = new BasicProviderScorer();
    this.executionEngine = new BasicExecutionEngine();
  }

  async executeRequest(request: ACSRequest): Promise<ACSResponse> {
    const startTime = Date.now();

    try {
      // 1. Get candidate providers
      const candidateProviders = this.providerRegistry.getProvidersByDomain(request.intent.domain);
      
      if (candidateProviders.length === 0) {
        throw new Error(`No providers available for domain: ${request.intent.domain}`);
      }

      // 2. Score and rank providers
      const providerScores = this.providerScorer.scoreProviders(
        candidateProviders,
        request.intent,
        request.budget
      );

      // 3. Create execution plan
      const executionPlan = this.createExecutionPlan(providerScores, request.budget);

      // 4. Execute with primary and fallback providers
      const result = await this.executionEngine.executeWithFallback(
        executionPlan.selected_providers,
        request.intent.primary_goal,
        { max_tokens: 1000 }
      );

      // 5. Build response
      const totalLatency = Date.now() - startTime;
      
      return {
        request_id: request.request_id,
        results: [result.data],
        execution_metadata: {
          providers_used: [result.metadata.provider_id],
          total_cost_cents: result.metadata.cost_cents,
          total_latency_ms: totalLatency,
          quality_achieved: this.estimateQualityAchieved(result, executionPlan)
        }
      };

    } catch (error) {
      return {
        request_id: request.request_id,
        results: [],
        execution_metadata: {
          providers_used: [],
          total_cost_cents: 0,
          total_latency_ms: Date.now() - startTime,
          quality_achieved: 0
        },
        errors: [error.message]
      };
    }
  }

  private createExecutionPlan(
    providerScores: ProviderScore[],
    budget: ResourceBudget
  ): ExecutionPlan {
    // Select primary provider (highest score within budget)
    const affordableProviders = providerScores.filter(score => {
      const provider = this.providerRegistry.getProvider(score.provider_id);
      return provider && 
             provider.cost_per_request_cents <= budget.max_cost_cents &&
             provider.avg_latency_ms <= budget.max_latency_ms;
    });

    if (affordableProviders.length === 0) {
      throw new Error('No providers within budget constraints');
    }

    const selectedProviders = affordableProviders
      .slice(0, Math.min(budget.max_providers, 2))
      .map(score => this.providerRegistry.getProvider(score.provider_id)!)
      .filter(p => p);

    const fallbackProviders = affordableProviders
      .slice(budget.max_providers)
      .map(score => this.providerRegistry.getProvider(score.provider_id)!)
      .filter(p => p);

    return {
      selected_providers: selectedProviders,
      fallback_providers: fallbackProviders,
      total_estimated_cost: selectedProviders.reduce((sum, p) => sum + p.cost_per_request_cents, 0),
      total_estimated_latency: Math.max(...selectedProviders.map(p => p.avg_latency_ms))
    };
  }

  private estimateQualityAchieved(result: any, plan: ExecutionPlan): number {
    if (result.success && plan.selected_providers.length > 0) {
      return plan.selected_providers[0].quality_score;
    }
    return 0;
  }

  async healthCheck(): Promise<boolean> {
    try {
      const providers = this.providerRegistry.getAllProviders();
      return providers.length > 0;
    } catch {
      return false;
    }
  }
}

Usage Examples

Basic Usage

import { BasicACS } from './services/acs';
import { BasicCEO } from './services/ceo';

async function handleQuery() {
  const ceo = new BasicCEO();
  const acs = new BasicACS();

  // CEO processes user query
  const ceoRequest = await ceo.processQuery({
    text: "How do I implement JWT authentication in Node.js?",
    user_id: "user123"
  });

  // ACS executes the request
  const acsRequest: ACSRequest = {
    request_id: ceoRequest.request_id,
    intent: ceoRequest.intent,
    budget: ceoRequest.budget,
    timestamp: new Date()
  };

  const result = await acs.executeRequest(acsRequest);
  
  console.log('Result:', result.results[0]);
  console.log('Cost:', result.execution_metadata.total_cost_cents, 'cents');
  console.log('Latency:', result.execution_metadata.total_latency_ms, 'ms');
}

Custom Provider Registration

const acs = new BasicACS();

// Add custom provider
const customProvider: ProviderCapability = {
  provider_id: 'custom_llm',
  name: 'Custom LLM',
  type: 'llm',
  domains: ['code'],
  capabilities: ['completion'],
  avg_latency_ms: 800,
  cost_per_request_cents: 5,
  quality_score: 0.82,
  reliability_score: 0.90,
  endpoint: 'https://api.custom-llm.com/v1/complete',
  timeout_ms: 8000,
  max_retries: 2
};

acs.providerRegistry.addProvider(customProvider);

Testing Your Implementation

Unit Tests

import { BasicACS } from '../services/acs';

describe('BasicACS', () => {
  let acs: BasicACS;

  beforeEach(() => {
    acs = new BasicACS();
  });

  test('should select appropriate provider for code domain', async () => {
    const request: ACSRequest = {
      request_id: 'test-123',
      intent: {
        primary_goal: 'implement',
        domain: 'code',
        complexity: 'medium',
        urgency: 'medium',
        keywords: ['jwt', 'authentication']
      },
      budget: {
        max_latency_ms: 5000,
        max_cost_cents: 15,
        quality_threshold: 0.8,
        max_providers: 2
      },
      timestamp: new Date()
    };

    // Mock successful execution
    jest.spyOn(acs.executionEngine, 'executeWithFallback').mockResolvedValue({
      success: true,
      data: 'Mocked response',
      metadata: { provider_id: 'openai_gpt4', latency_ms: 1500, cost_cents: 10 }
    });

    const result = await acs.executeRequest(request);

    expect(result.request_id).toBe('test-123');
    expect(result.results).toHaveLength(1);
    expect(result.execution_metadata.total_cost_cents).toBeLessThanOrEqual(15);
  });

  test('should handle provider failures gracefully', async () => {
    const request: ACSRequest = {
      request_id: 'test-fail',
      intent: { primary_goal: 'test', domain: 'nonexistent', complexity: 'simple', urgency: 'low', keywords: [] },
      budget: { max_latency_ms: 1000, max_cost_cents: 5, quality_threshold: 0.5, max_providers: 1 },
      timestamp: new Date()
    };

    const result = await acs.executeRequest(request);

    expect(result.results).toHaveLength(0);
    expect(result.errors).toBeDefined();
    expect(result.errors!.length).toBeGreaterThan(0);
  });
});

Next Steps

1. Provider Integration: Add real HTTP clients and API integrations
2. Advanced Scoring: Implement ML-based provider selection
3. Caching: Add response caching to reduce costs
4. Monitoring: Add comprehensive metrics collection
5. Load Balancing: Distribute requests across multiple providers

Common Issues & Debugging

Issue: Provider selection fails

Solution: Check domain mappings and budget constraints

Issue: API calls timing out

Solution: Adjust timeout values and retry logic

Issue: High costs

Solution: Review scoring algorithm and budget allocation

---

Next: Testing Guide →