Финансовый аналитик: Google ADK + dbhub + PostgreSQL

Демонстрационный проект запускает финансового аналитика в Google ADK Web. Агент использует только MCP-инструменты dbhub и не подключается к PostgreSQL напрямую.

Браузер → ADK Web → dbhub (MCP) → PostgreSQL (fin_data)
                 ↘ PostgreSQL (adk_data)

В financial_analyst/prompt.md находится согласованный ReAct-промпт. Он требует сначала сверять каталог и семантические шаблоны, а фактические выводы подтверждать результатами execute_sql.

Настройка

1. Скопируйте .env.example в .env.

2. Задайте действительный LLM_API_KEY. По умолчанию настроена локальная Qwen3.6 через LiteLLM, как в проекте-образце:

   LLM_API_URL=https://api.llm.nstcloud.ru/v1
   LLM_API_MODEL=litellm_proxy/Qwen/Qwen36-27B-FP8

3. При необходимости измените пароли, порты и строки подключения в .env. Для пароля со специальными символами URL-кодируйте его в ADK_SESSION_SERVICE_URI и DBHUB_POSTGRES_DSN.

Запуск

Copy-Item .env.example .env
docker compose up --build -d
docker compose ps

После готовности PostgreSQL заполните финансовую базу:

.\prepare_db\run_prepare_fin_data.bat

Утилита подключается к localhost:$POSTGRES_PORT, базе $POSTGRES_DB и использует параметры из prepare_db/prepare_fin_data.yaml.

Откройте http://localhost:$ADK_WEB_PORT. В ADK Web выберите пакет financial_analyst и задайте финансовый вопрос. dbhub доступен для технической диагностики по http://localhost:$DBHUB_PORT.

Проверка

powershell -ExecutionPolicy Bypass -File .\tests\run-unit-tests.ps1
docker compose config

Локальная среда находится в venv. Она создаётся один раз командой:

py -m venv venv
& .\venv\Scripts\python.exe -m pip install -r requirements.txt -r requirements-test.txt

Проверочный сценарий после загрузки: попросите агента сравнить факт и план за период либо показать крупнейшие отклонения. Агент сначала запросит семантические шаблоны и каталог, затем выполнит SQL через dbhub.

Полная пересборка баз данных

Команда ниже удаляет оба тома PostgreSQL и все данные в них. Финансовые данные после этого заново загружаются из файлов, указанных в prepare_db/prepare_fin_data.yaml. Сессии Google ADK начинаются с пустого состояния.

docker compose down -v
docker compose up -d postgres adk-postgres
.\prepare_db\run_prepare_fin_data.bat
docker compose up -d --build dbhub adk-web
docker compose ps

Резервное копирование и перенос базы данных

Для передачи проекта другому разработчику передайте URL Git-репозитория, идентификатор коммита и дамп базы данных. Получить URL и идентификатор текущего коммита можно командами:

git remote get-url origin
git rev-parse HEAD

Создайте переносимый дамп PostgreSQL в формате pg_dump:

.\prepare_db\make_dump.bat

Скрипт требует запущенный сервис postgres. Если он остановлен, выполните docker compose up -d postgres и дождитесь готовности базы данных. Скрипт переносимо выгружает всю базу POSTGRES_DB без фильтрации таблиц или схем, поэтому будущие изменения структуры автоматически попадут в дамп.

Передавайте transfer/fin_data.dump безопасным способом: файл содержит финансовые данные. Технические таблицы Google ADK в дамп не входят, потому что находятся в отдельном сервисе adk-postgres.

На машине получателя нужно клонировать репозиторий, переключиться на переданный коммит, создать .env, запустить PostgreSQL и восстановить дамп:

git clone <URL-репозитория> dbhub_example
Set-Location .\dbhub_example
git checkout <идентификатор-коммита>

# Скопируйте полученный .env или создайте его из .env.example.
docker compose up -d postgres

$postgres = docker compose ps -q postgres
docker cp .\transfer\fin_data.dump "${postgres}:/tmp/fin_data.dump"
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner --no-privileges /tmp/fin_data.dump'

docker compose up -d --build

Сервисы

• postgres — хранилище финансовой базы fin_data.
• adk-postgres — хранилище технической базы Google ADK adk_data.
• dbhub — HTTP MCP-сервер с инструментами чтения SQL и каталогом данных.
• adk-web — веб-интерфейс Google ADK.

Остановить сервисы без удаления данных:

docker compose down