🔄 Los 5 componentes fundamentales
INTELECTO tiene exactamente 5 responsabilidades distintas. Esta división no es arbitraria: cada componente puede sustituirse, probarse y evolucionar independientemente de los demás. Es el secreto que mantiene el sistema manejable.
🧩 Los 5 componentes
El cerebro. Recibe mensajes, construye el contexto, decide si usar tools o responder directamente y lo orquesta todo.
Acceso a los LLM. OpenRouter, Ollama, API directa. Cualquiera que implemente BaseProvider funciona.
Cómo se comunica el usuario. Telegram, WhatsApp, Discord, CLI. Implementan BaseChannel.
Persistencia del contexto. SQLite FTS5 con búsqueda semántica BM25 y deduplicación automática.
Acciones en el mundo real. Google Calendar, GitHub, navegador, shell. Implementan BaseTool.
📨 Flujo completo de un mensaje
Cada mensaje sigue una ruta precisa. Entender este flujo es fundamental para saber dónde intervenir cuando algo falla y dónde agregar nuevas funcionalidades.
📊 Diagrama de flujo
💡 Consejo práctico
Para depurar, agrega logs en cada etapa del flujo. El logging de Python con distintos niveles (DEBUG para Channel, INFO para Agent, WARNING para Safety) permite filtrar exactamente dónde ocurre el problema.
🔁 El Agent Loop — Max 5 Rounds
O loop.py es el corazón de INTELECTO. Implementa el patrón ReAct (Reason + Act): la IA piensa, decide actuar con una herramienta, recibe el resultado, vuelve a pensar y así sucesivamente, hasta llegar a una respuesta final o alcanzar el límite de 5 rounds.
🔄 El ciclo ReAct
El LLM analiza el mensaje + el contexto y decide qué hacer
Si decides usar una tool → llama a tool.execute() con los parámetros
El resultado de la herramienta entra en el contexto → vuelve a Reason
El LLM genera una respuesta en lenguaje natural para el usuario
⚠ ¿Por qué el límite de 5 rondas?
Sin un límite, un error en la lógica de la IA puede causar un bucle infinito, que cueste cientos de dólares en tokens. El límite de 5 es el disyuntor que protege tu facturación. Para tareas complejas, ajusta el límite con cuidado y siempre con monitoreo.
📁 El Workspace — Configuración en Markdown
El directorio workspace/ es donde defines qué es tu Jarvis. Tres archivos Markdown que se leen y se inyectan en cada system prompt. Cambiar el comportamiento de la IA no requiere modificar el código: solo editar estos archivos.
🧬 SOUL.md
La personalidad de la IA: nombre, tono de voz, valores, estilo de comunicación, limitaciones éticas. Define quién es Jarvis.
📋 AGENTS.md
Reglas de comportamiento: qué hacer, qué nunca hacer, cómo priorizar tareas y cuándo pedir confirmación.
🧠 MEMORY.md
Hechos de bootstrap: información que la IA necesita conocer desde la primera conversación sin que tengas que enseñársela.
💡 Configuration as Code
Los archivos del workspace son «código» en el sentido de que controlan el comportamiento del sistema. Contrólalos con git, haz copias de seguridad y trata los cambios en ellos con el mismo cuidado que los cambios de código.
🧩 Contratos de interfaz
El secreto de la extensibilidad de INTELECTO son los contratos de interfaz. Cada tipo de componente tiene una clase base abstracta con métodos obligatorios. Si respetas el contrato, tu componente funciona automáticamente con todo lo demás.
📋 Los 3 contratos principales
Único método obligatorio. Cualquier LLM que implemente esto funciona con el Agent.
async def send(user_id, msg) → None
async def stop() → None
3 métodos. Telegram, WhatsApp, CLI: todos implementan estos 3.
description: str
parameters: dict # JSON Schema
async def execute(**kwargs) → str
La descripción + los parámetros se envían al LLM para que sepa cómo usar la tool.
🗄 Persistencia en ~/.intelecto/
Todo lo que INTELECTO persiste queda en ~/.intelecto/. Tres archivos críticos que debes conocer, respaldar y nunca eliminar accidentalmente.
memory.db
Base de datos SQLite con FTS5 habilitado. Almacena datos (categoría: fact/conversation/solution), historial de conversaciones y resultados de búsquedas anteriores. BM25 para la clasificación por relevancia.
.secrets
Claves de API cifradas con Fernet. La clave de cifrado se deriva del UUID del hardware mediante PBKDF2. El archivo solo puede descifrarse en la misma máquina.
audit.log
Registro de todas las acciones: quién las solicitó, qué se ejecutó, cuándo y con qué resultado. Inmutable por diseño: cada línea es append-only.
✅ Resumen del Módulo 1.2
Próximo módulo:
1.3 — Configuración del entorno: desde cero hasta tener Jarvis funcionando en Telegram