AI Backend — Introducción

¿Qué es el AI Backend?

apps/ai-backend es un microservicio NestJS independiente que actúa como motor de IA de la academia. Es la única pieza del sistema que habla directamente con los proveedores LLM (Anthropic, OpenAI, Gemini).

Regla absoluta (CLAUDE.md): NUNCA llamar LLMs directamente desde apps/api o apps/web. Toda IA pasa por apps/ai-backend.

Posición en la arquitectura

graph LR
  Web["apps/web\n(React)"] -->|REST| API["apps/api\n(NestJS :3000)"]
  API -->|HTTP interno\n+ AIBACKEND_API_KEY| AIB["apps/ai-backend\n(NestJS :3001)"]
  AIB -->|SDK| Anthropic["Anthropic\nclaude-sonnet-4-5"]
  AIB -->|SDK| OpenAI["OpenAI\ngpt-4o / gpt-4o-mini"]
  AIB -->|SDK| Gemini["Gemini\ngemini-1.5-pro / flash"]
  AIB -->|REST| Qdrant["Qdrant\nVector DB"]
  API -->|Prisma| DB["Neon PostgreSQL"]
  AIB -->|Lee credenciales| API

Puerto y autenticación

Parámetro	Valor
Puerto	`3001` (configurable con `PORT`)
Auth	Header `x-internal-key: $AIBACKEND_API_KEY`
Guard	`InternalAuthGuard` en todos los endpoints

El AIBACKEND_API_KEY es un secret compartido entre apps/api y apps/ai-backend. Mínimo 32 caracteres.

Stack del microservicio

Dependencia	Versión	Uso
`@anthropic-ai/sdk`	^0.36.0	Cliente Anthropic Claude
`openai`	^4.77.0	Cliente OpenAI GPT + Embeddings
`@google/generative-ai`	^0.21.0	Cliente Gemini
`@qdrant/js-client-rest`	^1.13.0	Cliente Qdrant Vector DB
`@nestjs/axios`	^4.0.0	HTTP para llamar a Fluency API

Variables de entorno

PORT=3001
NODE_ENV=development

# Secret compartido con apps/api (mínimo 32 caracteres)
AIBACKEND_API_KEY=internal-secret-min-32-chars-here

# Clave maestra AES-256-GCM para cifrado de credenciales (64 chars hex)
# Generar: openssl rand -hex 32
# IMPORTANTE: misma clave en apps/api y apps/ai-backend
AI_CREDENTIALS_MASTER_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# URL de Fluency API (para leer AIRouteConfig y AICredential)
FLUENCY_API_URL=http://localhost:3000

# URL de Qdrant (la API key va en BD, no aquí)
QDRANT_URL=https://your-cluster.qdrant.io

PROVIDER_TIMEOUT_MS=15000
FALLBACK_TIMEOUT_MS=10000