rag-service/RAG/docs/BITACORA_DISENO_RAG.md

Bitacora de diseño del RAG

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-04-02
Ultima modificacion por: Agente tools IA para potenciar servicios empresariales
Estado: Activa

---

Proposito

Esta bitacora registra el camino de diseño que estamos siguiendo para construir el RAG.

No se limita a guardar decisiones finales. Tambien recoge:

• como se llego a una decision
• por que se prefirio una opcion frente a otra
• que posibilidades quedan abiertas para mas adelante
• que vision general da sentido al resto de documentos del modulo

Su funcion es servir como panorama vivo del diseño del RAG.

---

Vision general actual

El RAG que se esta diseñando no busca ser una demo cerrada ni una herramienta pensada solo para este workspace.

La intencion es crear una base reutilizable que pueda:

• integrarse con proyectos de clientes
• potenciar agentes y soluciones con IA ya existentes
• servir tanto para conocimiento empresarial como para desarrollo de software
• crecer hacia un modelo de servicio consumible por distintas herramientas

La carpeta docs/ del workspace solo se usara como primer caso real de prueba, no como limite conceptual del sistema.

Otro criterio ya explicitado es que las decisiones de la v1 deben tomarse como base estable y duradera del sistema. La evolucion futura debe venir por ampliacion de capacidades, no por sustituir continuamente decisiones nucleares ya cerradas.

---

Casos de uso principales aceptados

1. Agente experto en empresa

El RAG debe poder ayudar a un agente a atender clientes durante venta, postventa, soporte y seguimiento.

Eso implica que el sistema debe poder aportar contexto sobre:

• empresa
• productos
• servicios
• formas de trabajo
• empleados, areas y responsabilidades
• informacion relevante para atender correctamente al cliente

2. Agente experto en proyecto o desarrollo

El RAG debe poder dar a un agente una vision util de un proyecto para:

• iniciar un desarrollo desde cero
• continuar un proyecto existente
• retomar proyectos de terceros
• comprender tecnologia, arquitectura, metodos y estructura interna
• desarrollar nuevas funcionalidades bien integradas con lo que ya existe

---

Decisiones y razonamiento acumulado

El RAG no debe limitarse a pregunta y respuesta

Decision: El sistema no se diseñara solo como pregunta -> respuesta.

Por que:

• los casos de uso reales requieren dar contexto util a agentes, no solo contestar preguntas
• en desarrollo y continuidad de proyectos, el mayor valor esta en cargar panorama y contexto rico
• para atencion al cliente tambien puede ser util devolver contexto y no solo respuesta final

Consecuencia: La salida del RAG debe contemplar al menos recuperacion de contexto, y no solo respuesta sintetizada.

---

El RAG debe poder funcionar como servicio

Decision: La base de acceso principal se esta pensando como API o endpoint.

Por que:

• facilita que otras apps, agentes y soluciones lo consuman
• permite pruebas inmediatas desde terminal
• encaja bien con una futura capa MCP
• es mas util para integracion que pensarlo primero como libreria interna

Posibilidad abierta:

• MCP como forma estandar de conexion a sistemas de IA
• CLI como capa opcional de uso interno o pruebas

Decision tecnica posterior vinculada a esta direccion: La v1 se orienta a un stack basado en Node.js + TypeScript + Express + Qdrant, con API HTTP como base principal y proveedor de embeddings desacoplado.

Matiz importante ya detectado: Desacoplar el proveedor de embeddings no evita que cambiar de modelo obligue normalmente a reindexar el contenido afectado.

Lo correcto sera:

• registrar con que proveedor, modelo y dimensiones se genero cada embedding
• mantener trazabilidad de la version de indexacion
• evitar mezclar embeddings de modelos distintos dentro de la misma logica de recuperacion

Decision cerrada posterior: Se adopta Qwen3 Embedding 8B como modelo base estable del sistema.

Por que se cierra asi:

• el usuario quiere que las decisiones nucleares de la v1 nazcan como base duradera
• el modelo encaja con recuperacion textual y de codigo
• ofrece una via realista de arranque ahora y despliegue local despues
• encaja mejor con la estrategia general del RAG que un modelo puramente comercial y dependiente de proveedor cerrado

Referencia comparativa mantenida: OpenAI text-embedding-3-large se conserva como referencia de calidad y comparacion, pero no como decision principal del sistema.

---

La arquitectura debe separar entrada y salida

Decision: Se ha aceptado que el RAG tiene al menos dos grandes usos operativos:

• entrada de informacion
• salida de informacion por consulta o recuperacion de contexto

Por que:

• ambas tareas son distintas y complementarias
• ayudan a pensar el sistema con responsabilidades claras
• permiten dejar preparada una arquitectura robusta y ampliable

Ampliacion ya detectada: Tambien se considera necesario un futuro subsistema de actualizacion del conocimiento.

---

Debe existir una via futura para actualizacion y versionado

Decision: Aunque no se implementara de entrada, el sistema debe nacer preparado para manejar contenido cambiante.

Por que:

• el conocimiento empresarial y tecnico no es estatico
• parte de la informacion puede cambiar, quedar obsoleta o dejar de ser valida
• un RAG robusto no puede asumir que todo lo ingerido vale para siempre

Idea asociada en exploracion: Una inspiracion parecida a git puede ser util para pensar el historico, la vigencia y la actualizacion incremental del conocimiento.

---

El modelo no solo participa en la salida, tambien puede participar en la entrada

Decision en formacion: Se deja claro que, cuando hablamos de uso de modelo, no nos referimos solo al modelo que consumira el contexto del RAG en consulta.

Tambien se contempla un modelo que participe en el proceso de entrada de informacion al RAG.

Por que:

• un modelo puede ayudar a entender documentos de calidad irregular
• puede identificar tema, estructura y puntos clave
• puede enriquecer la informacion que entra al sistema antes de indexarla

Criterio adoptado:

• no conviene depender desde el inicio de modelos caros para esta fase
• puede existir mas adelante un modelo fijo y economico dentro del pipeline de ingesta
• tambien queda abierta una fase posterior con una interfaz interactiva de alimentacion, en la que el usuario pueda elegir un modelo mas potente para procesar mejor ciertas entradas

Direccion que sugiere esta idea:

• fase basica: ingesta principalmente mecanica y economica
• fase posterior: ingesta asistida por modelo
• fase mas avanzada: ingesta interactiva con eleccion de modelo segun necesidad

Matiz posterior aceptado: La arquitectura debe nacer preparada para recibir parametros que indiquen si la ingesta va en modo basico o en modo enriquecido/interactivo.

La idea es que:

• si no llegan parametros especiales, el sistema opere por defecto de forma mecanica y con su modelo predefinido
• si llegan parametros desde una interfaz, el sistema pueda cambiar de modelo o recibir directrices y marcado del usuario

Consecuencia positiva de este enfoque: Permite que el sistema crezca hacia una ingesta mas rica sin exigir una reescritura posterior del flujo base.

---

Identidad del conocimiento por niveles

Decision: Se ha aceptado una jerarquia de identificacion con tres niveles:

• source_id
• document_id
• chunk_id

Por que:

• no basta con identificar solo la carpeta o fuente global
• los cambios reales suelen ocurrir a nivel de documento
• los chunks son unidades de recuperacion, no la identidad principal del conocimiento

Decision relacionada: Los documentos sueltos tambien tendran source_id mediante una fuente logica por defecto, evitando valores nulos.

Propuesta concreta ya aceptada como base de trabajo:

• source_id: src:<tenant>:<source_kind>:<source_name>
• document_id: doc:<source_id>:<document_key>
• chunk_id: chk:<document_id>:<chunk_mode>:<chunk_index>

Por que esta forma parece adecuada:

• mantiene legibilidad humana
• deja espacio para multi-tenant desde ahora sin obligar a usarlo plenamente
• separa bien fuente, documento y chunk
• permite distinguir tambien el modo de chunking en el identificador del fragmento

Aclaracion importante sobre tenant: En este diseño, tenant significa el espacio logico de separacion de datos dentro del servicio RAG.

No obliga a que desde el primer dia haya varios clientes activos, pero evita que la arquitectura quede cerrada a un unico contexto.

Usar default al inicio permite trabajar simple hoy y quedar preparados para mañana.

Hallazgo practico posterior: Una misma coleccion vectorial puede servir varias fuentes distintas siempre que queden bien separadas por identificadores y por alcance de consulta.

Ejemplo ya probado:

• docs/ del workspace como documentacion global
• RAG/docs/ como documentacion propia del modulo RAG

La separacion operativa actual se hace por sourceRef y source_id dentro del scope de consulta.

Esto demuestra en pequeno el mismo patron que luego servira para separar clientes, proyectos o dominios dentro del mismo sistema.

Decision complementaria sobre document_key: Se adopta como regla base que el documento se identifique por una clave interna normalizada, preferiblemente relativa a la fuente.

La idea es:

• usar rutas relativas cuando existan
• usar nombres normalizados para documentos sueltos
• usar referencias estables para fuentes externas o derivadas

Por que esta decision completa bien el esquema:

• evita depender de rutas absolutas locales
• mantiene IDs legibles y estables
• hace posible tratar con la misma logica archivos, PDFs sueltos, APIs documentales u otras fuentes futuras

Matiz adicional aceptado: document_key no sustituye al localizador real del fichero o recurso. Su papel es servir como identidad interna estable dentro del sistema.

---

Metadatos minimos aceptados

Decision: Se ha aceptado como base este conjunto:

• source_id
• source_type
• source_path o source_ref
• document_id
• chunk_id
• title
• updated_at
• hash
• status
• version
• tags

Por que:

• equilibran simplicidad y preparacion para evolucion
• permiten trazabilidad
• preparan el sistema para cambios y actualizaciones futuras
• evitan tener que rediseñar demasiado pronto el modelo de datos

---

Chunking: una sola estrategia como implementacion inicial, pero no como vision final

Decision: Se empezo aceptando una estrategia comun de chunking para la v1 por simplicidad.

Matiz importante posterior: Dado que el RAG tambien servira para desarrollo de software, la vision final no debe quedarse en un unico chunking universal.

Conclusion actual: La arquitectura debe quedar preparada al menos para dos modos:

• documental
• codigo

Aclaracion importante: El modo codigo no se deja de lado como direccion del sistema. Sigue siendo parte del objetivo del RAG por su uso previsto en desarrollo de software.

Lo que se prioriza primero es cerrar y construir una v1 documental estable para arrancar antes, sin renunciar a incorporar despues el modo codigo sobre una arquitectura ya preparada.

Decision posterior ya implementada: El modo codigo ha quedado implementado en la v1 con:

• soporte de extensiones tecnicas habituales
• chunking por bloques top-level
• retrieve filtrable por mode: codigo
• answer con referencias de bloque y rango de lineas cuando aplica

Prueba funcional ya realizada: se ingirio RAG/src/ y se respondio correctamente a una consulta real sobre como se construye source_id en el sistema.

Por que:

• documentacion y codigo no se parten ni se recuperan igual de bien
• un chunking puramente documental podria aprovechar mal el codigo fuente
• el objetivo del sistema exige servir a ambos mundos

Matiz importante ya asumido: Cambiar de forma relevante la estrategia de chunking en el futuro implicara normalmente reprocessar e indexar de nuevo la informacion afectada.

Esto no invalida avanzar con una v1 simple, pero refuerza la idea de elegir una base suficientemente solida desde ahora.

Decision ya cerrada para el modo documental de la v1:

• cortar primero por estructura natural
• subdividir por parrafos cuando haga falta
• usar corte por longitud solo como ultimo recurso
• trabajar con una referencia aproximada por caracteres
• aplicar overlap pequeno y fijo

Valores elegidos para arrancar:

• objetivo aproximado: 1500 caracteres
• maximo aproximado: 2200 caracteres
• overlap aproximado: 200 caracteres

Por que se cierran ya estos valores:

• permiten construir la v1 sin seguir aplazando decisiones basicas
• mantienen una complejidad baja
• ofrecen una base razonablemente estable para documentacion normal
• dejan abierta una futura variante documental_largo para libros o contenido tecnico extenso

---

Seleccion de modo: enfoque hibrido

Decision: La seleccion del modo debe ser hibrida.

Forma acordada:

• el consumidor puede indicar el modo explicitamente
• si no lo hace, el sistema intenta inferirlo

Por que:

• combina control y comodidad
• evita obligar a multiples interfaces separadas demasiado pronto
• permite a un agente elegir segun el contenido o dejar que el sistema ayude

Modo base previsto:

• documental
• codigo
• auto

---

La salida del RAG debe contemplar contexto, no solo respuestas

Decision: Se consideran validos al menos estos tipos de salida conceptuales:

• retrieve
• answer
• opcion intermedia de contexto mas sintesis

Por que:

• el mayor valor para agentes de desarrollo esta en recuperar contexto rico y trazable
• atencion al cliente puede beneficiarse de contexto mas respuesta sintetizada
• una salida solo orientada a respuesta dejaría corto el sistema para los usos previstos

Decision posterior ya implementada: answer se monta sobre retrieve, no como un camino independiente.

Por que:

• mantiene una arquitectura mas limpia
• obliga a que la respuesta final siga dependiendo del contexto recuperado
• hace visible que mejorar retrieve mejora tambien answer

Ajuste posterior relevante: retrieve specific se ha afinado para preguntas operativas frecuentes mediante subconsultas y reordenacion por intencion.

Efecto visible: mejora respuestas como la consulta de pendientes del workspace, que ahora ya baja a lineas concretas del backlog en lugar de quedarse solo en la descripcion general del documento.

---

Retrieve inicial y retrieve especifico

Decision en formacion: Se ve mucho valor en separar:

• un retrieve inicial o de arranque
• un retrieve especifico para profundizar

Idea del retrieve inicial: Debe comportarse como un mapa del dominio, no como una respuesta en detalle.

Ese mapa deberia incluir:

• vision general
• temas principales
• puntos criticos
• estructura o areas
• referencias para profundizar

Aporte adicional aceptado: Algunas piezas podran marcarse explicitamente como criticas para que el sistema les de prioridad en ese contexto inicial.

Por que:

• evita saturar al modelo con demasiado detalle desde el principio
• da orientacion general al agente
• permite usar consultas posteriores para profundizar solo donde haga falta

Decision posterior ya estructurada: El retrieve inicial queda entendido como un paquete de contexto de arranque con esta estructura base:

• mode
• intent
• summary
• topics
• critical_points
• items
• follow_up_refs
• scope

Sentido de esta estructura:

• combina panorama general y trazabilidad
• sirve tanto a agentes conversacionales como a agentes de desarrollo
• permite pasar de una carga inicial de contexto a una profundizacion posterior sin perder el mapa del dominio

Matiz posterior aceptado: El retrieve, y en especial el bootstrap, debe poder recibir un alcance explicito para cargar solo el contexto de una fuente concreta, por ejemplo un workspace o proyecto determinado.

Decision posterior ya implementada: El bootstrap deja de comportarse como una sola busqueda ampliada y pasa a usar varias subconsultas internas para construir un mapa inicial mas util.

Por que:

• mejora la cobertura del contexto de arranque
• recupera mejor documentos base como indice, README, pendientes o historial
• se ajusta mejor al objetivo de volver rapidamente experto a un agente sobre un workspace o proyecto concreto

---

Posibilidades abiertas que siguen vivas

• integrar el RAG con MCP como canal de conexion a sistemas de IA
• potenciar el RAG con Obsidian como posible fuente, capa de organizacion o entorno complementario de conocimiento
• usarlo como servicio comun para distintos clientes y aplicaciones
• permitir mejoras del motor que beneficien a todos los consumidores del servicio
• evolucionar hacia algun tipo de historico o versionado inspirado en ideas parecidas a git
• introducir estrategias especificas de chunking por tipo de documento o fuente
• ampliar el modo documental con soporte especializado para PDFs complejos o escaneados mediante OCR si llegara a hacer falta
• definir memoria base de sesion mas retrieves dinamicos posteriores

---

Los PDFs entran en la v1

Decision: Los PDFs no se aplazan. Deben estar soportados desde la primera version del sistema.

Por que:

• en entornos reales de empresa y proyectos, mucha informacion relevante llega en PDF
• dejarlos fuera desde el inicio recortaria demasiado el valor practico de la v1
• el objetivo del RAG es ser util desde pronto en escenarios reales, no solo con Markdown o texto plano

Matiz importante: El soporte inicial se entiende para PDFs con texto extraible. PDFs escaneados o de mala calidad podran requerir despues una capa adicional de OCR o tratamiento especializado.

---

Pendientes inmediatos del diseño

1. Definir como se construiran exactamente source_id, document_id y chunk_id.
2. Definir la estrategia concreta del chunking inicial.
3. Definir que debe devolver exactamente retrieve.
4. Definir que bloques tendra el retrieve inicial tipo mapa de dominio.
5. Definir como se accedera a los servicios minimos del RAG desde la API.
6. Definir si la ingesta asistida por modelo estara presente desde la v1 o quedara para la siguiente fase.

---

Rol de esta bitacora dentro del modulo

Los otros documentos del modulo deben ir recogiendo decisiones concretas por areas.

Esta bitacora, en cambio, debe conservar la panoramica del camino seguido:

• que se quiere construir
• para que se quiere construir
• como se esta razonando el diseño
• que se decide ahora
• que se deja abierto para mas adelante