https://github.com/urpagin/gh-topicgen
AI-generates (OpenAI) GitHub repo topics for you!
https://github.com/urpagin/gh-topicgen
ai auto-tagging cli command-line-tool generative-ai github github-topics keyword-extraction llm machine-learning natural-language-processing openai openai-api python python-package semantic-analysis tagging text-classification topic-generation topic-modeling
Last synced: 5 months ago
JSON representation
AI-generates (OpenAI) GitHub repo topics for you!
- Host: GitHub
- URL: https://github.com/urpagin/gh-topicgen
- Owner: Urpagin
- License: mit
- Created: 2025-08-16T21:22:38.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-08-17T01:15:31.000Z (7 months ago)
- Last Synced: 2025-09-06T04:36:19.731Z (6 months ago)
- Topics: ai, auto-tagging, cli, command-line-tool, generative-ai, github, github-topics, keyword-extraction, llm, machine-learning, natural-language-processing, openai, openai-api, python, python-package, semantic-analysis, tagging, text-classification, topic-generation, topic-modeling
- Language: Python
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# gh-topicgen
Automatically fills in all GitHub repository topics to the max using AI to guess which topics are the best.
> [!NOTE]
> Still rough around the edges, untested & lacks features.
## Why? đź§
I found myself wanting to fill each of my repos’ topics as much as I could, but it came at the cost of slowly and
sequentially thinking about what keywords to choose. So of course I will take hours of my time to shave off a few
seconds of creative thought.
## Brief 📦
A Python program that uses GitHub and OpenAI’s APIs, wiring them together to make an AI model generate a list of
topics (the tags/keywords you see on the repository page) based on the repo’s metadata:
i.e., title, description, existing tags, programming languages, and of course the contents of the legendary `README.md`
file.
## Behavior ⚙️
Final topics are ordered as: existing topics first, then AI-generated ones.
If you already have 5 topics, those five remain; the app only appends new topics until it reaches the maximum (`GithubConn.MAX_TOPIC_COUNT`). You can change this limit programmatically if you prefer to cap the list at N topics.
## Quickstart 🚀
> [!TIP]
> As we’ll be working with dotfiles (files beginning with a `.`), your file manager may not show them by default.
> For a better experience, enable “show hidden files”.
1. **Clone the repository and enter it.**
```bash
git clone https://github.com/Urpagin/gh-topicgen.git
cd gh-topicgen
```
2. **Before running, populate the two API tokens you’ll need.**
Copy the `.env.example` file to `.env` and follow the instructions inside.
```bash
cp .env.example .env
```
3.A **\[Linux/macOS] Create a Python virtual environment and activate it (optional).**
```bash
python3 -m venv .venv
source .venv/bin/activate
```
3.B **\[Windows] Create a Python virtual environment and activate it (optional).**
```bash
py -m venv .venv
.\.venv\Scripts\activate
```
4. **Install the app (editable mode).**
```bash
pip install -e .
```
5. **Run it to generate relevant topics for a repository.**
> [!CAUTION]
> For a first run, narrow changes to a single repository to try things out.
> Use `--regex`/`-r`, e.g. `ghtopicgen -v public -r 'Urpagin/slpcli'` to affect only the
> [Urpagin/slpcli](https://github.com/Urpagin/slpcli) repository.
> More info in the [Usage section](#usage).
```bash
ghtopicgen --visibility public --regex 'YourUserName/YourRepoTitle'
```
> [!TIP]
> If calling `ghtopicgen` doesn’t work, try:
> `python3 -m gh_topicgen `
To quickly get the hang of the app, skim the [Examples section](#examples--uses).
## Usage 🛠️
```text
$ python -m gh_topicgen -h
usage: ghtopicgen [-h] [--gh-token GH_TOKEN] [--openai-token OPENAI_TOKEN] [--model MODEL] [--prompt PROMPT] [--regex REGEX] [--ignore-case]
[--env-file PATH] [--no-input] [--take-my-money] --visibility {public,private,all}
Manage tokens/config.
optional arguments:
-h, --help show this help message and exit
--gh-token GH_TOKEN, -g GH_TOKEN
GitHub token (overrides env; aka GH_TOKEN)
--openai-token OPENAI_TOKEN, -o OPENAI_TOKEN
OpenAI token (overrides env; aka OPENAI_API_KEY)
--model MODEL, -m MODEL
Which OpenAI model to use (https://platform.openai.com/docs/models)
--prompt PROMPT, -p PROMPT
Path to AI system prompt file.
--regex REGEX, -r REGEX
Regex for repo names (matches against full_name, e.g., 'Urpagin/slpcli').
--ignore-case, -i Case-insensitive regex.
--env-file PATH, -e PATH
Path to .env to load first (default: auto-detect)
--no-input Do not prompt; fail if tokens are missing
--take-my-money Special model spec: GPT-5 Thinking with high effort. If set, any --model value is ignored.
--visibility {public,private,all}, -v {public,private,all}
What type of repositories to use.
```
## Examples / Uses đź’ˇ
Used to generate this repo’s topics:
```bash
ghtopicgen -v public -m gpt-5 -r 'Urpagin/gh-topicgen'
```
Generate the topics of **all** your repos (private + public) using the best model currently:
```bash
ghtopicgen -v all --take-my-money
```
Generate the topics of **all** your repos using the fastest and cheapest model (default model):
```bash
ghtopicgen -v all -m gpt-5-nano
```
## AI Instructions 🤖
The system prompt given to the model is stored in `system_prompt.txt`.
Feel free to tweak it as you wish.
## Compatibility 🧪
Made with compatibility in mind, avoiding highly modern 3.11/3.12-only features.
Compatible with **Python ≥ 3.9**.
```bash
$ vermin --no-tips src/gh_topicgen/*
Minimum required versions: 3.9
Incompatible versions: 2
```
## Acknowledgements 🙏
* [The PyGithub library](https://github.com/pygithub/pygithub) — interacting with the GitHub REST API
* [The official OpenAI Python library](https://github.com/openai/openai-python) — interacting with the OpenAI REST API
## License đź“„
Every file in the repository falls under the MIT License.
MIT © 2025 Urpagin.