AVCMT-PY - AI-Powered Semantic Release Style Git Commit Automation for Python Projects

Tired of manually crafting Git commit messages? Supercharge your Python development workflow with avcmt-py, the intelligent CLI tool that automates semantic, structured commit message generation using AI. Boost productivity and maintain a crystal-clear repository history effortlessly.

TL;DR: AI-powered, semantic-release-style git commit automation for Python projects. One command, zero guesswork: meaningful, structured commits using your Pollinations AI API Token. Install, configure your API key, and enjoy never writing boring commit messages again!

🚀 What is avcmt-py?

AVCMT-PY (Automated Version Control & Management Tool for Python) is a blazing-fast, fully-automated CLI tool for generating meaningful, structured git commit messages using AI (Gemini, OpenAI, Pollinations, etc) — optimized for Python developers who want clean semantic-release workflow, better productivity, and crystal-clear repo history.

• No more generic "fix bug", "update code" commits.
• Just run avcmt and get a ready-to-commit, semantic-release-formatted message, automatically grouped by directory or file.
• Integrates with pre-commit, CI/CD, and release workflows.
• Flexible AI provider: choose your favorite (support for Gemini, Pollinations, OpenAI out-of-the-box).

✨ Features

• AI-Powered Commit Messages: Generate detailed, semantic-release-style commit messages from git diff with a single command.

• Directory Grouping: Automatically groups and commits related changes per directory (or as a catch-all).

• Semantic Release Ready: Commit format fully compatible with semantic-release for auto versioning & changelogs.

• Multi-Provider AI: Easily switch between Gemini, Pollinations, OpenAI (or extend to your own LLM API).

• Jinja2 Prompt Templates: Fully customizable prompt rendering using Jinja2 templates for flexible commit messaging.

• Zero Hardcoded Secrets: API keys are loaded from .env or environment variables.

• Easy to Install, Easy to Use: Works on any Python project, no lock-in.

• Developer Tools Included: Scripts for linting, formatting, preflight check, and triggering semantic release.

• Pre-commit & CI/CD Friendly: Fully integrated with pre-commit and GitHub Actions for automated workflows.

📦 Installation

pip install avcmt-py

Or install from source:

git clone https://github.com/andyvandaric/avcmt-py.git
cd avcmt-py
pip install .

⚡️ Quick Start (TL;DR)

1. Add your API key

   • Copy .env.example to .env

   • Edit .env and fill your Pollinations or OpenAI API key

   # Example (.env)
   OPENAI_API_KEY=your_openai_token
   POLLINATIONS_TOKEN=your_pollinations_token

2. (Optional) Enable pre-commit hook:

   pre-commit install
   

3. Run avcmt:

   avcmt           # AI generates & applies grouped commits!

   • Optionally use:

     • --dry-run (preview messages)

     • --push (auto-push after commit)

     • --debug (show AI prompts & raw response)

4. Done!

   • Check your git log for clean, structured, semantic-release-ready commit messages.

🛠️ Usage

avcmt [OPTIONS]

• --dry-run : Preview commit messages without applying

• --push : Push commits to remote after done

• --debug : Show debug info (prompts & AI response)

Example

avcmt --dry-run
avcmt --push

🔒 Environment & Configuration

• Place .env in your project root (or set env vars globally)

• Supported ENV:

  • POLLINATIONS_API_TOKEN

  • (other providers: applied next update)

📦 Project Structure (avcmt-py/)

avcmt-py/
├── .env.example
├── .github/
│   └── workflows/
│       ├── pre-commit.yml
│       └── release.yaml
├── .gitignore
├── .pre-commit-config.yaml
├── CHANGELOG.md
├── LICENSE
├── README.md
├── pyproject.toml
├── avcmt/
│   ├── __init__.py
│   ├── ai.py
│   ├── cli.py
│   ├── commit.py
│   ├── utils.py
│   ├── prompt_templates/
│   │   └── commit_message.j2
│   └── providers/
│       ├── __init__.py
│       ├── openai.py
│       └── pollinations.py
├── scripts/
│   ├── check.py
│   ├── clean.py
│   ├── format.py
│   ├── helper.py
│   ├── lintfix.py
│   ├── preflight.py
│   ├── semrel.py
│   └── setup.py
└── setup.cfg

✨ File Descriptions

• avcmt/cli.py --- CLI entry point, handles argument parsing and triggers auto-commit.

• avcmt/commit.py --- Core logic for grouping, git interaction, and structured AI commit message generation.

• avcmt/ai.py --- Manages prompt rendering and request to the AI provider (Jinja2-powered).

• avcmt/utils.py --- Helper functions for environment, logging, and file operations.

• avcmt/__init__.py --- Marks the core package.

• avcmt/prompt_templates/commit_message.j2 --- Jinja2 template for AI commit prompt.

• avcmt/providers/openai.py --- Adapter for OpenAI API.

• avcmt/providers/pollinations.py --- Adapter for Pollinations API.

• avcmt/providers/__init__.py --- Provider interface loader.

• scripts/check.py --- Run validation checks on repo status.

• scripts/clean.py --- Optional cleanup utility.

• scripts/format.py --- Format code using Ruff or Black.

• scripts/helper.py --- Shared utilities across scripts.

• scripts/lintfix.py --- Lint and auto-fix with Ruff.

• scripts/preflight.py --- Pre-commit safety check runner.

• scripts/semrel.py --- Trigger python-semantic-release publish process.

• scripts/setup.py --- One-shot setup script for dev environment.

• .env.example --- Environment file template. Copy to .env and fill your token.

• .pre-commit-config.yaml --- Pre-commit hook configuration.

• .gitignore --- Ignore compiled files, .env, cache, etc.

• pyproject.toml --- Project metadata and dependency configuration.

• setup.cfg --- Optional setup file for tools compatibility.

• README.md --- Full project description and usage.

• LICENSE --- MIT License.

• CHANGELOG.md --- Auto-generated changelog via semantic release.

• .github/workflows/release.yaml --- CI workflow for auto versioning and publishing.

• .github/workflows/pre-commit.yaml --- CI pre-commit hook runner.

🧩 Advanced

• Custom AI Providers: See avcmt/ai.py to extend with your own LLM API.

• Integration with pre-commit: Works out-of-the-box, can be called in hooks or CI.

• Full CLI options: Run avcmt --help for all flags.

📚 FAQ

Q: Will this overwrite my changes or commit everything automatically? A: No, only staged files are affected. You're always in control.

Q: Can I use it for monorepos? A: Yes, directory grouping is automatic, but fully configurable.

Q: What if my provider's API token is missing or invalid? A: You'll see a clear error and nothing will be committed.

Q: Is it safe for public/private repos? A: Yes, no token or diff is ever sent to any server except the AI you choose.

🌟 Why avcmt-py?

• ✨ Stop wasting time on commit messages

• ✨ Zero learning curve, drop-in to any Python repo

• ✨ Works everywhere: CLI, hook, CI/CD, local/dev/remote

• ✨ Your AI, your rules: bring your own API key, use any LLM

🔗 Links

• GitHub

• PyPI

📝 License

Apache 2.0 Made by Andy Vandaric

👏 Credits

• Inspired by semantic-release, and real-life productivity pain points.

• Powered by Pollinations AI.