MALLO: MultiAgent LLM Orchestrator

Tabla de Contenidos

1. Descripción
2. Características Principales
3. Estructura del Proyecto
4. Requisitos Previos
5. Instalación
6. Configuración
7. Uso
8. Evaluación Ética y de Cumplimiento
9. TIPS y Trucos
10. Arquitectura del Sistema
11. Componentes Principales
12. Flujo de Trabajo
13. APIs y Servicios Integrados
14. Manejo de Errores y Logging
15. Optimización y Caché
16. Pruebas
17. Contribución
18. Registro de Cambios
19. ExperimentaLABs
20. Roadmap
21. Licencia
22. Contacto

Descripción

MALLO (MultiAgent LLM Orchestrator) es una plataforma avanzada de orquestación de modelos de lenguaje que implementa una arquitectura distribuida basada en agentes. Diseñada específicamente para el procesamiento de consultas complejas, MALLO utiliza un sistema de selección dinámica de agentes que combina:

• Modelos de lenguaje locales para procesamiento de baja latencia
• APIs de modelos en la nube para tareas complejas
• Asistentes especializados para dominios específicos
• Sistemas de búsqueda y enriquecimiento de contexto

La arquitectura del sistema se basa en principios de diseño modular y extensible, permitiendo la integración seamless de nuevos modelos y servicios. El núcleo del sistema implementa algoritmos avanzados de evaluación de complejidad y selección de agentes, optimizando la relación entre precisión, latencia y consumo de recursos.

Características Principales

1. Arquitectura Multi-Agente Avanzada

• Procesamiento Distribuido:

  • Pipeline de procesamiento paralelo para múltiples agentes
  • Sistema de votación y consenso para respuestas múltiples
  • Mecanismos de fallback y recuperación automática
  • Sistema robusto de manejo de errores para APIs externas
  • Selección automática de modelos basada en el tipo de consulta
  • Personalización de etapas de procesamiento (evaluación inicial, búsqueda web, meta-análisis, evaluación ética)

• Integración de Modelos:

  • Modelos locales vía Ollama para baja latencia (offline-capable)
  • APIs cloud premium (OpenAI, Anthropic, Groq)
  • Proveedores especializados (Together, DeepInfra, DeepSeek)
  • Modelos open-source optimizados (Mistral, Cohere)
  • Acceso a modelos avanzados vía OpenRouter con manejo robusto de errores
  • Soporte para modelos multimodales (Llama 4 Maverick/Scout)
  • Sistema de respaldo para modelos que fallan

2. Sistema de Procesamiento Inteligente

• Análisis de Complejidad:

  • Evaluación heurística de consultas
  • Detección automática de dominio y contexto
  • Selección dinámica de agentes basada en métricas
  • Identificación de tipo de prompt para procesamiento especializado
  • Determinación automática de necesidad de búsqueda web y meta-análisis

• Optimización de Recursos:

  • Sistema de caché multinivel con validación
  • Balanceo dinámico de carga entre agentes
  • Gestión inteligente de cuotas y límites de API
  • Inicialización eficiente de componentes con @st.cache_resource
  • Sistema de respaldo para APIs no disponibles

3. Capacidades Avanzadas de Búsqueda y Contextualización

• Motor de Búsqueda Multi-Fuente:

  • Integración primaria con API de YOU
  • Fallback a Tavily para búsquedas especializadas
  • Sistema de respaldo con DuckDuckGo
  • Agregación y deduplicación de resultados
  • Visualización detallada de resultados de búsqueda en pestaña dedicada
  • Identificación automática del proveedor de búsqueda utilizado

• Procesamiento de Contexto:

  • Análisis semántico de consultas
  • Extracción de entidades y relaciones
  • Generación de embeddings para búsqueda contextual
  • Procesamiento de documentos con OCR mediante Mistral
  • Carga de archivos integrada directamente en el chat

4. Framework de Evaluación y Mejora

• Sistema de Evaluación Ética:

  • Detección automática de sesgos
  • Validación de privacidad y seguridad
  • Alineación con principios éticos configurables
  • Opción para activar/desactivar la evaluación ética
  • Visualización detallada de resultados de evaluación ética

• Mecanismos de Feedback:

  • Evaluación continua de calidad de respuestas
  • Sistema de aprendizaje basado en retroalimentación
  • Métricas de rendimiento en tiempo real
  • Exportación detallada de todo el proceso de análisis
  • Meta-análisis configurable para síntesis de múltiples fuentes

5. Interfaz y Monitoreo

• UI Moderna y Responsive:

  • Framework Streamlit con diseño optimizado
  • Componentes dinámicos de visualización
  • Sistema de progreso en tiempo real
  • Interfaz simplificada con carga de documentos integrada en el chat
  • Personalización de etapas de procesamiento y selección de modelos
  • Sistema de pestañas para organizar la información (Detalles, Búsqueda Web, Meta-análisis, etc.)
  • Botón para limpiar la conversación y el contexto sin refrescar la página
  • Exportación mejorada con toda la información del procesamiento

• Logging y Observabilidad:

  • Logging estructurado con niveles configurables
  • Métricas Prometheus para monitoreo
  • Sistema de alertas para eventos críticos
  • Mensajes de error amigables y detallados para el usuario
  • Visualización en tiempo real del proceso de selección de modelos

6. Configuración y Extensibilidad

• Sistema de Configuración Robusto:

  • Configuración centralizada via YAML
  • Soporte para múltiples entornos
  • Hot-reload de configuraciones
  • Guardado y carga de configuraciones personalizadas
  • Interfaz gráfica para personalizar etapas de procesamiento

• Arquitectura Extensible:

  • APIs bien documentadas para nuevos agentes
  • Sistema de plugins para funcionalidades adicionales
  • Hooks para personalización de comportamiento
  • Selección flexible de modelos principales y de respaldo
  • Organización de modelos por proveedor con nombres descriptivos

7. Seguridad y Cumplimiento

• Protección de Datos:

  • Encriptación en tránsito y en reposo
  • Sanitización de entradas y salidas
  • Gestión segura de credenciales
  • Verificación previa de disponibilidad de APIs
  • Sistema robusto de manejo de errores para APIs externas

• Auditoría y Compliance:

  • Registro detallado de operaciones
  • Trazabilidad de decisiones del sistema
  • Reportes de cumplimiento normativo
  • Validación de respuestas de APIs externas
  • Exportación completa de conversaciones con todos los detalles del procesamiento
  • Documentación de etapas ejecutadas en cada respuesta

8. Optimización de Rendimiento

• Sistema de Caché Avanzado:

  • Caché multinivel (memoria, disco, distribuido)
  • Políticas de invalidación inteligentes
  • Compresión y optimización de almacenamiento
  • Inicialización eficiente de componentes con @st.cache_resource
  • Carga diferida de recursos no críticos

• Gestión de Recursos:

  • Límites de consumo configurables
  • Balanceo de carga automático
  • Recuperación graceful ante fallos
  • Sistema de respaldo para modelos que fallan
  • Selección automática de modelos basada en disponibilidad y tipo de consulta

Estructura del Proyecto

MALLO/
│
├── agents.py                   # Implementación de la clase AgentManager y lógica de agentes
├── config.yaml                 # Configuración general del sistema
├── config_streamlit.py         # Configuración de la interfaz de Streamlit
├── custom_config.json          # Configuración personalizada guardada por el usuario
├── document_processor.py       # Procesamiento de documentos y OCR
├── error_recovery.json         # Registro de errores para recuperación
├── load_secrets.py             # Carga de secretos y claves API
├── main.py                     # Punto de entrada principal y UI de Streamlit
├── model_loader.py             # Carga de modelos desde diferentes fuentes (OpenRouter, Groq, Ollama)
├── model_speeds.json           # Índice de velocidad de modelos locales y en la nube
├── README.md                   # Documentación del proyecto (este archivo)
├── utilities.py                # Funciones de utilidad y helpers
├── CHANGELOG.md                # Registro de cambios y versiones
│
├── .streamlit/                 # Configuración de Streamlit
│   └── secrets.toml            # Almacenamiento seguro de claves API (no incluido en el repositorio)
│
├── assets/                     # Directorio para recursos estáticos (imágenes, estilos, etc.)
│
├── docs/                       # Documentación adicional
│   ├── informes/               # Informes técnicos, de investigación y otros documentos
│   │
│   └── ejemplos_consultas/     # Ejemplos de consultas y respuestas para demostración
│
├── legacy_code/                # Código histórico y no esencial
│   ├── cache_manager.py        # Sistema de caché (versión anterior)
│   ├── cached_init.py          # Inicialización en caché (versión anterior)
│   ├── compatibility_check.py  # Verificación de compatibilidad
│   ├── groq_model_speeds.json  # Velocidades de modelos Groq
│   ├── mallo.log               # Archivo de registro
│   └── mallo_enhancer.py       # Lógica experimental para mejorar respuestas
│
├── static/                     # Archivos estáticos para la interfaz
│
├── temp/                       # Directorio para archivos temporales
│
├── tools/                      # Utilidades externas
│   ├── test_groq_model_speed.py    # Script para medir velocidad de modelos Groq
│   ├── test_model_speeds.py        # Script para medir velocidad de modelos
│   └── test_replicate_model_speed.py # Script para medir velocidad de modelos Replicate
│
├── packages.txt                # Dependencias del sistema
└── requirements.txt            # Dependencias de Python

Requisitos Previos

• Python 3.8+
• Ollama instalado localmente (para modelos locales)
• Claves API para servicios externos (OpenAI, Groq, Together, etc.)
• Conexión a Internet (para búsqueda web y APIs externas)

Instalación

1. Clona el repositorio:

   git clone https://github.com/bladealex9848/MALLO.git
   cd MALLO
   

2. Crea y activa un entorno virtual:

   python3 -m venv venv
   source venv/bin/activate  # En Windows usa `venv\Scripts\activate`
   

3. Instala las dependencias:

   pip install -r requirements.txt
   

4. Configura tus claves API: Crea un archivo .streamlit/secrets.toml y añade tus claves API:

   OPENAI_API_KEY = "tu_clave_openai_aqui"
   GROQ_API_KEY = "tu_clave_groq_aqui"
   TOGETHER_API_KEY = "tu_clave_together_aqui"
   DEEPINFRA_API_KEY="tu_clave_deepinfra_aqui"
   ANTHROPIC_API_KEY="tu_clave_anthropic_aqui"
   DEEPSEEK_API_KEY="tu_clave_deepseek_aqui"
   MISTRAL_API_KEY="tu_clave_mistral_aqui"
   COHERE_API_KEY="tu_clave_cohere_aqui"
   REPLICATE_API_TOKEN= "tu_clave_replicate_aqui"
   OPENROUTER_API_KEY= "tu_clave_openrouter_aqui"
   # Añade otras claves API según sea necesario
   

Configuración

El archivo config.yaml contiene la configuración principal del sistema. Aquí puedes ajustar:

• Modelos disponibles para cada proveedor de LLM
• Prioridades de procesamiento
• Umbrales de complejidad para la selección de agentes
• Configuración de asistentes especializados
• Parámetros de utilidades como búsqueda web y análisis de imágenes

Ejemplo de configuración:

ollama:
  base_url: "http://localhost:11434"
  default_model: "gemma2:2b"
  models:
    - "gemma2:2b"
    - "llava:latest"

openai:
  default_model: "gpt-5-nano"
  models:
    - "gpt-5-nano"

# ... (otras co