es Nikolay Nikitin, PhD. Soy el líder de investigación en el Instituto de IA de la Universidad ITMO y un entusiasta del código abierto. A menudo veo que muchos de mis colegas no encuentran el tiempo y la energía para crear repositorios abiertos para sus trabajos de investigación y garantizar que sean de la calidad adecuada. En este artículo, analizaré cómo podemos ayudar a resolver este problema utilizando OSA, una herramienta de inteligencia artificial desarrollada por nuestro equipo que ayuda al repositorio a convertirse en una mejor versión de sí mismo. Si mantiene o contribuye al código abierto, esta publicación le ahorrará tiempo y esfuerzo: aprenderá cómo OSA puede mejorar automáticamente su repositorio agregando un archivo README adecuado, generando documentación, configurando scripts CI/CD e incluso resumiendo las fortalezas y debilidades clave del proyecto.
Existen muchas herramientas diferentes para mejorar la documentación. Sin embargo, se centran en diferentes componentes individuales de la documentación del repositorio. Por ejemplo, la herramienta Readme-AI genera el archivo README, pero no tiene en cuenta el contexto adicional, lo cual es importante, por ejemplo, para repositorios de artículos científicos. Otra herramienta, RepoAgent, genera documentación completa para el código del repositorio, pero no archivos README ni scripts CI/CD. Por el contrario, OSA considera el repositorio de manera integral, con el objetivo de hacerlo más fácil de entender y listo para ejecutar. La herramienta se creó originalmente para nuestros colegas de investigación, incluidos biólogos y químicos, que a menudo carecen de experiencia en ingeniería de software y prácticas de desarrollo modernas. El objetivo principal era ayudarlos a hacer que el repositorio fuera más legible y reproducible con unos pocos clics. Pero OSA se puede utilizar en cualquier repositorio, no sólo en los científicos.
¿Por qué es necesario?
El código abierto científico enfrenta desafíos con la reutilización de los resultados de la investigación. Incluso cuando el código se comparte con artículos científicos, rara vez está disponible o está completo. Este código suele ser difícil de leer; no hay documentación al respecto y, a veces, incluso falta un archivo README básico, ya que el desarrollador intentó escribirlo en el último momento pero no tuvo tiempo. Las bibliotecas y los marcos a menudo carecen de configuraciones básicas de CI/CD, como linters, pruebas automatizadas y otros controles de calidad. Por tanto, es imposible reproducir el algoritmo descrito en el artículo. Y esto es un gran problema, porque si alguien publica su investigación, lo hace con ganas de compartirla con la comunidad.
Pero este problema no se limita sólo a la ciencia. Los desarrolladores profesionales también suelen posponer la escritura del archivo Léame y la documentación durante largos períodos. Y si un proyecto tiene docenas de repositorios, mantenerlos y usarlos puede resultar complicado.
Lo ideal es que cada repositorio sea fácil de ejecutar y fácil de usar. Y, a menudo, los desarrollos publicados carecen de elementos esenciales, como un archivo README claro o cadenas de documentación adecuadas, que pueden compilarse en documentación completa utilizando herramientas estándar como mkdocs.
Basándonos en nuestra experiencia y análisis del problema, intentamos sugerir una solución e implementarla como la herramienta Open Source Advisor – OSA.
¿Qué es la herramienta OSA?
OSA es una biblioteca Python de código abierto que aprovecha los agentes LLM para mejorar los repositorios de código abierto y hacerlos más fáciles de reutilizar.
La herramienta es un paquete que se ejecuta a través de una interfaz de línea de comandos (CLI). También se puede implementar localmente usando Docker. Al especificar una clave API para su LLM preferido, puede interactuar con la herramienta a través de la consola. También puedes probar OSA a través de la GUI web pública. Hay una breve introducción a las ideas principales de mejora del repositorio con OSA:
[insertar]https://www.youtube.com/watch?v=LDSb7JJgKoY[/embed]
¿Cómo funciona OSA?
El Open Source Advisor (OSA) es una herramienta multiagente que ayuda a mejorar la estructura y usabilidad de los repositorios científicos de forma automatizada. Aborda problemas comunes en proyectos de investigación al manejar tareas como generar documentación (archivos README, cadenas de documentos de código), crear archivos esenciales (licencias y requisitos) y sugerir mejoras prácticas al repositorio. Los usuarios simplemente proporcionan un enlace al repositorio y pueden recibir una solicitud de extracción (PR) generada automáticamente con todos los cambios recomendados o revisar las sugerencias localmente antes de aplicarlas.
OSA se puede utilizar de dos maneras: clonando el repositorio y ejecutándolo a través de una interfaz de línea de comandos (CLI) o mediante una interfaz web. También ofrece tres modos de trabajo: básico, automático y avanzado, que se eligen en tiempo de ejecución para adaptarse a las diferentes necesidades. En el modo básico, OSA aplica un pequeño conjunto de mejoras estándar sin entrada adicional: genera un informe, README, documentación de la comunidad y una sección Acerca de, y agrega carpetas comunes como "pruebas" y "ejemplos" si faltan. El modo avanzado brinda a los usuarios control manual total sobre cada paso. En modo automático, OSA utiliza un LLM para analizar la estructura del repositorio y el archivo README existente, luego propone una lista de mejoras para que los usuarios las aprueben o rechacen. También se está desarrollando un modo conversacional experimental de múltiples agentes, que permitirá a los usuarios especificar las mejoras deseadas en el lenguaje natural de forma libre a través de la CLI. OSA interpreta esta solicitud y aplica los cambios correspondientes. Este modo se encuentra actualmente en desarrollo activo.
Otra fortaleza clave de OSA es su flexibilidad con los modelos de lenguaje. Funciona con proveedores populares como OpenRouter y OpenAI, así como con modelos locales como Ollama y LLM autohospedados que se ejecutan a través de FastAPI.
OSA también admite múltiples plataformas de repositorio, incluidas GitHub y GitLab (tanto GitLab.com como instancias autohospedadas). Puede ajustar archivos de configuración de CI/CD, configurar flujos de trabajo de implementación de documentación y configurar correctamente rutas para la documentación de la comunidad.
un sistema experimental multiagente (MAS), actualmente en desarrollo activo, que sirve como base para sus modos automático y conversacional. El sistema descompone la mejora del repositorio en una secuencia de etapas de razonamiento y ejecución, cada una manejada por un agente especializado. Los agentes se comunican a través de un estado compartido y se coordinan a través de un gráfico de estado dirigido, lo que permite transiciones condicionales y flujos de trabajo iterativos.
Generación LÉAME
OSA incluye una herramienta de generación README que crea automáticamente archivos README claros y útiles en dos formatos: un README estándar y un README estilo artículo. La herramienta decide qué formato usar por sí sola; por ejemplo, si el usuario proporciona una ruta o URL a un artículo científico a través de la CLI, OSA cambia al formato de artículo. Para empezar, escanea el repositorio para encontrar los archivos más importantes, centrándose en la lógica central y las descripciones del proyecto, y tiene en cuenta la estructura de carpetas y cualquier archivo README existente.
Para el README estándar, OSA analiza los archivos clave del proyecto, la estructura del repositorio, los metadatos y las secciones principales de un README existente, si hay uno presente. Luego genera una sección de "Características principales" que sirve como base para el resto del documento. Utilizando esta información, OSA escribe una descripción general clara del proyecto y agrega una sección de "Cómo comenzar" cuando hay scripts de ejemplo o archivos de demostración disponibles, lo que ayuda a los usuarios a comprender rápidamente cómo usar el proyecto.
En modo artículo, la herramienta crea un resumen del artículo científico asociado y extrae información relevante de los archivos de código principales. Estas piezas se combinan en una descripción general que explica los objetivos del proyecto, una sección de contenido que describe los componentes principales y cómo funcionan juntos, y una sección de algoritmos que explica cómo los métodos implementados encajan en la investigación. Este enfoque mantiene la documentación científicamente precisa y al mismo tiempo la hace más fácil de leer y comprender.
Generación de documentación
La herramienta de generación de documentación produce documentación concisa y contextual para funciones, métodos, clases y módulos de código. El proceso de generación de documentación es el siguiente:
(1) Análisis de referencia: inicialmente, un analizador controlado por TreeSitter busca módulos importados y resuelve las rutas a ellos para cada archivo de código fuente en particular, formando un mapa de importación que se utilizará para determinar las llamadas a métodos y funciones para la utilidad de módulos externos. Al implementar un enfoque de este tipo, es relativamente fácil rectificar las interconexiones entre diferentes partes del proyecto procesado y distinguir entre alias internos. Junto con los mapas de importación, el analizador también conserva información general, como el archivo de procesamiento, una lista de clases que ocurren y funciones independientes. Cada clase contiene su nombre, lista de atributos, decoradores, cadena de documentación, lista de sus métodos, y cada método tiene sus detalles específicos que tienen la misma estructura que las funciones independientes, es decir: nombre del método, cadena de documentación, tipo de retorno, código fuente y alias de llamadas a métodos externos resueltas con un nombre del módulo, clase, método y ruta importados.
(2) Generación inicial de cadenas de documentos para funciones, métodos y clases: con un analizador que tiene una estructura formada, se lleva a cabo una etapa inicial de generación de cadenas de documentos. En esta etapa solo se procesan cadenas de documentos que carecen de clases, métodos y funciones. A continuación se ofrece una descripción general de lo que hace el método "qué". El contexto es principalmente el código fuente del método, ya que en este punto es crucial formar una descripción general de la funcionalidad. El mensaje siguiente incluye información sobre los argumentos y decoradores del método, y sigue el código fuente de los métodos externos llamados para proporcionar contexto adicional para la utilidad del método de procesamiento. Un buen momento aquí es que las cadenas de documentación de clase se generan solo después de que se generan todos los métodos que carecen de cadenas de documentación; luego se proporcionan al modelo los atributos de clase, los nombres de sus métodos y las cadenas de documentación.
(3) Generación de “la idea principal” del proyecto utilizando descripciones de componentes derivados de la etapa anterior.
(4) Actualización de cadenas de documentos utilizando la “idea principal” generada: por lo tanto, presumiblemente todas las cadenas de documentos para el proyecto están presentes, se puede realizar la generación de la idea principal del proyecto. Esencialmente, el mensaje de la idea consta de cadenas de documentación para todas las clases y funciones, junto con su puntuación de importancia basada en la tasa de aparición de cada componente en los mapas de importación mencionados anteriormente, y su lugar en la jerarquía del proyecto determinado por la ruta de origen. La respuesta del modelo se devuelve en formato Markdown, resumiendo los componentes del proyecto. Una vez adquirida la idea principal, comienza la segunda etapa de generación de cadenas de documentación, durante la cual se procesan todos los componentes del código fuente del proyecto. En este momento, el enfoque clave es proporcionar al modelo una cadena de documentación original o generada en la etapa inicial con la idea principal de explicar "por qué" este componente es necesario para el proyecto. También se proporciona el código fuente de los métodos, ya que una narrativa ampliada del proyecto puede hacer que el modelo corrija algunos puntos en la cadena de documentación original.
(5) Generación de descripción de módulos jerárquicos comenzando de abajo hacia arriba.
(6) Uso de páginas Mkdocs y GitHub para envío y transmisión automatizados de documentación: etapa final del proceso de cadena de documentos, considerando un recorrido recursivo a través de los módulos y submódulos del proyecto. La jerarquía se basa en la ruta de origen; en cada nivel de procesamiento de hojas, se utiliza una estructura previamente analizada para crear una descripción de qué submódulo se utiliza, de acuerdo con la idea principal. A medida que el procesamiento avanza a niveles superiores de la jerarquía, los resúmenes de los submódulos generados también se utilizan para proporcionar contexto adicional. El modelo devuelve resúmenes en Markdown para garantizar una integración perfecta con el proceso de generación de documentación de mkdocs. El esquema completo del enfoque se describe en la imagen siguiente.
CI/CD y organización de la estructura
OSA ofrece una configuración de CI/CD automatizada que funciona en diferentes plataformas de alojamiento de repositorios. Genera flujos de trabajo configurables que facilitan la ejecución de pruebas, verificar la calidad del código e implementar proyectos. La herramienta admite utilidades comunes como Black para formatear código, unit_test para ejecutar pruebas, PEP8 y autopep8 para comprobaciones de estilo, fix_pep8 para correcciones automáticas de estilo, pypi_publish para publicar paquetes y slash_command_dispatch para manejar comandos. Dependiendo de la plataforma, estos flujos de trabajo se colocan en las ubicaciones apropiadas, por ejemplo, .github/workflows/ para GitHub o un archivo .gitlab-ci.yml en la raíz del repositorio para GitLab.
Los usuarios pueden personalizar los flujos de trabajo generados usando opciones como –use-poetry para habilitar Poetry para la gestión de dependencias, –branches para definir qué ramas activan los flujos de trabajo (de forma predeterminada, principal y maestra) y configuraciones de cobertura de código a través de –codecov-token y –include-codecov.
Para garantizar pruebas confiables, OSA también reorganiza la estructura del repositorio. Identifica archivos de prueba y de ejemplo y los mueve a directorios de pruebas y ejemplos estandarizados, lo que permite que los flujos de trabajo de CI ejecuten pruebas de manera consistente sin configuración adicional.
Los archivos de flujo de trabajo se crean a partir de plantillas que combinan información específica del proyecto con configuraciones definidas por el usuario. Este enfoque mantiene los flujos de trabajo consistentes en todos los proyectos y al mismo tiempo permite flexibilidad cuando es necesario.
OSA también automatiza la implementación de documentación utilizando MkDocs. Para los repositorios de GitHub, genera un flujo de trabajo YAML en el directorio .github/workflows y requiere habilitar permisos de lectura/escritura y seleccionar la rama gh-pages para la implementación en la configuración del repositorio. Para GitLab, OSA crea o actualiza el archivo .gitlab-ci.yml para incluir trabajos de compilación e implementación utilizando imágenes, scripts y reglas de retención de artefactos de Docker. Luego, la documentación se publica automáticamente cuando los cambios se combinan en la rama principal.
Cómo utilizar OSA
Para comenzar a usar OSA, elija su repositorio con código borrador que esté incompleto o poco documentado. Opcionalmente, incluya un artículo científico relacionado u otro documento que describa la biblioteca o algoritmo implementado en el repositorio elegido. El documento se carga como un archivo separado y se utiliza para generar el archivo README. También puede especificar el proveedor de LLM (por ejemplo, OpenAI) y el nombre del modelo (como GPT-4o).
OSA genera recomendaciones para mejorar el repositorio, que incluyen:
Un archivo README generado a partir del análisis de código, utilizando plantillas estándar y ejemplos Docstrings para clases y métodos que faltan actualmente, para permitir la generación automática de documentación con scripts de CI/CD MkDocs Basic, incluidos linters y pruebas automatizadas. Un informe con recomendaciones prácticas para mejorar el repositorio. Pautas y archivos de contribución (Código de conducta, solicitudes de extracción y plantillas de problemas, etc.)
Puede instalar OSA fácilmente ejecutando:
instalación de pip osa_tool
Después de configurar el entorno, debe elegir un proveedor de LLM (como OpenAI o un modelo local). A continuación, debe agregar GIT_TOKEN (token de GitHub con permisos de repositorio estándar) y OPENAI_API_KEY (si usa una API compatible con OpenAI) como variables de entorno, o también puede almacenarlas en el archivo .env. Finalmente, puedes iniciar OSA directamente desde la línea de comando. OSA está diseñado para funcionar con un repositorio de código abierto existente proporcionando su URL. El comando de inicio básico incluye la dirección del repositorio y parámetros opcionales como el modo de operación, el punto final de API y el nombre del modelo:
osa_tool -r {repositorio} [–mode {modo}] [–api {api}] [–base-url {base_url}] [–model {model_name}]
OSA admite tres modos de funcionamiento:
automático (predeterminado): analiza el repositorio y crea un plan de mejora personalizado utilizando el agente LLM especializado. básico: aplica un conjunto predefinido de mejoras: genera un informe del proyecto, README, pautas de la comunidad, una sección "Acerca de" y crea directorios estándar para pruebas y ejemplos (si faltan). avanzado: permite la selección y configuración manual de acciones antes de su ejecución.
Hay opciones CLI adicionales disponibles aquí. Puede personalizar OSA pasando estas opciones como argumentos a la CLI o seleccionando las funciones deseadas en el modo de línea de comandos interactiva.
Una vez iniciado, OSA realiza un análisis inicial del repositorio y muestra información clave: detalles generales del proyecto, la configuración actual del entorno y tablas con acciones planificadas e inactivas. Luego se le solicita al usuario que acepte el plan sugerido, cancele la operación o ingrese a un modo de edición interactivo.
En el modo interactivo, el plan se puede modificar: activar o desactivar acciones, ajustar parámetros (cadenas y listas) y configurar opciones adicionales. El sistema guía al usuario a través de la descripción de cada acción, los valores posibles y la configuración actual. Este proceso continúa hasta que el usuario confirma el plan final.
Este flujo de trabajo basado en CLI garantiza flexibilidad, desde el procesamiento totalmente automatizado hasta el control manual preciso, lo que lo hace adecuado tanto para evaluaciones iniciales rápidas como para refinamientos detallados de proyectos.
OSA también incluye un modo de interacción conversacional experimental que permite a los usuarios especificar las mejoras deseadas en el repositorio utilizando lenguaje natural de formato libre a través de la CLI. Si la solicitud es ambigua o no está suficientemente relacionada con el procesamiento del repositorio, el sistema solicita aclaraciones de forma iterativa y permite que se actualice el archivo complementario adjunto. Una vez obtenida una instrucción válida, OSA analiza el repositorio, selecciona los módulos internos apropiados y ejecuta las acciones correspondientes. Este modo se encuentra actualmente en desarrollo activo.
Cuando OSA finaliza, crea una solicitud de extracción (PR) en el repositorio. El PR incluye todos los cambios propuestos, como el archivo README, cadenas de documentos, página de documentación, scripts de CI/CD, pautas de contribución, informes y más. El usuario puede revisar fácilmente el PR, realizar cambios si es necesario y fusionarlo en la rama principal del proyecto.
Veamos un ejemplo. GAN-MFS es un repositorio que proporciona una implementación PyTorch de Wasserstein GAN con penalización de gradiente (WGAN-GP). A continuación se muestra un ejemplo de un comando para iniciar OSA en este repositorio:
osa_tool -r github.com/Roman223/GAN_MFS –mode auto –api openai –base-url https://api.openai.com/v1 –model gpt-4.1-mini
OSA hizo varias contribuciones al repositorio, incluido un archivo README generado a partir del contenido del artículo.
OSA también agregó un archivo de licencia a la solicitud de extracción, así como algunos scripts CI/CD básicos.
OSA agregó cadenas de documentación a todas las clases y métodos donde faltaba documentación. También generó un sitio de documentación estructurado basado en web utilizando esas cadenas de documentación.
El informe generado incluye una auditoría de los componentes clave del repositorio: README, licencia, documentación, ejemplos de uso, pruebas y un resumen del proyecto. También analiza secciones clave del repositorio, como estructura, README y documentación. Sobre la base de este análisis, el sistema identifica áreas clave de mejora y proporciona recomendaciones específicas.
Finalmente, OSA interactúa con el repositorio de destino a través de GitHub. El bot OSA crea una bifurcación del repositorio y abre una solicitud de extracción que incluye todos los cambios propuestos. El desarrollador sólo necesita revisar las sugerencias y ajustar todo lo que parezca incorrecto. En mi opinión, esto es mucho más fácil que escribir el mismo archivo README desde cero. Después de la revisión, el responsable del repositorio fusionó con éxito la solicitud de extracción. Todos los cambios propuestos por OSA están disponibles aquí.
Aunque la cantidad de cambios introducidos por OSA es significativa, es difícil evaluar la mejora general en la calidad del repositorio. Para ello, decidimos examinar el repositorio desde una perspectiva de seguridad. La herramienta de cuadro de mando nos permite evaluar el repositorio utilizando la métrica agregada. Scorecard se creó para ayudar a los mantenedores de código abierto a mejorar sus mejores prácticas de seguridad y para ayudar a los consumidores de código abierto a juzgar si sus dependencias son seguras. La puntuación agregada tiene en cuenta muchos parámetros del repositorio, incluida la presencia de artefactos binarios, pruebas de CI/CD, la cantidad de contribuyentes y una licencia. La puntuación agregada del repositorio original fue 2,2/10. Tras el procesamiento por parte de OSA, ascendió a 3,7/10. Esto sucedió debido a la adición de una licencia y scripts CI/CD. Esta puntuación aún puede parecer demasiado baja, pero el repositorio que se está procesando no está diseñado para integrarse en proyectos grandes. Se trata de una pequeña herramienta para generar datos sintéticos a partir de un artículo científico, por lo que sus requisitos de seguridad son menores.
¿Qué sigue para la AOS?
Planeamos integrar un sistema RAG en OSA, basado en las mejores prácticas en desarrollo de código abierto. OSA comparará el repositorio de destino con ejemplos de referencia para identificar los componentes faltantes. Por ejemplo, si el repositorio ya tiene un archivo README de alta calidad, no se regenerará. Inicialmente, utilizamos OSA para los repositorios de Python, pero planeamos admitir lenguajes de programación adicionales en el futuro.
Si tienes un repositorio abierto que requiere mejoras, ¡prueba OSA! También agradeceríamos ideas sobre nuevas funciones que pueda dejar como problemas y relaciones públicas.
Si deseas utilizar OSA en tus trabajos, puedes citarlo como:
Nikitin N. y otros. Una herramienta impulsada por LLM para mejorar los repositorios científicos de código abierto // Defender el desarrollo de código abierto en ML Workshop @ ICML25.