La alforja: la bolsa doble de montura que carga todo lo del jinete para el camino.
Motor de consulta sobre un portafolio de ingeniería gobernado por un método con artefactos estructurados: 59 repositorios donde los proyectos serios llevan SAD (arc42), decisiones como ADRs, deuda técnica visible como AUD-NNN y fase declarada por topics de GitHub.
Eso cambia el problema. "RAG sobre markdown" es un commodity; un corpus con semántica formal permite algo mejor: tratar el método de trabajo como dato de primera clase.
| Plano | Pregunta típica | Cómo responde |
|---|---|---|
| Semántico | "¿Cómo resolvió Faro la auditabilidad?" | Retrieval dual (Pinecone vectorial ‖ Weaviate híbrido BM25), fusión RRF determinista, síntesis con contrato de citas |
| Estructural | "¿Qué deudas AUD siguen abiertas en todo el portafolio?" | Registros ADR/AUD/fase parseados a Postgres, consultados por un catálogo cerrado de herramientas tipadas — SQL parametrizado y testeado, nunca text-to-SQL |
Un agente con loop acotado (máx. 3 iteraciones) elige el plano — o los combina: SQL localiza, el retrieval expande. Expuesto por CLI, FastAPI y FastMCP (consultable desde Claude Code).
- Toda afirmación lleva cita verificable: permalink de GitHub anclado al commit exacto del snapshot (
.../blob/<sha>/SAD-x.md#L120-L145). La validación rechaza respuestas con afirmaciones sin fuente; ante fallo persistente, la respuesta degrada a extractos citados — nunca a prosa plausible. - Reproducibilidad real: el corpus se congela como snapshot inmutable (hash por archivo, contenido normalizado); hasta los embeddings de las consultas de evaluación se congelan, porque las APIs de embeddings no garantizan determinismo bit a bit.
- Benchmark honesto: en lugar del clásico "Pinecone vs Weaviate" con los mismos embeddings (que solo mide ruido de ANN y latencia de red), un estudio de ablación donde las diferencias sí informan: híbrido vs vectorial (barrido de alpha), chunking arc42-aware vs naïve, contribución de la fusión. Pinecone/Weaviate quedan como notas operacionales.
- Evaluación eval-first: las 31 consultas gold (25 semánticas estratificadas + 6 estructurales) se escribieron antes de construir el pipeline, con fixtures verificados contra el censo real del portafolio.
- Núcleo determinista, probado con propiedades: la fusión y las métricas son funciones puras con property-based tests. Hypothesis ya pagó el boleto: detectó que la suma naïve de floats hacía que el score RRF dependiera del orden de los retrievers en el último bit — corregido con
math.fsumen Fase 0.
| # | Configuración | recall@5 | MRR | p50 | p95 | notas |
|---|---|---|---|---|---|---|
| A1 | Pinecone vectorial · chunking arc42 | — | — | — | — | pendiente |
| A3 | Weaviate híbrido (α ∈ {0.25, 0.5, 0.75}) | — | — | — | — | pendiente |
| A4/A5 | A/B chunking arc42 vs naïve 512 | — | — | — | — | pendiente |
| A6 | Fusión RRF (ambos stores) | — | — | — | — | pendiente |
También pendientes: consulta transversal de gobernanza de ejemplo, demo asciinema con 3 Q&A reales, y el experimento router LoRA vs routing por RAG vs baseline trivial (adapter en Hugging Face) — con hold-out escrito a mano, ≥3 consultas por proyecto.
Clean Architecture sobre el molde Veredicto (FastAPI · Pydantic v2 · SQLAlchemy · injector · FastMCP):
domain/— stdlib-only, hay un test que lo hace cumplir. Entidades inmutables + fusión/scoring/citas como funciones puras.application/— puertos (VectorStorePort,GobernanzaPort,RouterPort, …) y casos de uso.infrastructure/— LlamaIndex confinado a la ingesta; adaptadores propios delgados en el runtime de consulta.- Postgres es la fuente de verdad; los índices vectoriales son derivados y desechables (
make reindex).
docker compose up -d # postgres + weaviate (BYO vectors)
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
make test # 28 tests: sin red, sin API keys
make censo # censo de gobernanza del portafolio (solo GITHUB_TOKEN)Alforja se rige por el mismo método que indexa — es a la vez consumidor y caso de prueba:
SAD-alforja.md— arc42 + 10 ADRs, fuente de verdad; cambia solo por ADR o enmienda versionada (v0.6.0, 3 rondas críticas registradas).docs/AUDIT.md— deuda aceptada (AUD-001..004 con plan de pago) + bitácora de corridas con hashes.docs/CASES.md— 43 casos borde del dominio (10 confirmados con evidencia); ninguna heurística se ajusta sin caso previo.experiments/eval_queries.yaml— el gold set, también fixture de regresión.
MIT.