OSA: OPEN-SOURCE ADVISOR

Built with:

---

Overview

OSA (Open-Source-Advisor) is a LLM-based tool for improving the quality of scientific open source projects and helping create them from scratch. It automates the generation of README, different levels of documentation, CI/CD scripts, etc. It also generates advices and recommendations for the repository.

OSA is currently under development, so not all features are implemented.

---

How it works?

Here is a short demo:

---

Table of contents

• Core features
• Installation
• Getting started
• Examples
• Documentation
• Contributing
• License
• Acknowledgments
• Citation

---

Core features

1. README file generation: Automates the creation of a clear and structured README file for a repository, including projects based on research papers.

2. Documentation generation: Automatically generates docstrings for Python code.

3. Automatic implementation of changes: Clones the repository, creates a branch, commits and pushes changes, and creates a pull request with proposed changes.

4. Various LLMs: Use OSA with an LLM accessible via API (e.g., OpenAI, VseGPT), a local server, or try an osa_bot hosted on ITMO servers.

---

Installation

Install Open-Source-Advisor using one of the following methods:

Using PyPi:

pip install osa-tool

Build from source:

1. Clone the Open-Source-Advisor repository:

git clone https://github.com/ITMO-NSS-team/Open-Source-Advisor

2. Navigate to the project directory:

cd Open-Source-Advisor

3. Install the project dependencies:

Using pip  

pip install -r requirements.txt

Using poetry  

poetry install 

Using docker  

docker build --build-arg GIT_USER_NAME="your-user-name" --build-arg GIT_USER_EMAIL="your-user-email" -f docker/Dockerfile -t {image-name} .

---

Getting started

Prerequisites

OSA requires Python 3.10 or higher.

File .env is required to specify GitHub token (GIT_TOKEN) and LLM API key (OPENAI_API_KEY or VSE_GPT_KEY)

Usage

Run Open-Source-Advisor using the following command:

Using pip  

python main.py -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}]

Using docker  

docker run --env-file .env {image-name} -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}]

The --article option enables you to choose a README template for a repository based on an article. You can provide either a link to a PDF file of the article or a path to a local PDF file after the --article option. If you are using Docker, ensure that you upload the PDF file to the OSA folder before building the image, then, specify the path as /app/OSA/... or just use volume mounting to access the file.

Configuration

Flag	Description	Default
-r, --repository	URL of the GitHub repository (Mandatory)
--api	LLM API service provider	llama
--base-url	URL of the provider compatible with API OpenAI	https://api.openai.com/v1
--model	Specific LLM model to use	gpt-3.5-turbo
--article	Link to the pdf file of the article	None
--translate-dirs	Enable automatic translation of the directory name into English	disabled

---

Examples

Examples of generated README files are available in examples.

URL of the GitHub repository, LLM API service provider (optional) and Specific LLM model to use (optional) are required to use the generator.

To see available models go there:

1. VseGpt
2. OpenAI

Local Llama ITMO:

python main.py -r https://github.com/ITMO-NSS-team/Open-Source-Advisor

OpenAI:

python main.py -r https://github.com/ITMO-NSS-team/Open-Source-Advisor --api openai

VseGPT:

python main.py -r https://github.com/ITMO-NSS-team/Open-Source-Advisor --api openai --base-url https://api.vsegpt.ru/v1 --model openai/gpt-3.5-turbo

---

Documentation

Detailed description of OSA API is available here.

---

Contributing

• Report Issues: Submit bugs found or log feature requests for the Open-Source-Advisor project.

---

License

This project is protected under the BSD 3-Clause "New" or "Revised" License. For more details, refer to the LICENSE file.

---

Acknowledgments

The project is supported as ITMO University Research Project in AI Initiative (RPAII).

OSA is tested by the members of ITMO OpenSource community. Useful content from community is available in Open-source-ops

Also, we thank Readme-ai for their code that we used as a foundation for our own version of README generator.

---

Citation

If you use this software, please cite it as below.

APA format:

ITMO, NSS Lab (2025). Open-Source-Advisor repository [Computer software]. https://github.com/ITMO-NSS-team/Open-Source-Advisor

BibTeX format:

@misc{Open-Source-Advisor,

    author = {ITMO, NSS Lab},

    title = {Open-Source-Advisor repository},

    year = {2025},

    publisher = {github.com},

    journal = {github.com repository},

    howpublished = {\url{https://github.com/ITMO-NSS-team/Open-Source-Advisor.git}},

    url = {https://github.com/ITMO-NSS-team/Open-Source-Advisor.git}

}

---