Привет, Хабр! Меня зовут Андрей Гетманов, я работаю ML-инженером в Исследовательском центре «Сильный ИИ в промышленности» в ИТМО, а кроме того выступаю энтузиастом open source. В этой статье хочу рассказать о нашей новой разработке ― ИИ-инструменте, который помогает репозиторию стать лучшей версией себя.
Разнообразных «улучшателей» много, но все они фокусируются преимущественно на качестве самого кода. Мы же смотрим шире ― на репозиторий в целом, насколько он понятен стороннему наблюдателю. Инструмент нацелен на наших коллег от науки ― например, биологов и химиков ― которые не обладают опытом коммерческой разработки и соответствующего оформления кода. Он поможет в несколько кликов сделать репозиторий более читаемым и воспроизводимым.
Зачем он нужен
В одной из предыдущих статей в блоге на Хабре коллеги рассказывали про проблему воспроизводимости научных open source разработок. Действительно, в научном open source есть проблема с переиспользованием результатов исследований. Даже просто выложенный к статье код встречается очень редко. Как правило, этот код сложно читать, к нему нет документации, иногда даже банального Readme, поскольку разработчик планировал подойти к его созданию в последний момент, но на это времени так и не выделил. Библиотекам и фреймворкам часто не хватает базовых CI/CD настроек: линтеров, автотестов и т.п. Поэтому воспроизвести описанный в статье алгоритм оказывается невозможно. И это проблема ― ведь если кто-то публикует свое исследование, он делает это не просто так, а с желанием поделиться с сообществом.
По-хорошему каждый репозиторий должен быть удобен для запуска и использования. И зачастую выложенным разработкам не хватает каких-то мелочей ― хорошего читаемого Readme или docstring, которые можно было бы собрать в документацию.
Анализируя проблему и опираясь на свой опыт разработки, мы пришли к идее инструмента OSA ― Open Source Advisor. Создавать его решили в рамках конкурса проектов НИРСИИ, на который подали заявку от коллектива NSS Lab института искусственного интеллекта ИТМО. После того, как заявку поддержали (в конце 2024), под руководством Николая Никитина начали работу.
Что такое OSA
OSA ― открытая библиотека на Python, которая использует LLM-агенты, чтобы улучшить репозитории с открытым кодом, сделать их более пригодными для переиспользования.
Инструмент представляет собой python-репозиторий, запускаемый через CLI. Его также можно развернуть локально в Docker, чтобы, указав API-ключ к любой LLM, взаимодействовать с инструментом через консоль. В будущем мы планируем развернуть этот инструмент как веб-приложение на базе Streamlit на серверах ИТМО, чтобы можно было воспользоваться им по ссылке.
Репозиторий полностью открыт ― пользуйтесь на здоровье!
Основные возможности OSA
На входе в OSA можно загрузить репозиторий с черновым программным кодом, в котором много всего не хватает, а также научную статью, описывающую эту библиотеку или алгоритм (если она есть). Статья загружается отдельным файлом и используется для генерации Readme. Дополнительно можно задать параметры работы OSA – провайдера LLM (например, OpenAI) или название модели (gpt-4o).
Как раз во входных данных и проявляются нюансы именно научного репозитория. Например, сейчас мы внедряем функцию, которая позволяет в качестве начальных данных брать документацию по ГОСТу в формате Word. На практике многие научные группы создают такую документацию в качестве необходимой отчётности. Мы же можем преобразовать её в нечто более читаемое и структурированное, что поможет развитию проекта.
Под капотом OSA декомпозирует имеющийся код и документацию и итеративно применяет к полученным фрагментам специализированные промты, отправляя их в одну из LLM через API. На данный момент есть возможность отправить всё в OpenAI (для этого надо использовать свой ключ API), в другой сервис или локальную модуль - для удобной работы с различными LLM использован наш фреймворк ProtoLLM. В ближайшем будущем планируем развернуть инструмент на серверах ИТМО через локальную Gemma 3 27b.
На выходе OSA генерирует рекомендации по улучшению репозитория:
Readme на английском языке на основе анализа кода ― доступных шаблонов и примеров;
docstring к классам и методам, где это необходимо, но они отсутствовали, на английском языке для автоматической сборки документации с помощью одного из доступных фреймворков;
базовые CI/CD-скрипты;
отчёт с рекомендациями по улучшению репозитория.
В отчёте указывается наличие основных составляющих репозитория: Readme, лицензии, документации, примеров использования, тестов и краткого описания.
Также проводится анализ различных его разделов: структуры, Readme, документации. На основании всей информации делается вывод о ключевых точках роста проекта и даются рекомендации.
На данный момент инструмент работает с GitHub. OSA-бот создает форк репозитория и предлагает пулл-реквест со всеми изменениями. Разработчику остаётся посмотреть предложения и исправить то, что кажется неправильным. На мой взгляд, это намного проще, чем писать тот же Readme с нуля.
OSA — это отличный инструмент для быстрой подготовки качественного описания репозитория. Эта библиотека позволяет создать чёткий и хорошо организованный README-файл с ключевыми секциями, каждая с кратким описанием и легко редактируема. Такой подход особенно полезен студентам и новичкам, которые впервые создают собственные проекты на GitHub/GitLab/GitVerse.
Например, часто студенты испытывают трудности с оформлением своего репозитория: выбирают неправильную структуру, сомневаются в содержании отдельных разделов или вовсе оставляют README пустым. OSA помогает решить эту проблему буквально несколькими строчками кода, делая проект доступным и понятным для любого пользователя.
С удовольствием слежу за развитием проекта и жду новых функций!
Михаил Гущин, старший научный сотрудник, заместитель заведующего научно-учебной лаборатории методов анализа больших данных
Примеры из жизни
Наши коллеги уже использовали OSA для улучшения репозиториев с некоторыми инструментами.
Коллеги из Лаборатории «Компьютерные технологии» в ИТМО прогнали через OSA свой репозиторий CoolPrompt. OSA создала вполне читаемый и соответствующий реальности Readme с ключевыми функциями и инструкцией по установке. Несмотря на то, что автоматические рекомендации в целом стандартны, они как минимум обеспечивают большее доверия к репозиторию. Человеку со стороны не придется вспоминать, как ставить пакеты.
В нашем опыте применения OSA для проекта CoolPrompt инструмент показал себя как эффективное решение для быстрой структуризации репозитория и подготовки необходимой документации на английском языке. Особенно ценно, что OSA поддерживает работу с различными LLM-провайдерами и потенциально может быть интегрирован в существующие рабочие процессы через CLI или Docker. Применение OSA довольно сильно сэкономило время на составление шаблона документации. Из недостатков можно выделить, что на текущий момент нам всё равно пришлось дорабатывать написание содержания для каждой главы Readme, поскольку встречались галлюцинации в написании текста и ссылок, однако в целом, стоит отметить, что суммарное время, потраченное на документацию, сократилось кратно.
Сергей Муравьёв, к.т.н., руководитель лаборатории "Компьютерные технологии" ИТМО
Также мы протестировали OSA на проекте DNAZYME коллег из Лаборатории генеративного дизайна молекулярных машин (Центр ИИ в химии, ИТМО).
Еще два примера – уже от коллег из Бразилии. Один из них был посвящен анализу климатических данных для предсказания засухи. OSA добавил Readme и документацию к коду. Авторы подтвердили изменения и влили их в проект.
Второй проект был посвящен повышению эффективности логистики сбора и вывоза мусора. В этом репозитории было намного больше схем, статей и заметок Jupiter notebook. Поэтому изменения OSA были небольшие – добавился файл Readme, плюс названия папок перевели с португальского на английский язык. Кстати, эта функция в нашем инструменте появилась как раз благодаря этому тесту – мы поняли, что названия папок на локальном языке здорово осложняют задачу. Авторы подтвердили изменения и влили их в проект.
Бразильские коллеги дали комментарий об опыте использования OSA:
The OSA-bot is helping us co-organize our Git repositories by streamlining files and folders, making them much more appealing and accessible for other users
We reviewed the results and were impressed, only minimal editing was needed 😁
It was also interesting to see the bot translating an entire repository from Portuguese to English. It boosts the visibility of our repo.
The bot has been incredibly helpful and we’re excited to see even more improvements in the next versions
Dr. Leonardo Goliatt, Professor, Universidade Federal de Juiz de Fora
Что планируем в будущем
Мы бы хотели добавить в OSA RAG-систему на основе нашего репозитория с лучшими практиками оформления в open source. Предполагается, что сравнивая с образцом, OSA будет определять, чего именно не хватает проверяемому репозиторию. Допустим, если у него уже есть отличный Readme, то его можно будет не генерировать.
В идеале хотелось бы также преобразовать принцип работы инструмента. Сейчас все артефакты генерируются единоразово, но было бы логично идти итеративным методом ― через общение с LLM-агентом. Также на выходе хотелось бы генерировать некоторый отчет, который поможет команде разработки понять, что можно улучшить.
Как я уже отметил, сейчас мы работаем только на GitHub, потому что там больше всего проектов и с ним банально проще работать. Но часто научные разработки выкладывают в локальные версии GitLab или аналоги GitHub, поэтому вполне вероятно, что мы постараемся присутствовать и там.
Изначально мы ориентировались на Python ― на нем же и тестировали инструмент, но планируем поддержку и C, и C++. А в будущем будем расширять список ключевых языков.
В целом мы планируем расширить OSA на автогенерацию кода тестов и CI/CD. Это убережет разработчиков от огромного количества головной боли и ошибок. Еще хотелось бы интегрировать OSA с IDE для разработки. А в остальном будем тестировать и экспериментировать.
Если у вас есть научный репозиторий, попробуйте OSA. Мы будем рады, если вы дадите нам обратную связь или расскажете о своей специфике и нюансах. У инструмента есть Telegram-чат с поддержкой, где можно задать интересующие вопросы.
Также на базе Университета ИТМО работает сообщество любителей открытого кода Научный опенсорс ― здесь можно найти советы по разработке и поддержке своего ПО и обсудить насущные вопросы. Сообщество открыто для всех желающих, присоединяйтесь!
