Агент и MCP-сервер для проверки контрагента

Кейс Альфа-Банка на AI Product Hack (AI Talent Hub ИТМО), 1–7 сентября 2026. Команда 1.

Витрина кейса: https://talenttrack.aitalenthub.ru/hackathon/cases/462 Кейсодатель: Денис Анастасьев — @Imvaze · Юлия Отпущенко — @yuliaotp

⚠️ Репозиторий приватный и должен таким остаться. В data/ лежат отчёты о реальных компаниях с ФИО и ИНН учредителей и директоров — это персональные данные, переданные кейсодателем для работы над кейсом. Не выкладывать в публичный доступ, не постить скриншоты с ФИО, не заливать в сторонние сервисы.

Команда

Коммиты в main на 05.09 (git shortlog -sn HEAD): Александр — 86, Иван — 6, Ольга — 4 (данные на 200 компаний перенесены из её ветки с её авторством; агент на LangChain — в ветке olga-dev). Кто что делал по существу — docs/09 §6 и team/*/README.md.

Дедлайны

В презентации и описании обязателен раздел с участниками, ролями, зонами ответственности и фактической степенью участия. Отсюда практическое следствие: коммитьте от своего имени и ведите свою папку — в конце это станет доказательством вклада.

С чего начать (20 минут)

1. CONTEXT.md — постановка задачи, критерии успеха, что вне скоупа. Прочитать целиком.

2. docs/06-ответы-кейсодателя.md — что кейсодатель ответил на часовой сессии. Важнее описания на витрине: три пункта там уточнены, один исправлен.

3. docs/01-разбор-данных.md — что реально лежит в данных и на чём ломается наивный парсер.

4. docs/03-продуктовая-стратегия.md — что строим, для кого, как работаем с данными, что должен уметь чат.

5. Открыть docs/05-карта-рынка.html в браузере — 30 конкурентов и незанятые ниши.

6. Завести свою папку в team/ — см. team/README.md.

Что где лежит

CONTEXT.md      постановка задачи, критерии, дедлайны — главный файл
внутренние рабочие записи команды       контекст для ИИ-ассистентов (Claude Code, Cursor и т.п.)

docs/           наши решения и аналитика
  01-разбор-данных.md          что в снапшоте, аномалии, ловушки парсинга
  02-референс-заказчика.md     разбор analitika_kontragentov.pdf — эталон качества
  03-продуктовая-стратегия.md  позиционирование, MVP, метрики, экономика
  04-вопросы-кейсодателю.md    что спрашивали и что уже отвечено
  05-карта-рынка.html          30 игроков × 7 возможностей, интерактив
  06-ответы-кейсодателя.md     ⭐ сводка двух встреч 2 сентября — главный источник
  07-спецификация-полей-и-рынок.md  расшифровка всех полей, расхождения, карта рынка от банка

data/           данные кейса (⚠️ персональные данные)
  contractors_audit.snapshot.json      100 отчётов, экспорт из MongoDB
  contractors_audit.snapshot_*.csv     ещё 100 других компаний, 2654 колонки (итого 200)
  analysis/                            разбор схемы, аномалий, распределений
  README.md                            описание схемы и ловушек

research/       исследование по 11 направлениям, ~730 КБ
source/         исходники от кейсодателя: презентация, референс, лог чата
  meetings/                    полные транскрипты встреч с кейсодателем
team/           личные папки участников

Запуск

Бэкенд — Python 3.12+, зависимости закреплены в requirements.txt; фронтенд без сборки (app/web — статические файлы, Node не нужен). Переменные окружения с дефолтами — в .env.example: без единой переменной приложение подключается к модели команды, с LLM_OFF=1 работает по фактам отчёта.

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.api.main:app --port 8765            # интерфейс и API: http://127.0.0.1:8765
.venv/bin/python -m pytest -q                              # тесты, модель в них выключена
cd app && LLM_OFF=1 ../.venv/bin/python -m eval.run --suite all   # тест-сет по фактам (150), stress (419), reasoning (101)
cd app && ../.venv/bin/python -m eval.tools_check --limit 20      # выбор инструментов агентом на живой модели
app/mcp/run.sh                                             # MCP по stdio; run.sh --http 8766 — HTTP

Агент чата работает на LangChain (AGENT_ENGINE=langchain, по умолчанию): модель сама выбирает инструменты, роутер по фактам — только аварийный путь, когда модель недоступна. Откат на собственный цикл — AGENT_ENGINE=native, только детерминированные ответы — AGENT_ENGINE=router. Подробно — docs/26-агент-на-langchain.md. Развёртывание на сервер — deploy/deploy.sh <ip> (колёса для офлайн-установки — в deploy/wheels, см. deploy/remote-setup.sh).

Как работаем

Ветки. main — то, что готово. Работа — в ветках product/…, eng/…. Мержим через pull request, чтобы второй человек хотя бы посмотрел.

Своя папка. Всё, что нашли и решили лично, — в свою папку в team/. Это не бюрократия: 4 и 7 сентября придётся показать фактический вклад каждого, и история коммитов плюс личные заметки закроют этот вопрос без споров.

Общие решения — в docs/. Если решение меняет то, что уже написано, правьте файл и опишите изменение в PR, а не заводите второй документ на ту же тему.

Данные не редактируем. data/contractors_audit.snapshot.json — исходник от заказчика, он неизменен. Всё производное — в data/analysis/ или в свою папку.

Что уже решено

Коротко, чтобы не переоткрывать. Подробности — в docs/03-продуктовая-стратегия.md, первоисточник — docs/06-ответы-кейсодателя.md.

• Позиционирование: отчёт отвечает «что мы знаем о компании», клиенту нужен ответ на «что мне делать». Мы закрываем разрыв — и сразу по пулу контрагентов, а не по одному.

• Светофор банка — константа и единственный источник истины. Он комплексный, учитывает в том числе судебные дела и транзакционные данные банка, правила закрыты. Своего скоринга не строим, с меткой не спорим: берём её отправной точкой и добавляем факты, которые её уточняют.

• Пользователь один — предприниматель малого бизнеса, оборот до 20 млн ₽, часто в одном лице. Шесть ролей из презентации кейса не нужны, это подтверждено дважды.

• Ядро — не чат, а надёжность. Критерий №1 заказчика: не выдумывать. Отсюда архитектура: агент читает факт-стор с идентификаторами полей, а не сырой JSON; каждое утверждение несёт evidence_ids; всё считаемое считает код.

• Главный экран — пул, а не карточка. Сквозного анализа по 10–20 контрагентам нет ни у банка, ни у конкурентов: у Контура и СПАРКа потолок сравнения — 5 компаний.

• Отказ — это фича. «Если нет судебных дел, это не значит, что их и нет; возможно, просто не найдены данные» — формулировка кейсодателя. У трети компаний нет финансов, у четверти — данных о директоре.

• Рекомендация — действие, а не запрет. Категоричных «не работайте с этой компанией» не выдаём.

• Измерение вместо обещаний. Эталонного датасета нет — собираем свой: 100 отвечаемых вопросов + 40 ловушек.

Чего в данных нет

Чтобы не потратить день впустую:

• Связей между компаниями нет — выборка случайная, кейсодатель подтвердил, что выгрузить связи не получилось. Граф связей строить не на чем.

• Реального API не будет — доступ только внутри контура банка. Работаем со снапшотом как с базой.

• Ключи к внешним LLM под вопросом. Если не дадут — Groq (бесплатный лимит), gpt-oss-20b или Qwen3 27–32B. Этот вариант предложил сам кейсодатель.