<div align="center">
    <h1 align="center">
        <img src="https://img.icons8.com/?size=512&id=55494&format=png" width="80" />
        <img src="https://img.icons8.com/?size=512&id=kTuxVYRKeKEY&format=png" width="80" />
        <br>README-AI
    </h1>
    <h3>◦ Generate beautiful and informative README.md files.</h3>
    <h3>◦ Developed with OpenAI's GPT language model APIs.</h3>
    <br>
    <p align="center">
        <img src="https://img.shields.io/badge/Markdown-000000.svg?stylee&logo=Markdown&logoColor=white" alt="Markdown" />
        <img src="https://img.shields.io/badge/OpenAI-412991.svg?stylee&logo=OpenAI&logoColor=white" alt="OpenAI" />
        <img src="https://img.shields.io/badge/Python-3776AB.svg?stylee&logo=Python&logoColor=white" alt="Python" />
        <img src="https://img.shields.io/badge/Pytest-0A9EDC.svg?stylee&logo=Pytest&logoColor=white" alt="pytest" />
        <img src="https://img.shields.io/badge/Docker-2496ED.svg?style&logo=Docker&logoColor=white" alt="Docker" />
        <img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style&logo=GitHub-Actions&logoColor=white" alt="actions" />
    </p>
    <a href="https://pypi.org/project/readmeai/">
        <img src="https://img.shields.io/pypi/v/readmeai?color=5D6D7E&logo=pypi" alt="pypi-version" />
    </a>
    <a href="https://pypi.org/project/readmeai/">
        <img src="https://img.shields.io/pypi/pyversions/readmeai?color=5D6D7E&logo=python" alt="pypi-python-version" />
    </a>
    <a href="https://pypi.org/project/readmeai/">
        <img src="https://img.shields.io/pypi/dm/readmeai?color=5D6D7E" alt="pypi-downloads" />
    </a>
    <img src="https://img.shields.io/github/license/eli64s/readme-ai?color=5D6D7E" alt="github-license" />
</div>

---

## 📖 Table of Contents

- [📖 Table of Contents](#-table-of-contents)
- [📍 Overview](#-overview)
- [🤖 Demo](#-demo)
- [🕹 Play](#-play)
- [✨ Features](#-features)
- [🚀 Getting Started](#-getting-started)
  - [📋 Dependencies](#-dependencies)
    - [📂 Repository](#-repository)
    - [🔑 OpenAI API](#-openai-api)
  - [📦 Install](#-install)
  - [🎮 Usage](#-usage)
    - [🎈 Streamlit Community Cloud](#-streamlit-community-cloud)
    - [🔡 Command-Line Arguments](#-command-line-arguments)
    - [🛠 Configuration](#-configuration)
  - [🪄 Running *README-AI*](#-running-readme-ai)
  - [🧪 Running Tests](#-running-tests)
- [🛣 Roadmap](#-roadmap)
- [📒 Changelog](#-changelog)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [👏 Acknowledgments](#-acknowledgments)

---

## 📍 Overview

*README-AI* is a powerful command-line tool that generates robust README.md files for your software and data projects. By simply providing a remote repository URL or path to your codebase, this tool auto-generates documentation for your entire project, leveraging the capabilities OpenAI's GPT language model APIs. *README-AI* is currently available as a Python library and Docker image.

**🎯 Motivation**

*README-AI* simplifies the process of writing and maintaining high-quality project documentation, enhancing developer productivity and workflow. The ultimate goal of *readme-ai* is to improve the adoption and usability of open-source software, enabling all skill levels to better understand complex codebases and easily use open-source tools.

**⚠️ Disclaimer**

This project is currently under development and has an opinionated configuration. While *readme-ai* provides an excellent starting point for documentation, its important to review all text generated by the OpenAI API to ensure it accurately represents your codebase. Additionally, ensure all content in your repository is free of sensitive information before executing, and remember to frequently monitor your API costs using the [OpenAI API Usage Dashboard.](https://platform.openai.com/account/usage)

---

## 🤖 Demo

<a href="https://youtu.be/pl-VcVfGbbk">
    <img src="https://raw.githubusercontent.com/eli64s/readme-ai/f0c5a038f63ae04b2d4452974676a92db42be8ce/examples/imgs/demo.png" alt="demo-video">
</a>

---

## 🕹 Play

Ready to dive in? Explore and use *readme-ai* in your web browser with Streamlit Community Cloud, no installation required!

- [**Launch readme-ai on Streamlit**](https://readmeai.streamlit.app/)

---

## ✨ Features

<h1 align="center">1.<br>👇<br><br>📑 Codebase Documentation</h1>
<table align="center">
    <tr>
        <td>
            <h3>◦ Repository File Summaries</h3>
            <ul>
                <li>Code summaries are generated for each file via OpenAI's <i>gpt-3.5-turbo</i> engine.</li>
                <li>The File column in the markdown table contains a link to the file on GitHub.</li>
            </ul>
        </td>
    </tr>
    <tr>
        <td>
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/modules.png" alt="docs">
        </td>
    </tr>
</table>

<h1 align="center">⒉<br>👇<br><br>🎖 Badges</h1>
<table align="center">
    <tr>
        <td>
            <h3>◦ Introduction, Badges, & Table of Contents</h3>
            <ul>
                <li>The OpenAI API is prompted to create a 1-sentence phrase describing your project.</li>
                <li>Project dependencies and metadata are visualized using <a href="https://shields.io/">Shields.io</a> badges.</li>
                <li>Badges are sorted by hex code, displayed from light to dark hues.</li>
            </ul>
        </td>
    </tr>
    <tr>
        <td>
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/header.png" alt="docs">
        </td>
    </tr>
</table>

<h1 align="center">⒊<br>👇<br><br>🧚 Prompted Text Generation</h1>
<table align="center">
    <tr>
        <td>
            <h3>◦ Features Table & Overview</h3>
            <ul>
                <li>Detailed prompts are embedded with repository metadata and passed to the OpenAI API.</li>
                <ul>
                    <li><em>Features</em> table highlights various technical attributes of your codebase.
                    </li>
                    <li><em>Overview</em> section describes your project's use case and applications.
                    </li>
                </ul>
            </ul>
        </td>
    </tr>
    <tr>
        <td>
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/features.png" alt="features">
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/overview.png" alt="overview">
        </td>
    </tr>
</table>

<h1 align="center">⒋<br>👇<br><br>🌲 Repository Tree</h1>
<table align="center">
    <tr>
        <td>
        <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/tree.png" alt="tree">
        </td>
    </tr>
</table>

<h1 align="center">⒌<br>👇<br><br>📦 Dynamic User Setup Guides</h1>
<table align="center">
    <tr>
        <td>
            <h3><b>◦ Installation, Usage, & Testing</b></h3>
            <ul>
                <li>Generates instructions for installing, using, and testing your codebase.</li>
                <li>README-AI currently supports this feature for code written with:</li>
                <ul>
                    <li>
                        <i>Python, Rust, Go, C, Kotlin, Java, JavaScript, TypeScript.</i>
                    </li>
                </ul>
            </ul>
        </td>
    </tr>
    <tr>
        <td>
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/getting_started.png" alt="getting_started">
        </td>
    </tr>
</table>

<h1 align="center">⒍<br>👇<br><br>👩‍💻 Contributing Guidelines & more!</h1>
<table align="center">
    <tr>
        <td>
            <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/imgs/closing.png" alt="contribute">
        </td>
    </tr>
</table>

<h1 align="center">⒎<br>👇<br><br>💥 Example <i>README</i> Files</h1>
<p align="center">Example markdown files generated by <i>readme-ai!</i></p>

<div align="center">

|     | Example File                                                                                              | Repository                                                                                      | Language               | Bytes   |
|-----|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|------------------------|---------|
| 1️⃣ | [readme-python.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-python.md)               | [readme-ai](https://github.com/eli64s/readme-ai)                                                | Python                 | 19,839  |
| 2️⃣ | [readme-typescript.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-typescript.md)       | [chatgpt-app-react-typescript](https://github.com/Yuberley/ChatGPT-App-React-Native-TypeScript) | TypeScript, React      | 988     |
| 3️⃣ | [readme-javascript.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-javascript.md)       | [assistant-chat-gpt-javascript](https://github.com/idosal/assistant-chat-gpt)                   | JavaScript, React      | 212     |
| 4️⃣ | [readme-kotlin.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-kotlin.md)               | [file.io-android-client](https://github.com/rumaan/file.io-Android-Client)                      | Kotlin, Java, Android  | 113,649 |
| 5️⃣ | [readme-rust-c.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-rust-c.md)               | [rust-c-app](https://github.com/DownWithUp/CallMon)                                             | C, Rust                | 72      |
| 6️⃣ | [readme-go.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-go.md)                       | [go-docker-app](https://github.com/olliefr/docker-gs-ping)                                      | Go                     | 41      |
| 7️⃣ | [readme-java.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-java.md)                   | [java-minimal-todo](https://github.com/avjinder/Minimal-Todo)                                   | Java                   | 17,725  |
| 8️⃣ | [readme-fastapi-redis.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-fastapi-redis.md) | [async-ml-inference](https://github.com/FerrariDG/async-ml-inference)                           | Python, FastAPI, Redis | 355     |
| 9️⃣ | [readme-mlops.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-mlops.md)                 | [mlops-course](https://github.com/GokuMohandas/mlops-course)                                    | Python, Jupyter        | 8,524   |
| 🔟  | [readme-pyflink.md](https://github.com/eli64s/readme-ai/blob/main/examples/readme-pyflink.md)             | [flink-flow](https://github.com/eli64s/flink-flow)                                              | PyFlink                | 32      |

</div>

<h1 align="center">⒏<br>👇<br><br>📜 Custom README templates coming soon!</h1>
<p align="center">Developing a feature that allows users to select from a variety of README formats and styles.</p>
<p align="center">Custom templates will be tailored for use-cases such as data, ai & ml, research, minimal, and more!</p>

<p align="right">
    <a href="#top"><b>🔝 Return </b></a>
</p>

---

## 🚀 Getting Started

### 📋 Dependencies

Please ensure you have the following dependencies installed on your system:

- *Python version 3.9 or higher*
- *Package manager (i.e. pip, conda, poetry) or Docker*
- *OpenAI API paid account and api key*

#### 📂 Repository

A remote repository URL or path to your local project's directory is needed to use *readme-ai*. The following repository types are currently supported:
- *GitHub*
- *GitLab*
- *File System*

#### 🔑 OpenAI API

An OpenAI API account and API key are needed to use *readme-ai*. The steps below outline this process:

<details closed><summary>OpenAI API User Guide</summary>

1. Go to the [OpenAI website](https://platform.openai.com/).
2. Click the "Sign up for free" button.
3. Fill out the registration form with your information and agree to the terms of service.
4. Once logged in, click on the "API" tab.
5. Follow the instructions to create a new API key.
6. Copy the API key and keep it in a secure place.

**⚠️ Additional Notes**
- To maximize your experience using *readme-ai*, its recommended to set up a payment method with OpenAI.
  - By doing so, you gain access to more powerful models like gpt-3.5-turbo.
  - Without a payment method, your API usage will be restricted to the base gpt-3 models, potentially leading to less accurate README file generation and API exceptions occurring.
- The OpenAI API is **NOT** free and you will be charged for each request made, which can accumulate costs rapidly.
  - Regularly monitor your API usage and costs by visiting the [OpenAI API Usage Dashboard.](https://platform.openai.com/account/usage)
  - Also ensure your OpenAI account has sufficient credits to run the *readme-ai* application.
- README file generation should take under 1 minute. If *readme-ai* is running for longer than a few minutes, terminate the process immediately.

</details>

---

### 📦 Install

*Using Pip*

Pip is the recommended installation method for most users. More details about the Python package can be found on [PyPI.](https://pypi.org/project/readmeai/)

```sh
pip install --upgrade readmeai
```

*Using Docker*

Docker is recommended for users wanting to run *readme-ai* in a containerized environment. More details about the image can be found on [Docker Hub.](https://hub.docker.com/repository/docker/zeroxeli/readme-ai/general)

```sh
docker pull zeroxeli/readme-ai:latest
```

<details><summary><i>Install Manually</i></summary>

1️⃣ Clone the readme-ai repository.
```sh
git clone https://github.com/eli64s/readme-ai
```

2️⃣ Navigate to readme-ai directory.

```sh
cd readme-ai
```

3️⃣ Install dependencies using a method below.

*Using Bash*
```sh
bash setup/setup.sh
```

*Using Conda*
```sh
conda create -n readmeai python=3.9 -y && \
conda activate readmeai && \
pip install -r requirements.txt
```

*Using Poetry*
```sh
poetry install
```

</details>

---

### 🎮 Usage

#### 🎈 Streamlit Community Cloud

You can directly use *readme-ai* in your web browser without installing anything! The Streamlit app is still under development and bugs may exist. If you encounter any errors, please create a new issue!

- [Launch readme-ai on Streamlit](https://readmeai.streamlit.app/)

---

#### 🔡 Command-Line Arguments

To generate a *README.md* file, use the `readmeai` command in your terminal, along with the arguments below.

| Short Flag | Long Flag       | Description                                         | Status        |
|------------|-----------------|-----------------------------------------------------|---------------|
| `-k`       | `--api-key`     | Your OpenAI API key.                                | Required      |
| `-o`       | `--output`      | The output path for your README.md file.            | Required      |
| `-r`       | `--repository`  | The URL or path to your code repository.            | Required      |
| `-t`       | `--template`    | The README template format to use. (coming soon!)   | Coming Soon!  |
| `-l`       | `--language`    | The language of text written in the README file.    | Coming Soon!  |

---

#### 🛠 Configuration

To customize the README file generation process, you can modify the [configuration file](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml). The file contains the following sections:

- [*api*](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml#L2) - OpenAI language model API configuration settings.
- [*git*](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml#L12) - Default git repository settings used if no repository is provided.
- [*paths*](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml#L17) - Directory paths and files used by the *readme-ai* application.
- [*prompts*](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml#L26) - Large language model prompts used to generate the README file.
- [*md*](https://github.com/eli64s/readme-ai/blob/main/readmeai/conf/conf.toml#L59) - Dynamic Markdown section code templates used to build the README file.

---

### 🪄 Running *README-AI*

*Using Pip*

```sh
# Option 1: Run readmeai command with all required command-line arguments.
readmeai --api-key "YOUR_API_KEY" --output readme-ai.md --repository https://github.com/eli64s/readme-ai
```
```sh
# Option 2: Run readmeai command with OpenAI API key set as environment variable.
export OPENAI_API_KEY="YOUR_API_KEY"
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
```

*Using Docker*

```sh
# Option 1: Run Docker container with all required command-line arguments.
docker run -it \
-e OPENAI_API_KEY="YOUR_API_KEY" \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
```
```sh
# Option 2: Run Docker container with OpenAI API key set as environment variable.
export OPENAI_API_KEY="YOUR_API_KEY"
docker run -it \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
```

<details><summary><i>Run Manually</i></summary>

*Using Conda*
```sh
conda activate readmeai
export OPENAI_API_KEY="YOUR_API_KEY"
python readmeai/main.py -o readme-ai.md -r https://github.com/eli64s/readme-ai
```

*Using Poetry*
```sh
poetry shell
export OPENAI_API_KEY="YOUR_API_KEY"
poetry run python readmeai/main.py -o readme-ai.md -r https://github.com/eli64s/readme-ai
```

</details>

---

### 🧪 Running Tests

Execute the test suite using command below.

```sh
bash scripts/test.sh
```

---

## 🛣 Roadmap

- [X] Publish project as a Python library via PyPI and a Docker image on Docker Hub.
  - [*PyPI - readmeai*](https://pypi.org/project/readmeai/)
  - [*Docker Hub - readme-ai*](https://hub.docker.com/repository/docker/zeroxeli/readme-ai/general)
- [X] Integrate and deploy app with Streamlit to provide a simple user-interface for using the tool.
  - [*Streamlit Community Cloud - readmeai*](https://readmeai.streamlit.app/)
- [ ] Develop GitHub Actions script to automatically update the README file when new code is pushed.
- [ ] Design README output templates for a variety of use-cases (i.e. data, web-dev, minimal, etc.)
- [ ] Add support for generating README files in any language (i.e. CN, ES, FR, JA, KO, RU).

---

## 📒 Changelog

[Changelog](https://github.com/eli64s/readme-ai/blob/main/CHANGELOG.md)

---

## 🤝 Contributing

[Contributing Guidelines](https://github.com/eli64s/readme-ai/blob/main/CONTRIBUTING.md)

---

## 📄 License

[MIT](https://github.com/eli64s/readme-ai/blob/main/LICENSE)

---

## 👏 Acknowledgments

*Badges*
  - [Shields.io](https://shields.io/)
  - [Aveek-Saha/GitHub-Profile-Badges](https://github.com/Aveek-Saha/GitHub-Profile-Badges)
  - [Ileriayo/Markdown-Badges](https://github.com/Ileriayo/markdown-badges)

<p align="right">
  <a href="#top"><b>🔝 Return </b></a>
</p>


---
