AI Integration

PadawanForge leverages Cloudflare Workers AI to provide intelligent, edge-based AI functionality for statement generation, NPC interactions, and cognitive training content creation.

Overview

AI Capabilities

  • Statement Generation: AI-powered creation of true/false statements for cognitive training sessions
  • NPC Chat: Intelligent responses from game NPCs using distinct AI personalities
  • Edge Performance: Low-latency AI inference at Cloudflare’s global edge locations
  • Cost Efficiency: Integrated billing with Cloudflare, no external API costs
  • Scalability: Automatic scaling with Cloudflare’s infrastructure

Supported Models

  • Primary Model: @cf/meta/llama-3.1-8b-instruct - General purpose language model
  • Alternative Models: Multiple models available for specialized tasks
  • Model Selection: Automatic fallback and selection based on task requirements

Architecture

AI Binding Configuration

The AI functionality is configured through Cloudflare’s AI binding in wrangler.jsonc:

{
  "name": "padawanforge-beta",
  "ai": {
    "binding": "AI"
  },
  "compatibility_date": "2024-09-25",
  "compatibility_flags": ["nodejs_compat"]
}

TypeScript Integration

Generated types provide full TypeScript support:

interface Env {
  AI: Ai;           // Cloudflare AI binding
  DB: D1Database;   // Database binding
  SESSION: KVNamespace; // Session storage
}

// AI model interface
interface AIResponse {
  response: string;
  model: string;
  success: boolean;
  usage?: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
}

AI Service Architecture

// Central AI service for all AI operations
class AIService {
  constructor(private ai: Ai) {}
  
  async generateStatements(topic: string, count: number = 40): Promise<Statement[]>
  async generateNPCResponse(npcId: string, prompt: string): Promise<string>
  async testConnection(): Promise<AIResponse>
}

Setup and Configuration

Prerequisites

  • Cloudflare Account: Workers paid plan required for AI access
  • Node.js 18+: Modern JavaScript runtime
  • Bun Package Manager: For optimal performance
  • Git: Version control for development

Local Development Setup

1. Install Dependencies

cd /path/to/PadawanForge
bun install

2. Database Setup

# Create and migrate database with AI-related tables
bun run db:migrate

3. Generate TypeScript Types

# Generate Cloudflare-specific types including AI binding
bun run cf-typegen

4. Start Development Server

# Start with full AI binding support
bun run dev

Environment Variables

No additional environment variables are required for Cloudflare AI integration. Authentication is handled automatically through your Cloudflare account and Workers environment.

Verification

Test AI binding availability:

# Test AI connection
curl http://localhost:4321/api/ai/test-connection

# Expected response:
{
  "success": true,
  "model": "@cf/meta/llama-3.1-8b-instruct",
  "message": "AI connection successful",
  "timestamp": "2024-01-15T10:30:00Z"
}

AI-Powered Features

Statement Generation

Generates educational true/false statements for cognitive training sessions.

API Endpoint

POST /api/ai/generate-statements
Content-Type: application/json

{
  "topic": "History",
  "difficulty": "intermediate",
  "count": 40,
  "subtopics": ["World War II", "Ancient Rome"]
}

Response Format

{
  "statements": [
    {
      "text": "The Roman Empire reached its greatest extent under Emperor Trajan.",
      "answer": true,
      "difficulty": "intermediate",
      "topic": "History",
      "subtopic": "Ancient Rome",
      "explanation": "Trajan expanded the empire to include Dacia, Mesopotamia, and Armenia."
    }
  ],
  "metadata": {
    "generated_at": "2024-01-15T10:30:00Z",
    "model": "@cf/meta/llama-3.1-8b-instruct",
    "prompt_tokens": 150,
    "completion_tokens": 800
  }
}

Quality Assurance

  • Factual Accuracy: Statements verified against reliable sources
  • Clarity: Clear, unambiguous language for rapid judgment
  • Difficulty Calibration: Matched to specified cognitive load
  • Topic Relevance: Direct relationship to selected subject area

NPC Personality System

AI-powered NPCs with distinct personalities for educational guidance.

Available NPCs

const NPCs = {
  einstein: {
    personality: "Thoughtful physicist with analogical teaching style",
    expertise: ["Physics", "Science", "Mathematics"],
    tone: "patient, encouraging, uses metaphors"
  },
  curie: {
    personality: "Methodical researcher with systematic approach",
    expertise: ["Chemistry", "Science", "Research"],
    tone: "precise, encouraging, detail-oriented"
  },
  confucius: {
    personality: "Wise philosopher focused on ethics and wisdom",
    expertise: ["Philosophy", "Ethics", "Wisdom"],
    tone: "contemplative, Socratic, probing"
  },
  sherlock: {
    personality: "Sharp detective with logical reasoning",
    expertise: ["Logic", "Deduction", "Analysis"],
    tone: "analytical, direct, systematic"
  }
};

NPC Response Generation

// Generate contextual NPC response
const response = await aiService.generateNPCResponse(npcId, {
  playerMessage: "I'm struggling with this physics concept",
  context: {
    topic: "Physics",
    difficulty: "intermediate",
    playerLevel: 5,
    recentPerformance: "struggling with momentum problems"
  }
});

Adaptive Difficulty System

AI analyzes player performance to adjust statement difficulty in real-time.

Performance Analysis

interface PerformanceAnalysis {
  accuracyTrend: number[];
  responseTimePattern: number[];
  topicStrengths: Record<string, number>;
  recommendedDifficulty: 'basic' | 'intermediate' | 'advanced';
  learningPath: string[];
}

// AI-generated difficulty recommendation
const analysis = await aiService.analyzePerformance(playerData);

API Endpoints

AI Connection Testing

GET /api/ai/test-connection
Response: {
  success: boolean;
  model: string;
  latency: number;
  timestamp: string;
}

Statement Generation

POST /api/ai/generate-statements
Body: {
  topic: string;
  difficulty: 'basic' | 'intermediate' | 'advanced';
  count: number;
  subtopics?: string[];
}
Response: {
  statements: Statement[];
  metadata: GenerationMetadata;
}

NPC Chat

POST /api/npcs/[id]/chat
Body: {
  message: string;
  context?: ChatContext;
}
Response: {
  response: string;
  npc: NPCInfo;
  timestamp: string;
}

Performance Analysis

POST /api/ai/analyze-performance
Body: {
  playerUuid: string;
  sessionData: SessionData[];
  analysisType: 'difficulty' | 'topics' | 'learning_path';
}
Response: {
  analysis: PerformanceAnalysis;
  recommendations: string[];
}

Production Deployment

Database Migration

# Deploy AI-related database schema to production
bun run db:migrate:remote

Cloudflare Deployment

# Deploy with AI binding support
bun run deploy

# Verify deployment
bun run test:ai:prod

Production Verification

# Test production AI endpoints
curl https://your-domain.workers.dev/api/ai/test-connection

# Load test AI generation
for i in {1..5}; do
  curl -X POST https://your-domain.workers.dev/api/ai/generate-statements \
    -H "Content-Type: application/json" \
    -d '{"topic": "Science", "difficulty": "basic", "count": 10}' &
done
wait

Performance Optimization

Response Caching

// Cache generated statements to reduce AI calls
const CACHE_TTL = 3600; // 1 hour

const getCachedStatements = async (cacheKey: string): Promise<Statement[] | null> => {
  const cached = await kv.get(`statements:${cacheKey}`);
  return cached ? JSON.parse(cached) : null;
};

const cacheStatements = async (cacheKey: string, statements: Statement[]) => {
  await kv.put(`statements:${cacheKey}`, JSON.stringify(statements), { expirationTtl: CACHE_TTL });
};

Batch Processing

// Generate multiple statement sets efficiently
const generateBatchStatements = async (requests: GenerationRequest[]) => {
  const batched = requests.reduce((acc, req) => {
    const batchKey = `${req.topic}-${req.difficulty}`;
    if (!acc[batchKey]) acc[batchKey] = [];
    acc[batchKey].push(req);
    return acc;
  }, {} as Record<string, GenerationRequest[]>);
  
  return Promise.all(
    Object.entries(batched).map(([key, reqs]) => 
      generateStatements(reqs[0].topic, reqs.reduce((sum, r) => sum + r.count, 0))
    )
  );
};

Rate Limiting

// Implement intelligent rate limiting for AI calls
class AIRateLimiter {
  private calls: number = 0;
  private resetTime: number = Date.now() + 60000; // 1 minute window
  
  async canMakeCall(): Promise<boolean> {
    if (Date.now() > this.resetTime) {
      this.calls = 0;
      this.resetTime = Date.now() + 60000;
    }
    
    return this.calls < 100; // 100 calls per minute
  }
  
  recordCall() {
    this.calls++;
  }
}

Error Handling and Fallbacks

Graceful Degradation

const generateStatementsWithFallback = async (topic: string, count: number) => {
  try {
    // Primary: AI generation
    return await aiService.generateStatements(topic, count);
  } catch (aiError) {
    console.warn('AI generation failed, using fallback:', aiError);
    
    try {
      // Fallback: Pre-generated statements from database
      return await getPreGeneratedStatements(topic, count);
    } catch (dbError) {
      console.error('All generation methods failed:', dbError);
      
      // Last resort: Static statements
      return getStaticStatements(topic, count);
    }
  }
};

Error Types and Handling

enum AIErrorType {
  MODEL_UNAVAILABLE = 'model_unavailable',
  RATE_LIMITED = 'rate_limited',
  QUOTA_EXCEEDED = 'quota_exceeded',
  INVALID_PROMPT = 'invalid_prompt',
  TIMEOUT = 'timeout'
}

class AIErrorHandler {
  static handle(error: any): AIErrorResponse {
    switch (error.code) {
      case 10001: // Model unavailable
        return {
          type: AIErrorType.MODEL_UNAVAILABLE,
          message: 'AI model temporarily unavailable',
          retryAfter: 60,
          fallbackAvailable: true
        };
      
      case 10007: // Rate limited
        return {
          type: AIErrorType.RATE_LIMITED,
          message: 'Rate limit exceeded',
          retryAfter: 300,
          fallbackAvailable: true
        };
      
      default:
        return {
          type: AIErrorType.TIMEOUT,
          message: 'AI request timed out',
          retryAfter: 30,
          fallbackAvailable: true
        };
    }
  }
}

Testing and Validation

Automated Testing

# Comprehensive AI testing
bun run test:ai

# Production environment testing
bun run test:ai:prod

# Load testing
bun run test:ai:load

Test Scenarios

describe('AI Integration', () => {
  test('Statement Generation Quality', async () => {
    const statements = await generateStatements('History', 10);
    
    expect(statements).toHaveLength(10);
    statements.forEach(stmt => {
      expect(stmt.text).toMatch(/^[A-Z].*[.!?]$/); // Proper sentence
      expect(typeof stmt.answer).toBe('boolean');
      expect(stmt.topic).toBe('History');
      expect(['basic', 'intermediate', 'advanced']).toContain(stmt.difficulty);
    });
  });
  
  test('NPC Response Consistency', async () => {
    const response1 = await generateNPCResponse('einstein', 'Explain gravity');
    const response2 = await generateNPCResponse('einstein', 'Explain gravity');
    
    // Responses should be different but consistent in tone
    expect(response1).not.toBe(response2);
    expect(response1).toMatch(/analogy|metaphor|simple/i);
    expect(response2).toMatch(/analogy|metaphor|simple/i);
  });
  
  test('Error Handling', async () => {
    // Mock AI failure
    const result = await generateStatementsWithFallback('InvalidTopic', 40);
    
    expect(result.statements).toBeDefined();
    expect(result.source).toBe('fallback');
  });
});

Performance Benchmarks

  • Statement Generation: < 60 seconds for 40 statements
  • NPC Response: < 5 seconds for typical chat response
  • AI Connection Test: < 2 seconds for health check
  • Batch Processing: Linear scaling with request count

Monitoring and Analytics

AI Usage Metrics

interface AIMetrics {
  totalRequests: number;
  successRate: number;
  averageLatency: number;
  modelUsage: Record<string, number>;
  errorsByType: Record<AIErrorType, number>;
  tokensConsumed: number;
  cacheHitRate: number;
}

// Track AI usage for optimization
const trackAIUsage = async (operation: string, duration: number, success: boolean) => {
  await db.prepare(`
    INSERT INTO ai_usage_logs (operation, duration_ms, success, timestamp)
    VALUES (?, ?, ?, ?)
  `).bind(operation, duration, success, new Date().toISOString()).run();
};

Cost Monitoring

// Monitor token usage for cost optimization
const trackTokenUsage = (prompt_tokens: number, completion_tokens: number) => {
  const total_tokens = prompt_tokens + completion_tokens;
  const estimated_cost = total_tokens * 0.00001; // Approximate cost per token
  
  console.log(`AI Usage: ${total_tokens} tokens (~$${estimated_cost.toFixed(6)})`);
};

Best Practices

Prompt Engineering

  1. Clear Instructions: Specific, unambiguous prompts for consistent results
  2. Context Provision: Include relevant context for better responses
  3. Output Format: Specify exact JSON structure for automated processing
  4. Error Handling: Include instructions for handling edge cases

Performance Optimization

  1. Caching Strategy: Cache frequently requested statement combinations
  2. Batch Operations: Group similar requests for efficiency
  3. Fallback Systems: Multiple layers of fallback for reliability
  4. Rate Limiting: Respect AI service limits and quotas

Security Considerations

  1. Input Validation: Sanitize all user inputs before AI processing
  2. Output Filtering: Validate AI responses before serving to users
  3. Quota Management: Monitor and limit AI usage per user/session
  4. Error Information: Avoid exposing internal AI errors to users

This AI integration provides PadawanForge with powerful, scalable artificial intelligence capabilities while maintaining performance, reliability, and cost-effectiveness through Cloudflare’s edge infrastructure.

← AI Features AI Integration System →
PadawanForge v1.4.1