CreaRack-SL

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

Vista limpiaEditar
Funcionalidadactivecreado Tue May 19#workspace#oraculo#biblioteca#conversational-ai#cloudflare#workers#d1#gemini

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

ModoScopeAudienciaChunksLongitudHistoria
helpCreaRack Pro (in-app)Usuarios finales✅80-200 w❌
tutorIT general (sin grounding)Equipo ops aprendiendo❌libre✅ multi-turn
oracleUniverso EsfericLabs completoEquipo 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

ArchivoCambio
functions/api/oraculo/ask.tsNuevo — handler CF Pages Functions
functions/api/mcp/handlers/archivo-core.tsAñade buildOraclePrompts() + expande union type mode
migrations/0031_create_oraculo_queries.sqlNueva — 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]]

Referenciado desde

Inicio
Yo