rag-service/RAG/docs/TASK_INGESTA_GSTREAMER.md

Task: Ingesta controlada de corpus GStreamer

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-04-09
Ultima modificacion por: Agente RAG 2
Estado: Ejecutado y validado

---

Proposito

Preparar una ingesta controlada y verificable de la documentacion oficial de GStreamer para usarla como corpus documental especializado dentro del RAG.

El objetivo final no es solo "cargar docs", sino dejar el corpus listo para:

• hacer bootstrap global del dominio GStreamer
• recuperar documentacion oficial de forma fiable
• apoyar a un modelo local en revision y correccion de codigo que use GStreamer

---

Fuente elegida

Fuente principal confirmada:

/home/pancho/Documentos/Empresa/Desarrollo/IA/_imports/gstreamer-rag-text

Motivos:

• la documentacion ya esta normalizada a .txt
• la estructura en carpetas y ficheros es mejor que un monolito para retrieval
• permite recuperar mejor por tema, plugin, elemento o manual
• evita mezclar demasiadas secciones distintas en el mismo chunk

---

Objetivo de modelado del corpus

Todo el corpus debe quedar agrupado bajo un unico scope logico dedicado a GStreamer.

Eso permitira que en el playground aparezca como un scope identificable y seleccionable, en lugar de quedar repartido en multiples scopes pequenos.

Scope recomendado

• sourceRef: gstreamer-official
• sourceId: corpus:gstreamer:official:v1
• mode: mechanical
• chunk mode esperado: documental

Tags recomendados

• gstreamer
• official-docs
• multimedia
• documental

---

Resultado esperado tras la ingesta

Al consultar GET /sources, deberiamos ver un scope similar a:

gstreamer-official [documental]

Y ese scope deberia servir para:

1. hacer bootstrap general del dominio GStreamer
2. recuperar docs sobre plugins, pads, states, negotiation, bus, pipelines, caps, etc.
3. mantenerlo aislado de docs, RAG/docs y RAG/src

---

Riesgos identificados

1. Volumen alto

La fuente contiene miles de ficheros.

Riesgos:

• tardanza alta en la vectorizacion
• errores parciales en una carga masiva
• fallos del playground en una subida tan grande

2. Ruido documental

Los ficheros incluyen restos de navegacion tipo:

• Toggle navigation
• Edit on GitLab
• breadcrumbs y subpages

Esto no impide la ingesta, pero puede introducir ruido semantico.

3. Recuperacion dispersa

Aunque todo quede en un mismo scope, el corpus cubre muchas capas:

• core
• libraries
• plugins
• tutorials
• app manual
• plugin development

Esto obliga a validar retrieval antes de usarlo para tareas reales de depuracion.

---

Estrategia de ejecucion recomendada

Fase 1. Validacion tecnica de la ingesta

Objetivo:

• confirmar que el flujo de ingesta soporta este volumen y formato sin romper

Pasos:

1. revisar y corregir el error actual de ingesta (Cannot read properties of undefined (reading 'map')) si sigue reproduciendose
2. elegir el metodo de ingesta mas fiable para esta carga
3. ejecutar una ingesta controlada con el corpus completo bajo el scope acordado

Fase 2. Verificacion del scope

Objetivo:

• confirmar que el corpus quedo agrupado correctamente

Pasos:

1. comprobar GET /sources
2. verificar que aparece un unico scope de GStreamer
3. comprobar tags y sourceId

Fase 3. Validacion funcional del retrieval

Objetivo:

• asegurar que el RAG devuelve documentacion oficial util, no solo chunks ruidosos

Consultas de prueba sugeridas:

1. "explica la diferencia entre pads static y request pads en GStreamer"
2. "como funciona caps negotiation en GStreamer"
3. "que estados principales tiene un pipeline y como se gestionan"
4. "como enlazar elementos dinamicos y manejar pads-added"
5. "que dice la documentacion oficial sobre bus messages y manejo de errores"

Fase 4. Validacion del bootstrap

Objetivo:

• comprobar que el corpus sirve como mapa inicial del dominio completo

Consulta sugerida:

dame un mapa inicial de la documentacion oficial de GStreamer, sus bloques principales, conceptos nucleares, areas tecnicas y que partes son mas utiles para depurar aplicaciones grandes

Fase 5. Preparacion del flujo con modelo local

Objetivo:

• usar el corpus ya validado como base documental para revisar codigo real

Enfoque recomendado:

1. no pedir al modelo local que revise toda una aplicacion enorme de golpe
2. pasarle modulos o archivos concretos
3. acompañar siempre con:
   • logs de error
   • mensajes de GStreamer
   • sintomas observados
4. usar el RAG como fuente documental oficial, no como sustituto del contexto tecnico del fallo

---

Criterio de exito

La task se considerara bien cerrada cuando se cumplan estas condiciones:

1. la documentacion de GStreamer este ingerida bajo un unico scope reconocible
2. el playground permita seleccionarlo facilmente
3. el bootstrap global funcione sobre todo el corpus
4. el retrieval devuelva documentacion oficial util en consultas de prueba
5. el corpus quede listo para usarse con un modelo local en tareas de revision de codigo

---

Siguiente ejecucion prevista

Si el usuario valida este plan, la siguiente fase sera:

1. diagnosticar y corregir definitivamente el fallo actual de ingesta
2. ejecutar la ingesta real del corpus GStreamer
3. validar retrieval y bootstrap
4. dejar preparado el terreno para la integracion con el modelo local

---

Ejecucion realizada

Resultado real de la ejecucion controlada:

• metodo usado: ingesta local controlada contra la misma Qdrant remota del servicio
• scope final:
  • sourceId: corpus:gstreamer:official:v1
  • sourceRef: gstreamer-official
  • tags: gstreamer, official-docs, multimedia, documental
• documentos procesados: 3117
• chunks almacenados: 22003

Incidencia detectada y corregida

Durante la ingesta aparecio el error:

Cannot read properties of undefined (reading 'map')

Diagnostico:

• no era un fallo generico del corpus completo
• se reproducia en ficheros documentales con bloques desmesurados
• caso detectado: decklink/decklinkvideosink.txt
• ese fichero generaba un chunk de aproximadamente 168061 caracteres, demasiado grande para el proveedor de embeddings

Correccion aplicada en codigo:

• ajuste del chunking documental para trocear correctamente buffers sobredimensionados antes de enviarlos a embeddings
• validacion defensiva adicional en OpenRouterEmbeddingProvider.embed() para detectar respuestas invalidas sin data

Validacion funcional realizada

1. GET /sources

• el scope gstreamer-official aparece correctamente en produccion

2. POST /retrieve con intent=bootstrap

• devuelve un mapa inicial coherente del dominio GStreamer
• referencias principales recuperadas:
  • application-development/introduction/basics.txt
  • application-development/basics/index.txt
  • application-development/introduction/index.txt
  • tutorials/basic/index.txt

3. POST /retrieve con consulta especifica sobre request pads

• devuelve contenido util y oficial sobre:
  • request pads
  • gst_element_get_request_pad
  • gst_element_request_pad_simple
  • tutoriales de pad availability y multithreading

Estado resultante

El corpus de GStreamer ha quedado listo como base documental especializada dentro del RAG para:

• bootstrap general del dominio
• consultas documentales tecnicas
• apoyo posterior a un modelo local en revision de codigo que use GStreamer