Crea un sistema que lea documentos subidos y permita a agentes de IA buscar en ellos

## Nombra bien las ramas y separa el código de API, workers y compartido Haga visible la responsabilidad antes de cambiar el código, para que cada comportamiento permanezca en la capa capaz de probarlo y mantenerlo. ### Usar ramas trazables - Nombre las ramas según `type/user/description pattern`. - Mantenga `type` en minúsculas y elija una clase de cambio reconocida, como `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `ci`, `build` o `revert`. - Use en `user` a la persona responsable del trabajo; nunca la sustituya por el nombre genérico de un agente o una herramienta. - Mantenga `description` breve, en minúsculas y con formato kebab-case. ### Separar las responsabilidades de ejecución - Mantenga en paquetes distintos el procesamiento síncrono de la API, el trabajo documental asíncrono, los modelos y servicios compartidos y los aspectos relativos al despliegue. - Coloque la orquestación de puntos de conexión, las reglas de negocio, la persistencia, el análisis, la recuperación y las utilidades genéricas en módulos con responsabilidades explícitas; trate los SDK distribuidos de forma independiente como productos separados. - Cuando un comportamiento abarque varios paquetes, defina primero el contrato compartido y pruebe cada implementación responsable. ## Envía cada archivo subido a un analizador adecuado a su formato Use una canalización por etapas para que cada documento siga una ruta visible desde la carga hasta evidencias de recuperación citables. 1. Acepte la carga, cree un trabajo, persista el objeto de origen y ponga en cola el procesamiento asíncrono. 2. Perfile el documento una sola vez y diríjalo a un analizador según el tipo de archivo y la evidencia estructural. 3. Convierta la salida del analizador en un único contrato tabular tipado. 4. Convierta las filas en registros de fragmentos tipados. 5. Publique el estado del documento, las secciones, los fragmentos y el grafo antes de la recuperación. ### Mantener explícito el enrutamiento de analizadores - Use un único punto de entrada tipado para los analizadores de todos los formatos y devuelva rutas de artefactos locales a la tarea. - Dirija las entradas PDF, DOCX, PPTX, de hojas de cálculo, Markdown, texto, imagen y fragmentos sin procesar mediante estrategias específicas para cada formato; convierta los formatos ofimáticos heredados antes de usar el analizador moderno. - En los PDF, separe la clasificación semántica abierta de las categorías usadas solo para el enrutamiento, como atlas, escaneado, diapositivas y genérico. - Ejecute una sola vez el análisis anatómico de la estructura en el punto de entrada de los documentos sobredimensionados y transfiera el plan de particiones resultante a las etapas posteriores. - Después del análisis, retire las imágenes sin referencias y aplique una compresión de imágenes determinista. ## Detecta la jerarquía de títulos y conserva tablas e imágenes al convertir Determine la estructura a partir de la evidencia disponible más sólida y conserve las tablas, las imágenes y las relaciones entre encabezados durante la conversión. ### Resolver los encabezados por orden de la evidencia 1. Use como fuente de verdad una tabla de contenido incrustada cuando esté disponible. 2. Identifique patrones de numeración explícitos y marcadores de capítulo específicos del idioma. 3. Use un modelo de jerarquía con LLM solo para los encabezados candidatos que sigan sin resolverse. 4. En los PDF con diseños complejos, agrupe la geometría de las fuentes en un conjunto limitado de niveles de encabezado. ### Preservar el comportamiento específico de cada formato - Recorra los elementos del cuerpo de un DOCX en el orden de origen, incluidos párrafos, tablas, imágenes y regiones de la tabla de contenido. - Mantenga una pila de encabezados que cierre los descendientes cuando un encabezado nuevo regrese al nivel del padre. - Convierta las tablas a HTML con valores `rowspan` y `colspan` precisos, y elimine imágenes duplicadas mediante un hash perceptual. - Dirija los PDF estándar a la extracción y al análisis de Markdown; dirija los documentos similares a atlas o sobredimensionados a sus rutas especializadas. - Mantenga el resumen, el reconocimiento de jerarquías, la descripción de imágenes, el OCR y la clasificación general detrás de claves independientes de configuración del modelo. ## Guarda fragmentos, navegación y manifiesto en un formato fijo Trate el corpus persistido como fuente de autoridad; los DataFrames intermedios son detalles transitorios de implementación. ### Almacenar el estado del corpus y de los documentos - Mantenga los metadatos del grafo de todo el corpus y las estadísticas de aciertos de recuperación junto a un directorio por cada documento ingerido. - Persista los fragmentos ordenados, la navegación jerárquica, los metadatos de análisis, el árbol completo de encabezados, los recursos de origen archivados, las imágenes y tablas extraídas y las salidas de diagnóstico. - Use exactamente tres tipos principales de fragmento: `text`, `image` y `table`. - Asigne a cada fragmento un `chunk_id` determinista, contenido tipado, una ruta jerárquica y metadatos de longitud, resúmenes, números de página, tókenes, palabras clave, rutas de archivo y referencias entre fragmentos. ### Preservar las referencias y la navegación - Represente las relaciones insertadas mediante entradas `connect_to` que contengan `target`, `relation`, `ref` y la `position` expresada como desplazamiento de caracteres. - Use `embeds` para los recursos insertados y `related` para las asociaciones no insertadas. - Construya `doc_nav.json` como un árbol de secciones con resúmenes, cantidades de fragmentos, elementos secundarios y recursos de imagen o tabla. - Construya `manifest.json` con metadatos del origen, estadísticas y una `HIERARCHY` anidada. - Convierta las filas transitorias del analizador en cargas útiles de fragmentos tipados antes de escribir `chunks.json`. ## Publica juntos los registros de base de datos, los índices de búsqueda y el grafo Publique una revisión coherente para que los registros relacionales, los canales de búsqueda y las aristas del grafo describan el mismo conjunto de fragmentos. ### Mantener la responsabilidad de los datos relacionales - Almacene en el nivel del documento su identidad, propietario, espacio de nombres, estado, revisión activa y nombre del archivo de origen. - Almacene los vínculos con el padre, las rutas, los títulos, los niveles, los resúmenes y el orden en un árbol de secciones que tenga en cuenta la revisión. - Almacene para cada fragmento los hashes del contenido, los tipos de fragmento, el texto consultable, las rutas de origen, las rutas de los recursos, los metadatos y el orden. - Mantenga los nodos del grafo dentro del ámbito del documento y use aristas no dirigidas cuando representen relaciones simétricas. ### Publicar en una secuencia fija 1. Elimine fragmentos duplicados entre documentos mediante un hash determinista del contenido. 2. Construya las secciones antecesoras a partir de las rutas de los fragmentos, de arriba abajo. 3. Genere para cada fragmento canales separados de búsqueda por contenido, ruta y términos sin procesar. 4. Cree nodos del grafo documental y aristas por coincidencia de palabras clave solo cuando se compartan al menos 3 palabras clave y la puntuación sea de 0.8 como mínimo. Use contenido tokenizado más resúmenes para buscar por contenido, nombres de archivo y rutas de sección tokenizados para buscar por ruta, y contenido y rutas sin procesar para buscar por subcadenas. ## Ofrece búsqueda clásica por ranking y búsqueda con agentes dentro de un presupuesto Separe por responsabilidad la preparación de solicitudes, la búsqueda léxica, la hidratación, el acceso al grafo, las estadísticas de aciertos, la ejecución de flujos de trabajo, la navegación y la representación de evidencias. ### Preservar ambos modos de recuperación - En el modo heredado, combine los canales de ruta, contenido y términos mediante fusión por rango recíproco. - Use los pesos predeterminados `path=1.0`, `content=2.0` y `term=1.5`, con `score = weight / (k + rank + 1)` y `k=60`. - En el modo agéntico, permita que un planificador descomponga las consultas complejas en un DAG de pasos de recuperación; no planifique pasos de síntesis de respuestas dentro de la recuperación. - Imponga un único presupuesto de tókenes para todo el DAG. Cuando se agote, deténgase de forma segura y devuelva las mejores evidencias recopiladas hasta ese momento. - Ejecute el descubrimiento, la navegación de secciones en anchura con restricciones y la representación de evidencias como fases distintas. - Exponga `evidence_text` como respuesta principal y conserve el campo obsoleto `answer_text` únicamente como campo de compatibilidad vacío. ### Hidratar y clasificar deliberadamente - Represente las secciones sin abrir como esquemas de título y resumen, e hidrate los fragmentos `text`, `image` y `table` sin procesar solo para las hojas seleccionadas. - Resuelva de forma nativa los recursos conectados e insértelos en línea sin marcadores de posición frágiles basados en sustitución de cadenas. - Clasifique los resultados del agente primero por `agent_score` y después por `discovery_score`; relegue las filas con `agent_score=0` a un grupo de reserva. - Antes del ensamblaje, excluya los documentos y las secciones indicados y limite el resultado a los tipos de fragmento permitidos. - Adjunte citas que contengan `document_id`, `chunk_id`, `source_file_name` y `section_path`. ## Mantén estables los ID de fragmentos y guarda en caché solo resultados exitosos Haga explícitos los atajos, los identificadores, el orden de las mutaciones y la telemetría para que las optimizaciones no cambien la semántica de la recuperación. ### Mantener resultados reproducibles - Derive los identificadores de fragmento únicamente de un hash estable del contenido textual, sin incluir referencias a imágenes ni tablas, para que el contenido idéntico se deduplique entre cargas. - Planifique primero las mutaciones del DOM y aplíquelas después en orden inverso para evitar desplazamientos de índices. - Elimine las imágenes iguales dentro de un documento mediante un hash perceptual y reutilice sus metadatos almacenados en caché. - Asigne a las imágenes repetidas en posiciones diferentes identificadores deterministas pero únicos y, al buscar contexto textual cercano, avance más allá de los identificadores binarios. ### Limitar los atajos y las cachés - Cuando `total_chunks <= top_k`, devuelva directamente todos los fragmentos mediante una ruta explícita para corpus pequeños. - Almacene en caché por usuario, espacio de nombres, consulta, `top_k` y filtros; verifique la versión de la caché antes de ejecutar y escriba solo después de que la ejecución concluya correctamente. - Registre los aciertos por fragmento y por documento para mejorar la clasificación sin modificar el contenido de origen. - Mantenga registros de ejecución y de pasos que solo admitan anexiones para las acciones, entradas, salidas, latencia y consumo de tókenes del agente. ## Atiende las particularidades de la API del LLM y verifica en local antes de terminar Mantenga explícitas las restricciones de los modelos y las órdenes de verificación local para que los fallos sigan siendo diagnosticables. ### Reforzar las integraciones de modelos - Incluya la palabra `json` al solicitar el modo `json_object` de DeepSeek. - Durante la transmisión, concatene `delta.content` solo cuando no sea `None`. - Rote los tókenes de API dentro de los límites de frecuencia de cada token, aplique períodos de espera y reintente en el mismo punto con el siguiente token disponible. - Mantenga la recuperación limitada a evidencias; los agentes posteriores deciden si estas son suficientes y sintetizan las respuestas fuera del servicio de recuperación. ### Verificar el sistema localmente - Instale desde el espacio de trabajo con versiones fijadas, copie localmente las plantillas de entorno e inicie los servicios necesarios de base de datos, caché, almacenamiento de objetos, API y procesamiento. - Proporcione órdenes de depuración integrales y específicas para el analizador, el perfilador, la jerarquía y el procesamiento agéntico; después ejecute el lint, las correcciones automáticas seguras y las comprobaciones de tipos en los paquetes de API, procesamiento y componentes compartidos. - Verifique la documentación de la API local y los puntos de conexión de los servicios subyacentes antes de diagnosticar fallos de nivel superior en la canalización. - No informe de que el trabajo está terminado hasta obtener resultados directos del analizador afectado, la ruta de publicación, el modo de recuperación y los controles de calidad.