OSA: OPEN-SOURCE ADVISOR

pip install osa_tool

git clone https://github.com/aimclub/OSA

cd Open-Source-Advisor

pip install -r requirements.txt

poetry install 

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

# Linux / macOS (bash/zsh)
export OPENAI_API_KEY=<your_api_key>
export GIT_TOKEN=<your_git_token>

# Windows (PowerShell)
setx OPENAI_API_KEY "<your_api_key>"
setx GIT_TOKEN "<your_git_token>"

python -m osa_tool.run -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--attachment {article}] [--convert-notebooks {notebook_paths}]

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

The --generate-workflows option is intended to create customizable CI/CD pipelines for Python repositories. For detailed documentation, see the Workflow Generator README.

Also OSA supports custom configuration via TOML files. Use the --config-file option to specify a path to custom configuration file. If no custom configuration file is provided, OSA will use the default configuration.

By default, OSA uses a single model for all tasks (specified via --model). If you want to use different models for different types of tasks, disable the --use-single-model flag and specify models for each task type ( --model-docstring, --model-readme, --model-validation, --model-general).

To learn how to work with the interactive CLI and view descriptions of all available keys, visit the CLI usage guide.

Examples of generated README files are available in examples.

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

Supported LLM providers are available as part of the ProtoLLM ecosystem. See the connectors directory for the full list.

Local ITMO model:

python -m osa_tool.run -r https://github.com/aimclub/OSA --base-url [ITMO_MODEL_URL]

For this API provider itmo model url must be specified in dotenv (ITMO_MODEL_URL=) or in the --base-url argument.

OpenAI:

python -m osa_tool.run -r https://github.com/aimclub/OSA --api openai

VseGPT:

python -m osa_tool.run -r https://github.com/aimclub/OSA --api openai --base-url https://api.vsegpt.ru/v1 --model openai/gpt-3.5-turbo

Openrouter:

python -m osa_tool.run -r https://github.com/aimclub/OSA --api openai --base-url https://openrouter.ai/api/v1 --model qwen/qwen3-30b-a3b-instruct-2507

Ollama:

python -m osa_tool.run -r https://github.com/aimclub/OSA --api ollama --base-url http://[YOUR_OLLAMA_IP]:11434 --model gemma3:27b

Detailed description of OSA API is available here.

In our Telegram chat OSA_helpdesk you can ask questions about working with OSA and find the latest news about the project.

In English:

• Automate Your Coding with OSA – ITMO-Made AI Assistant for Researchers

In Russian:

• OSA: ИИ-помощник для разработчиков научного open source кода

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

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

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.

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

Nikitin N. et al. An LLM-Powered Tool for Enhancing Scientific Open-Source Repositories // Championing Open-source DEvelopment in ML Workshop@ ICML25.

    @inproceedings{nikitinllm,
    title={An LLM-Powered Tool for Enhancing Scientific Open-Source Repositories},
    author={Nikitin, Nikolay and Getmanov, Andrey and Popov, Zakhar and 
        Ulyanova Ekaterina and Aksenkin, Yaroslav and 
        Sokolov, Ilya and Boukhanovsky, Alexander},
    booktitle={Championing Open-source DEvelopment in ML Workshop@ ICML25}}