Oráculo de EL · Backend Fase 1 — Endpoint + Modo Oracle

Oráculo de EL · Backend Fase 1

Sprint: s72 · Commit: 56463f6 · Fecha: 2026-05-19

El Oráculo de EL es el asistente conversacional del Workspace (workspace.crearack.com). A diferencia del Help Widget de CreaRack Pro (modo help, scope restringido a la app), el Oráculo cubre el universo EsfericLabs completo: CreaRack Pro + Workspace + claude-method + ADRs + incidents + runbooks. Está orientado al equipo interno (Edu, Dani, Txell), no a usuarios finales.

Esta Fase 1 cubre el backend completo. El cableado en la caja de búsqueda del Workspace llega en el siguiente PR (SearchInline híbrido).

Arquitectura

Workspace UI (próximo PR)
        │
        ▼
POST /api/oraculo/ask          ← functions/api/oraculo/ask.ts
        │
        ├── embedTexts(AI, [question])   ← Workers AI · BGE-M3
        ├── searchChunks(env, vec, K=8)  ← Vectorize / D1 fallback (bib_chunks)
        │         SIN filtros app/source_type  ← diferencia clave vs /biblioteca/ask
        └── synthesizeAnswer(..., mode='oracle')  ← Google AI Studio (Gemma 4)
                    │
                    └── buildOraclePrompts()  ← archivo-core.ts

Retrieval: idéntico a /api/biblioteca/ask — embeddings BGE-M3 sobre Cloudflare Vectorize con D1 fallback sobre bib_chunks. La diferencia es que no se aplican filtros de app ni source_type, por lo que el Oráculo ve todo el grafo de conocimiento indexado.

Síntesis: modo oracle en synthesizeAnswer(). System prompt con scope amplio, tono coloquial de compañero de equipo senior, target 100-250 palabras (máx 350).

Telemetría: cada llamada inserta un row en oraculo_queries (migración 0031). Sin almacenar respuestas. Best-effort (si el INSERT falla, no bloquea la respuesta).

Modos de síntesis comparados

Modo	Scope	Audiencia	Chunks	Longitud	Historia
`help`	CreaRack Pro (in-app)	Usuarios finales	✅	80-200 w	❌
`tutor`	IT general (sin grounding)	Equipo ops aprendiendo	❌	libre	✅ multi-turn
`oracle`	Universo EsfericLabs completo	Equipo interno	✅	100-250 w	❌ (Fase 1)

Decisión de diseño: modo separado vs reusar `help`

El system prompt de help está hard-restricted a “in-app help assistant for CreaRack Pro” — el modelo rechaza o frena preguntas sobre Workspace, ADRs, claude-method, etc. Por eso se añadió un modo oracle separado en buildOraclePrompts() con un system prompt de scope-amplio. Documentado en el header de cada builder en archivo-core.ts.

Archivos involucrados

Archivo	Cambio
`functions/api/oraculo/ask.ts`	Nuevo — handler CF Pages Functions
`functions/api/mcp/handlers/archivo-core.ts`	Añade `buildOraclePrompts()` + expande union type `mode`
`migrations/0031_create_oraculo_queries.sql`	Nueva — tabla D1 telemetría

Response shape

{
  "answer": "<markdown string>",
  "sources": [...],
  "model": "gemini-...",
  "chunks_used": 8,
  "duration_ms": 1240
}

Campos de error: { "error": "<mensaje>" } con status 400 / 503 / 500.

Casos de no-match

Si searchChunks devuelve 0 resultados, el endpoint retorna inmediatamente con respuesta predefinida en español (sin llamar a Gemma) y registra el evento en telemetría con sources_count=0.

Estado y próximos pasos

Fase 1: Backend — endpoint + modo oracle + telemetría
Fase 2: SearchInline híbrido (queries cortas → Fuse fuzzy local; preguntas NL → /api/oraculo/ask)
Fase 3 (pendiente definir): historial multi-turn, variantes de modo

Véase también

[[entity—oraculo—endpoint—ask]]
[[entity—oraculo—model—oraculo-queries]]
[[feature—biblioteca—ask-endpoint]]
[[concept—workspace—oraculo-el]]