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

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

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

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

---


## Команда

| Кто | Роль | Telegram | Папка |
|---|---|---|---|
| Александр Майгер | AI Product | @alex_maiger | [`team/alexander-product/`](team/alexander-product/) |
| Ольга Тасенко | AI Engineer | @twwhu | [`team/olga-engineer/`](team/olga-engineer/) |
| Иван Черненко | AI Engineer | @Rifker | [`team/ivan-engineer/`](team/ivan-engineer/) |

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

---

## Дедлайны

| Когда | Что сдаём в Talent Track |
|---|---|
| **04.09, 10:00** | промежуточные: презентация · описание проекта в Markdown · продуктовые материалы (~3 компактных) · доп. материалы |
| 04.09 | чекпоинт с кейсодателем |
| **07.09, 10:00** | финальные версии тех же четырёх артефактов |
| 07.09 | **Demo Day** — защита перед экспертами |

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

---

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

1. **[`CONTEXT.md`](CONTEXT.md)** — постановка задачи, критерии успеха, что вне скоупа. Прочитать целиком.
2. **[`docs/06-ответы-кейсодателя.md`](docs/06-ответы-кейсодателя.md)** — что кейсодатель ответил на часовой сессии. Важнее описания на витрине: три пункта там уточнены, один исправлен.
3. **[`docs/01-разбор-данных.md`](docs/01-разбор-данных.md)** — что реально лежит в данных и на чём ломается наивный парсер.
4. **[`docs/03-продуктовая-стратегия.md`](docs/03-продуктовая-стратегия.md)** — что строим, для кого, как работаем с данными, что должен уметь чат.
5. Открыть **[`docs/05-карта-рынка.html`](docs/05-карта-рынка.html)** в браузере — 30 конкурентов и незанятые ниши.
6. Завести свою папку в `team/` — см. [`team/README.md`](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`](requirements.txt); фронтенд без сборки
(`app/web` — статические файлы, Node не нужен). Переменные окружения с дефолтами — в [`.env.example`](.env.example):
без единой переменной приложение подключается к модели команды, с `LLM_OFF=1` работает по фактам отчёта.

```bash
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`](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/03-продуктовая-стратегия.md), первоисточник — [`docs/06-ответы-кейсодателя.md`](docs/06-ответы-кейсодателя.md).

- **Позиционирование:** отчёт отвечает «что мы знаем о компании», клиенту нужен ответ на «что мне делать». Мы закрываем разрыв — и сразу по пулу контрагентов, а не по одному.
- **Светофор банка — константа и единственный источник истины.** Он комплексный, учитывает в том числе судебные дела и транзакционные данные банка, правила закрыты. Своего скоринга не строим, с меткой не спорим: берём её отправной точкой и добавляем факты, которые её уточняют.
- **Пользователь один** — предприниматель малого бизнеса, оборот до 20 млн ₽, часто в одном лице. Шесть ролей из презентации кейса не нужны, это подтверждено дважды.
- **Ядро — не чат, а надёжность.** Критерий №1 заказчика: не выдумывать. Отсюда архитектура: агент читает факт-стор с идентификаторами полей, а не сырой JSON; каждое утверждение несёт `evidence_ids`; всё считаемое считает код.
- **Главный экран — пул, а не карточка.** Сквозного анализа по 10–20 контрагентам нет ни у банка, ни у конкурентов: у Контура и СПАРКа потолок сравнения — 5 компаний.
- **Отказ — это фича.** «Если нет судебных дел, это не значит, что их и нет; возможно, просто не найдены данные» — формулировка кейсодателя. У трети компаний нет финансов, у четверти — данных о директоре.
- **Рекомендация — действие, а не запрет.** Категоричных «не работайте с этой компанией» не выдаём.
- **Измерение вместо обещаний.** Эталонного датасета нет — собираем свой: 100 отвечаемых вопросов + 40 ловушек.

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

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

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