Код из научных статей — это клад, погребенный под завалами хардкода, неявных зависимостей и одноразовых 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. Он оценивает их по строгим критериям.
Процесс оценки:
- Поиск: Агент начинает поиск с папки
docs/, так как там обычно лежат официальные гайды. Затем проходит по всему репозиторию. - Фильтрация мусора: Исключаются тесты, бенчмарки, устаревшие (
legacy,deprecated) и демонстрационные материалы. - Классификация: Каждый найденный туториал помечается как
include-in-toolsилиexclude-from-tools.
[!INFO] Критерии для включения в инструменты Чтобы туториал был признан достойным, его код должен быть:
- Запускаемым и самодостаточным: Не просто набор сниппетов.
- Переиспользуемым: Выполнять полезную задачу, а не просто вызывать одну функцию из библиотеки.
- Обобщаемым: Не быть жестко привязанным к одному датасету из примера.
- Иметь четкие входы/выходы: Понятно, какие данные подаются и какой результат ожидается.
Результат работы этого агента — два JSON-файла: полный отчет о сканировании и отфильтрованный список туториалов, которые отправятся на следующий этап конвейера.
Шаг 2: "Золотой" прогон (tutorial-executor)
Миссия: Взять одобренные туториалы и безупречно выполнить их от начала до конца в подготовленной стерильной среде.
Этот агент — исполнитель. Его задача — создать "золотой стандарт" выполнения, эталон, с которым будут сверяться все последующие шаги.
Что он делает:
- Подготовка ноутбука: Копирует оригинальный туториал, приводит его к формату
.ipynb(если это был.pyили.mdфайл с помощьюjupytext), очищает от старых выводов и добавляет в начало конфигурацию дляmatplotlib, чтобы все графики сохранялись в высоком разрешении (dpi=300). - Выполнение: Запускает ноутбук с помощью
papermill. Это позволяет не только выполнить все ячейки, но и зафиксировать все выводы, графики и результаты. - Обработка ошибок: Если что-то идет не так (отсутствующий пакет, несовместимость версий, битая ссылка на данные), агент пытается это исправить. Например, доустановить зависимость или адаптировать код под новую версию библиотеки. У него есть до 5 попыток на каждый туториал.
- Сохранение артефактов: Финальный, успешно выполненный ноутбук сохраняется как
_execution_final.ipynb. Все сгенерированные им изображения извлекаются и складываются в отдельную папкуimages/.
На выходе мы получаем выполненный ноутбук.
Шаг 3: Магия экстракции (tutorial-tool-extractor-implementor)
Это сердце всей системы. Здесь происходит превращение кода из ноутбука в переиспользуемые функции.
Миссия: Трансформировать код из "золотого" ноутбука в production-ready инструменты, которые можно применять к новым данным, сохраняя при этом всю аналитическую логику оригинала.
Этот агент — инженер-рефакторщик. Он следует набору очень строгих правил.
Определение границ инструмента: Каждый раздел туториала (например, "Quality Control" или "Clustering") становится одним инструментом (одной функцией). Все ячейки кода внутри этого раздела объединяются. Визуализации не выделяются в отдельные инструменты, а становятся частью того инструмента, который генерирует данные для них.
Именование: Инструменты именуются по строгому шаблону:
библиотека_действие_объект. Например,scanpy_cluster_cells.Параметризация (самое важное!): Агент анализирует код и выносит все, что зависит от конкретного примера, в параметры функции.
- Пути к файлам становятся параметрами.
- Хардкодные значения (пороги, имена колонок, ключи кластеризации) становятся параметрами с дефолтными значениями, взятыми из туториала.
[!DANGER] Золотое правило параметризации Агент НИКОГДА не добавляет параметры, которых не было в явном виде в коде туториала. Если в оригинале был вызов
sc.tl.pca(adata), то и в инструменте будетsc.tl.pca(adata). Агент не имеет права "улучшить" код, добавив параметрn_comps. Но если в оригинале былоsc.tl.pca(adata, n_comps=40), тоn_compsстанет параметром функции. Это защищает от "галлюцинаций" и сохраняет 100% соответствие оригинальной логике.
- Входные и выходные данные:
- Все инструменты принимают на вход пути к файлам, а не объекты в памяти (вроде
pandas.DataFrame). Это делает их универсальными. - Каждый инструмент возвращает стандартизированный
dict, содержащий сообщение о статусе, ссылку на оригинальный туториал и список путей к артефактам (сохраненным файлам с результатами и графикам).
- Все инструменты принимают на вход пути к файлам, а не объекты в памяти (вроде
На выходе этого этапа мы получаем Python-файл src/tools/имя_туториала.py, наполненный чистыми, документированными и готовыми к использованию функциями.
Шаг 4: Тестирование (test-verifier-improver)
Следующий агент — тестировщик.
Миссия: Создать исчерпывающие тесты для каждого извлеченного инструмента, запустить их и итеративно исправлять код, пока тесты не пройдут на 100%.
Как он работает:
- Генерация тестов: Для каждого инструмента (
@toolдекоратор) создается отдельный тестовый файлpytest. В качестве входных данных и ожидаемых результатов используются значения из "золотого" ноутбука. - Последовательное выполнение: Тесты для инструментов из одного туториала запускаются строго по порядку. Это важно, так как следующий инструмент может зависеть от артефактов, созданных предыдущим.
- Итеративное исправление: Если тест падает, агент не сдается. Он анализирует ошибку, пытается исправить ее (либо в коде теста, либо в коде самого инструмента) и запускает тест заново.
- Правило 6 попыток: У агента есть 6 попыток, чтобы заставить тест пройти. Если после 6 попыток тест все еще падает, агент признает поражение, удаляет у функции декоратор
@tool(выводя ее из состава MCP-сервера) и оставляет комментарий:# Did not pass the test after 6 attempts. Это гарантирует, что в финальный продукт попадут только надежные, проверенные инструменты. - Верификация графиков: Если инструмент генерирует изображения, тест сравнивает их с эталонными картинками из папки
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 — это больше, чем просто инструмент для автоматизации. Это сдвиг парадигмы в том, как мы взаимодействуем с научным кодом.
- Воспроизводимость как стандарт: Система не просто пытается воспроизвести результаты, она строит вокруг этого весь процесс, делая невоспроизводимый код бесполезным для финального продукта.
- Демократизация науки: Сложные аналитические пайплайны, ранее доступные только узким специалистам, готовым потратить недели на разбор кода, теперь становятся инструментами, доступными через естественный язык.
- Живые статьи: Научная публикация перестает быть конечной точкой. Репозиторий, связанный со статьей, становится "живым" артефактом, который можно не просто читать, а с которым можно взаимодействовать, задавать ему вопросы и применять к своим задачам.
Это амбициозная попытка навести мосты между миром академических исследований и миром надежной программной инженерии, используя для этого мощь современных AI-агентов.