Konversationsbudget – Core-Pipeline

System zur Erfassung von Ausgaben über natürliche Sprache, per Telegram, unter Verwendung von Google Gemini (offizielle API, Modell über .env konfigurierbar, standardmäßig gemini-3.6-flash) als Sprachmodell, orchestriert vom Nanobot, mit Daten, die in Postgres gespeichert werden.

Dieses Dokument geht davon aus, dass Sie noch nie Docker verwendet haben und erklärt jeden Schritt, jeden Befehl und was Sie als Ergebnis von jedem erwarten können.

Inhaltsverzeichnis

1. Was Sie installiert haben müssen

2. Telegram-Bot-Token erhalten

3. Gemini-API-Schlüssel erhalten

4. Die .env-Datei konfigurieren

5. Alles mit Docker starten

6. In Telegram testen

7. Befehle für den Alltag

8. Häufige Probleme und deren Lösung

9. Was jede Projektdatei macht

10. Alternative: lokale Installation (ohne Docker)

11. Nächste Schritte des Projekts

Related MCP server: Expense Tracker MCP Server

1. Was Sie installiert haben müssen

Nur eine Sache auf Ihrem Rechner. Sie müssen Python, Postgres oder Nanobot nicht separat installieren – all das läuft in den Containern.

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

• Windows oder Mac: Laden Sie Docker Desktop herunter und installieren Sie es unter https://www.docker.com/products/docker-desktop/ – öffnen Sie nach der Installation die Docker-Desktop-Anwendung und warten Sie, bis sie „Docker is running“ anzeigt (das Symbol wird grün/stabil in der Taskleiste).

• Linux: Folgen Sie https://docs.docker.com/engine/install/ für Ihre Distribution und danach https://docs.docker.com/engine/install/linux-postinstall/, um docker ohne sudo ausführen zu können.

Überprüfen, ob alles korrekt ist

Öffnen Sie ein Terminal (PowerShell unter Windows, Terminal unter Mac/Linux) und führen Sie aus:

docker --version
docker compose version

Sie sollten zwei Versionszeilen sehen, ohne Fehler.

2. Telegram-Bot-Token erhalten

1. Öffnen Sie Telegram (Handy oder Desktop) und suchen Sie in der Suche nach @BotFather. Es ist der offizielle Telegram-Bot zum Erstellen anderer Bots – stellen Sie sicher, dass er das verifizierte Abzeichen hat.

2. Senden Sie ihm: /newbot

3. Er fragt nach einem Namen für Ihren Bot. Er kann beliebig sein, z. B.: Konversationsbudget.

4. Danach fragt er nach einem Benutzernamen. Dieser muss in ganz Telegram eindeutig sein und muss auf „bot“ enden, z. B.: budget_ihrname_bot.

5. Wenn es klappt, antwortet BotFather mit einer Nachricht wie dieser:

   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. Kopieren Sie die gesamte Token-Zeile (das Format ist Zahlen:Buchstaben_und_Zahlen). Sie fügen diese im nächsten Schritt in die .env-Datei ein.

Bewahren Sie dieses Token auf.

3. Gemini-API-Schlüssel erhalten

Der Nanobot verwendet die offizielle Google-Gemini-API als Sprachmodell.

1. Rufen Sie https://aistudio.google.com/api-keys auf und melden Sie sich mit Ihrem Google-Konto an.

2. Klicken Sie auf Create API key (Google erstellt automatisch ein Projekt).

3. Kopieren Sie den Schlüssel und fügen Sie ihn im nächsten Schritt in die .env-Datei ein.

Zu den Kosten: Es wird keine Karte verlangt. Der Free-Tier deckt die Flash-/Flash-Lite-Modelle mit Limits für Anfragen pro Minute/Tag (~10 Anfragen/min und ~250–1.500 Anfragen/Tag je nach Modell) ab – ausreichend für dieses Projekt. Die Pro-Modelle sind kostenpflichtig. Offizielle Tabelle: https://ai.google.dev/gemini-api/docs/pricing

4. Die .env-Datei konfigurieren

Das Projekt enthält bereits eine Datei namens .env im Stammverzeichnis (orcamento-conversacional/.env). Sie wird automatisch von Docker Compose gelesen – Sie müssen nichts umbenennen.

Achtung: Dateien, die mit einem Punkt beginnen (.env), sind standardmäßig „versteckt“ im Windows-Explorer, im Mac-Finder und bei ls ohne Flags unter Linux/Mac. Verwenden Sie ls -la, um sie im Terminal zu sehen, oder öffnen Sie den Ordner im Texteditor.

Ersetzen Sie in der .env-Datei diese beiden Zeilen durch die tatsächlichen Werte:

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)

Die Variable GEMINI_MODEL legt fest, welches Modell verwendet wird (Standard: gemini-3.6-flash). Ändern Sie sie nur, wenn Sie ein anderes gültiges ID aus der offiziellen Liste verwenden möchten: https://ai.google.dev/gemini-api/docs/models

Die anderen Variablen (POSTGRES_PASSWORD, DATABASE_URL) haben bereits funktionierende Werte – Sie müssen sie für Docker nicht ändern.

Speichern Sie die Datei.

5. Alles mit Docker starten

Öffnen Sie ein Terminal im Ordner orcamento-conversacional (dem mit der Datei docker-compose.yml) und führen Sie aus:

docker compose up -d --build

Was dieser Befehl in Reihenfolge tut:

Es wird kein Modell auf Ihrem Rechner heruntergeladen oder ausgeführt: Gemini läuft in der Google-Cloud.

Das Flag -d („detached“) lässt alles im Hintergrund laufen. Wenn Sie später docker compose up -d (ohne --build) ausführen, startet es in Sekunden.

So erkennen Sie, ob alles geklappt hat

Führen Sie aus:

docker compose ps

Sie sollten 2 Dienste sehen:

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

Überprüfen Sie auch die Nanobot-Logs – der MCP sollte verbunden erscheinen:

docker compose logs nanobot

Suchen Sie nach Zeilen wie:

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

Wenn orcamento_nanobot als „Restarting“ erscheint oder aus der Liste verschwindet, sehen Sie den Abschnitt Häufige Probleme.

6. In Telegram testen

1. Suchen Sie in Telegram nach dem Benutzernamen des Bots, den Sie bei BotFather erstellt haben (z. B. @budget_ihrname_bot) und öffnen Sie einen Chat mit ihm.

2. Senden Sie /start. Beim ersten Gespräch kann Nanobot einen Pairing-Code anfordern – er erscheint in den Logs (docker compose logs -f nanobot, Zeile „Generated pairing code ...“). Senden Sie diesen Code an den Bot.

3. Senden Sie etwas wie:

   Gastei 35 no almoço hoje

4. Nach einigen Sekunden sollte der Bot mit einer Bestätigung der Erfassung antworten, etwa:

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

Wenn der Bot nicht antwortet, sehen Sie den Abschnitt zu häufigen Problemen unten.

7. Befehle für den Alltag

Alle werden im Ordner orcamento-conversacional ausgeführt.

Logs von allem in Echtzeit anzeigen:

docker compose logs -f

(Ctrl+C zum Beenden – das stoppt nur das Anzeigen der Logs, die Container laufen weiter.)

Nur die Nanobot-Logs anzeigen (am nützlichsten zum Debuggen von Gesprächen):

docker compose logs -f nanobot

Alles stoppen (Daten bleiben erhalten):

docker compose down

Nach dem Stoppen wieder starten:

docker compose up -d

Nach dem Bearbeiten von SOUL.md, config.docker.json oder .env (kein Neubauen des Images nötig; Konfiguration und Prompts werden direkt in den Container gemountet):

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

Nach dem Bearbeiten von mcp_server/expense_tools.py oder db/connection.py (Neubauen erforderlich, da die MCP-venv im Image erstellt wird):

docker compose up -d --build nanobot

Absolut alles löschen, einschließlich der Datenbankdaten (nützlich, wenn etwas beschädigt ist und Sie von vorne beginnen möchten):

docker compose down -v

In die Datenbank gehen, um die erfassten Ausgaben manuell anzusehen:

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

Innerhalb von psql probieren Sie:

SELECT * FROM despesas ORDER BY criado_em DESC LIMIT 10;

Zum Verlassen von psql: \q und Enter eingeben.

Optionaler Abkürzung: Wenn Sie make installiert haben (Standard unter Mac/Linux), enthält das Projekt ein Makefile mit den häufigsten Befehlen: make up, make down, make logs, make restart, make ps.

8. Häufige Probleme und deren Lösung

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

Die .env-Datei hat die Variable GEMINI_API_KEY nicht definiert. Öffnen Sie .env, stellen Sie sicher, dass die Zeile existiert (auch mit einem vorläufigen Wert) und führen Sie docker compose up -d nanobot erneut aus.

401, unauthorized oder invalid api key in den Nanobot-Logs

Die GEMINI_API_KEY ist falsch, widerrufen oder enthält ein zusätzliches Leerzeichen. Erstellen Sie einen neuen Schlüssel unter https://aistudio.google.com/api-keys und aktualisieren Sie .env.

429 oder Rate-Limit-/Quota-Fehler

Sie haben das Limit des Gemini-Free-Tiers erreicht (Anfragen pro Minute oder pro Tag). Optionen: einige Minuten warten, GEMINI_MODEL in .env auf ein Flash-Lite-Modell ändern (höhere Limits, z. B. gemini-3.1-flash-lite) und neu starten, oder Abrechnung in Ihrem Google-Cloud-Konto aktivieren.

model not found in den Logs

Der Wert von GEMINI_MODEL ist keine gültige ID der Gemini-API. Überprüfen Sie die offizielle Liste unter https://ai.google.dev/gemini-api/docs/models und korrigieren Sie .env.

Der Bot ruft die Tools nicht auf / sagt, er kann nicht erfassen

Führen Sie docker compose logs nanobot aus und suchen Sie nach:

• MCP server 'orcamento': connected – wenn es nicht erscheint, gab es einen Fehler beim Starten des eingebetteten MCP-Servers; sehen Sie Fehler direkt über dieser Zeile;

• Max iterations (...) reached – bedeutet, dass das Modell in eine Schleife von Tool-Aufrufen geraten ist; das konfigurierbare Limit steht in agents.defaults.maxToolIterations der Konfiguration.

Der Bot antwortet nicht in Telegram

• Überprüfen Sie docker compose logs -f nanobot, während Sie eine Nachricht senden – es sollte sofort eine Aktivität im Log erscheinen.

• Stellen Sie sicher, dass Sie das Pairing abgeschlossen haben (Abschnitt 6, Schritt 2).

docker compose version sagt „unknown flag“ oder existiert nicht

Sie haben das alte Docker Compose (v1, mit Bindestrich: docker-compose). Aktualisieren Sie Docker Desktop oder installieren Sie das Plugin docker-compose-plugin separat (Linux).

9. Was jede Projektdatei macht

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.

Details zur aktuellen Architektur

• Sprachmodell: Google Gemini über offizielle API (providers.gemini). Das Modell wird durch die Variable GEMINI_MODEL in .env gewählt (Standard: gemini-3.6-flash). Es läuft kein lokales Modell.

• MCP-Server: läuft als Unterprozess (stdio) im selben Nanobot-Container, unter Verwendung der isolierten venv /opt/mcpvenv. Warum isoliert? Das Python-SDK mcp 2.x, das von den Tools verwendet wird, kollidiert mit der Version (mcp>=1.26,<2), die der Nanobot selbst benötigt.

• Schutz vor Schleifen: agents.defaults.maxToolIterations: 6 begrenzt, wie viele aufeinanderfolgende Tool-Aufrufe der Agent in einem einzelnen Turn ausführen kann.

Warum gibt es zwei Nanobot-Konfigurationsdateien?

config.json (für lokale Ausführung außerhalb von Docker) verweist auf den MCP-Server über stdio relativ zum Projektstamm. config.docker.json (innerhalb von Docker verwendet) nutzt absolute Container-Pfade (/opt/mcp_server/...) und die venv /opt/mcpvenv/bin/python3.

10. Alternative: lokale Installation (ohne Docker)

Wenn Sie Postgres/Nanobot lieber direkt auf Ihrem Rechner statt in Containern ausführen möchten (mühsamer einzurichten, aber einfacher Zeile für Zeile zu debuggen):

10.1. Nur Postgres in Docker starten

docker compose up -d postgres

(Das startet nur Postgres. Das schema.sql wird automatisch angewendet.)

10.2. Python-Abhängigkeiten des MCP-Servers installieren

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

Exportieren Sie die Umgebungsvariablen im selben 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

(Unter Windows PowerShell verwenden Sie $env:DATABASE_URL = "...", usw.)

10.3. Nanobot installieren und ausführen

pip install -U nanobot-ai

Kopieren Sie nanobot_config/config.json nach ~/.nanobot/config.json und nanobot_config/SOUL.md nach ~/.nanobot/workspace/SOUL.md (erstellen Sie den Ordner workspace, falls er nicht existiert).

Führen Sie vom Stammverzeichnis dieses Projekts aus (der Pfad zum MCP-Server in config.json ist relativ zu diesem Verzeichnis):

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

Ohne Telegram testen (nützlich zum Debuggen der Extraktion)

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

11. Nächste Schritte des Projekts

1. Testen Sie den End-to-End-Fluss mit echten Nachrichten und passen Sie die SOUL.md entsprechend den beobachteten Extraktionsfehlern an (informelle Sprache, Abkürzungen, mehrdeutige Werte).

2. Fügen Sie das Tool für vollständige Berichte hinzu (Vergleich zwischen Zeiträumen, Entwicklung der Ausgaben).

3. Implementieren Sie die Empfehlungsebene: Konsolidieren Sie die Daten aus resumo_por_categoria und senden Sie sie über eine API an eine fortschrittliche LLM.

4. Verknüpfen Sie die Ausgaben automatisch mit dem authentifizierten Telegram-Benutzer (heute wird die telegram_id vom Modell beim Aufruf des Tools übergeben).

Hinweis zur Validierung

Die Pipeline wurde in realer Ausführung mit Docker validiert: Container starten, MCP über stdio mit den 3 registrierten Tools verbunden, und Einfügungen in Postgres über psql bestätigt. Die Syntax der docker-compose.yml und der Konfig-JSONs wird vor jedem Start überprüft.

Wenn etwas genau bei docker compose up hängen bleibt, beginnen Sie mit dem Abschnitt 8. Häufige Probleme.