Este repositorio contiene la interfaz de usuario interactiva desarrollada en Streamlit para interactuar con el Agente de Inteligencia Artificial enfocado en la infraestructura de Foro Hub. La aplicación implementa una arquitectura RAG (Retrieval-Augmented Generation) local para responder consultas técnicas precisas basándose en el entorno real de despliegue.
- Interfaz de Chat Fluida: Basada en los componentes nativos de chat de Streamlit para una experiencia limpia y responsiva.
- Contexto RAG de Infraestructura: El agente consume el archivo
contexto_infraestructura.txtpara responder con datos reales del entorno sin recurrir a alucinaciones genéricas. - Seguridad Anti-Bots (Honeypot Nativo): Implementación de una trampa de seguridad oculta mediante un sistema de pestañas (
st.tabs) asimétricas. El input de confirmación es invisible para usuarios humanos pero completamente expuesto para scrapers y bots automatizados, mitigando spam y ataques dirigidos. - Despliegue Aislado: Configurado para convivir de forma segura con entornos modernos de Python 3.13.
El agente está entrenado para dar soporte sobre la siguiente arquitectura de infraestructura documentada en el contexto local:
-
Servidor Web: Nginx actuando como proxy inverso en el puerto 8000.
-
SO del Servidor: Ubuntu Server alojado en la nube de Oracle Cloud Infrastructure (OCI) (Instancia Always Free).
-
Cifrado: Certificados SSL administrados y renovados mediante Let's Encrypt y Certbot.
-
Dominio Público: https://foro-hub-christian.duckdns.org/api/swagger-ui/index.html.
-
Backend Relacionado: API REST desarrollada con Spring Boot 3.x y Java 21.
-
Persistencia y Conexión de Datos: Base de datos Oracle Cloud (26ai) de alta disponibilidad (@forohubdb_high). Utiliza credenciales cifradas con Oracle Wallet dinámico mediante la siguiente configuración externalizada:
Properties
# CONFIGURACION DE CONEXION (ORACLE 26ai)
# ==========================================
# La ruta usa ${user.dir} para que funcione en cualquier PC donde descargues el proyecto
spring.datasource.url=jdbc:oracle:thin:@forohubdb_high?TNS_ADMIN=${TNS_ADMIN_PATH}
spring.datasource.username=ADMIN
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
├── agent_frontend.py # Script principal de la aplicación Streamlit.
├── contexto_infraestructura.txt # Base de conocimiento RAG con la topología de la app.
├── README.md # Documentación del proyecto (este archivo).
└── requirements.txt # Dependencias del entorno Python.
- Requisitos Previos
- Python 3.11 o superior (Testeado con éxito en Python 3.13).
- Clonación del Repositorio y Configuración del Entorno
Abre tu terminal y ejecuta los siguientes comandos para descargar el proyecto y aislar sus dependencias en un entorno virtual (
.venv):
bash
# Clonar el repositorio
git clone [https://github.com/cris959/rag-updater-streamlit.git](https://github.com/cris959/rag-updater-streamlit.git)
cd rag-updater-streamlit
# Crear el entorno virtual (Venv)
python -m venv .venv
# Activar el entorno virtual
# En Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# En Linux/macOS:
source .venv/bin/activate
# Instalar los paquetes requeridos
pip install -r requirements.txt
-
Configurar la Base de Conocimiento Asegurate de que el archivo contexto_infraestructura.txt contenga los datos actualizados del pipeline de despliegue, entidades JPA, reglas de negocio del foro y configuraciones del proxy inverso.
-
Lanzar la Aplicación Ejecutá el servidor local de Streamlit:
Bash
streamlit run agent_frontend.py
Abre tu navegador en http://localhost:8501 para interactuar con el frontend.
Para evitar peleaduras con las restricciones de inyección de CSS/JS en iFrames aislados de las últimas versiones de Streamlit, la trampa anti-bots se despliega utilizando contenedores de layouts nativos:
Python
tab_principal, tab_sistema = st.tabs(["💬 Chat", " "])
with tab_principal:
# Renderizado normal del historial de chat y chat_input
pass
with tab_sistema:
# Input trampa expuesto en el DOM pero fuera de la vista humana
honeypot_field = st.text_input("Confirm email (dejar en blanco)", value="", key="email_confirm")
Si un script automatizado intenta rellenar masivamente los campos detectados en el DOM, el backend detectará que el valor de key="email_confirm" no está vacío y procederá a rechazar o bloquear la sesión del atacante.
Este proyecto consiste en una aplicación interactiva desarrollada en Streamlit que implementa una arquitectura RAG (Retrieval-Augmented Generation) y un sistema de enrutamiento inteligente multi-agente. La plataforma asiste al desarrollador en tareas críticas de infraestructura, migración de código y optimización de bases vectoriales.
Implementamos un flujo donde una cadena router (router_chain) analiza la consulta del desarrollador en milisegundos y la deriva dinámicamente al agente especialista ideal:
- Agente Foro Hub e Infraestructura Cloud (Gemini 2.5 Flash): Diseñado específicamente para asistir en la gestión del backend de proyectos locales como Foro Hub, leyendo bases de conocimiento contextuales locales (
CONTEXTO_FOROHUB_TXT). - Agente LangChain Migrator (Buscador Web Avanzado + Mistral Large): Especializado en la actualización viva de sintaxis de Python y LangChain. Implementa un pipeline híbrido de búsqueda: utiliza DuckDuckGo API para el descubrimiento de URLs oficiales y lo integra dinámicamente con el motor de Jina AI Reader (
r.jina.ai). Esto permite scrapear y transformar la documentación web compleja en Markdown ultra-limpio en tiempo real, garantizando que Mistral Large procese el código de refactorización con el contexto exacto de las últimas versiones de la librería. - Agente Arquitecto RAG (FAISS + Qwen/DeepSeek): Analiza estrategias complejas de fragmentación, embeddings y rendimiento consultando una base de datos vectorial local en
./data/rag_knowledge_base.
Para solucionar la "inercia de tokens" en temas de DevOps (donde los modelos tendían a responder en inglés al procesar documentación técnica o bases vectoriales nativas en ese idioma), se integró un mecanismo de control desde la interfaz de usuario:
- Punto 1 (UI Selector): Se añadió un componente
st.radioen la barra lateral (with st.sidebar) para que el desarrollador defina de forma explícita el idioma de salida de la aplicación (Español / English). - Punto 2 (Inyección de Prompt): El pipeline intercepta la selección y concatena una instrucción mandatoria (
[INSTRUCCIÓN DE SALIDA OBLIGATORIA]) con formato de bloques delimitados ([...]), forzando respuestas 100% monolingües sin importar el idioma del contexto inyectado.
- Se migraron los endpoints obsoletos o discontinuados de la API v1beta de Google hacia la familia
gemini-2.5-flashpara evitar errores404 NOT_FOUND. - Se implementaron filtros de advertencias (
warnings.filterwarnings) para silenciar logs e interferencias de consola provocadas por el renombrado interno del paqueteduckduckgo_search(DDGS).
A continuación se detalla cómo interactúan los componentes desde que ingresas una consulta en la interfaz de Streamlit hasta que el agente especialista genera la respuesta en el idioma seleccionado:
flowchart TD
A["Christian ingresa consulta en Streamlit"] --> B("Captura de idioma desde Sidebar: idioma_seleccionado")
B --> C{"Router_Chain: Clasifica consulta"}
C -->|FOROHUB| D["Agente Foro Hub / Gemini 2.5 Flash"]
C -->|MIGRATOR| E["Agente LangChain Migrator / Mistral Large"]
C -->|RAG_OPTIMIZER| F["Agente Arquitecto RAG / Qwen"]
D --> G["Inyecta Contexto Local Foro Hub"]
E --> H["Buscador Web: DuckDuckGo + Scraper Jina AI r.jina.ai"]
F --> I["Consulta Base Vectorial local: FAISS"]
G --> J["Aplica Bloque: INSTRUCCIÓN DE SALIDA OBLIGATORIA"]
H --> J
I --> J
J --> K{"¿Idioma es Español?"}
K -->|Sí| L["Fuerza respuesta 100% Monolingüe en Español"]
K -->|No| M["Fuerza respuesta 100% Monolingüe en English"]
L --> N["Renderiza st.markdown en pantalla"]
M --> N
N --> O["Guarda Historial de Sesión e Incrementa Métricas"]
Para mantener el repositorio liviano, seguro y evitar la fuga de índices binarios pesados que cambian constantemente en el entorno de desarrollo, aplicamos una estrategia de desacoplamiento de datos:
data/(Ignorado): Esta carpeta contiene los índices vectoriales reales de FAISS (index.faisseindex.pkl) y las bases de datos ficticias de la app. No se sube a GitHub. Se genera y actualiza localmente en cada entorno ejecutando el script de inicialización.data_ejemplo/(Subido al Repo): Contiene archivos de configuración y estructuras de muestra con consultas mock. Sirve como plantilla para que el pipeline sepa qué formato esperar al desplegar la aplicación desde cero.
Si clonas el proyecto en un entorno nuevo (o al desplegar en el servidor Ubuntu de OCI), debés ejecutar el script de parseo y embeddings para reconstruir la carpeta data/ y sus índices:
# Generar los índices FAISS locales en la carpeta /data
python actualizar_db.py
# Levantar el frontend interactivo con Streamlit
streamlit run agent_frontend.py
- Base de Datos de Transición (Mock/Local DB): Configuramos una base de datos ficticia/local estructurada para simular el almacenamiento de credenciales, logs e historial de consultas. Este diseño desacoplado nos permite validar la lógica de los agentes y el comportamiento del backend localmente, garantizando una migración limpia y sin fricciones antes de conectar los servicios productivos una vez que subamos la aplicación a la infraestructura de Oracle Cloud Infrastructure (OCI)
El Panel de Control Multi-Agente ha sido completamente contenedorizado utilizando Docker y Docker Compose, lo que garantiza un entorno de producción aislado, ligero y replicable, ideal para el despliegue en instancias "Always Free" de Oracle Cloud Infrastructure (OCI).
- Optimización de Dependencias: Se reestructuró el archivo
requirements-prod.txtpara solucionar conflictos de dependencias cruzadas con el ecosistema de LangChain (ResolutionImpossible). Además, se fijó una versión estable del conector de búsquedas (duckduckgo-search) libre de compiladores nativos de Rust (cargo/maturin), reduciendo drásticamente el peso y el tiempo de construcción de la imagen Docker. - Seguridad Avanzada (Honeypot Anti-Bots): Se integró una trampa nativa invisible (email_confirm) para interceptar y bloquear scripts automatizados. El sistema de ocultamiento visual se fijó de forma quirúrgica mediante selectores avanzados de CSS (div[data-testid="stTextInput"]:has(...)) apuntando directamente al placeholder e id interno del componente. Esto garantiza que el Honeypot quede 100% aislado en las sombras dentro de Docker sin interferir con el renderizado reactivo ni bloquear el flujo de respuestas del chat principal.
- Interfaz Bilingüe: Se rediseñó el componente global de entrada de datos (
st.chat_input), ofreciendo una experiencia de usuario (UX) más intuitiva que explicita el soporte nativo de procesamiento técnico tanto en Español como en Inglés.
Para levantar el entorno con las últimas optimizaciones de dependencias e interfaz, ejecutar en la raíz del proyecto:
bash
# Construir la imagen desde cero y levantar los servicios
docker compose up --build
# Levantar el contenedor en segundo plano (Modo producción)
docker compose up -d
# Detener los servicios por completo
docker compose down
El proyecto se encuentra completamente desplegado, operativo y accesible de forma segura en un entorno de producción en la nube.
- Hosting: Instancia ARM (Oracle Cloud Infrastructure - OCI) con sistema operativo Ubuntu Server.
- Contenerización: El frontend bilingüe de la aplicación está empaquetado y corriendo de forma aislada mediante Docker en el puerto interno
8501. - Servidor Web y Proxy Inverso: Se configuró Nginx para actuar como proxy inverso unificado. Esto permite que el backend (Java/Spring Boot - Foro Hub) y este nuevo frontend (Streamlit) convivan bajo el mismo dominio de forma armónica.
- Seguridad y SSL: Se implementaron certificados criptográficos de Let's Encrypt (vía Certbot). Toda la comunicación externa está forzada mediante HTTPS.
El servidor Nginx actúa como selector de rutas bajo el dominio principal:
https://foro-hub-christian.duckdns.org/➔ Direcciona al backend original en Java (Foro Hub).https://foro-hub-christian.duckdns.org/rag/➔ Direcciona mediante WebSockets seguros al contenedor de Streamlit (Agente RAG) en el puerto8501.
- Honeypot Integrado: Se implementó una trampa silenciosa (campo oculto) en el frontend para detectar, invalidar y bloquear automáticamente solicitudes automatizadas de bots y scrapers malignos.
- Firewall por Capas: Tráfico regulado tanto a nivel interno del sistema operativo (
iptables/netfilter-persistenten Ubuntu) como a nivel perimetral de la nube mediante las Listas de Seguridad (Ingress Rules) en la VCN de OCI para los puertos80,443y8501.
Este módulo implementa un sistema de Generación Aumentada por Recuperación (RAG) integrado con un Agente Inteligente, utilizando Oracle Autonomous Database en la nube como motor persistente y vectorial, y Streamlit como interfaz de usuario.
El proyecto está completamente dockerizado y diseñado bajo estándares de seguridad para entornos productivos.
Actualmente, el sistema cuenta con las siguientes implementaciones clave:
- Motor Vectorial Nativo: Conexión robusta en modo Thin a Oracle Cloud (OCI), validando la persistencia e indexación de fragmentos en la base de datos a través de la tabla
RAG_KNOWLEDGE_BASE. - Enrutamiento Inteligente (Decision Router): Implementación de lógica en el backend para la selección dinámica de modelos de Inteligencia Artificial según el contexto y complejidad de la consulta del usuario.
- Telemetría en Tiempo Real: Sistema de auditoría integrado que registra cada interacción, modelo seleccionado y longitud de respuesta en la tabla
TELEMETRIA_AGENTESpara un monitoreo continuo del rendimiento del RAG. - Infraestructura Desacoplada y Segura: Dockerización completa del frontend y backend mediante
docker-compose, aislando las credenciales mTLS de la Wallet de Oracle y centralizando la configuración mediante variables de entorno (.env).
La aplicación web permite interactuar con el Agente Inteligente en tiempo real, procesando las consultas mediante el motor RAG.
Monitoreo nativo dentro de la base de datos OCI. A la izquierda, la persistencia de embeddings en RAG_KNOWLEDGE_BASE; a la derecha, el log dinámico del Decision Router en TELEMETRIA_AGENTES.
Para maximizar el rendimiento del Agente, la base de datos se configuró bajo un esquema híbrido que resuelve tres necesidades críticas del sistema:
- Gestión de Embeddings (Chunks de Conocimiento): Evidencia de la fragmentación semántica almacenada vectorialmente para alimentar el contexto del RAG.
- Historial y Trazabilidad (Últimos Prompts): Registro lineal de las consultas de los usuarios entrantes desde Streamlit, permitiendo auditorías de auditoría y auditorías de seguridad en vivo.
- Métricas de Enrutamiento y Especialización de Agentes: Vista analítica de la telemetría que valida cómo el
Decision Routerdistribuye las cargas de trabajo analizando la consulta para derivarla al agente y modelo correspondiente:- Agente Foro Hub e Infraestructura Cloud (Gemini 2.5 Flash)
- Agente LangChain Migrator (Buscador Web Avanzado + Mistral Large)
- Agente Arquitecto RAG (FAISS + Qwen/DeepSeek)
Diseño conceptual de la infraestructura Always Free en la región de Chile Central, detallando la convivencia de los entornos, el aislamiento de red (VCN) y el flujo de los agentes autónomos hacia la base de datos vectorial Oracle 26ai.
graph TD
classDef oci fill:#7FA6B3,stroke:#4A6B78,stroke-width:2px,color:#0f1720;
classDef app fill:#4A6B78,stroke:#2d3f45,stroke-width:1px,color:#ffffff;
classDef db fill:#8AAE9B,stroke:#5f8a6e,stroke-width:2px,color:#0f1720;
classDef ext fill:#9EA3A8,stroke:#6f7376,stroke-width:1px,color:#0f1720;
classDef label fill:#F4F6F7,stroke:#d6dcdc,stroke-width:0.5px,color:#0f1720;
subgraph OCI_Region["☁️ Infraestructura en OCI (Chile Central)"]
direction TB
Budget["💰 Budget (Presupuesto-Seguridad)"]
SecList["🔒 Default Security List<br/>(Puertos: 80, 443, 8501)"]
subgraph VCN["🌐 Virtual Cloud Network (VCN_Test)"]
direction TB
%% Servidor e Infraestructura física
VM_Info["💻 Servidor_Foro_Hub<br/>(OS: Ubuntu 24.04 LTS)"]
BootVol["💾 Boot Volume<br/>(47 GB Storage)"]
%% Componentes de Software (Módulos independientes)
ForoCode["📦 Módulo Core: Foro Hub<br/>(Backend Logic / Archivo Estático)"]
StreamlitApp["🚀 Módulo IA: App Streamlit<br/>(Puerto 8501 - Decision Router)"]
%% Base de Datos
AutonomousDB["🗄️ Autonomous AI Database (forohubdb)<br/>[Oracle 26ai - Always Free]<br/>(Backup: 40 GB)"]
end
end
subgraph External_APIs["🌐 Integración Externa: Modelos de Lenguaje"]
direction LR
Gemini["♊ Gemini 2.5 Flash"]
Mistral["🌪️ Mistral Large<br/>(LCEL Migrator)"]
DeepSeek["🐋 DeepSeek / Qwen<br/>(Arquitecto RAG)"]
end
%% Relaciones de Infraestructura del Servidor
VM_Info --- BootVol
SecList -.-> VM_Info
%% Flujos Lógicos Libres de Cruces
ForoCode -->|Auditoría / Persistencia| AutonomousDB
StreamlitApp -->|1. Búsqueda Vectorial y Telemetría| AutonomousDB
StreamlitApp -->|2. Orquestación ReAct| Gemini
StreamlitApp -->|2. Orquestación ReAct| Mistral
StreamlitApp -->|2. Orquestación ReAct| DeepSeek
%% Aplicación de Estilos
class OCI_Region,VCN,VM_Info oci;
class ForoCode,StreamlitApp app;
class AutonomousDB db;
class External_APIs,Gemini,Mistral,DeepSeek ext;
class SecList,BootVol,Budget label;
- Docker y Docker Compose instalados.
- Descargar la Wallet de tu instancia de Oracle Autonomous Database.
Cloná el archivo de plantilla .env.example para crear tu configuración local sin exponer credenciales reales:
bash
cp .env.example .env
Asegurate de completar el .env con tus credenciales de OCI y colocar los archivos de tu Wallet descomprimidos dentro de la carpeta correspondiente en la raíz (la cual se encuentra protegida en el .gitignore):
-
Ruta origen en la máquina: /home/ubuntu/Wallet_forohubdb3
-
Ruta destino en el contenedor: /app/oracle_wallet
-
Variable TNS_ADMIN: /app/Wallet_forohubdb3
- Levantar la Aplicación Para limpiar la caché del entorno y levantar el contenedor compilando la última versión del Agente, ejecutá:
Bash
docker compose down --remove-orphans
docker compose up --build -d
La interfaz de Streamlit quedará accesible de inmediato en el puerto http://localhost:8501.
¡Toda ayuda para optimizar los agentes o mejorar el RAG es bienvenida! Para contribuir, sigue este flujo de trabajo estándar de Git:
-
Haz un Fork de este repositorio.
-
Crea una rama (Branch) para tu nueva funcionalidad o corrección de errores:
Bash
git checkout -b feature/nueva-funcionalidad
-
Realiza tus cambios en el código. Recuerda no incluir datos reales dentro de la carpeta data/ y documentar tus preguntas de prueba en el archivo banco_pruebas.json.
-
Haz un Commit de tus cambios con un mensaje claro y descriptivo:
Bash
git commit -m "feat: agregar soporte para chunking semántico en RAG"
- Sube tus cambios (Push) a tu repositorio remoto:
Bash
git push origin feature/nueva-funcionalidad
- Abre un Pull Request (PR) detallando los cambios introducidos y qué problema resuelven para que lo revisemos y lo integremos a la rama main.
El Decision Router analiza la consulta técnica del usuario en lenguaje natural y la deriva instantáneamente al agente experto correspondiente. A continuación, se presentan ejemplos reales de lo que el sistema puede resolver:
- Pregunta del usuario:
"¿Cómo puedo ver los tópicos que creó el autor 'Christian Dev' en el Foro Hub y cuál es el estado actual del servidor?"
- Respuesta del Agente (Gemini 2.5 Flash):
💻 [Agente Foro Hub]: Consultando la persistencia en
forohubdb... Detecté que el autor Christian Dev tiene 3 tópicos activos en la plataforma. El estado del servidor en la IP enmascarada de OCI es estable (HTTP 200). Te adjunto el listado detallado de las discusiones encontradas...
- Pregunta del usuario:
"Necesito migrar un script de PL/SQL antiguo de Oracle 11g a la nueva base de datos autónoma Oracle 26ai. ¿Qué funciones vectoriales nativas cambian?"
- Respuesta del Agente (Mistral Large via LCEL):
🌪️ [Agente Migrator]: Analizando compatibilidad de dialectos... Para aprovechar al máximo Oracle 26ai, te recomiendo reemplazar los índices tradicionales por bloques
VECTOR_DISTANCEutilizando la métricaCOSINE. Tu script original de PL/SQL ha sido optimizado. Aquí tienes el bloque de código compatible con la infraestructura Always Free...
- Pregunta del usuario:
"¿Cuáles son los fragmentos de código más relevantes en nuestra base de conocimientos sobre la configuración de seguridad en la VCN para habilitar Streamlit?"
- Respuesta del Agente (DeepSeek / Qwen):
🐋 [Arquitecto RAG]: Ejecutando búsqueda semántica... La base de conocimientos actual detalla la infraestructura core de Foro Hub (OCI, Ubuntu, Nginx en puerto 8000 y certificados SSL). Sin embargo, se detecta una brecha de información: no existen registros de reglas de ingreso (Ingress Rules) para el puerto 8501 de Streamlit en la VCN. Procediendo a escalar la consulta para su próxima indexación.
ℹ️ Nota de Auditoría y Telemetría: Cada una de estas interacciones (el prompt del usuario, el agente seleccionado por el enrutador, los tokens consumidos y la respuesta final) se registra automáticamente en las tablas de auditoría de
forohubdbpara un control estricto del presupuesto (Budget) en OCI.
Gracias al programa Oracle Next Education y Alura Latam por el desafío y las herramientas proporcionadas para llevar este proyecto al siguiente nivel con Inteligencia Artificial.
Este proyecto está bajo la Licencia MIT. Para más detalles, consulta el archivo LICENSE adjunto en este repositorio.
Copyright © 2026 Christian Garay - Backend Developer.