Статьи

Paper2Agent: превращаем репозиторий научной работы в AI-агента

2025-09-21 16:08 ML / DL LLM

Код из научных статей — это клад, погребенный под завалами хардкода, неявных зависимостей и одноразовых Jupyter-ноутбуков. Каждый, кто пытался воспроизвести результаты исследования, знает эту боль. Вы скачиваете репозиторий в надежде применить мощный алгоритм к своим данным, а получаете скрипты, которые работают только на данных автора, в его окружении, и только в тот вторник, когда сошлись звезды.

Что, если бы мы могли автоматически, систематически и надежно превращать такой код в промышленные, переиспользуемые инструменты, которыми мог бы управлять AI-агент?

Именно эту задачу решает Paper2Agent — система, построенная на ансамбле специализированных AI-агентов, которая берет на себя всю грязную работу: от развертывания окружения до экстракции, рефакторинга, тестирования и финальной упаковки кода в единый, удобный интерфейс. Давайте разберем его архитектуру и философию по косточкам.

Что такое Paper2Agent?

Представьте, что вы хотите использовать метод анализа пространственной транскриптомики из новой статьи. Вместо того чтобы часами разбираться в чужом коде, вы просто даете системе ссылку на GitHub репозиторий.

На выходе вы получаете не просто набор скриптов, а полноценный MCP-сервер (Model Context Protocol). Это, по сути, API, который предоставляет все ключевые функции из статьи в виде стандартизированных «инструментов». Этот сервер может "подключить" к себе любой современный AI-ассистент, например, Claude Code или Google Gemini CLI.

В результате вы можете давать команды на естественном языке:

«Проанализируй мои данные экспрессии генов с помощью метода из TISSUE, рассчитай 95% доверительный интервал для гена Acta2».

И AI-агент, используя сгенерированные Paper2Agent инструменты, выполнит эту задачу. Научная статья перестает быть статичным PDF-файлом и превращается в интерактивного помощника.

Звучит как магия? Под капотом — выстроенный конвейер и слаженная работа команды узкоспециализированных AI-агентов.

Архитектура системы: как это работает под капотом

Весь процесс оркестрируется серией координаторов, которые запускают и контролируют специализированных агентов. Каждый агент — это, по сути, сверхдетальный промпт, описывающий его миссию, принципы, рабочий процесс и критерии успеха.

Давайте пройдемся по всему конвейеру шаг за шагом.

Шаг 1 (Параллельный): Подготовка плацдарма

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

Агент 1: environment-python-manager (Менеджер окружения)

Миссия: Создать идеально чистое, изолированное и воспроизводимое Python-окружение для проекта с помощью uv.

Этот агент не просто выполняет pip install -r requirements.txt. Его работа — это детективное расследование с целью создать стерильную среду.

Ключевые принципы его работы:

  • Приоритет PyPI: Агент всегда будет пытаться установить пакеты из PyPI, даже если в README написано ставить их из исходников. Это гарантирует максимальную воспроизводимость.
  • Анализ версий: Он ищет требования к версии Python (.python-version, pyproject.toml) и выбирает наиболее подходящую, но не ниже 3.10.
  • Комплексная установка: Устанавливаются не только основные зависимости, но и все для тестов и работы с ноутбуками (pytest, papermill, ipykernel).
  • Создание инфраструктуры для тестов: Агент автоматически генерирует файлы pytest.ini и conftest.py со стандартной конфигурацией. Это фундамент для последующего беспощадного тестирования.

В итоге мы получаем предсказуемую и надежную среду имя_репозитория-env/, готовую к дальнейшей работе.

Агент 2: tutorial-scanner (Сканер туториалов)

Миссия: Просканировать весь репозиторий и найти туториалы, код из которых достоин превращения в инструменты.

Этот агент — аудитор. Он не просто ищет файлы .ipynb или .md. Он оценивает их по строгим критериям.

Процесс оценки:

  1. Поиск: Агент начинает поиск с папки docs/, так как там обычно лежат официальные гайды. Затем проходит по всему репозиторию.
  2. Фильтрация мусора: Исключаются тесты, бенчмарки, устаревшие (legacy, deprecated) и демонстрационные материалы.
  3. Классификация: Каждый найденный туториал помечается как include-in-tools или exclude-from-tools.

[!INFO] Критерии для включения в инструменты Чтобы туториал был признан достойным, его код должен быть:

  • Запускаемым и самодостаточным: Не просто набор сниппетов.
  • Переиспользуемым: Выполнять полезную задачу, а не просто вызывать одну функцию из библиотеки.
  • Обобщаемым: Не быть жестко привязанным к одному датасету из примера.
  • Иметь четкие входы/выходы: Понятно, какие данные подаются и какой результат ожидается.

Результат работы этого агента — два JSON-файла: полный отчет о сканировании и отфильтрованный список туториалов, которые отправятся на следующий этап конвейера.

Шаг 2: "Золотой" прогон (tutorial-executor)

Миссия: Взять одобренные туториалы и безупречно выполнить их от начала до конца в подготовленной стерильной среде.

Этот агент — исполнитель. Его задача — создать "золотой стандарт" выполнения, эталон, с которым будут сверяться все последующие шаги.

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

  1. Подготовка ноутбука: Копирует оригинальный туториал, приводит его к формату .ipynb (если это был .py или .md файл с помощью jupytext), очищает от старых выводов и добавляет в начало конфигурацию для matplotlib, чтобы все графики сохранялись в высоком разрешении (dpi=300).
  2. Выполнение: Запускает ноутбук с помощью papermill. Это позволяет не только выполнить все ячейки, но и зафиксировать все выводы, графики и результаты.
  3. Обработка ошибок: Если что-то идет не так (отсутствующий пакет, несовместимость версий, битая ссылка на данные), агент пытается это исправить. Например, доустановить зависимость или адаптировать код под новую версию библиотеки. У него есть до 5 попыток на каждый туториал.
  4. Сохранение артефактов: Финальный, успешно выполненный ноутбук сохраняется как _execution_final.ipynb. Все сгенерированные им изображения извлекаются и складываются в отдельную папку images/.

На выходе мы получаем выполненный ноутбук.

Шаг 3: Магия экстракции (tutorial-tool-extractor-implementor)

Это сердце всей системы. Здесь происходит превращение кода из ноутбука в переиспользуемые функции.

Миссия: Трансформировать код из "золотого" ноутбука в production-ready инструменты, которые можно применять к новым данным, сохраняя при этом всю аналитическую логику оригинала.

Этот агент — инженер-рефакторщик. Он следует набору очень строгих правил.

  1. Определение границ инструмента: Каждый раздел туториала (например, "Quality Control" или "Clustering") становится одним инструментом (одной функцией). Все ячейки кода внутри этого раздела объединяются. Визуализации не выделяются в отдельные инструменты, а становятся частью того инструмента, который генерирует данные для них.

  2. Именование: Инструменты именуются по строгому шаблону: библиотека_действие_объект. Например, scanpy_cluster_cells.

  3. Параметризация (самое важное!): Агент анализирует код и выносит все, что зависит от конкретного примера, в параметры функции.

    • Пути к файлам становятся параметрами.
    • Хардкодные значения (пороги, имена колонок, ключи кластеризации) становятся параметрами с дефолтными значениями, взятыми из туториала.

[!DANGER] Золотое правило параметризации Агент НИКОГДА не добавляет параметры, которых не было в явном виде в коде туториала. Если в оригинале был вызов sc.tl.pca(adata), то и в инструменте будет sc.tl.pca(adata). Агент не имеет права "улучшить" код, добавив параметр n_comps. Но если в оригинале было sc.tl.pca(adata, n_comps=40), то n_comps станет параметром функции. Это защищает от "галлюцинаций" и сохраняет 100% соответствие оригинальной логике.

  1. Входные и выходные данные:
    • Все инструменты принимают на вход пути к файлам, а не объекты в памяти (вроде pandas.DataFrame). Это делает их универсальными.
    • Каждый инструмент возвращает стандартизированный dict, содержащий сообщение о статусе, ссылку на оригинальный туториал и список путей к артефактам (сохраненным файлам с результатами и графикам).

На выходе этого этапа мы получаем Python-файл src/tools/имя_туториала.py, наполненный чистыми, документированными и готовыми к использованию функциями.

Шаг 4: Тестирование (test-verifier-improver)

Следующий агент — тестировщик.

Миссия: Создать исчерпывающие тесты для каждого извлеченного инструмента, запустить их и итеративно исправлять код, пока тесты не пройдут на 100%.

Как он работает:

  1. Генерация тестов: Для каждого инструмента (@tool декоратор) создается отдельный тестовый файл pytest. В качестве входных данных и ожидаемых результатов используются значения из "золотого" ноутбука.
  2. Последовательное выполнение: Тесты для инструментов из одного туториала запускаются строго по порядку. Это важно, так как следующий инструмент может зависеть от артефактов, созданных предыдущим.
  3. Итеративное исправление: Если тест падает, агент не сдается. Он анализирует ошибку, пытается исправить ее (либо в коде теста, либо в коде самого инструмента) и запускает тест заново.
  4. Правило 6 попыток: У агента есть 6 попыток, чтобы заставить тест пройти. Если после 6 попыток тест все еще падает, агент признает поражение, удаляет у функции декоратор @tool (выводя ее из состава MCP-сервера) и оставляет комментарий: # Did not pass the test after 6 attempts. Это гарантирует, что в финальный продукт попадут только надежные, проверенные инструменты.
  5. Верификация графиков: Если инструмент генерирует изображения, тест сравнивает их с эталонными картинками из папки images/, используя библиотеку imagehash. Сравнивается не попиксельно, а хэш изображений, что устойчиво к мелким изменениям.

Этот этап отсеивает все, что было извлечено некорректно или работает нестабильно. Только прошедшие через это чистилище инструменты попадают в финальную сборку.

Шаг 5: Сборка и интеграция

Миссия: Собрать все проверенные инструменты из разных модулей в единый, унифицированный MCP-сервер.

Это финальный и самый простой шаг. Агент-сборщик генерирует один файл: src/имя_репозитория_mcp.py.

"""
Model Context Protocol (MCP) for AlphaPOP

...описание...

This MCP Server contains the tools extracted from the following tutorials:
1. score_batch
    - score_batch_variants: Score genetic variants...
"""

from fastmcp import FastMCP

# Импортируем все MCP-инстансы из сгенерированных модулей
from tools.score_batch import score_batch_mcp
# ...другие импорты

# Создаем главный сервер
mcp = FastMCP(name="AlphaPOP")

# "Монтируем" инструменты из каждого модуля
mcp.mount(score_batch_mcp)
# ...монтируем остальные

if __name__ == "__main__":
  mcp.run()

Этот файл является точкой входа для AI-агента. Запустив его, мы поднимаем локальный сервер, к которому может подключиться тот же Claude Code.

Результат: Что мы получаем на выходе?

После завершения работы всего конвейера в директории проекта мы видим четкую и понятную структуру:

<project_dir>/
├── src/
│   ├── <repo_name>_mcp.py          # ✅ Финальный MCP-сервер
│   └── tools/
│       └── <tutorial_name>.py      # ✅ Извлеченные и оттестированные инструменты
├── <repo_name>-env/                # Изолированное Python-окружение
├── repo/                           # Оригинальный код репозитория
├── reports/                        # Отчеты сканера, исполнителя и т.д.
├── tests/
│   ├── code/                       # Сгенерированные pytest-тесты
│   ├── data/                       # Данные для тестов
│   └── logs/                       # Логи выполнения тестов
└── notebooks/
    └── <tutorial_name>/
        ├── _execution_final.ipynb  # "Золотой" ноутбук
        └── images/                 # Эталонные изображения

Главные артефакты — это папка src/ с готовым к запуску MCP-сервером и tests/ с доказательством его надежности.

Философия Paper2Agent: От статики к динамике

Paper2Agent — это больше, чем просто инструмент для автоматизации. Это сдвиг парадигмы в том, как мы взаимодействуем с научным кодом.

  1. Воспроизводимость как стандарт: Система не просто пытается воспроизвести результаты, она строит вокруг этого весь процесс, делая невоспроизводимый код бесполезным для финального продукта.
  2. Демократизация науки: Сложные аналитические пайплайны, ранее доступные только узким специалистам, готовым потратить недели на разбор кода, теперь становятся инструментами, доступными через естественный язык.
  3. Живые статьи: Научная публикация перестает быть конечной точкой. Репозиторий, связанный со статьей, становится "живым" артефактом, который можно не просто читать, а с которым можно взаимодействовать, задавать ему вопросы и применять к своим задачам.

Это амбициозная попытка навести мосты между миром академических исследований и миром надежной программной инженерии, используя для этого мощь современных AI-агентов.