Metadata-Version: 2.3
Name: osa_tool
Version: 0.2.0.1
Summary: Tool that just makes your open source project better!
License: BSD-3-Clause
Author: ITMO-NSS-team
Author-email: itmo.nss.team@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: ProtoLLM (>=0.1.2)
Requires-Dist: PyYAML (==6.0.2)
Requires-Dist: Pygments (==2.19.1)
Requires-Dist: aiohappyeyeballs (==2.4.4)
Requires-Dist: aiohttp (==3.11.11)
Requires-Dist: aiosignal (==1.3.2)
Requires-Dist: annotated-types (==0.7.0)
Requires-Dist: anyio (==4.7.0)
Requires-Dist: async-timeout (>=4.0.0,<5.0.0)
Requires-Dist: attrs (==25.1.0)
Requires-Dist: black (==25.1.0)
Requires-Dist: certifi (==2024.12.14)
Requires-Dist: charset-normalizer (==3.4.1)
Requires-Dist: colorama (==0.4.6)
Requires-Dist: distro (==1.9.0)
Requires-Dist: exceptiongroup (==1.2.2)
Requires-Dist: frozenlist (==1.5.0)
Requires-Dist: gitdb (==4.0.11)
Requires-Dist: gitpython (==3.1.43)
Requires-Dist: h11 (==0.16.0)
Requires-Dist: httpcore (==1.0.9)
Requires-Dist: httpx (>=0.27.2,<0.28.0)
Requires-Dist: idna (==3.10)
Requires-Dist: iniconfig (==2.0.0)
Requires-Dist: jiter (==0.8.2)
Requires-Dist: markdown-it-py (==3.0.0)
Requires-Dist: mdurl (==0.1.2)
Requires-Dist: mkdocs (==1.6.1)
Requires-Dist: mkdocs-material (==9.6.13)
Requires-Dist: mkdocstrings[python] (==0.29.1)
Requires-Dist: multidict (==6.1.0)
Requires-Dist: nbconvert (>=6.0)
Requires-Dist: nbformat (>=5.0)
Requires-Dist: openai (==1.58.1)
Requires-Dist: openpyxl (==3.1.5)
Requires-Dist: packaging (==24.2)
Requires-Dist: pandas (==2.2.3)
Requires-Dist: pdfminer.six (==20231228)
Requires-Dist: pdfplumber (==0.11.5)
Requires-Dist: pipreqs (>=0.5.0,<0.6.0) ; python_version < "3.13"
Requires-Dist: pluggy (==1.5.0)
Requires-Dist: prompt_toolkit (==3.0.51)
Requires-Dist: propcache (==0.2.1)
Requires-Dist: pydantic (>=2.9.0,<2.11.0)
Requires-Dist: pydantic-extra-types (==2.9.0)
Requires-Dist: pydantic_core (>=2.23.4,<2.24.0)
Requires-Dist: pytest (==8.3.4)
Requires-Dist: pytest-mock (==3.14.0)
Requires-Dist: python-dotenv (==1.0.1)
Requires-Dist: qrcode (==8.0)
Requires-Dist: regex (==2024.11.6)
Requires-Dist: reportlab (==4.3.1)
Requires-Dist: requests (==2.32.3)
Requires-Dist: rich (==13.9.4)
Requires-Dist: smmap (==5.0.2)
Requires-Dist: sniffio (==1.3.1)
Requires-Dist: structlog (==24.4.0)
Requires-Dist: tiktoken (==0.8.0)
Requires-Dist: tomli (==2.2.1)
Requires-Dist: tqdm (==4.67.1)
Requires-Dist: tree-sitter (==0.23.2)
Requires-Dist: tree-sitter-python (==0.23.4)
Requires-Dist: typing_extensions (==4.12.2)
Requires-Dist: urllib3 (==2.3.0)
Requires-Dist: yarl (==1.18.3)
Project-URL: Documentation, https://itmo-nss-team.github.io/Open-Source-Advisor/
Project-URL: Homepage, https://github.com/aimclub/OSA
Project-URL: Issues, https://github.com/aimclub/OSA/issues
Description-Content-Type: text/markdown

# OSA: OPEN-SOURCE ADVISOR

<p align="center">

<img src="./docs/images/osa_logo_h.PNG" width="600">
</p>

<p align="center">

[![Acknowledgement ITMO](https://raw.githubusercontent.com/aimclub/open-source-ops/43bb283758b43d75ec1df0a6bb4ae3eb20066323/badges/ITMO_badge.svg)](https://itmo.ru/)
[![Open-source-ops website](https://raw.githubusercontent.com/aimclub/open-source-ops/7de1e1321389ec177f236d0a5f41f876811a912a/badges/open--source--ops-black.svg)](https://aimclub.github.io/open-source-ops/)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![PyPi](https://badge.fury.io/py/osa_tool.svg)](https://badge.fury.io/py/osa_tool)
[![OSA-improved](https://img.shields.io/badge/improved%20by-OSA-yellow)](https://github.com/aimclub/OSA)
[![Telegram Chat](https://img.shields.io/badge/Telegram-group-blue)](https://t.me/OSA_helpdesk)
</p>

<p>Built with:</p>
<p>
 <img src="https://img.shields.io/badge/Python-3776AB.svg?style=BadgeStyleOptions.DEFAULT&logo=Python&logoColor=white" alt="Python">
 <img src="https://img.shields.io/badge/Docker-2496ED.svg?style=BadgeStyleOptions.DEFAULT&logo=Docker&logoColor=white" alt="Docker">
 <img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=BadgeStyleOptions.DEFAULT&logo=GitHub-Actions&logoColor=white" alt="GitHub%20Actions">
 <img src="https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=BadgeStyleOptions.DEFAULT&logo=AIOHTTP&logoColor=white" alt="AIOHTTP">
 <img src="https://img.shields.io/badge/OpenAI-412991.svg?style=BadgeStyleOptions.DEFAULT&logo=OpenAI&logoColor=white" alt="OpenAI">
 <img src="https://img.shields.io/badge/Pydantic-E92063.svg?style=BadgeStyleOptions.DEFAULT&logo=Pydantic&logoColor=white" alt="Pydantic">
</p>

---

## 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:

![Animation](./docs/images/osa_demo.gif)

---

## Table of contents

- [Core features](#core-features)
- [Installation](#installation)
- [Getting started](#getting-started)
- [Examples](#examples)
- [Documentation](#documentation)
- [Chat with developers: OSA_helpdesk](#chat-with-developers-osa_helpdesk)
- [Publications about OSA](#publications-about-osa)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Citation](#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, Ollama), a local server, or try
   an [osa_bot](https://github.com/osa-bot) hosted on ITMO servers.

5. **GitHub Action Workflow Generator**: Automatically generates customizable CI/CD workflows for Python repositories,
   including unit tests, code formatting, PEP 8 compliance checks, and PyPI publication.

---

## Installation

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

**Using PyPi:**

```sh
pip install osa_tool
```

**Build from source:**

1. Clone the Open-Source-Advisor repository:

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

2. Navigate to the project directory:

```sh
cd Open-Source-Advisor
```

3. Install the project dependencies:

**Using `pip`** &nbsp;
[<img align="center" src="https://img.shields.io/badge/Pip-3776AB.svg?style={badge_style}&logo=pypi&logoColor=white" />](https://pypi.org/project/pip/)

```sh
pip install -r requirements.txt
```

**Using `poetry`** &nbsp;
[<img align="center" src="https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json" />](https://python-poetry.org/)

```sh
poetry install 
```

**Using `docker`** &nbsp;
[<img align="center" src="https://img.shields.io/badge/Docker-2CA5E0.svg?style={badge_style}&logo=docker&logoColor=white" />](https://www.docker.com/)

```sh
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/GitLab/Gitverse token (GIT_TOKEN) and LLM API key (OPENAI_API_KEY or VSE_GPT_KEY)

When running `osa-tool` from CLI, you need to set the GIT_TOKEN and API key first:

```commandline
export OPENAI_API_KEY=<your_api_key>
export GIT_TOKEN=<your_git_token>
```

### Tokens

| Token name       | Description                                                                                                        | Mandatory |
|------------------|--------------------------------------------------------------------------------------------------------------------|-----------|
| `GIT_TOKEN`      | Personal GitHub/GitLab/Gitverse token used to clone private repositories, access metadata, and interact with its API.       | Yes       |
| `OPENAI_API_KEY` | API key for accessing [OpenAI](https://platform.openai.com/docs/api-reference/introduction)'s language models.     | No        |
| `VSE_GPT_KEY`    | API key for [vsegpt](https://vsegpt.ru/Docs/API) LLM provider compatible with OpenAI's API format.                 | No        |
| `X-API-Key`      | API key for the [pepy.tech](https://pepy.tech/pepy-api) REST API, used to fetch Python package download statistics | No        |

### Usage

Run Open-Source-Advisor using the following command:

**Using `pip`** &nbsp;
[<img align="center" src="https://img.shields.io/badge/Pip-3776AB.svg?style={badge_style}&logo=pypi&logoColor=white" />](https://pypi.org/project/pip/)

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

**Using `docker`** &nbsp;
[<img align="center" src="https://img.shields.io/badge/Docker-2CA5E0.svg?style={badge_style}&logo=docker&logoColor=white" />](https://www.docker.com/)

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

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.

The --generate-workflows option is intended to create customizable CI/CD pipelines for Python repositories. For detailed
documentation, see the [GitHub Action Workflow Generator README](./osa_tool/github_workflow/README.md).

### Configuration

| Flag                 | Description                                                                         | Default                     |
|----------------------|-------------------------------------------------------------------------------------|-----------------------------|
| `-r`, `--repository` | URL of the GitHub/GitLab/Gitverse repository (**Mandatory**)                        |                             |
| `-b`, `--branch`     | Branch name of the repository                                                       | Default branch              |
| `--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`             |
| `-m`, `--mode`       | Operation mode for repository processing: `basic`, `auto` (default), or `advanced`. | `auto`                      |
| `--delete-dir`       | Enable deleting the downloaded repository after processing                          | `disabled`                  |
| `--no-fork`          | Avoid create fork for target repository                                             | `False`                     |
| `--no-pull-request`  | Avoid create pull request for target repository                                     | `False`                     |
| `--top_p`            | Nucleus sampling probability                                                        | `null`                      |
| `--temperature`      | Sampling temperature to use for the LLM output (0 = deterministic, 1 = creative).   | `null`                      |
| `--max_tokens`       | Maximum number of tokens the model can generate in a single response                | `null`                      |

To learn how to work with the interactive CLI and view descriptions of all available keys, visit
the [CLI usage guide](./osa_tool/scheduler/README.md).

---

## Examples

Examples of generated README files are available in [examples](https://github.com/aimclub/OSA/tree/main/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.

To see available models go there:

1. [VseGpt](https://vsegpt.ru/Docs/Models)
2. [OpenAI](https://platform.openai.com/docs/models)
3. [Ollama](https://ollama.com/library)

Local Llama ITMO:

```sh
python -m osa_tool.run -r https://github.com/aimclub/OSA
```  

OpenAI:

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

VseGPT:

```sh
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
```

Ollama:

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

---

## Documentation

Detailed description of OSA API is available [here](https://aimclub.github.io/OSA/).

---

## Chat with developers: OSA_helpdesk

In our Telegram chat [OSA_helpdesk](t.me/osa_helpdesk) you can ask questions about working with OSA and find the latest news about the project.

--- 

## Publications about OSA

In English:

- [Automate Your Coding with OSA – ITMO-Made AI Assistant for Researchers](https://news.itmo.ru/en/news/14282/)

In Russian:

- [OSA: ИИ-помощник для разработчиков научного open source кода](https://habr.com/ru/companies/spbifmo/articles/906018/)

---

## Contributing

- **[Report Issues](https://github.com/aimclub/OSA/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](https://github.com/aimclub/OSA/blob/main/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](https://t.me/scientific_opensource) community. Useful content from
community
is available in [**Open-source-ops**](https://github.com/aimclub/open-source-ops)

Also, we thank [**Readme-ai**](https://github.com/eli64s/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/aimclub/OSA

### 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/aimclub/OSA.git}},

        url = {https://github.com/aimclub/OSA.git}

    }

---

