Imported from gsiasp-hash/Asistente-clientes-RAG (AGENTS.md). Install upstream with npx skills add gsiasp-hash/Asistente-clientes-RAG. Copyright stays with the author.

AGENTS.md — Guía para agentes de IA en este repositorio

Este archivo existe para que cualquier agente de IA (Claude Code, Cursor, Copilot, opencode, etc.) pueda poner en marcha el proyecto y trabajar sobre él siguiendo las mismas convenciones. Léelo completo antes de ejecutar o modificar nada.

Qué es este proyecto

Asistente de soporte al cliente basado en RAG (Retrieval-Augmented Generation): los usuarios suben PDFs de conocimiento y un chat responde preguntas anclándose únicamente a esos documentos, con respuestas en streaming. Aplicación única Next.js 16 (App Router) en la raíz del repo: frontend React 19 + Tailwind CSS v4 y API mediante Route Handlers, mismo origen sin CORS. Desarrollo en el puerto 3000.

Stack completo, pipeline interno y documentación de la API: README.md.

Puesta en marcha paso a paso

1. Base de datos (Supabase — requiere cuenta gratis)

1. Crear un proyecto en supabase.com
2. En el SQL Editor, ejecutar el contenido completo de supabase/schema.sql (extensión pgvector, tablas document_sections, conversations, messages, sessions, índices y función RPC match_document_sections)
3. Copiar credenciales desde Project Settings → Data API:
   • Project URL: solo el dominio raíz (https://xxx.supabase.co) — NUNCA incluyas /rest/v1
   • service_role secret o secret key sb_secret_... (no la clave anon)

2. Claves de IA

• Groq Cloud (console.groq.com) → API Keys → clave gsk_...
• Google AI Studio (aistudio.google.com/apikey) → Create API key → clave AIza...

3. Configurar entorno

cd server && cp .env.example .env

Completar como mínimo: GROQ_API_KEY, GEMINI_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_KEY. El resto de variables tiene valores por defecto razonables (ver tabla en README). El .env vive en la raíz y Next lo carga automáticamente; en producción las mismas variables se configuran cifradas en Vercel Environment Variables.

4. Instalar y correr

npm install
npm run dev          # http://localhost:3000

5. Validar que todo funciona

npm run verify    # prueba embeddings (Gemini), RPC (Supabase) y modelos (Groq)

Salida esperada: los tres checks con ✓. Si algo falla, el detalle indica qué servicio revisar.

Comandos

Regla de oro: tras cualquier cambio, correr npm run build antes de dar la tarea por terminada.

Arquitectura en una mirada

Ingesta:   PDF → unpdf (pdf.js serverless) → RecursiveCharacterTextSplitter(500/50)
           → Gemini embedContent lote 100 (RETRIEVAL_DOCUMENT) → Supabase document_sections

Consulta:  pregunta → embedding (RETRIEVAL_QUERY)
           → RPC match_document_sections(top 3, globales + sesión propia)
           → prompt anti-alucinación + formato Markdown + historial (10 msgs) + contexto
           → Groq streaming (reasoning_format hidden) → SSE al cliente
           → respuesta persistida con fuentes en messages.sources

Render:    useChatStream (parser SSE) → ChatWindow → MessageBubble
           → asistente vía MarkdownContent (react-markdown + remark-gfm):
             tablas GFM con scroll horizontal, listas y código estilizados;
             usuario = texto plano; cursor de streaming = carácter ▍ inline

Código por capas: src/app/api/*/route.ts (HTTP/SSE, delgados) → src/server/*.ts (services y clientes SDK). La sesión se valida con requireSession(request) dentro de cada handler. Configuración centralizada en src/server/env.ts con validación fail-fast. Las rutas que tocan IA o PDFs declaran runtime = 'nodejs' y maxDuration = 60.

Modelo multi-tenant (importante para cualquier cambio)

• Toda ruta (salvo /api/health) exige header X-Session-Token — validado por src/server/session.ts, que además registra actividad en la tabla sessions
• document_sections.session_id y conversations.session_id: NULL = documento global de demostración (visible a todos); token = privado del visitante
• Subir con header X-Admin-Token igual a ADMIN_TOKEN guarda como global y omite límites
• Límites: 5 documentos y 300 chunks por sesión, 15 mensajes/sesión/día, 50 subidas/día global (utils/rateLimiter.ts, contadores en memoria)
• La limpieza perezosa (session.ts → cleanupService.ts) purga sesiones con throttling de 10 min al validar sesiones (patrón serverless: no hay proceso persistente). Doble criterio: inactivas > SESSION_TTL_HOURS o con vida > SESSION_MAX_AGE_HOURS aunque sigan activas (timeout absoluto anti-acumulación de recursos; requiere sessions.created_at, ya incluida en schema.sql)
• La RPC de búsqueda SIEMPRE recibe p_session_id; initConversation valida ownership (404 si no es tuya)

Blindaje anti-abuso (no retirar sin entender el impacto)

El repo es público y la API está documentada en el README: asume que cualquiera puede llamarla. Capas independientes:

1. Anti-iframe (next.config.ts): X-Frame-Options: DENY + CSP frame-ancestors 'none' en todas las rutas
2. Allowlist de orígenes (src/server/originGuard.ts, env ALLOWED_ORIGINS): si la petición trae header Origin y no está en la lista → 403. Sin Origin (curl, server-to-server) pasa a propósito: el freno real es la capa 3
3. Límite global diario persistido (src/server/globalBudget.ts, env GLOBAL_DAILY_MESSAGE_LIMIT=200): conteo head-only de messages del día en Postgres antes de cada llamada IA → 429 amigable. Requiere el índice idx_messages_created_at (migración supabase/migrations/002). Race condition benigna aceptada (mismo patrón que el presupuesto de chunks)
4. Turnstile (src/server/turnstile.ts + src/components/TurnstileWidget.tsx): siteverify fail-closed valida success, action==='chat' y hostname ∈ TURNSTILE_HOSTNAMES. Si TURNSTILE_SECRET_KEY está vacía se omite (dev local). Tokens de un solo uso: ChatWindow resetea el widget tras cada envío vía resetSignal
5. Cuotas externas: recomendar al dueño configurar límites diarios en Google AI Studio / Groq y Attack Challenge Mode en Vercel

Al añadir una ruta nueva que consuma IA o cuota: llamar assertAllowedOrigin(request) al inicio y registrar contador en rateLimiter; si consume chat, respetar también assertGlobalDailyBudget.

Convenciones del proyecto

1. Todo el copy visible de la interfaz y los mensajes de error van en español
2. Sin comentarios en el código; nombres autoexplicativos
3. Errores HTTP mediante throw new HttpError(status, mensaje) — el errorHandler central los serializa a JSON
4. Los modelos de IA se configuran por .env (EMBEDDING_MODEL, LLM_MODEL), nunca hardcodeados — los proveedores rotan catálogos seguido
5. TypeScript estricto; respetar noUncheckedIndexedAccess

Errores comunes ya resueltos (leer antes de depurar)

Tareas típicas y cómo abordarlas

• "Levanta la app": npm run dev (paso 4), confirmar /api/health y abrir localhost:3000
• "Agrega un endpoint": crear src/app/api/<ruta>/route.ts delgado (validación + HttpError + jsonError) apoyado en un service de src/server/; declarar runtime='nodejs' si usa SDK/PDF; registrar contador de rate-limit si consume cuota de IA
• "Cambie las claves/modelos": actualizar .env (o las Environment Variables de Vercel) y correr npm run verify
• "La BD está vacía/rara": re-ejecutar supabase/schema.sql es destructivo solo si borras datos; preferir migraciones incrementales como archivos SQL nuevos versionados
• Limitaciones aceptadas (documentadas, no bugs): subidas concurrentes de la misma sesión pueden exceder transitoriamente el presupuesto de chunks (sin unique index en session_id, file_name); los contadores de rate-limit viven en memoria y se reinician con cada deploy; un PDF con contenido adversarial podría intentar inyección de prompt en su propia sesión (el contexto no contiene secretos)