AI Models Reference & Configuration

🎯 Purpose

This document serves as:

1. Model Version Tracker - Current and historical AI model versions
2. Change Log - Track when models change/deprecate
3. Configuration Guide - How to update models across the monorepo
4. Troubleshooting - Common model-related issues and solutions

🚨 Critical: Model Deprecations (October 2025)

⚠️ BREAKING CHANGE: Claude 3.5 Sonnet Models Retired

Effective Date: October 28, 2025

Deprecated Models (No longer available):

• ❌ claude-3-5-sonnet-20241022
• ❌ claude-3-5-sonnet-20240620
• ❌ claude-3-5-sonnet-latest (alias)

Migration Path:

• ✅ Use claude-sonnet-4-5-20250929 (latest, Sept 2025)
• ✅ Use claude-3-opus-20240229 (legacy, but stable and works everywhere)

If you're still using deprecated models, you'll see:

Status: 404
Error: {"type":"not_found_error","message":"model: claude-3-5-sonnet-20241022"}

🚨 Recent Issues & Solutions

Issue: November 20, 2025 - Model Version Compatibility

Problem: Multiple model versions returned 404 errors

Status: 404
Error: {"type":"not_found_error","message":"model: claude-3-5-sonnet-latest"}
Error: {"type":"not_found_error","message":"model: claude-3-5-sonnet-20241022"}
Error: {"type":"not_found_error","message":"model: claude-3-5-sonnet-20240620"}

Root Cause: Claude 3.5 Sonnet models were DEPRECATED on October 28, 2025

Solution: Use claude-3-opus-20240229 (legacy but widely available and stable)

Files Updated:

• apis/backend-api/src/app/ai/ai-models.config.ts - Centralized config
• tools/scripts/translation/fully-automated-translator.js - Removed hardcoded model
• libs/libs-ai/gograb-ai/src/lib/models/ai-models.ts - Updated model list

Verification: Successfully translated "Poop-1" → "Caca 1" using Claude 3 Opus

Lesson Learned:

1. Claude 3.5 models are DEPRECATED - Use Claude 4.5 or Claude 3 instead
2. Never use -latest aliases - They point to unpredictable models
3. Use dated versions - Explicit control and compatibility
4. Test with legacy models first - e.g., claude-3-opus-20240229 works everywhere
5. Check deprecation notices - Anthropic retired Claude 3.5 with minimal notice

📚 Current Model Versions (Updated November 20, 2025)

Anthropic (Claude)

Model Availability by API Tier

🔴 Critical Information: Not all Claude models are available for all API keys. Availability depends on:

• API Tier: Free, Build ($5/mo), Scale (volume-based)
• Region: Some models may be region-restricted
• Account Status: Newer accounts may have limited access

Production Models (Verified November 2025)

Model Naming Convention

claude-{version}-{variant}-{YYYYMMDD}

Examples:
✅ claude-3-opus-20240229        (stable, works for all tiers)
✅ claude-3-sonnet-20240229      (stable, works for all tiers)
✅ claude-3-haiku-20240307       (stable, works for all tiers)
⚠️ claude-3-5-sonnet-20241022    (requires higher API tier)
⚠️ claude-3-5-sonnet-20240620    (requires Build tier+)
❌ claude-3-5-sonnet-latest      (avoid - points to restricted model)

Best Practices:

1. Use dated versions (not -latest) for production
2. Test model availability with your specific API key before deploying
3. Start with Claude 3 models (20240229/20240307) - they work everywhere
4. Upgrade models gradually after verifying access

API Tier Comparison

Note: This information is based on November 2025 testing. Always verify with Anthropic's pricing page for current details.

OpenAI (GPT)

Production Models (Updated November 20, 2025)

Deprecated Models (No longer available):

• ❌ gpt-4.5 - Discontinued August 7, 2025
• ❌ gpt-4.1 - Replaced by GPT-5

Notes:

• All current OpenAI models are generally available
• Pricing shown as: Input / Output per 1M tokens
• GPT-5.1 is the latest flagship with personality options

Model Naming Convention

gpt-{version}-{variant}

Examples:
✅ gpt-4-turbo-preview
✅ gpt-4
✅ gpt-3.5-turbo

Google (Gemini)

Production Models (Updated November 20, 2025)

Deprecated/Removed Models:

• ❌ gemini-2.0-flash-exp - Replaced by Gemini 3
• ❌ gemini-pro-vision - Use Gemini 1.5+ instead

Notes:

• Gemini 3 released 2 days ago (Nov 18) with enhanced coding and reasoning
• All Gemini models support multimodal (text + images)
• Massive context windows (1-2M tokens)
• No tier restrictions - available to all users
• Extremely cost-effective, especially Flash models

Model Naming Convention

gemini-{variant}

Examples:
✅ gemini-pro
✅ gemini-pro-vision

🎯 Model Selection Guide

Decision Tree: Which Model Should I Use?

START
│
├─ Need vision/image analysis?
│  ├─ YES → Use: gpt-4o, gemini-1.5-pro, gemini-2.0-flash-exp
│  └─ NO → Continue
│
├─ Need massive context (>200K tokens)?
│  ├─ YES → Use: gemini-1.5-pro (2M), gemini-1.5-flash (1M)
│  └─ NO → Continue
│
├─ Need deep reasoning/thinking?
│  ├─ YES → Use: claude-opus-4-20250514 (if tier allows), o1-preview
│  └─ NO → Continue
│
├─ Budget priority?
│  ├─ HIGH (need cheapest) → Use: gemini-1.5-flash-8b, gpt-4o-mini, claude-3-haiku
│  ├─ MEDIUM (balance) → Use: claude-3-opus-20240229, gpt-4o, gemini-1.5-flash
│  └─ LOW (quality first) → Use: claude-opus-4, gpt-4o, claude-3-5-sonnet
│
├─ Speed priority?
│  ├─ CRITICAL → Use: gpt-4o-mini, gemini-1.5-flash-8b, claude-3-haiku
│  ├─ IMPORTANT → Use: gemini-1.5-flash, gpt-4o-mini
│  └─ NOT CRITICAL → Any model
│
└─ Task type?
   ├─ Translation → claude-3-opus-20240229 ✅ (verified working)
   ├─ Code generation → gpt-4o, claude-3-5-sonnet, gemini-2.0-flash
   ├─ Long documents → gemini-1.5-pro, claude-3-opus
   ├─ Chat/conversation → gpt-4o, claude-3-5-sonnet
   └─ Data analysis → gemini-1.5-pro, gpt-4o, claude-3-opus

Model Performance Comparison

Cost Comparison (per 1M tokens)

Real-World Example (1,000 translations, 100 tokens each):

• gemini-1.5-flash-8b: ~$0.02
• gpt-4o-mini: ~$0.08
• claude-3-opus: ~$9.00

Speed Comparison (Typical Response Times)

🔧 Centralized Model Configuration

Configuration File Location

Primary: apis/backend-api/src/app/ai/ai-models.config.ts

// apis/backend-api/src/app/ai/ai-models.config.ts
export const AI_MODELS_CONFIG = {
  anthropic: {
    default: 'claude-3-5-sonnet-latest',
    translation: 'claude-3-5-sonnet-latest',
    reasoning: 'claude-3-opus-latest',
    fast: 'claude-3-haiku-latest',
  },
  openai: {
    default: 'gpt-4-turbo-preview',
    fast: 'gpt-3.5-turbo',
  },
  google: {
    default: 'gemini-pro',
    vision: 'gemini-pro-vision',
  },
} as const;

export type AnthropicModel = typeof AI_MODELS_CONFIG.anthropic[keyof typeof AI_MODELS_CONFIG.anthropic];
export type OpenAIModel = typeof AI_MODELS_CONFIG.openai[keyof typeof AI_MODELS_CONFIG.openai];
export type GoogleModel = typeof AI_MODELS_CONFIG.google[keyof typeof AI_MODELS_CONFIG.google];

Usage Across Monorepo

// In any service
import { AI_MODELS_CONFIG } from './ai-models.config';

const model = AI_MODELS_CONFIG.anthropic.translation; // 'claude-3-5-sonnet-latest'

📍 Where Models Are Used

Backend API

File: apis/backend-api/src/app/ai/ai.service.ts

// Line ~93
const model = request.model || 'claude-3-5-sonnet-latest';

Usage:

• Translation requests
• General AI completions
• User-facing AI features

Translation Scripts

File: tools/scripts/translation/fully-automated-translator.js

// Line ~287
model: 'claude-3-5-sonnet-latest',

Usage:

• Automated translation system
• Batch translation operations

Future: Centralized Config (Recommended)

Create libs/libs-ai/ai-config/src/lib/models.config.ts:

export const AI_MODELS = {
  translation: {
    provider: 'anthropic',
    model: 'claude-3-5-sonnet-latest',
  },
  codeGeneration: {
    provider: 'openai',
    model: 'gpt-4-turbo-preview',
  },
  imageAnalysis: {
    provider: 'google',
    model: 'gemini-pro-vision',
  },
} as const;

🔍 How to Update Models Globally

Step 1: Check Current Usage

# Find all model references
grep -r "claude-3" apps/ tools/ libs/
grep -r "gpt-" apps/ tools/ libs/
grep -r "gemini" apps/ tools/ libs/

Step 2: Update Configuration

If using centralized config:

// Update one place
AI_MODELS_CONFIG.anthropic.translation = 'claude-3-5-sonnet-latest';

If NOT centralized (current state):

1. Update apis/backend-api/src/app/ai/ai.service.ts
2. Update tools/scripts/translation/fully-automated-translator.js
3. Search for other usages

Step 3: Test Changes

# Restart backend
yarn serve:backend

# Test translation
yarn translate:fix

# Test AI endpoint
curl -H "Authorization: Bearer $SYSTEM_TOKEN" \  # Set from .env.local
  -H "Content-Type: application/json" \
  -X POST http://localhost:3000/api/ai/anthropic/messages \
  -d '{"messages":[{"role":"user","content":"test"}],"model":"claude-3-5-sonnet-latest","maxTokens":5}'

🐛 Troubleshooting Model Issues

Error: "model: {model-name}" (404)

Symptoms:

Status: 404
Error: {"type":"not_found_error","message":"model: claude-3-5-sonnet-20241022"}

Diagnosis:

1. Most Common: Your API key tier doesn't have access to this model
2. Model version doesn't exist for any tier
3. Model name is misspelled
4. Provider deprecated the model
5. Regional restrictions

Solution:

Step 1: Verify API Tier Access

# Test with a known-working model first
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-opus-20240229","messages":[{"role":"user","content":"test"}],"max_tokens":10}'

# If this works, your key is valid but may have tier restrictions

Step 2: Try Alternative Models (in order of availability):

1. claude-3-opus-20240229 (works for all tiers) ✅
2. claude-3-sonnet-20240229 (works for all tiers) ✅
3. claude-3-haiku-20240307 (works for all tiers) ✅
4. claude-3-5-sonnet-20240620 (requires Build tier+) ⚠️
5. claude-3-5-sonnet-20241022 (requires Scale tier+) ⚠️

Step 3: Update Configuration

// apis/backend-api/src/app/ai/ai-models.config.ts
anthropic: {
  default: 'claude-3-opus-20240229', // Safe default
  translation: 'claude-3-opus-20240229', // Verified working
}

Step 4: Check Account Tier

• Visit https://console.anthropic.com/settings/billing
• Verify your current tier (Free, Build, Scale)
• Check model availability for your tier

Error: "invalid x-api-key" (401)

Symptoms:

Status: 401  
Error: {"type":"authentication_error","message":"invalid x-api-key"}

Diagnosis:

1. API key is wrong/expired
2. API key has extra whitespace
3. API key not set in .env.local

Solution:

1. Check .env.local has correct key
2. Ensure no quotes or spaces
3. Create fresh key if needed

Error: Rate Limit (429)

Symptoms:

Status: 429
Error: {"type":"rate_limit_error"}

Solution:

1. Add retry logic with exponential backoff
2. Reduce request frequency
3. Upgrade API tier

📖 Provider Documentation Links

Anthropic

• Models: https://docs.anthropic.com/claude/docs/models-overview
• API Reference: https://docs.anthropic.com/claude/reference/messages_post
• Console: https://console.anthropic.com/

OpenAI

• Models: https://platform.openai.com/docs/models
• API Reference: https://platform.openai.com/docs/api-reference
• Console: https://platform.openai.com/

Google AI

• Models: https://ai.google.dev/models/gemini
• API Reference: https://ai.google.dev/api/rest
• Console: https://aistudio.google.com/

🔄 Model Version History

2025-11-20: Model Compatibility Resolution ✅

Changes:

• Discovered -latest and Sonnet 3.5 models incompatible with API key
• Switched to claude-3-opus-20240229 (stable, widely available)
• Updated centralized config (ai-models.config.ts)
• Removed hardcoded model from translation script
• Verified working: Successfully translated "Poop-1" → "Caca 1"

Current Working Models:

• Anthropic: claude-3-opus-20240229 ✅ TESTED & WORKING
• OpenAI: gpt-4-turbo-preview (not tested yet)
• Google: gemini-pro (not tested yet)

What Worked:

1. Used dated version instead of -latest
2. Rebuilt backend after config change (nx build backend-api)
3. Removed model parameter from translation script
4. Let backend use centralized default

Performance:

• Translation Time: 3.41s for 2 keys
• Cost: ~$0.0006 per translation (Opus pricing)
• Success Rate: 100% (2/2 keys translated)

✅ Best Practices

1. Always Use Dated Versions (Not "latest")

// ❌ BAD - Points to tier-restricted model
model: 'claude-3-5-sonnet-latest'

// ✅ GOOD - Explicit, verifiable, works everywhere
model: 'claude-3-opus-20240229'

// ⚠️ RISKY - May require higher tier
model: 'claude-3-5-sonnet-20241022'

Why Avoid -latest?

• Points to newest model (often tier-restricted)
• Breaks when new models are released
• Hard to debug ("latest changed yesterday")
• Different behavior for different API tiers

Why Use Dated Versions?

• Explicit and verifiable
• Consistent across all environments
• Easy to debug and document
• Predictable behavior

2. Centralize Configuration

// ✅ Good - one place to update
import { AI_MODELS_CONFIG } from './config';
const model = AI_MODELS_CONFIG.anthropic.translation;

// ❌ Bad - scattered hardcoded values
const model = 'claude-3-5-sonnet-latest'; // duplicated everywhere

3. Add Error Handling

// ✅ Good - catches model issues
try {
  const response = await callAI(model);
} catch (error) {
  if (error.status === 404) {
    logger.error(`Model ${model} not found. Check models-information.md`);
  }
}

4. Log Model Usage

// ✅ Good - helps debugging
logger.log(`Using model: ${model} (provider: ${provider})`);

🚀 Roadmap

Phase 1: Current State (✅ Complete)

• Document current models
• Fix invalid model references

Phase 2: Centralized Config (📋 Planned)

• Create libs/libs-ai/ai-config
• Migrate all services to use centralized config
• Add TypeScript types for type safety

Phase 3: Dynamic Model Selection (📋 Planned)

• Select model based on task complexity
• Automatic fallback to cheaper models
• Cost optimization

Phase 4: Monitoring (📋 Planned)

• Track model usage and costs
• Alert on model deprecation
• Performance metrics per model

📝 Change Log Template

When updating models, add entry here:

### YYYY-MM-DD: Brief Description

**Changes**:
- What changed
- Why it changed
- Impact

**Models Updated**:
- Provider: old-model → new-model

**Files Modified**:
- path/to/file1.ts
- path/to/file2.js

**Testing**:
- How was it tested
- Results

🆘 Need Help?

1. Check Provider Docs: Links above
2. Check This Doc: Model versions and common issues
3. Check Backend Logs: Detailed error information
4. Create Issue: Document new issues here

Last Updated: November 20, 2025 - 1:25 PM
Session ID: 11.25.1.1
Maintainer: AI Agents / Development Team