Presupuesto Conversacional — Pipeline Core

Sistema de registro de gastos por lenguaje natural, vía Telegram, usando Google Gemini (API oficial, modelo configurable vía .env, por defecto gemini-3.6-flash) como modelo de lenguaje, orquestado por Nanobot, con los datos guardados en Postgres.

Este documento asume que nunca has usado Docker antes y explica cada paso, cada comando, y qué esperar como resultado de cada uno.

Índice

1. Lo que necesitas tener instalado

2. Conseguir el token del bot en Telegram

3. Conseguir la clave de la API de Gemini

4. Configurar el archivo .env

5. Levantar todo con Docker

6. Probar en Telegram

7. Comandos del día a día

8. Problemas comunes y cómo resolverlos

9. Qué hace cada archivo del proyecto

10. Alternativa: instalación local (sin Docker)

11. Próximos pasos del proyecto

Related MCP server: Expense Tracker MCP Server

1. Lo que necesitas tener instalado

Solo una cosa en tu máquina. No necesitas instalar Python, Postgres ni Nanobot por separado — todo eso corre dentro de los contenedores.

Docker Desktop (Windows/Mac) o Docker Engine (Linux)

• Windows o Mac: descarga e instala Docker Desktop en https://www.docker.com/products/docker-desktop/ — después de instalar, abre la aplicación Docker Desktop y espera a que muestre "Docker is running" (el icono se pone verde/estable en la bandeja del sistema).

• Linux: sigue https://docs.docker.com/engine/install/ para tu distribución, y luego https://docs.docker.com/engine/install/linux-postinstall/ para poder ejecutar docker sin sudo.

Verificar que todo está bien

Abre una terminal (PowerShell en Windows, Terminal en Mac/Linux) y ejecuta:

docker --version
docker compose version

Debes ver dos líneas de versión, sin error.

2. Conseguir el token del bot en Telegram

1. Abre Telegram (móvil o escritorio) y busca @BotFather en la búsqueda. Es el bot oficial de Telegram para crear otros bots — verifica que tenga el sello de verificado.

2. Envíale: /newbot

3. Te preguntará un nombre para tu bot. Puede ser cualquier cosa, ej.: Presupuesto Conversacional.

4. Luego te pregunta un username. Este debe ser único en todo Telegram y tiene que terminar en "bot", ej.: presupuesto_tunombre_bot.

5. Si funciona, BotFather responde con un mensaje parecido a este:

   Done! Congratulations on your new bot. You will find it at
   t.me/orcamento_seunome_bot. You can now add a description...
   
   Use this token to access the HTTP API:
   7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   
   Keep your token secure and store it safely...

6. Copia la línea del token completa (el formato es números:letras_y_números). La pegarás en el archivo .env en el siguiente paso.

Guarda ese token.

3. Conseguir la clave de la API de Gemini

Nanobot usa la API oficial de Google Gemini como modelo de lenguaje.

1. Accede a https://aistudio.google.com/api-keys e inicia sesión con tu cuenta de Google.

2. Haz clic en Create API key (Google crea un proyecto automáticamente).

3. Copia la clave y pégala en el .env en el siguiente paso.

Sobre costos: no pide tarjeta. El free tier cubre los modelos Flash/Flash-Lite con límites de solicitudes por minuto/día (~10 req/min y ~250–1.500 req/día según el modelo) — suficiente para este proyecto. Los modelos Pro son de pago. Tabla oficial: https://ai.google.dev/gemini-api/docs/pricing

4. Configurar el archivo .env

El proyecto ya viene con un archivo llamado .env en la raíz de la carpeta (presupuesto-conversacional/.env). Docker Compose lo lee automáticamente — no necesitas renombrar nada.

Atención: los archivos que empiezan con punto (.env) son "ocultos" por defecto en el Explorador de Archivos de Windows, en el Finder de Mac, y en ls sin flags en Linux/Mac. Usa ls -la para verlo en la terminal, o abre la carpeta desde el editor de texto.

Dentro del .env, cambia estas dos líneas por los valores reales:

TELEGRAM_TOKEN=coloque_seu_token_aqui      ← token do BotFather (seção 2)
GEMINI_API_KEY=coloque_sua_chave_aqui      ← chave do AI Studio (seção 3)

La variable GEMINI_MODEL define qué modelo usar (por defecto: gemini-3.6-flash). Solo modifícala si quieres cambiarla por otro ID válido de la lista oficial: https://ai.google.dev/gemini-api/docs/models

Las otras variables (POSTGRES_PASSWORD, DATABASE_URL) ya vienen con valores que funcionan — no necesitas tocarlas para ejecutar en Docker.

Guarda el archivo.

5. Levantar todo con Docker

Con la terminal abierta dentro de la carpeta presupuesto-conversacional (la que tiene el archivo docker-compose.yml), ejecuta:

docker compose up -d --build

Lo que hace este comando, en orden:

No hay descarga ni ejecución de modelo en tu máquina: Gemini corre en la nube de Google.

La bandera -d ("detached") hace que todo corra en segundo plano. Las próximas veces que ejecutes docker compose up -d (sin --build), se levanta en segundos.

Cómo saber si todo salió bien

Ejecuta:

docker compose ps

Debes ver 2 servicios:

NAME                    IMAGE                    STATUS
orcamento_postgres      postgres:16-alpine       Up (healthy)
orcamento_nanobot       ...nanobot               Up

Revisa también los logs de Nanobot — debe aparecer el MCP conectado:

docker compose logs nanobot

Busca líneas como:

MCP: registered tool 'mcp_orcamento_registrar_despesa' from server 'orcamento'
MCP server 'orcamento': connected, 3 capabilities registered
✓ Health endpoint: http://127.0.0.1:18790/health
bot @seubot connected

Si orcamento_nanobot aparece como "Restarting" o desaparece de la lista, consulta la sección Problemas comunes.

6. Probar en Telegram

1. En Telegram, busca el username del bot que creaste con BotFather (ej.: @presupuesto_tunombre_bot) y abre una conversación con él.

2. Envía /start. En la primera conversación, Nanobot puede pedir un código de emparejamiento — aparece en los logs (docker compose logs -f nanobot, línea "Generated pairing code ..."). Envía ese código al bot.

3. Envía algo como:

   Gastei 35 no almoço hoje

4. En unos segundos, el bot debe responder confirmando el registro, algo como:

   Registrado: R$ 35,00 em alimentação (almoço).

Si el bot no responde nada, consulta la sección de problemas comunes abajo.

7. Comandos del día a día

Todos se ejecutan dentro de la carpeta presupuesto-conversacional.

Ver los logs de todo, en tiempo real:

docker compose logs -f

(Ctrl+C para salir — esto solo deja de mostrar los logs, los contenedores siguen corriendo.)

Ver los logs solo de Nanobot (el más útil para depurar conversaciones):

docker compose logs -f nanobot

Parar todo (manteniendo los datos guardados):

docker compose down

Levantar de nuevo después de parar:

docker compose up -d

Después de editar SOUL.md, config.docker.json o el .env (no necesitas reconstruir la imagen; la configuración y los prompts se montan directamente en el contenedor):

docker compose up -d nanobot    # recria o container aplicando o novo .env

Después de editar mcp_server/expense_tools.py o db/connection.py (necesitas reconstruir, porque el venv del MCP se crea en la imagen):

docker compose up -d --build nanobot

Borrar absolutamente todo, incluidos los datos de la base de datos (útil si algo se corrompió y quieres empezar de cero):

docker compose down -v

Entrar en la base de datos para ver los gastos registrados manualmente:

docker exec -it orcamento_postgres psql -U orcamento -d orcamento

Dentro de psql, prueba:

SELECT * FROM despesas ORDER BY criado_em DESC LIMIT 10;

Para salir de psql: escribe \q y Enter.

Atajo opcional: si tienes make instalado (estándar en Mac/Linux), el proyecto incluye un Makefile con los comandos más usados: make up, make down, make logs, make restart, make ps.

8. Problemas comunes y cómo resolverlos

Error: Environment variable 'GEMINI_API_KEY' referenced in config is not set

El .env no tiene la variable GEMINI_API_KEY definida. Abre el .env, asegúrate de que la línea exista (aunque sea con un valor provisional) y ejecuta docker compose up -d nanobot de nuevo.

401, unauthorized o invalid api key en los logs de Nanobot

La GEMINI_API_KEY está mal, revocada o tiene un espacio extra. Genera una nueva clave en https://aistudio.google.com/api-keys y actualiza el .env.

429 o errores de rate limit / cuota

Has alcanzado el límite del free tier de Gemini (solicitudes por minuto o por día). Opciones: esperar unos minutos, cambiar GEMINI_MODEL en el .env a un modelo Flash-Lite (límites mayores, ej.: gemini-3.1-flash-lite) y levantar de nuevo, o habilitar facturación en tu cuenta de Google Cloud.

model not found en los logs

El valor de GEMINI_MODEL no es un ID válido de la API de Gemini. Consulta la lista oficial en https://ai.google.dev/gemini-api/docs/models y corrige el .env.

El bot no llama a las tools / dice que no puede registrar

Ejecuta docker compose logs nanobot y busca:

• MCP server 'orcamento': connected — si no aparece, hubo un fallo al iniciar el servidor MCP integrado; mira los errores justo encima de esa línea;

• Max iterations (...) reached — significa que el modelo entró en un bucle de tool-calls; el límite configurable está en agents.defaults.maxToolIterations de la configuración.

El bot no responde nada en Telegram

• Revisa docker compose logs -f nanobot mientras envías un mensaje — debe aparecer alguna actividad en el log en el mismo instante.

• Verifica que completaste el emparejamiento (sección 6, paso 2).

docker compose version dice "unknown flag" o no existe

Tienes el Docker Compose antiguo (v1, con guion: docker-compose). Actualiza Docker Desktop, o instala el plugin docker-compose-plugin por separado (Linux).

9. Qué hace cada archivo del proyecto

orcamento-conversacional/
├── .env                         # SUAS credenciais (token do Telegram, chave
│                                #   do Gemini, senha do banco). Lido
│                                #   automaticamente pelo docker compose.
├── .env.example                 # Modelo de referência do .env, sem credenciais reais.
├── docker-compose.yml           # Define os containers (postgres, nanobot) e
│                                #   a ordem de inicialização.
├── Makefile                     # Atalhos opcionais (make up, make logs, etc).
├── requirements.txt             # Dependências Python do servidor MCP (mcp, psycopg2-binary).
│
├── db/
│   ├── schema.sql               # Cria as tabelas usuarios, categorias, despesas.
│   │                            #   Aplicado automaticamente na 1ª subida do Postgres.
│   └── connection.py            # Código Python que conecta no Postgres (pool de conexões)
│                                #   e resolve o usuário do Telegram para um id interno.
│
├── mcp_server/
│   ├── expense_tools.py         # As "ferramentas" que o agente de IA usa:
│   │                            #   registrar_despesa, listar_despesas, resumo_por_categoria.
│   │                            #   Roda via stdio DENTRO do container do Nanobot.
│   └── Dockerfile               # Imagem standalone opcional do MCP server (modo HTTP).
│
└── nanobot_config/
    ├── config.json              # Config do Nanobot para rodar FORA do Docker
    │                            #   (instalação local — ver seção 10). MCP via stdio
    │                            #   relativo à raiz do projeto.
    ├── config.docker.json       # Config do Nanobot para rodar DENTRO do Docker —
    │                            #   é este que está ativo quando você usa `docker compose up`.
    │                            #   MCP via stdio em /opt/mcpvenv (venv isolado).
    ├── Dockerfile               # Como construir a imagem do Nanobot. Instala o
    │                            #   nanobot + um venv isolado (/opt/mcpvenv) com as
    │                            #   dependências do servidor MCP.
    ├── SOUL.md                  # As instruções que dizem ao agente COMO se comportar:
    │                            #   como extrair valor/categoria/data de uma mensagem,
    │                            #   quando pedir confirmação, o que ele NÃO deve fazer ainda.
    ├── AGENTS.md                # Regras gerais de comportamento (idioma, uso de tools,
    │                            #   tratamento de erro). Complementa o SOUL.md.
    └── USER.md                  # Perfil do usuário — começa vazio, o Nanobot vai
                                  preenchendo automaticamente com o tempo.

Detalles de la arquitectura actual

• Modelo de lenguaje: Google Gemini vía API oficial (providers.gemini). El modelo se elige con la variable GEMINI_MODEL en el .env (por defecto: gemini-3.6-flash). No se ejecuta ningún modelo local.

• Servidor MCP: corre como subproceso (stdio) dentro del propio contenedor de Nanobot, usando el venv aislado /opt/mcpvenv. ¿Por qué aislado? El SDK de Python mcp 2.x usado por las tools entra en conflicto con la versión (mcp>=1.26,<2) que exige el propio nanobot.

• Protección contra bucles: agents.defaults.maxToolIterations: 6 limita cuántas llamadas de tool seguidas puede hacer el agente en un mismo turno.

¿Por qué hay dos archivos de configuración de Nanobot?

config.json (para ejecutar localmente, fuera de Docker) apunta al servidor MCP vía stdio relativo a la raíz del proyecto. config.docker.json (usado dentro de Docker) usa rutas absolutas del contenedor (/opt/mcp_server/...) y el venv /opt/mcpvenv/bin/python3.

10. Alternativa: instalación local (sin Docker)

Si prefieres ejecutar Postgres/Nanobot directamente en tu máquina en lugar de en contenedores (más tedioso de configurar, pero más fácil de depurar línea por línea):

10.1. Levantar solo Postgres en Docker

docker compose up -d postgres

(Esto levanta solo Postgres. El schema.sql se aplica automáticamente.)

10.2. Instalar las dependencias de Python del servidor MCP

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Exporta las variables de entorno en la misma terminal:

export DATABASE_URL=postgresql://orcamento:orcamento@localhost:5432/orcamento
export TELEGRAM_TOKEN=seu_token_aqui
export GEMINI_API_KEY=sua_chave_aqui
export GEMINI_MODEL=gemini-3.6-flash

(En Windows PowerShell, usa $env:DATABASE_URL = "...", etc.)

10.3. Instalar y ejecutar Nanobot

pip install -U nanobot-ai

Copia nanobot_config/config.json a ~/.nanobot/config.json, y nanobot_config/SOUL.md a ~/.nanobot/workspace/SOUL.md (crea la carpeta workspace si no existe).

Ejecuta desde la raíz de este proyecto (la ruta del servidor MCP en el config.json es relativa a ese directorio):

nanobot gateway --config nanobot_config/config.json --verbose

Probar sin Telegram (útil para depurar la extracción)

nanobot agent -c nanobot_config/config.json -m "Paguei 120 no mercado no cartão hoje"

11. Próximos pasos del proyecto

1. Probar el flujo de extremo a extremo con mensajes reales y ajustar el SOUL.md según los errores de extracción observados (lenguaje informal, abreviaciones, valores ambiguos).

2. Añadir la tool de informes completos (comparación entre períodos, evolución de gastos).

3. Implementar la capa de recomendaciones: consolidar los datos de resumo_por_categoria y enviarlos a una LLM avanzada vía API.

4. Vincular automáticamente los gastos al usuario de Telegram autenticado (hoy el telegram_id es pasado por el modelo al llamar a la tool).

Aviso sobre validación

El pipeline fue validado en ejecución real con Docker: contenedores levantándose, MCP conectado vía stdio con las 3 tools registradas, e inserciones en Postgres confirmadas vía psql. La sintaxis del docker-compose.yml y de los JSONs de config se verifica antes de cada subida.

Si algo se traba exactamente en docker compose up, comience por la sección 8. Problemas comunes.