Asistente Personal con IA

Un asistente conversacional personal, accesible por Telegram, con memoria persistente entre sesiones. Pensado como proyecto de aprendizaje incremental: cada etapa agrega una capacidad real (proveedores de IA, herramientas/acciones, multi-agente, RAG, MCP) sobre una base que ya funciona de punta a punta.

Nota: proyecto desarrollado con asistencia de IA (Claude, de Anthropic).

Estado actual: V7 — Servidor MCP

• Bot de Telegram como interfaz (sin frontend propio).

• Memoria persistente por chat en SQLite (recuerda la conversación entre mensajes y reinicios del bot).

• Capa de abstracción de proveedor de IA (llm_client.py): el mismo bot puede correr contra Claude (Anthropic), OpenAI (GPT) o un modelo Llama local vía Ollama, sin costo, eligiendo con una variable de entorno. Los tres soportan el mismo loop de tools.

• Tool calling real (tools.py):

  • get_weather — clima actual vía Open-Meteo (sin API key).

  • set_reminder — recordatorio con entrega asíncrona real vía job_queue de Telegram, sin que el usuario vuelva a escribir.

  • generate_image — genera y envía una imagen (Pollinations.ai, sin API key) a partir de una descripción.

  • search_notes — RAG sobre archivos propios (documents/*.md, *.txt): busca por similitud semántica usando embeddings locales de Ollama (nomic-embed-text) guardados en SQLite, sin base de datos vectorial externa.

• Arquitectura multi-agente (agents.py): un orquestador recibe cada mensaje y decide si lo responde directamente (charla general) o lo delega a un agente especializado (clima, recordatorios, imágenes, notas), cada uno con su propio system prompt enfocado y acceso solo a su propia tool. Reusa el mismo loop de tool-calling de llm_client.py, generalizado para aceptar system prompt / tools / executor por agente.

• Servidor MCP (mcp_server.py): expone get_weather, search_notes y generate_image como un servidor MCP real (protocolo estándar, transporte stdio), para que cualquier cliente MCP (Claude Desktop, Claude Code, etc.) las use directamente — no solo el bot de Telegram. set_reminder no se expone acá porque depende del job_queue de un chat de Telegram especifico, que no existe fuera de ese contexto; generate_image devuelve la URL de la imagen en vez de enviarla, porque acá no hay chat al que mandarla.

Nota sobre offline: el modelo local (Ollama) corre sin internet, pero Telegram es un servicio en la nube — la interfaz del bot y las tools de clima/imágenes sí necesitan conexión. search_notes sí funciona 100% offline si LLM_PROVIDER=ollama (embeddings y modelo, ambos locales).

Related MCP server: MCP Quickstart Weather Server

Arquitectura

Telegram (usuario) ──▶ main.py (bot handler)
                              │
                              ├─▶ memory.py ──▶ SQLite (historial por chat_id)
                              │
                              └─▶ agents.py (orquestador)
                                        │
                                        ├─▶ responde directo (charla general)
                                        │
                                        └─▶ delegate ──▶ agente especialista (clima/recordatorios/imagenes/notas)
                                                              │        (system prompt + tools propias)
                                                              ▼
                                        llm_client.py ──▶ Anthropic API  (LLM_PROVIDER=anthropic)
                                                       ├──▶ OpenAI API    (LLM_PROVIDER=openai)
                                                       └──▶ Ollama local  (LLM_PROVIDER=ollama)
                                                              │
                                                              ▼ (si el agente pide su tool)
                                        tools.py ──▶ Open-Meteo / job_queue / Pollinations.ai / rag.py

Hallazgo de V6: confiabilidad de las cadenas multi-agente con modelos locales chicos

Probando V6 en vivo con llama3.1:8b (local, vía Ollama) apareció algo interesante: la arquitectura funciona (el orquestador delega bien, el agente especialista llama a su tool correctamente, el dato real llega), pero el relevo final — el paso donde un agente tiene que tomar el resultado de una tool y convertirlo en una respuesta en lenguaje natural — falla de forma intermitente, y el fallo se puede mover a cualquier eslabón de la cadena (a veces el especialista, a veces el propio orquestador), incluso reforzando el prompt con reglas explícitas y ejemplos concretos.

La causa más probable: modelos chicos como este tienen un sesgo de entrenamiento muy fuerte hacia responder "no tengo acceso a datos en tiempo real" ante preguntas de clima/hora/etc., y ese reflejo a veces gana incluso con el dato correcto ya en el contexto. Cada salto adicional en una cadena multi-agente es una nueva oportunidad para que ese reflejo se dispare — a diferencia del flujo de un solo agente (V1-V5), donde el mismo modelo respondió bien de forma consistente.

Conclusión práctica: la arquitectura multi-agente (orquestador + especialistas) está bien diseñada y funciona; la confiabilidad del paso final depende del modelo usado. Queda pendiente confirmar si un modelo más grande (Claude, GPT-4o) elimina este problema — es la hipótesis más probable dado que ninguno de estos fallos apareció durante las pruebas de V1-V5 con el mismo modelo en un solo salto.

Notas personales (RAG)

Poné tus propios archivos .md o .txt en la carpeta documents/ (se crea sola, y está en .gitignore — tus notas nunca se suben al repo). Se indexan automáticamente cada vez que arranca el bot.

Servidor MCP

Probarlo standalone (lanza el servidor como subproceso y llama a sus tools por el protocolo real):

python test_mcp_client.py

Para usarlo desde Claude Desktop, agregar en su config (claude_desktop_config.json):

{
  "mcpServers": {
    "asistente-personal": {
      "command": "C:\\ruta\\a\\este\\repo\\.venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\a\\este\\repo\\mcp_server.py"]
    }
  }
}

Cómo correrlo

1. Crear un bot con @BotFather en Telegram y copiar el token.

2. Elegir proveedor: API key de console.anthropic.com o de platform.openai.com (ambas requieren créditos de API, pago único — distinto de una suscripción a Claude Pro/ChatGPT Plus) o instalar Ollama y descargar un modelo local (ollama pull llama3.2) para no depender de ninguna API paga.

3. Copiar .env.example a .env y completar TELEGRAM_BOT_TOKEN, LLM_PROVIDER (anthropic, openai u ollama) y la key/modelo correspondiente.

4. python -m venv .venv
   .venv/Scripts/activate   # en Windows
   pip install -r requirements.txt
   python main.py

5. Escribirle al bot por Telegram.

Stack

• Python 3.11

• python-telegram-bot

• Anthropic SDK / OpenAI SDK / Ollama (modelo local)

• MCP Python SDK

• SQLite (memoria persistente + índice RAG)

Licencia

MIT