Risk Hackathon: LLM‑агент для генерации признаков (GigaChat + LangGraph)

Этот репозиторий — решение для хакатона, где нужно реализовать автономного агента для feature engineering под задачу бинарной классификации.

Агент читает произвольный набор CSV‑таблиц из data/, извлекает/объединяет полезный контекст, генерирует до 5 новых признаков, оценивает их с помощью CatBoost, выбирает лучший набор и сохраняет результат в output/train.csv и output/test.csv.

Что делает агент

• Читает данные: все *.csv из data/ + data/readme.txt.
• Понимает схему: строит контекст по таблицам (info/head) и текстовому описанию.
• Подготавливает данные: приводит реляционный набор к плоскому train/test (тонкие join/agg по найденным ключам).
• Генерирует признаки: LLM (GigaChat‑2‑Max) предлагает идеи и пишет исполняемый Python‑код, который добавляет new_feature_1..new_feature_k в dfs['train'] и dfs['test'].
• Проверяет качество: обучает CatBoostClassifier на hold‑out (80/20) и собирает важности фич.
• Финализирует: сохраняет в output/ исходные колонки из data/train.csv/data/test.csv + выбранные признаки (максимум 5).

Входные данные

Папка data/ должна содержать:

• train.csv — обучающая выборка (ID + таргет).
• test.csv — тестовая выборка (ID, без таргета).
• readme.txt — описание таблиц и полей (важно для LLM).
• Дополнительные таблицы *.csv (справочники/история/события и т.п.) — опционально.

Чтение CSV делается через авто‑определение разделителя и utf-8-sig, с нормализацией имён колонок (убирается BOM и пробелы) — см. src/utils/data_manager.py.

Выходные данные (то, что проверяет платформа)

После запуска обязательно должны появиться:

• output/train.csv
• output/test.csv

Требования (валидируются локально в src/utils/check_submission.py):

• В output/train.csv должны быть все исходные колонки из data/train.csv.
• В output/test.csv должны быть все исходные колонки из data/test.csv.
• Дополнительно должны быть признаки (колонки), одинаковые по именам и порядку в обоих файлах.
• Количество признаков: от 1 до 5.
• Признаки не должны быть полностью NaN.

Запуск

1) Переменные окружения (.env)

В корне проекта должен быть файл .env:

GIGACHAT_CREDENTIALS='<токен от организаторов>'
GIGACHAT_SCOPE='GIGACHAT_API_CORP'

Агент использует их через python-dotenv (см. src/utils/gigachat_manager.py).

2) Установка окружения (uv)

По требованиям хакатона окружение должно ставиться командами:

uv venv
uv sync

Важно: локальная проверка python src/utils/check_submission.py требует, чтобы в корне проекта существовал pyproject.toml с зависимостями (CatBoost, pandas/numpy, langchain‑gigachat, python‑dotenv и др.).

В текущем состоянии репозитория pyproject.toml отсутствует — добавьте его перед сабмитом, иначе проверка упадёт на шаге assert PYPROJECT_PATH.exists().

3) Запуск пайплайна

python run.py

run.py запускает основной граф LangGraph из src/solves/sasha_colve_072/graph.py.

4) Локальная проверка формата сабмита

Перед сабмитом рекомендуется прогнать:

python src/utils/check_submission.py

Проверка:

• наличие data/, run.py, .env
• ограничения по времени (таймаут 580 сек)
• корректность структуры output/train.csv и output/test.csv
• число признаков (≤ 5)

Архитектура (как устроен код)

Основной граф (start → generate_features → build_result)

Запуск идёт через src/solves/sasha_colve_072/graph.py:

• start (src/solves/sasha_colve_072/start_graph.py)

  • читает все CSV в dfs
  • делает плоскую подготовку данных flatten_raw_datasets(...)
  • строит LLM‑контекст по данным и readme.txt
  • просит LLM проанализировать схему (node analyze_context)

• generate_features (src/solves/sasha_colve_072/generate_features_graph.py)

  • LLM генерирует идеи признаков (JSON)
  • затем запускается code_subagent (подграф), который:
    • просит LLM сгенерировать исполняемый код
    • выполняет его в песочнице через src/utils/code_exec_manager.py
    • проверяет контракт: имена строго new_feature_1..new_feature_k, (1 \le k \le 5)
    • при ошибках делает ретраи, умеет “cold restart” и имеет детерминированный fallback
  • оценивает качество признаков CatBoost’ом (src/utils/evaluate_manager.py)
  • выбирает топ‑признаки по feature_importance и сохраняет чекпоинт лучшей итерации
  • учитывает мягкий дедлайн пайплайна (500 сек) — src/utils/time_budget.py

• build_result (src/solves/sasha_colve_072/build_result_graph.py)

  • берёт лучший чекпоинт (если есть) или текущее dfs['train']/'test'
  • “приклеивает” выбранные признаки к исходным data/train.csv и data/test.csv
  • пишет финальные файлы в output/

Плоская предобработка (flattening)

Файл src/solves/sasha_colve_072/flat_preprocessing.py превращает набор таблиц в плоские train/test:

• ищет безопасные ключи join (в т.ч. _id‑подобные)
• добавляет компактные признаки из вспомогательных таблиц:
  • либо прямые lookup‑колонки (если ключ уникален)
  • либо агрегаты row_count, mean по числовым, nunique по категориальным (если ключ не уникален)
• старается держать пайплайн быстрым (лимиты на число колонок/агрегатов/строк в lookup)
• после этого в dfs остаются только "train" и "test"

Логи

• Полные prompt/response и ошибки LLM пишутся в logs/llm_io.log (см. src/utils/gigachat_manager.py).

Ограничения и важные правила

• Лимит по времени: общий таймаут локальной проверки — 580 сек; в графе используется мягкий дедлайн 500 сек, чтобы успеть записать output/.
• Максимум 5 признаков: финальный результат обязан содержать от 1 до 5 новых колонок.
• Запрещено писать из LLM‑кода: CodeExecutor блокирует .to_csv(...). Сгенерированный код должен только модифицировать dfs['train']/dfs['test'] в памяти.
• Без утечек: признаки должны считаться одинаково для train и test; таргет используется только для оценки на train, но не для вычисления фичей на test.

Структура репозитория

• run.py — entrypoint для платформы.
• src/utils/ — менеджеры данных/LLM/оценки/выполнения кода, проверки сабмита.
• src/solves/sasha_colve_072/ — основная реализация пайплайна (LangGraph), промпты и чекпоинты.
• src/solves/* — альтернативные эксперименты/базлайны (не используются run.py по умолчанию).