🧠 Fundamentos de INTELECTO

Frameworks como LangChain y CrewAI abstraen todo, pero añaden capas de complejidad innecesaria que hacen que la depuración y la personalización sean una pesadilla.

Entender las ventajas y desventajas permite elegir conscientemente cuándo usar un framework y cuándo construir desde cero — una habilidad poco común en el mercado.

Costo de abstracción, dependencia del proveedor, filosofía de cero dependencias, control total del código.

INTELECTO está organizado como una tienda de abarrotes: recorres cada pasillo (el de seguridad, el de memoria, el de canales...) y tomas solo lo que necesitas para tu asistente.

Este modelo mental evita la ingeniería excesiva. No instalas lo que no vas a usar, y mantienes el sistema ligero, auditable y fácil de mantener.

8 corredores funcionales, composición modular, feature flags, ingredientes de framework.

Un análisis objetivo de las diferencias: LangChain tiene más de 200 dependencias y CrewAI impone un modelo rígido de agentes. INTELECTO no tiene dependencias obligatorias aparte de Python.

Saber defender técnicamente tu elección es esencial para los equipos y los clientes. Necesitas los números y los argumentos.

Tamaño del paquete, tiempo de inicio, latencia de depuración, costo de mantenimiento, curva de aprendizaje.

Jarvis conoce a su creador, recuerda conversaciones anteriores, actúa de forma proactiva y ejecuta tareas en el mundo real. Un chatbot genérico solo responde preguntas.

Define el nivel de ambición adecuado. Estás construyendo algo que crecerá contigo, no una demo descartable.

Identidad persistente, memoria a largo plazo, acción en el mundo real, personalización profunda.

Cada archivo tiene una responsabilidad clara: context.py arma el system prompt, loop.py gestiona el ciclo de razonamiento y secrets.py protege las credenciales.

Conocer el mapa antes de sumergirte en el código ahorra horas de desorientación. Cada modificación se hace en el lugar correcto.

context.py, loop.py, secrets.py, safety.py, store.py, providers/base.py, channels/base.py, tools/base.py.

Con APIs de LLM maduras y estables, el costo de abstracción de los frameworks supera los beneficios para proyectos serios. Python puro + contratos claros es suficiente.

El mercado está saturado de desarrolladores que solo saben usar wrappers. Quienes entienden los fundamentos tienen una ventaja competitiva real.

Madurez de la API, costo de abstracción, ventaja competitiva, contratos de interfaz, mantenimiento a largo plazo.

INTELECTO tiene exactamente 5 responsabilidades: el agente central que piensa, los proveedores que acceden a los LLM, los canales que reciben mensajes, la memoria que conserva el contexto y las herramientas que actúan en el mundo.

Cada componente tiene límites claros. Saber dónde termina uno y comienza otro permite agregar funcionalidades sin romper el sistema.

Separación de responsabilidades, contratos de interfaz, inyección de dependencias, composición modular.

Usuario → Telegram → Channel.receive() → Agent.loop() → Memory.search() → Provider.chat() → Tool.execute() → Memory.store() → Channel.send() → Usuario. Cada flecha es una llamada a una función con un contrato definido.

Visualizar el flujo completo permite identificar dónde depurar cuando algo falla y dónde optimizar cuando va lento.

Pipeline de procesamiento, async/await, manejo de errores en cascada, observabilidad.

loop.py implementa un ciclo de razonamiento: recibe un mensaje → piensa → decide si usa una tool o responde → si usó una tool, vuelve a pensar con el resultado → hasta 5 iteraciones por seguridad.

El límite de 5 rondas previene los bucles infinitos y los costos descontrolados. Entender el ciclo permite ajustar la profundidad del razonamiento para cada caso de uso.

Patrón ReAct, llamadas a herramientas, iteraciones máximas, costo por ronda, circuit breaker para bucles.

El directorio workspace/ contiene archivos Markdown que definen la personalidad (SOUL.md), las reglas de comportamiento (AGENTS.md) y los datos de inicio (MEMORY.md), que se inyectan en cada system prompt.

Toda personalización de la IA comienza aquí. Cambiar Jarvis no requiere modificar el código: solo los archivos del workspace.

Configuration as code, system prompt construction, context injection, SOUL.md como identidad.

Cada categoría de extensión tiene una clase base abstracta con métodos obligatorios. BaseProvider exige async chat(). BaseChannel exige start(), send(), stop(). BaseTool exige name, description, execute().

Los contratos garantizan que cualquier implementación funcione automáticamente con el resto del sistema. Es como un enchufe estandarizado: cualquier dispositivo que respeta el estándar funciona en la toma de corriente.

Clase base abstracta, duck typing, patrón protocol, arquitectura plug-and-play.

Tres archivos críticos en ~/.intelecto/: memory.db (base de datos SQLite con historial y datos), .secrets (claves cifradas con Fernet + UUID del hardware) y audit.log (registro de todas las acciones).

Entender dónde viven los datos es esencial para hacer copias de seguridad, migrar y diagnosticar. Nunca debes perder por accidente la memoria de tu Jarvis.

Home directory pattern, SQLite portabilidad, encrypted secrets, audit trail, backup strategy.

Python 3.11+ es obligatorio. Las dependencias son mínimas: httpx para HTTP async, python-telegram-bot para el canal, cryptography para Fernet. Ni LangChain ni CrewAI.

Conocer las dependencias reales permite auditar lo que está instalado y entender por qué existe cada paquete en el proyecto.

venv, requirements.txt minimalista, funcionalidades de Python 3.11, async nativo.

OpenRouter es un proxy de LLMs que da acceso a GPT-4, Claude, Mistral, Llama y más de 100 modelos con una sola clave de API y facturación unificada.

Evita la dependencia de un proveedor específico. Si Anthropic sube el precio, cambias a Mistral en 10 segundos modificando una variable de entorno.

Gestión de API keys, enrutamiento de modelos, seguimiento de costos, estrategia de fallback, modelo por tarea.

El archivo .env define OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, MODEL_NAME y otros parámetros sin incluirlos directamente en el código. El archivo .env NUNCA debe subirse a git.

Separar la configuración del código es una práctica de seguridad fundamental. Las claves en el código son la causa número 1 de filtraciones en repositorios públicos.

Aplicación de 12 factores, .gitignore, python-dotenv, variables de entorno y gestión de secretos.

El script setup.py hace preguntas interactivas: ¿qué canal usar? ¿Docker o nativo? ¿Qué modelo predeterminado? Y configura todo automáticamente, creando los archivos necesarios.

El asistente de configuración elimina errores de configuración manual y garantiza que no se olvide nada obligatorio. Es la puerta de entrada para nuevos usuarios.

CLI interactiva, generación de configuración, onboarding guiado, validación de inputs.

Docker ofrece aislamiento y un deploy reproducible. El modo nativo ofrece menos sobrecarga y una depuración más directa. Usa el modo nativo para desarrollo y Docker Compose para producción.

La elección afecta cómo depuras, cómo haces copias de seguridad y cómo actualizas el sistema. Entender las ventajas y desventajas evita sorpresas en producción.

Container isolation, volume mounts, docker-compose.yml, desarrollo vs. producción.

El momento de validación: ejecutar python main.py, abrir Telegram, enviar «Hola» y recibir la primera respuesta de tu Jarvis. Si funciona, toda la stack está correctamente configurada.

La prueba smoke inicial valida cada componente de punta a punta: canal, agente, proveedor, memoria. Es el hito que distingue entre «configurado» y «funcionando».

Smoke test, validación de extremo a extremo, token de BotFather, webhook vs. polling, depuración de la primera ejecución.