Ai Integration

Comprehensive guidelines for AI-assisted development within the Editor platform

AI Integration Documentation

Overview

This document provides information about the AI integration system, including setup, configuration, troubleshooting, and maintenance procedures for both OpenAI and Anthropic APIs.

🔑 API Keys & Configuration

Storage Locations

Security Best Practices

🌐 Proxy Server Architecture

Anthropic Proxy Server

Proxy Server Features

OpenAI Proxy

🔧 Service Configuration

Key Services

  1. AIFactoryService: Main service coordinator
  2. AnthropicService: Handles Anthropic API calls
  3. OpenAIService: Handles OpenAI API calls
  4. AIConfigService: Manages API keys and configuration

Critical Configuration Points

Anthropic Service (libs/gograb-ai/src/lib/services/anthropic.service.ts)

// Message role mapping - CRITICAL
role: msg.role === MessageRole.USER ? 'user' : 'assistant'

AI Factory Service (libs/gograb-ai/src/lib/services/ai-factory.service.ts)

// Model routing - CRITICAL
const service = this.getService(currentProvider); // NOT getBestAvailableService()

Proxy Configuration (apps/ux-test/proxy.conf.json)

{
  "/api/anthropic/**": {
    "target": "http://localhost:3001",
    "secure": false,
    "changeOrigin": true,
    "logLevel": "debug"
  }
}

🚨 Known Issues & Solutions

Issue 1: 404 Errors on Anthropic API

Cause: Anthropic proxy server not running Solution: Start proxy server on port 3001

cd anthropic-proxy && node proxy-server.js

Issue 2: Model Selection Routing Problems

Cause: Using getBestAvailableService() instead of getService(provider) Solution: Ensure sendMessage() uses the correct service selection

const service = this.getService(currentProvider);

Issue 3: 400 Bad Request - Role Mapping

Cause: Sending enum values instead of strings for message roles Solution: Map enum to string values

role: msg.role === MessageRole.USER ? 'user' : 'assistant'

Issue 4: CORS Errors

Cause: Direct API calls from browser Solution: Use proxy servers for all API calls

Issue 5: Connection Timeouts

Cause: Startup connection tests blocking initialization Solution: Skip startup tests, test on first message

// Skip startup connection tests - will test when first message is sent

🏃‍♂️ Startup Procedures

Development Environment Setup

  1. Start Anthropic Proxy: cd anthropic-proxy && node proxy-server.js
  2. Start Angular Dev Server: nx serve ux-test (port 5300)
  3. Verify Proxy: Check http://localhost:3001/api/anthropic/messages

Port Configuration

🧪 Testing Procedures

Manual API Testing

# Test Anthropic API via proxy (use your own API key)
curl -X POST http://localhost:3001/api/anthropic/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_ANTHROPIC_API_KEY" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "max_tokens": 50,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Component Testing

🔍 Debugging Procedures

Console Logging

Key services provide comprehensive logging:

Common Debug Checks

  1. Proxy Server Status: Check if running on port 3001
  2. API Keys: Verify keys are present and valid
  3. Model Selection: Ensure correct provider is selected
  4. Message Format: Verify role mapping is correct
  5. Network: Check proxy configuration and CORS

📦 Dependencies

Required Packages

Custom Implementations

🛠️ Maintenance Procedures

Regular Checks

  1. API Key Rotation: Update keys in AIConfigService
  2. Proxy Server: Ensure running and responding
  3. Database Cleanup: Monitor IndexedDB storage
  4. Log Review: Check for error patterns

Backup Procedures

📋 Success Indicators

Healthy System Logs

✅ AI Factory initialized - ready for requests
✅ OpenAI API response received via proxy
✅ ANTHROPIC SUCCESS: {response data}
✅ Chat configuration loaded successfully

Performance Metrics

🔄 Recovery Procedures

If Anthropic API Fails

  1. Restart proxy server: cd anthropic-proxy && node proxy-server.js
  2. Check API key validity
  3. Verify proxy configuration
  4. Test with curl command

If OpenAI API Fails

  1. Check Angular dev server proxy
  2. Verify API key in storage
  3. Restart Angular dev server if needed
  4. Test with direct API call

If Both APIs Fail

  1. Restart all services
  2. Clear IndexedDB storage
  3. Re-initialize API keys
  4. Check network connectivity

Production Deployment

Unified System Integration

In production mode (port 9200), the AI integration is handled differently:

Railway Environment Variables

Set these environment variables in Railway deployment:

OPENAI_API_KEY=your-openai-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here

API Endpoints

Development (Port 9100)

Production (Port 9200)

⚠️ SECURITY NOTE: Never commit API keys to version control. Always use environment variables or secure storage mechanisms.

💡 TIP: Always test both APIs after any changes to ensure continued functionality.

Last Updated: 2025-01-12 This guide covers both development and production AI integration setups.