Catálogo técnico. Si vas a usar un nombre (tabla, columna, ruta, tipo, tool), búscalo aquí antes de inventarlo.
| tabla | claves notables | nota |
|---|---|---|
profiles |
id (FK a auth.users), email, display_name |
Una fila por usuario, creada por trigger on_auth_user_created |
documents |
id, user_id, title, storage_path, size_bytes, page_count, status, error_message, ingested_at |
status ∈ pending | ingesting | ready | error |
chunks |
id, document_id, user_id, content, chunk_index, page_number, embedding vector(1536) |
Índice HNSW cosine en embedding. user_id denormalizado para RLS rápida |
conversations |
id, user_id, title, updated_at |
Listado en sidebar de /chat |
messages |
id, conversation_id, role, content (jsonb), tool_calls (jsonb) |
role ∈ user | assistant | tool |
ingestion_jobs |
document_id único, user_id, status, attempts, next_attempt_at, locked_at |
Cola durable de PDFs; el worker service-role reclama jobs atómicamente y reintenta hasta max_attempts |
chat_rate_limits |
user_id, window_started_at, request_count |
Ventana fija por usuario; solo se modifica a través de RPC que deriva auth.uid() |
trace_events |
request_id, user_id, stage, latency_ms, tokens, coste, metadata |
Metadatos operativos sin prompts, respuestas ni texto de PDFs |
message_feedback |
user_id, message_id, rating, note |
Una valoración útil/no útil por usuario y mensaje; valida propiedad del mensaje en la ruta API |
RLS activa en todas. Política base: user_id = auth.uid() (en messages, vía join con conversations). ingestion_jobs, chat_rate_limits y trace_events no aceptan mutación directa del cliente fuera de sus rutas/RPCs previstas.
| nombre | firma | uso |
|---|---|---|
match_chunks |
(query_embedding vector(1536), match_threshold float, match_count int, p_user_id uuid, p_document_ids uuid[]) |
Búsqueda vectorial filtrada por usuario. security invoker, respeta RLS |
match_chunks_hybrid |
(query_text text, query_embedding vector(1536), match_count int, candidate_multiplier int, rrf_k int, p_user_id uuid, p_document_ids uuid[]) |
Búsqueda híbrida pgvector + BM25 (tsvector con config simple) fusionada server-side con Reciprocal Rank Fusion. security invoker. Requiere migración 004 |
consume_chat_rate_limit |
(p_limit int, p_window_seconds int) |
Consume una cuota fija para auth.uid() y devuelve { allowed, retry_after_seconds } |
claim_ingestion_job |
(p_worker_id text) |
Reclama un job elegible con FOR UPDATE SKIP LOCKED. Solo service_role |
complete_ingestion_job |
(p_job_id uuid) |
Marca una ingesta completada. Solo service_role |
retry_ingestion_job |
(p_job_id uuid, p_error text, p_retry_delay_seconds int) |
Programa retry exponencial o estado failed. Solo service_role |
| método | ruta | request | response |
|---|---|---|---|
| POST | /api/upload |
multipart/form-data con file |
{ document_id } |
| GET | /api/documents |
— | { documents: Document[] } |
| DELETE | /api/documents/[id] |
— | { ok: true } |
| GET | /api/documents/[id]/status |
— | { status, error_message? } |
| POST | /api/chat |
{ messages, document_ids?, conversation_id? } |
Data stream del AI SDK, cabecera x-conversation-id |
| POST | /api/feedback |
{ message_id, rating, note? } |
{ ok: true }; requiere que el mensaje pertenezca al usuario |
| GET / POST | /api/internal/ingest |
Authorization: Bearer $CRON_SECRET |
Procesa como máximo un job de ingesta; endpoint para Vercel Cron |
| GET | /api/conversations |
— | { conversations: ConversationSummary[] } |
| GET | /api/conversations/[id] |
— | { conversation, messages } |
Definidas en lib/ai/tools.ts y compuestas con createAgentTools(context).
| tool | parámetros | qué hace |
|---|---|---|
search_documents |
query, document_ids?, top_k? |
Si la query menciona una página explícita (pagina 1, page 1), carga chunks por page_number; si no, embedea la query, llama match_chunks y devuelve chunks ordenados con {document_title, page_number, chunk_id} como fuentes. Si el retrieval vectorial queda vacío, usa un fallback léxico genérico (tokens de la query sin stopwords, sin diccionario de dominio) acotado a los documentos permitidos |
generate_quiz |
topic, num_questions, document_ids? |
RAG + generateObject con schema de QuizQuestion[] y fuentes recuperadas |
generate_summary |
document_id, length |
Carga todos los chunks del doc, resumen con generateText y fuente del documento |
generate_flashcards |
topic, num_cards, document_ids? |
RAG + generateObject con schema de Flashcard[] y fuentes recuperadas |
explain_concept |
concept, level, document_ids? |
RAG + generateText con prompt ajustado al nivel y fuentes recuperadas |
mcp-server/ expone las 5 tools del agente como servidor MCP stdio (reutiliza
createAgentTools). mcp-server/context.ts valida el entorno (loadMcpConfig) y
construye el AgentToolContext para un MCP_USER_ID fijo (buildAgentToolContext),
cargando sus documentos ready vía service-role. mcp-server/index.ts registra
cada tool con su mismo schema zod. Script npm run mcp. Detalles y seguridad
(salta RLS, nunca exponer a red) en docs/mcp.md y docs/adr/0003.
Server (secretas):
SUPABASE_SERVICE_ROLE_KEYAI_PROVIDER(defaultopenai, valores:openai|google). Conmuta el proveedor de chat/generación en todo el sistema vía la factoríalib/ai/provider.ts::getChatModel(). Los embeddings NO dependen de esto (siempre OpenAI). Verdocs/adr/0001OPENAI_API_KEY(obligatoria siempre: los embeddings usan OpenAI aunqueAI_PROVIDER=google)OPENAI_CHAT_MODEL(defaultgpt-4o-mini)OPENAI_EMBEDDING_MODEL(defaulttext-embedding-3-small)GOOGLE_GENERATIVE_AI_API_KEY(requerida siAI_PROVIDER=google; API key gratuita en https://aistudio.google.com/apikey)GOOGLE_CHAT_MODEL(defaultgemini-2.0-flash; modelo usado cuandoAI_PROVIDER=google)MAX_UPLOAD_BYTES(default26214400)CHAT_REQUESTS_PER_MINUTE(default20)CHAT_INPUT_COST_USD_PER_MILLIONyCHAT_OUTPUT_COST_USD_PER_MILLION(default0; tarifa configurada para trazas)CRON_SECRET(obligatorio para/api/internal/ingest)ADMIN_EMAILS(lista separada por comas)RAG_RETRIEVAL_MODE(defaultvector, valores:vector|hybrid). Si se ponehybrid, la migración 004 tiene que estar aplicadaRERANK_PROVIDER(defaultnone, valores:none|llm|cohere). Activa la etapa de reranking post-retrievalRERANK_LLM_MODEL(opcional, defaultgpt-4o-mini). Modelo usado por el rerankerllmCOHERE_API_KEY(requerido siRERANK_PROVIDER=cohere)COHERE_RERANK_MODEL(opcional, defaultrerank-multilingual-v3.0)
Cliente (públicas):
NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEYNEXT_PUBLIC_APP_URL
Bucket documents, privado, límite 25 MB, mime permitido application/pdf. Path: <user_id>/<document_id>.pdf. Políticas en supabase/migrations/003_documents_storage.sql.
lib/ai/config.ts (AI_CONFIG):
provider('openai' por defecto, override viaAI_PROVIDER),chatModel,googleChatModel(defaultgemini-2.0-flash),embeddingModel,embeddingDimensions: 1536lib/ai/provider.ts::getChatModel(modelId?): factoría del modelo de chat segúnprovider. ÚNICO punto que importa el SDK de proveedor (@ai-sdk/openai/@ai-sdk/google); migrar a Vertex se hace solo aquírag:chunkSizeTokens=700,chunkOverlapTokens=100,matchThreshold=0.5,matchCount=8,retrievalMode('vector' por defecto, override viaRAG_RETRIEVAL_MODE),hybridRRFConstant=60,hybridCandidateMultiplier=4,rerankProvider('none' por defecto, override viaRERANK_PROVIDER),rerankCandidatePoolMultiplier=3,rerankLlmModel(override viaRERANK_LLM_MODEL)agent:maxSteps=5,maxTokensPerResponse=2000limits:maxUploadBytes,maxQuizQuestions=20,maxFlashcards=30
Harness offline en evals/. Mide el pipeline RAG core (embed → match_chunks → generateText) contra un dataset etiquetado y reporta retrieval (recall@k, MRR, hit_rate@k), generation (faithfulness, answer_relevancy via LLM-as-judge) y latencia.
| archivo | rol |
|---|---|
evals/dataset.jsonl |
Casos: {id, question, ground_truth_answer, ground_truth_chunk_ids[], document_ids[]} |
evals/types.ts |
Schemas zod y tipos del reporte |
evals/metrics.ts |
recallAtK, meanReciprocalRank, hitRateAtK, average, percentile (puras) |
evals/judge.ts |
LLM-as-judge: judgeFaithfulness, judgeAnswerRelevancy |
evals/pipeline.ts |
runPipeline(supabase, userId, question, documentIds) |
evals/runner.ts |
CLI entry, ejecutable con npm run eval |
evals/compare.ts |
Compara dos RunReport con configs distintas (modo o reranker), ejecutable con npm run eval:compare |
evals/results/ |
<timestamp>_<mode>_<rerank>_<provider>.json por run, gitignored |
Detalles operativos en evals/README.md.
app/
(auth)/ login, callback OAuth
(app)/ rutas autenticadas: chat, documents, admin
api/ route handlers
components/
chat/ ChatInterface, ToolCallDisplay
documents/ UploadButton, DeleteDocumentButton, DocumentsPolling
auth/ LoginForm
lib/
supabase/ client.ts, server.ts, admin.ts, types.ts (generado)
ai/ chunker, embeddings, ingest, ingestion-jobs, tools, retrieval, rerank, prompts, provider, config
observability/ traces de metadatos operativos
chat/ persistence (conversations + messages)
evals/ harness offline (npm run eval)
mcp-server/ servidor MCP stdio sobre las tools del agente (npm run mcp)
supabase/migrations/ 001 schema, 002 match_chunks, 003 storage, 004 hybrid, 005 reliability