Разговорный бюджет — ядро конвейера

Система учёта расходов на естественном языке через Telegram, использующая Google Gemini (официальный API, модель настраивается через .env, по умолчанию gemini-3.6-flash) в качестве языковой модели, оркестрируемая Nanobot, с сохранением данных в Postgres.

Этот документ предполагает, что вы никогда раньше не запускали Docker, и объясняет каждый шаг, каждую команду и что ожидать в результате каждой из них.

Содержание

1. Что нужно установить

2. Получение токена бота в Telegram

3. Получение ключа API Gemini

4. Настройка файла .env

5. Запуск всего с помощью Docker

6. Тестирование в Telegram

7. Команды для повседневного использования

8. Частые проблемы и их решение

9. Назначение каждого файла проекта

10. Альтернатива: локальная установка (без Docker)

11. Следующие шаги проекта

Related MCP server: Expense Tracker MCP Server

1. Что нужно установить

Только одна вещь на вашей машине. Вам не нужно устанавливать Python, Postgres или Nanobot отдельно — всё это работает внутри контейнеров.

Docker Desktop (Windows/Mac) или Docker Engine (Linux)

• Windows или Mac: скачайте и установите Docker Desktop с https://www.docker.com/products/docker-desktop/ — после установки откройте приложение Docker Desktop и дождитесь, пока оно покажет "Docker is running" (значок станет зелёным/стабильным в системном трее).

• Linux: следуйте https://docs.docker.com/engine/install/ для вашего дистрибутива, а затем https://docs.docker.com/engine/install/linux-postinstall/ чтобы иметь возможность запускать docker без sudo.

Проверка, что всё в порядке

Откройте терминал (PowerShell в Windows, Terminal в Mac/Linux) и выполните:

docker --version
docker compose version

Вы должны увидеть две строки с версиями, без ошибок.

2. Получение токена бота в Telegram

1. Откройте Telegram (на телефоне или компьютере) и найдите @BotFather в поиске. Это официальный бот Telegram для создания других ботов — убедитесь, что у него есть значок проверки.

2. Отправьте ему: /newbot

3. Он спросит имя для вашего бота. Это может быть что угодно, например: Разговорный бюджет.

4. Затем он спросит username. Он должен быть уникальным во всём Telegram и обязан заканчиваться на "bot", например: orcamento_seunome_bot.

5. Если всё получилось, BotFather ответит сообщением, похожим на это:

   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. Скопируйте строку токена целиком (формат числа:буквы_и_числа). Вы вставите её в файл .env на следующем шаге.

Сохраните этот токен.

3. Получение ключа API Gemini

Nanobot использует официальный API Google Gemini в качестве языковой модели.

1. Перейдите на https://aistudio.google.com/api-keys и войдите в свою учётную запись Google.

2. Нажмите Create API key (Google автоматически создаст проект).

3. Скопируйте ключ и вставьте его в .env на следующем шаге.

О расходах: карта не требуется. Бесплатный тариф покрывает модели Flash/Flash-Lite с лимитами запросов в минуту/день (~10 запросов/мин и ~250–1,500 запросов/день в зависимости от модели) — с запасом для этого проекта. Модели Pro платные. Официальная таблица: https://ai.google.dev/gemini-api/docs/pricing

4. Настройка файла .env

В проекте уже есть файл с именем .env в корне папки (orcamento-conversacional/.env). Он автоматически читается Docker Compose — вам не нужно ничего переименовывать.

Внимание: файлы, начинающиеся с точки (.env), по умолчанию "скрыты" в Проводнике Windows, в Finder на Mac и в ls без флагов в Linux/Mac. Используйте ls -la, чтобы увидеть его в терминале, или откройте папку в текстовом редакторе.

Внутри .env замените эти две строки на реальные значения:

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)

Переменная GEMINI_MODEL определяет, какую модель использовать (по умолчанию: gemini-3.6-flash). Меняйте её, только если хотите переключиться на другой допустимый ID из официального списка: https://ai.google.dev/gemini-api/docs/models

Остальные переменные (POSTGRES_PASSWORD, DATABASE_URL) уже содержат рабочие значения — их не нужно менять для запуска в Docker.

Сохраните файл.

5. Запуск всего с помощью Docker

Откройте терминал внутри папки orcamento-conversacional (той, где находится файл docker-compose.yml) и выполните:

docker compose up -d --build

Что делает эта команда, по порядку:

Никакого скачивания или запуска модели на вашей машине не происходит: Gemini работает в облаке Google.

Флаг -d ("detached") запускает всё в фоновом режиме. При последующих запусках docker compose up -d (без --build) всё поднимается за секунды.

Как узнать, что всё прошло успешно

Выполните:

docker compose ps

Вы должны увидеть 2 сервиса:

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

Также проверьте логи Nanobot — должно появиться сообщение о подключении MCP:

docker compose logs nanobot

Ищите строки, подобные:

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

Если orcamento_nanobot отображается как "Restarting" или исчезает из списка, см. раздел Частые проблемы.

6. Тестирование в Telegram

1. В Telegram найдите username бота, которого вы создали у BotFather (например: @orcamento_seunome_bot), и откройте с ним чат.

2. Отправьте /start. При первом общении Nanobot может запросить код сопряжения — он появляется в логах (docker compose logs -f nanobot, строка "Generated pairing code ..."). Отправьте этот код боту.

3. Отправьте что-то вроде:

   Gastei 35 no almoço hoje

4. Через несколько секунд бот должен ответить подтверждением записи, примерно так:

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

Если бот ничего не отвечает, см. раздел о частых проблемах ниже.

7. Команды для повседневного использования

Все выполняются внутри папки orcamento-conversacional.

Просмотр логов всего в реальном времени:

docker compose logs -f

(Ctrl+C для выхода — это только останавливает показ логов, контейнеры продолжают работать.)

Просмотр логов только Nanobot (самое полезное для отладки разговоров):

docker compose logs -f nanobot

Остановка всего (с сохранением данных):

docker compose down

Повторный запуск после остановки:

docker compose up -d

После редактирования SOUL.md, config.docker.json или .env (не нужно пересобирать образ; конфигурация и промпты монтируются прямо в контейнер):

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

После редактирования mcp_server/expense_tools.py или db/connection.py (нужна пересборка, потому что venv MCP создаётся в образе):

docker compose up -d --build nanobot

Полное удаление всего, включая данные базы данных (полезно, если что-то повреждено и вы хотите начать с нуля):

docker compose down -v

Вход в базу данных для просмотра зарегистрированных расходов вручную:

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

Внутри psql попробуйте:

SELECT * FROM despesas ORDER BY criado_em DESC LIMIT 10;

Для выхода из psql: введите \q и Enter.

Необязательный ярлык: если у вас установлен make (стандартно в Mac/Linux), в проекте есть Makefile с наиболее часто используемыми командами: make up, make down, make logs, make restart, make ps.

8. Частые проблемы и их решение

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

В .env не определена переменная GEMINI_API_KEY. Откройте .env, убедитесь, что строка существует (даже с временным значением), и снова выполните docker compose up -d nanobot.

401, unauthorized или invalid api key в логах Nanobot

GEMINI_API_KEY неверна, отозвана или содержит лишний пробел. Создайте новый ключ на https://aistudio.google.com/api-keys и обновите .env.

429 или ошибки rate limit / quota

Вы достигли лимита бесплатного тарифа Gemini (запросов в минуту или в день). Варианты: подождать несколько минут, изменить GEMINI_MODEL в .env на модель Flash-Lite (большие лимиты, например: gemini-3.1-flash-lite) и запустить снова, или включить биллинг в своей учётной записи Google Cloud.

model not found в логах

Значение GEMINI_MODEL не является допустимым ID модели Gemini API. Проверьте официальный список на https://ai.google.dev/gemini-api/docs/models и исправьте .env.

Бот не вызывает tools / говорит, что не может записать

Выполните docker compose logs nanobot и поищите:

• MCP server 'orcamento': connected — если не появляется, произошла ошибка при запуске встроенного сервера MCP; смотрите ошибки чуть выше этой строки;

• Max iterations (...) reached — означает, что модель вошла в цикл tool-calls; настраиваемый лимит находится в agents.defaults.maxToolIterations в конфиге.

Бот вообще не отвечает в Telegram

• Проверьте docker compose logs -f nanobot, пока отправляете сообщение — в логе должна появиться какая-то активность в тот же момент.

• Убедитесь, что вы завершили сопряжение (раздел 6, шаг 2).

docker compose version сообщает "unknown flag" или не существует

У вас старый Docker Compose (v1, с дефисом: docker-compose). Обновите Docker Desktop или установите плагин docker-compose-plugin отдельно (Linux).

9. Назначение каждого файла проекта

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.

Детали текущей архитектуры

• Языковая модель: Google Gemini через официальный API (providers.gemini). Модель выбирается переменной GEMINI_MODEL в .env (по умолчанию: gemini-3.6-flash). Локально модель не запускается.

• Сервер MCP: работает как подпроцесс (stdio) внутри самого контейнера Nanobot, используя изолированный venv /opt/mcpvenv. Почему изолированный? Python SDK mcp 2.x, используемый tools, конфликтует с версией (mcp>=1.26,<2), требуемой самим nanobot.

• Защита от циклов: agents.defaults.maxToolIterations: 6 ограничивает количество последовательных вызовов tools, которые агент может сделать за один ход.

Почему существуют два файла конфигурации Nanobot?

config.json (для локального запуска, вне Docker) указывает на MCP server через stdio относительно корня проекта. config.docker.json (используется внутри Docker) использует абсолютные пути контейнера (/opt/mcp_server/...) и venv /opt/mcpvenv/bin/python3.

10. Альтернатива: локальная установка (без Docker)

Если вы предпочитаете запускать Postgres/Nanobot прямо на своей машине вместо контейнеров (сложнее настраивать, но проще отлаживать построчно):

10.1. Запуск только Postgres в Docker

docker compose up -d postgres

(Это запускает только Postgres. schema.sql применяется автоматически.)

10.2. Установка Python-зависимостей сервера MCP

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

Экспортируйте переменные окружения в том же терминале:

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

(В Windows PowerShell используйте $env:DATABASE_URL = "..." и т.д.)

10.3. Установка и запуск Nanobot

pip install -U nanobot-ai

Скопируйте nanobot_config/config.json в ~/.nanobot/config.json, а nanobot_config/SOUL.md в ~/.nanobot/workspace/SOUL.md (создайте папку workspace, если её нет).

Запустите из корня этого проекта (путь к MCP server в config.json относителен этому каталогу):

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

Тестирование без Telegram (полезно для отладки извлечения)

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

11. Следующие шаги проекта

1. Протестировать сквозной поток с реальными сообщениями и скорректировать SOUL.md в соответствии с наблюдаемыми ошибками извлечения (неформальный язык, сокращения, неоднозначные значения).

2. Добавить инструмент полных отчётов (сравнение между периодами, динамика расходов).

3. Реализовать слой рекомендаций: консолидировать данные из resumo_por_categoria и отправлять в продвинутую LLM через API.

4. Автоматически привязывать расходы к аутентифицированному пользователю Telegram (сейчас telegram_id передаётся моделью при вызове инструмента).

Предупреждение о валидации

Конвейер был проверен в реальном запуске с Docker: контейнеры поднимаются, MCP подключён через stdio с зарегистрированными 3 инструментами, вставки в Postgres подтверждены через psql. Синтаксис docker-compose.yml и JSON-конфигов проверяется перед каждым запуском.

Если что-то зависает именно на docker compose up, начните с раздела 8. Проблемы и их решения.