ArcRift cherry-pick #1: Sentence-trimming + harness A/B en retrieval

Qué

Primera fase de cherry-picks de ArcRift (plan s109: reference_arcrift_evaluation) sobre el RAG del Bibliotecario. Actualmente, bib_ask (Help Widget) y el Oráculo inyectan chunks enteros (hasta ~500 palabras) al prompt de Gemma/Gemini → ruido semántico y desperdicio de tokens. Esta feature añade:

1. Sentence-trimming: Recorta cada chunk a las frases relevantes para la query, conservando contexto ±N frases.
2. Harness A/B (bib_eval_retrieval): Compara baseline (chunks enteros) vs trim sobre preguntas reales, devolviendo métricas reproducibles: tokens en contexto, reducción %, scores y solapamiento de chunk_ids.

Estado de deploy: OFF por defecto. Sin cambio de comportamiento en PROD. El merge solo despliega la capacidad para correr el harness y decidir con datos.

Problema

El retrieval base de la Biblioteca devuelve chunks de hasta ~500 palabras que se inyectan completos al prompt:

• Ruido: Muchas frases del chunk no son relevantes para la pregunta → confunden al LLM.
• Tokens: ~650 tokens extra por pregunta sin valor.
• Decisión suspendida: Sin A/B no sabemos si merece la Fase 3 (small-to-big puro).

Solución

1. Sentence-trimming (trimChunksBySentence)

• Trocea cada chunk en frases respetando estructuras markdown (code blocks, tablas, bullets, blockquotes, abreviaturas).
• Embebe todas las frases en un batch de embeddings (eficiente).
• Puntúa por similaridad coseno contra el vector de la query.
• Reconstruye el content con frases ≥ threshold (+ ventana opcional ±N).
• Garantiza minSentences (las mejores) para no vaciar chunks.
• Marca huecos no contiguos con [...] para mantener legibilidad.

Precisión:

• Respeta abreviaturas (p.ej., etc., Sr., v1.2.3, 192.168.1.1).
• No parte dentro de code blocks ni filas de tabla.
• Parte por . / ! / ? seguidos de mayúscula o apertura.

2. Harness A/B (bib_eval_retrieval)

Tool nueva en tools.ts que:

• Compara variantes (baseline, trim) sobre un golden set.
• Aisla el retrieval: no llama al LLM salvo synthesize=true.
• Devuelve por pregunta: chunk_ids, top_score, tokens antes/después.
• Calcula agregados: reducción %, overlap vs baseline.
• Permite calibrar sin redesplegar: pasar trim_threshold / trim_window por argumento.

Golden set: Las questions pasadas, o si faltan, las últimas 15 reales de oraculo_queries.

Activación

Vía flag de entorno

RETRIEVAL_TRIM=1 RETRIEVAL_TRIM_THRESHOLD=0.38

Activa trimming en bib_ask (Help Widget) y oraculo/ask.ts (Oráculo).

Vía argumento

En bib_ask (MCP tool):

{
  "query": "cómo funciona multi-tenancy",
  "trim": true,
  "trim_threshold": 0.40
}

Correr el harness

{
  "tool": "bib_eval_retrieval",
  "arguments": {
    "top_k": 5,
    "trim_threshold": 0.38,
    "trim_window": 1,
    "synthesize": false
  }
}

Usa las últimas preguntas reales de oraculo_queries, o pasa un set custom de preguntas. Compara métricas baseline vs trim.

Cambios clave

Tipos nuevos

• RetrieveOpts: trim, trimThreshold, trimMinSentences, trimWindow.
• RetrievalResult: chunks, tokensInContext, tokensBefore.
• VariantMetrics: chunk_ids, top_score, tokens, tokens_before, overlap_vs_baseline, answer?.

Flags de entorno (Env)

• RETRIEVAL_TRIM: ‘1’ activa trimming en ambos endpoints.
• RETRIEVAL_TRIM_THRESHOLD: Umbral coseno (default 0.38). Calibrable sin redeploy.

Pruebas

• ✅ tsc --noEmit: Sin errores de tipado.
• ✅ Build Astro: OK.
• ✅ Prettier: OK.
• ✅ Smoke test splitSentences: No parte en v1.2.3, 192.168.1.1, etc., ni dentro de code blocks.
• Próximo paso: Correr bib_eval_retrieval con golden set oraculo_queries y comparar tokens baseline vs trim.

Requisitos para Fase 3

Una vez validado el harness:

1. ¿Token reduction viableƒ (>20%)?
2. ¿Overlap acceptable vs baseline? (>70%)?
3. ¿Mejora de calidad de respuesta o mismo nivel?

Si sí a 1-3 → considerar Fase 3 (small-to-big puro), que daría recortes adicionales re-chunkificando con ventanas más pequeñas.

Véase también

• [[entity—functions—service—split-sentences]]
• [[entity—functions—service—trim-chunks-by-sentence]]
• [[entity—functions—service—retrieve]]
• [[entity—functions—endpoint—bib-eval-retrieval]]
• [[concept—saas—observability]]