🛠️ Arma tu Jarvis de bolsillo (proyecto)
Es hora de unirlo todo. En este módulo pasas de «entendí la teoría» a «está funcionando en mi celular»: un bot personal de Telegram, con cerebro, memoria, alma (soul), una skill útil, voz y un heartbeat que te envía el resumen del día a las 7h. Cinco pasos breves, cada uno comprobable antes del siguiente. Sin app de tienda, sin servidor expuesto, sin mezclar claves.
🗺️ Visión del proyecto
Todo lo que viste en las rutas anteriores converge aquí en una frase: vamos a armar un bot personal de Telegram que conversa contigo, recuerda quién eres, ejecuta una rutina útil y además habla: accesible desde cualquier celular, sin instalar ninguna app de tienda. Telegram ya funciona en tu teléfono; se convierte en la puerta de entrada. El cerebro (el modelo de IA) y la memoria se ejecutan en una computadora tuya (en casa) o en la nube. El celular es solo el canal.
La regla de oro del proyecto es brick-by-brick (ladrillo por ladrillo): construyes UNA parte, pruebas que funciona y solo entonces pasas a la siguiente. Nada de montar todo de una vez y tratar de descubrir qué se rompió. Son cinco pasos, y cada uno hace que tu Jarvis esté un poco más vivo.
O celular nunca aloja el cerebro; solo se comunica, por Telegram, con el agente que vive en tu PC o en la nube. Cada pieza azul cian es uno de los cinco pasos: conectas uno a la vez.
¿Eres nuevo aquí? Uno bot y un programa que conversa a través de una app de mensajería (aquí, Telegram) en lugar de una pantalla propia. Agente y es nuestro Jarvis: el programa que recibe tu mensaje, piensa con el modelo de IA y responde —a veces usando herramientas. Heartbeat ("latido") es una tarea programada que hace que el agente actúe por su cuenta a una hora determinada, sin que tú se lo pidas.
🧰 Lo que vas a necesitar (1 vez)
- •Una computadora propia (Windows, Mac o Linux) con Node.js o Python instalado — donde se ejecutará el agente.
- •La cuenta de Telegram que ya usas en el celular.
- •Una clave de modelo (nube: OpenRouter/Anthropic) o o Ollama instalado para ejecutarse localmente — elige en el Paso 2.
- •~40 minutos y disposición para probar cada pieza.
Conceptos clave
La puerta por la que hablas con Jarvis: aquí, Telegram.
Construir y probar una parte a la vez, nunca todo junto.
"Telegram ya es móvil": nada de publicar una app nativa.
El cerebro está en la PC o en la nube; el teléfono solo conversa.
🤖 Paso 1: el bot
El primer paso es crear el bot. En Telegram hay un bot oficial llamado @BotFather que crea otros bots para ti. Conversas con él, recibes un token (una contraseña larga que identifica a tu bot) y listo: el canal existe. Luego pones la primera barrera de seguridad: la lista de permitidos (lista de permitidos), para que solo tú reciba atención.
Habla con @BotFather
En Telegram, busca @BotFather, abre la conversación y envía /newbot. Pregunta el nombre y el usuario (debe terminar en bot, p. ej.: meu_jarvis_bot).
Guarda el token
Responde con algo como 7891234:AAF...xYz. Este es el token: trátalo como una contraseña. Se guardará en un archivo .env, nunca en el código ni en una publicación pública.
Descubre TU user ID
Habla con @userinfobot: responde con tu número de usuario (p. ej.: 123456789). Ese es el número que se agrega a la whitelist.
.env
Objetivo: guardar el token y la whitelist fuera del código. Crea un archivo llamado .env en la carpeta del proyecto y pega el bloque de abajo, cambiando los fragmentos entre < > por tus valores.
# .env (NUNCA suba este arquivo pro GitHub)
TELEGRAM_BOT_TOKEN=<cole-seu-token-do-BotFather>
TELEGRAM_ALLOWED_IDS=<seu-user-id-do-userinfobot>Cómo verificar: ejecuta el agente (ej.: npm start o python main.py), envía /start conéctate a tu bot desde el celular y mira si responde. Después pídele a un amigo que le escriba al mismo bot: solo debe responderte a ti. ignorado en silencio. Si eso ocurre, la lista blanca está funcionando.
¿Eres nuevo aquí? Un archivo .env ("environment", entorno) es un bloque de texto donde guardas secretos (tokens, claves) separados del código. Long-polling y es la forma en que Telegram funciona sin abrir ninguna puerta en tu PC: es tu agente quien pregunta a Telegram "¿llegó un mensaje?", en vez de quedarse esperando a que alguien llame a la puerta de tu máquina. Por eso el bot es seguro incluso cuando se ejecuta en casa.
Conceptos clave
El bot oficial de Telegram que crea tu bot y te entrega el token.
La contraseña del bot. Está en .env, nunca en el código.
Lista de ID(s) permitidos; cualquier otro se ignora.
Sin puertos expuestos: el agente le pregunta a Telegram si llegó algo.
🧠 Paso 2: el cerebro
El bot ya recibe mensajes, pero todavía no piensa. Ahora conectas el cerebro: el modelo de IA que generará las respuestas. Aquí tomas la decisión más importante del proyecto, y solo lleva una línea en el .env. Puedes usar la nube (potente, se paga por uso) o ejecutar local con Ollama (gratis después de descargarlo, privado, más lento). Lo mejor: cambiar entre los dos no modifica el código: es hot-swap (cambio en caliente).
☁️ Nube (OpenRouter / Anthropic)
- ✓Respuestas rápidas y potentes, incluso en una PC de bajos recursos.
- ✓Cero configuración de hardware.
- ✗Pagas por token; los datos salen de tu máquina.
- ✗Necesita internet.
🏠 Local (Ollama)
- ✓$0 por token después de descargar; los datos se quedan en casa.
- ✓Funciona sin conexión.
- ✗Requiere RAM (3B@8GB, 8B@16GB); en CPU es lento (30-60s).
- ✗Respuestas un poco más débiles que las de la nube de punta.
.env
Objetivo: elegir el cerebro cambiando solo dos líneas. Agrega UNO de los bloques siguientes a tu .env (deja el otro comentado con #).
# --- opcao A: NUVEM (potente, paga por uso) ---
LLM_PROVIDER=openrouter
LLM_MODEL=<ex: anthropic/claude-3.5-sonnet>
LLM_API_KEY=<cole-sua-chave-do-openrouter>
# --- opcao B: LOCAL com Ollama (gratis, privado) ---
# LLM_PROVIDER=ollama
# LLM_MODEL=<ex: llama3.2>
# (rode antes, no terminal: ollama pull <ex: llama3.2> )Cómo verificar: reinicia el agente y envía desde el celular: «en una frase, ¿quién eres?». Si recibes una respuesta coherente, el cerebro está conectado. Para probar el hot-swap, cambia el bloque activo (comenta A, descomenta B), reinicia y vuelve a enviar el mensaje: misma conversación, cerebro diferente, sin tocar el código.
⚠️ Precaución clásica: no mezcles claves
Clave de OpenAI no es clave de Anthropic, y ninguna de las dos es el token de Telegram. Cada servicio tiene la suya. Mezclarlas es la causa número 1 de «no funciona y no sé por qué». Si aparece un error de autenticación (401/403), lo primero que debes revisar es qué clave se asignó a cada variable en el .env.
Conceptos clave
El modelo que piensa en texto y genera las respuestas.
Cambiar el modelo cambiando el .env, sin tocar el código.
Programa que ejecuta modelos de IA en tu propia computadora.
Local para tareas simples, nube para tareas difíciles.
💾 Paso 3: memoria + soul
Ahora el bot piensa, pero es un desconocido: lo olvida todo al cerrar y no tiene personalidad. Dos archivos lo resuelven. El soul.md ("el alma") del carácter —quién es, su tono de voz, qué prioriza— y se inyecta siempre al inicio de la conversación. La memoria hace que recuerde: las conversaciones se convierten en texto guardado y un índice SQLite permite buscar lo que ya se dijo. Sin el soul, tienes "una carpeta de código"; con él, tienes un Jarvis.
soul.md
Objetivo: darle identidad al bot. Crea un archivo soul.md en la carpeta del proyecto y pega el bloque, cambiando los fragmentos entre < >.
# soul.md — a alma do meu Jarvis
## Quem sou
Eu sou o <nome-do-seu-jarvis>, assistente pessoal de <seu-nome>.
## Tom de voz
Direto, caloroso e breve. Sem enrolacao. Trato <seu-nome> pelo nome.
## Prioridades
- Responder em portugues.
- Quando nao souber, dizer que nao sabe (nunca inventar).
- Lembrar do contexto das conversas anteriores.
## Sobre <seu-nome>
Fuso: <ex: America/Sao_Paulo>. Trabalho: <ex: professor>.
Prefere respostas em topicos curtos.Cómo verificar: reinicia y envía "¿cuál es tu nombre y quién soy yo para ti?". Debe responder con el nombre del soul.md y llamarte por tu nombre. Después envía «mi plato favorito es la lasaña», cierra Telegram, vuelve a abrirlo más tarde y pregunta "¿cuál es mi plato favorito?". Si lo recuerda, la memoria SQLite está guardando los datos.
🧩 Cómo funciona la memoria, sin misticismos
- •Cada conversación se convierte texto guardado en un archivo o una base de datos: la «verdad» es legible para ti.
- •Un índice SQLite FTS5/BM25 (la búsqueda por palabras) encuentra rápidamente el fragmento relevante cuando preguntas algo.
- •Antes de responder, el agente busca en la memoria y pega el fragmento en el contexto. Por eso «recuerda».
¿Eres nuevo aquí? SQLite y una base de datos que es solo un archivo en tu carpeta (nada de servidor). FTS5/BM25 y es la forma en que busca texto: preguntas "lasagna" y encuentra la frase donde hablaste de eso. System prompt y es el texto invisible que se pega al inicio de cada conversación: ahí es donde el soul.md entra para que el modelo «sepa quién es».
Conceptos clave
El alma: personalidad, tono y prioridades, siempre inyectados.
Las conversaciones se convierten en texto que perdura aunque cierres la app.
Archivo de base de datos simple; el índice de memoria.
El texto inicial donde el soul se convierte en la identidad del modelo.
🧩 Paso 4: una skill útil
Hasta aquí tu Jarvis conversa y recuerda. Es hora de que hacer algo concreto. Una skill y una «receta»: un archivo breve que empaqueta un paso a paso que repetirías cada vez. La nuestra: "resumen de mi día" — consulta tu agenda (mediante una herramienta MCP de calendario) y devuelve un resumen en viñetas. En vez de explicar cinco pasos, dices una frase y la skill la ejecuta.
MCP (Model Context Protocol) es el "USB de las herramientas de IA": cada integración (calendario, correo electrónico, GitHub) es un servidor independiente y estandarizado que conectas sin tener que reescribir el agente. Es más seguro que descargar "skills de la comunidad" de origen dudoso: sabes exactamente qué hace cada servidor.
skills/resumo-do-dia/SKILL.md
Objetivo: darle a Jarvis la receta para resumir tu día. Crea la carpeta y el archivo SKILL.md abajo, intercambiando las piezas entre < >.
---
name: resumo-do-dia
description: Resume os compromissos de hoje em topicos curtos.
Acionar quando o usuario disser "resumo do dia", "como esta
meu dia" ou "agenda de hoje".
---
# Resumo do meu dia
Passos:
1. Use a ferramenta de calendario (MCP) para listar os
eventos de HOJE no fuso <ex: America/Sao_Paulo>.
2. Para cada evento, pegue horario + titulo.
3. Responda em ate <ex: 5> topicos curtos, do mais cedo
ao mais tarde. Comece com "Bom dia, <seu-nome>!".
4. Se nao houver eventos, diga que a agenda esta livre.Cómo verificar: reinicia el agente y envía desde el celular "resumen de mi día". Debe activar la skill, consultar el calendario y responder con la lista de eventos en viñetas (o avisar que no hay eventos). Si responde de forma genérica sin revisar la agenda, verifica si el servidor MCP del calendario está conectado.
📊 Skill x herramienta: ¿cuál es la diferencia?
- •Herramienta (tool): una acción atómica — "listar eventos del calendario". Es una mano.
- •Skill: un procedimiento que orquesta herramientas + criterio: «arma el resumen del día». Es la receta que usa las manos.
- •La skill cuesta casi nada hasta que se activa: el agente lee solo el frontmatter (~100 tokens) y solo carga el resto cuando hace falta.
¿Eres nuevo aquí? O frontmatter y es el bloque entre --- en la parte superior del archivo (nombre + descripción). A partir de ahí, el agente decide si activa la skill. Carga progresiva significa que la receta completa solo se lee cuando hace falta: ahorra contexto y mantiene ligero a Jarvis.
Conceptos clave
Una receta empaquetada en un archivo markdown.
El «USB de las herramientas»: conecta integraciones estandarizadas.
Nombre + descripción en la parte superior; decide cuándo activar la skill.
La receta solo se lee cuando hace falta.
🎙️ Paso 5: voz y cadencia
Los dos últimos bloques hacen que Jarvis sea humano y proactivo. Voz: envías un audio por Telegram y el agente lo transcribe con Whisper (entiende lo que dices), piensa y, si quieres, responde hablando con TTS (síntesis de voz). Cadencia: un heartbeat programado (cron), hace que actúe por su cuenta — por ejemplo, que te envíe el «resumen de mi día» todos los días a las 7 h, aunque tengas el celular en el bolsillo y la laptop apagada.
O audio se convierte en texto (Whisper), el LLM piensa en texto, y la respuesta hablada (TTS) es opcional. Recuerda: "la voz es la interfaz, el orquestador es el cerebro": tú decides en cada mensaje si responde por texto o por voz.
.env + terminal
Objetivo: activar la voz y programar el resumen diario. Agrega al .env y prueba la conversión de audio en la terminal.
# .env (voz e cadencia)
VOICE_ENABLED=true
STT_PROVIDER=whisper
OPENAI_API_KEY=<chave-da-OpenAI-so-para-Whisper>
# heartbeat: rodar a skill "resumo-do-dia" todo dia as 7h
HEARTBEAT_CRON=<ex: 0 7 * * *>
HEARTBEAT_SKILL=resumo-do-dia
# --- teste rapido da conversao de audio (no terminal) ---
# ffmpeg -i <audio-do-telegram.ogg> -ar 16000 saida.wavCómo verificar: (voz) graba un audio en Telegram diciendo «cuéntame un dato curioso» — el agente debe transcribir y responder. (cadencia) para no esperar hasta las 7h, cambia temporalmente HEARTBEAT_CRON para dentro de 2 minutos (p. ej.: si son las 14h32, usa 34 14 * * *), reinicia y mira cómo llega el mensaje por sí solo. ¿Funcionó? Vuelve a poner el cron en 0 7 * * *.
⚠️ La clave de Whisper es diferente
Whisper (transcripción) suele usar la OPENAI_API_KEY, que NO es la clave de tu cerebro si elegiste Anthropic/OpenRouter, ni el token de Telegram. Tres servicios, tres credenciales. Si la voz "no transcribe", casi siempre falta esta clave o está cambiada.
¿Eres nuevo aquí? STT ("speech-to-text") es convertir voz en texto; Whisper y es el modelo que hace eso. TTS ("text-to-speech") es el camino inverso: el texto se convierte en voz. ffmpeg y un conversor de audio/video que prepara el archivo de Telegram para Whisper. cron y la notación de programación: 0 7 * * * quiere decir "a las 7h00, todos los días".
Conceptos clave
Transforma el audio que envías en texto.
Salida opcional: el Jarvis responde hablando.
Programación que hace que el agente actúe solo a una hora determinada.
De «responde cuando lo llamo» a «avísame antes».
Autoevaluación (opcional): en tu Jarvis de bolsillo, ¿dónde está el cerebro (el modelo)?
🎯 Resumen del módulo
Siguiente:
Volver a la trilha — concluiste la Trilha 5 (Jarvis en el celular). Es hora de revisar el recorrido y seguir con la Trilha 6.