Arquitectura
Un mapa completo del ecosistema Yggdrasil — desde la estructura de directorios de los Nueve Reinos hasta el Gateway REST, cada componente que hace funcionar a Lilith v5.0, incluyendo LLM Multi-Proveedor, Inteligencia de Enjambre, MCP, Habilidades, Modo por Lotes y el Panel de Control en tiempo real.
Estructura de los Nueve Reinos
La estructura de directorios sigue la cosmología nórdica. Cada reino es un directorio principal con un propósito estricto.
Yggdrasil/
│
├── Asgard/ ← Tecnología Central (permanente)
│ ├── Lilith/ Agente CLI, memoria, orquestador
│ │ ├── Lilith/ Módulos centrales (Core, Swarm, MCP,
│ │ │ Dashboard, Lilith, RAG, Scheduler, Plugins)
│ │ ├── memory/ Memoria híbrida (vectorial + grafo + FTS5)
│ │ └── skills/ Paquetes de habilidades en caliente
│ ├── lilith-orchestrator/gateway/ Gateway REST FastAPI
│ └── lilith-v3-master-plan.md Hoja de ruta
│
├── Vanaheim/ ← Agentes IA y Bots
│ ├── Bots_Lilith_v5/
│ │ ├── telegram/ Bot de Telegram (solo dueño)
│ │ └── bridge/ Cliente puente del Gateway
│ ├── Agents/ 4 agentes activos (Shalltear, Adán, Eva, Odín)
│ ├── bifrost/ Protocolo de comunicación inter-reinos
│ ├── Core/ Librerías compartidas de agentes
│ └── LLM_Experiments/ Pruebas de modelos
│
├── Alfheim/ ← Prototipos UI
│ ├── VSCode_Extension_Lilith/ Integración con IDE
│ └── ui-seed/ Experimentos visuales
│
├── Svartalfheim/ ← Base de Conocimiento
│ ├── Knowledge_Base/ Documentación
│ ├── Grimorios/ Decisiones de arquitectura
│ └── Playbooks/ Guías de despliegue
│
├── Muspelheim/ ← Desarrollo Activo
│ ├── AutoMode/ Plantillas de sprint
│ └── Hotfixes/ Parches de emergencia
│
├── Niflheim/ ← Recursos
│ ├── Datasets/ Datos de entrenamiento
│ └── Models/ Checkpoints LLM
│
├── Midgard/ ← Apps Personales
│ └── app/ Aplicaciones completadas
│
├── Jotunheim/ ← Proyectos Masivos
│ └── projects/ Proyectos a largo plazo
│
├── Helheim/ ← Cementerio
│ ├── Archives_Lilith_Legacy/ Código antiguo
│ └── Quarantine/ Basura regenerable
│
├── website/ ← Sitio de docs (GitHub Pages)
│ ├── index.html
│ ├── hermes-lilith.html
│ ├── architecture.html
│ ├── realms.html
│ ├── setup.html
│ ├── changelog.html
│ ├── js/main.js
│ └── css/style.css
│
├── REGLAS_YGGDRASIL.md ← Reglas de los reinos
├── README.md ← Resumen del proyecto
├── CHANGELOG.md ← Historial de versiones
├── setup_yggdrasil.py ← Script de instalación
├── yggdrasil_cli.py ← Herramienta CLI
└── start_lilith.bat ← Script lanzador
Ciclo de Vida de las Peticiones
Un solo mensaje de Telegram viaja a través de múltiples capas antes de regresar con una respuesta. Aquí está la ruta completa.
| Paso | Qué Sucede |
|---|---|
| 1. Telegram | El usuario envía un mensaje al bot. El bot valida al remitente (solo dueño) y reenvía el texto al Bridge. |
| 2. Bridge | El Bridge (cliente Python) empaqueta el mensaje en JSON y lo envía (POST) al Gateway en localhost:8000/api/telegram/chat. |
| 3. Gateway | FastAPI recibe la petición, genera un ID de sesión (gateway_{user_id}_{timestamp}) y enruta al manejador correspondiente. |
| 4. Lilith | La orquestadora carga el contexto, consulta la memoria híbrida (vectorial + grafo + FTS5) por interacciones pasadas, revisa Habilidades aplicables y construye el prompt. |
| 5. Proveedor LLM | El prompt se envía a LM Studio (local) vía API compatible con OpenAI. Si no está disponible, el Proveedor LLM recurre automáticamente a Kimi u otro proveedor remoto. |
| 6. Ejecución de Herramientas | Si el modelo solicita una herramienta o habilidad, Lilith la despacha — herramientas nativas, conexiones MCP, llamadas dinámicas, o invoca un agente Enjambre para trabajo paralelo. |
| 7. Dashboard | Los eventos en tiempo real se transmiten al Panel web en localhost:8080 vía WebSocket — mostrando llamadas al LLM, herramientas, operaciones de memoria y progreso del enjambre. |
| 8. Respuesta | La respuesta final regresa al Gateway, que la reenvía al Bridge, y este la envía de vuelta a Telegram. |
| 9. Almacenamiento | La conversación se comprime y almacena en los tres índices de memoria (vectorial, grafo, texto completo) para futura recuperación de contexto. |
Relaciones de Componentes
Cómo interactúan los paquetes principales. Las flechas indican dependencia o dirección de comunicación.
Capa 1: Interfaces
| Componente | Tipo |
|---|---|
| ᚨ Bot de Telegram | Interfaz |
| ᚲ Extensión VSCode | Interfaz |
| ᚱ CLI | Interfaz |
↓ HTTP / REST ↓
Capa 2: Gateway
| Componente | Detalle |
|---|---|
| ᚦ Gateway | FastAPI · Puerto 8000 |
↓ API Interna ↓
Capa 3: Núcleo
| Componente | Detalle |
|---|---|
| ᚦ Lilith | Orquestadora |
| ᛗ Memoria | Vectorial + Grafo + FTS5 |
| ᛏ Scheduler | Cron + SQLite |
| ᚦ Plugins | Herramientas dinámicas |
| ᛊ Enjambre | Agentes Especialistas |
| ᚺ Habilidades | Paquetes en Caliente |
| ᛇ MCP | Protocolo de Contexto de Modelo |
| ᛒ Dashboard | WebSocket · Puerto 8080 |
↓ LLM Multi-Proveedor ↓
Capa 4: LLM
| Componente | Detalle |
|---|---|
| ᛃ LM Studio | Local · localhost:1234 |
| ᚨ Kimi / OpenAI | Respaldo Remoto |
Modelo de Seguridad
Yggdrasil está diseñado para un solo propietario. La seguridad se centra en el aislamiento, la ejecución local y la prevención de daños accidentales.
Acceso Exclusivo del Propietario
El bot de Telegram solo responde al TELEGRAM_OWNER_CHAT_ID configurado. Cualquier otro usuario es ignorado silenciosamente. No hay soporte multi-usuario por diseño.
Ejecución Local
El LLM se ejecuta en localhost vía LM Studio. La memoria se almacena en SQLite local. Las operaciones de archivos están confinadas a la máquina host. Nada sale de tu red a menos que una herramienta lo solicite explícitamente.
Barreras de Confirmación
Las operaciones destructivas (borrar archivos, matar procesos, cambios en el sistema) requieren confirmación humana explícita vía Telegram. El agente no puede actuar autónomamente en comandos peligrosos.
Sin Secretos en el Código
Todos los tokens, claves de API y configuraciones sensibles viven en archivos .env (ignorados por git). La plantilla .env.example muestra qué se necesita sin exponer los valores.