rag-service/RAG/docs/SALIDA.md

Salida

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: En definicion

---

Proposito

Definir como sale el conocimiento del sistema RAG hacia los consumidores, especialmente en forma de contexto util para agentes, aplicaciones y soluciones con IA.

---

Vision general

La salida del RAG no se limita a responder preguntas.

El sistema debe poder:

• recuperar contexto util
• ofrecer un mapa inicial de conocimiento
• devolver respuesta apoyada en contexto cuando haga falta

Esto responde a los dos grandes casos de uso aceptados:

• agentes expertos en empresa
• agentes expertos en proyecto o desarrollo

---

Tipos de salida contemplados

Se consideran validos estos tipos de salida conceptuales:

1. retrieve

• devuelve contexto recuperado

2. answer

• devuelve una respuesta apoyada en contexto

3. context_plus_summary

• devuelve contexto mas una sintesis util

En la practica, retrieve es la pieza clave para la v1, porque es la base que permite contextualizar agentes y otras herramientas.

---

Modo answer

answer se apoya en retrieve.

Flujo aplicado:

1. recuperar contexto relevante
2. construir un prompt con resumen y citas del contexto recuperado
3. pedir a un modelo de respuesta que conteste usando solo ese contexto
4. devolver la respuesta junto con citas y trazabilidad minima

Estructura esperada

• mode
• intent
• answer
• summary
• topics
• criticalPoints
• citations
• scope

Por que se diseña asi

• mantiene a retrieve como nucleo del sistema
• evita que la respuesta se desconecte del contexto recuperado
• permite que el mismo RAG sirva tanto para cargar contexto como para responder directamente
• conserva trazabilidad para revisar de donde sale la respuesta

Limite importante

La calidad de answer depende directamente de la calidad de retrieve.

Si la recuperacion no trae el fragmento concreto adecuado, la respuesta puede quedar demasiado prudente o incompleta aunque el modo answer funcione correctamente.

En modo codigo, answer incluye tambien sectionTitle y rango de lineas cuando estan disponibles.

---

Mejora aplicada a retrieve specific

Para consultas operativas frecuentes, retrieve specific ya no se limita a una sola busqueda semantica directa.

Se ha mejorado con:

• subconsultas internas segun la intencion detectada
• reordenacion por alineacion con la pregunta
• refuerzo de documentos especialmente relevantes para ciertos casos, como backlog, reglas, historial o indice documental

Objetivo de esta mejora:

• que preguntas practicas como "que tenemos pendiente" o "cuales son las reglas" lleguen antes a los fragmentos verdaderamente utiles
• mejorar answer sin tener que cambiar su arquitectura

Tambien se ha ampliado para consultas tecnicas o conceptuales del modo codigo, por ejemplo preguntas sobre funciones, IDs, servicios, endpoints o flujo interno.

---

Retrieve inicial y retrieve especifico

Se adopta esta separacion conceptual:

1. retrieve inicial o de arranque

• entrega un mapa general del dominio
• orienta al agente sobre el panorama del conocimiento disponible
• no busca profundizar en exceso

2. retrieve especifico

• profundiza en un tema, duda o necesidad concreta
• recupera contenido mas cercano a la consulta puntual

---

Estructura acordada para retrieve inicial

Se adopta esta estructura base para el retrieve inicial.

1. mode

Indica el modo de recuperacion aplicado.

Valores previstos:

• documental
• codigo
• auto

Por que se incluye:

• permite trazabilidad de como se hizo la recuperacion
• ayuda al consumidor a entender el tipo de lectura aplicada

2. intent

Indica la intencion de la recuperacion.

Valores previstos:

• bootstrap
• specific

Para el retrieve inicial, el valor esperado es bootstrap.

Por que se incluye:

• separa claramente el mapa inicial de una consulta puntual
• evita confundir una carga de contexto general con una busqueda de detalle

3. summary

Resumen corto del contexto recuperado.

Por que se incluye:

• da una lectura rapida del panorama general
• permite al agente orientarse sin tener que leer todos los fragmentos completos de inmediato

4. topics

Lista de temas principales detectados.

Por que se incluye:

• ayuda a que el agente tenga un mapa tematico del dominio
• sirve como guia para decidir en que profundizar despues

5. critical_points

Lista de puntos criticos o prioritarios.

Estos puntos pueden salir de dos vias:

• inferidos por el sistema
• marcados explicitamente como criticos en las fuentes o durante la ingesta

Por que se incluye:

• algunos temas deben mantenerse visibles aunque el resumen general sea breve
• permite priorizar conocimiento especialmente sensible o importante

6. items

Lista de fragmentos o piezas recuperadas.

Cada item debe poder incluir como minimo:

• chunk_id
• document_id
• source_id
• title
• content
• score

Por que se incluye:

• es la parte trazable y reutilizable del contexto
• permite que un agente o sistema no dependa solo de una sintesis
• mantiene acceso a las piezas concretas del conocimiento recuperado

7. follow_up_refs

Referencias o pistas para profundizar despues.

Pueden apuntar a:

• temas
• documentos
• secciones
• preguntas sugeridas

Por que se incluye:

• convierte el retrieve inicial en una guia de navegacion
• facilita pasar de un mapa general a una consulta especifica sin perder el hilo

8. scope

Permite acotar la recuperacion a una fuente, workspace, proyecto o conjunto de tags concreto.

Campos previstos:

• sourceId
• sourceRef
• tags

Por que se incluye:

• evita que el bootstrap o la consulta especifica carguen contexto de todo el sistema cuando solo interesa un workspace o proyecto
• prepara el RAG para convivir con multiples fuentes sin mezclar panoramas
• hace util el retrieve inicial como carga contextual enfocada, no solo global

---

Que representa realmente este retrieve inicial

No es una respuesta final.

Es un paquete de contexto de arranque pensado para:

• dar orientacion general
• volver experto al agente en ese dominio durante la sesion de trabajo
• servir como base para posteriores consultas especificas

Su papel es parecido al de una carga inicial de contexto o mapa operativo del conocimiento.

---

Estrategia aplicada al retrieve inicial

El bootstrap no debe limitarse a ejecutar una sola busqueda semantica amplia.

Se adopta una estrategia de recuperacion orientada a mapa inicial:

• lanzar varias subconsultas relacionadas con panorama general, documentacion principal, pendientes y reglas del dominio
• fusionar resultados sin duplicar chunks
• ordenar los fragmentos priorizando relevancia y utilidad panoramica
• sintetizar un resumen final que ayude a orientarse rapido

Por que se decide asi:

• un retrieve inicial necesita mas cobertura que una consulta puntual
• una sola consulta suele dejar fuera piezas clave del mapa general
• combinar subconsultas mejora la calidad del contexto de arranque sin cambiar el modelo de embeddings ni la base vectorial

Resultado esperado:

• mejor identificacion de documentos base
• mejor panorama del workspace o proyecto
• referencias mas utiles para profundizar despues

---

Por que se ha elegido esta estructura

• porque el RAG debe servir para mucho mas que preguntas aisladas
• porque el usuario quiere que un agente pueda arrancar con una vision rica del tema o proyecto
• porque un mapa inicial ayuda a profundizar despues sin saturar contexto desde el principio
• porque mezcla panorama, criticidad, trazabilidad y capacidad de profundizacion posterior

---

Ajustes futuros posibles

Aunque esta estructura queda aceptada para la v1, se asume que en la practica podria requerir ajustes.

Posibles cambios futuros:

• afinar el nivel de detalle de summary
• separar mejor topics y critical_points
• enriquecer items con mas metadatos
• hacer que follow_up_refs sea mas estructurado
• incorporar niveles de confianza o explicacion de relevancia

La estructura actual se acepta como una base suficientemente clara para empezar a construir y evaluar.