ikomet 0.1.1

AI-powered Conventional Commit message generator using your staged changes

🚀 Komet

AI-Powered Conventional Commit Message Generator

Komet is a smart CLI tool that leverages Groq's LLM API to automatically generate professional, Conventional Commits formatted commit messages from your staged git changes. Say goodbye to bland commit messages and hello to consistent, meaningful version control history.

---

✨ Features

• 🤖 AI-Powered Analysis: Uses Groq's fast LLM (Llama 3.3 70B) to understand your code changes
• 📝 Conventional Commits: Automatically follows industry-standard commit message format
• ⚡ Lightning Fast: Groq's infrastructure provides near-instant responses
• 🎯 Context-Aware: Analyzes actual git diffs to generate accurate, meaningful messages
• 🛡️ Safe & Smart: Truncates large diffs, validates git repos, and handles edge cases gracefully
• 🎨 Beautiful CLI: Built with Typer for a modern, user-friendly command-line experience

---

🎬 Demo

# Stage your changes
$ git add src/komet/main.py

# Let Komet generate the commit message
$ komet

Suggested commit message:

feat(main): add automatic diff truncation for large changesets

Use it like this:
  git commit -m 'feat(main): add automatic diff truncation for large changesets'

---

🚀 Installation

Prerequisites

• Python 3.10 or higher
• Poetry (Python dependency management)
• Git repository
• Groq API key (Get it here)

Install via Poetry

# Clone the repository
git clone https://github.com/ajabrii/Komet.git
cd Komet

# Install dependencies
poetry install

# Set your Groq API key
export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx

# Run Komet
poetry run komet

Install as Global Command

# Install with pipx (recommended)
pipx install .

# Or install globally with poetry
poetry build
pip install dist/komet-0.1.0-py3-none-any.whl

# Now use it anywhere
komet

---

📖 Usage

Basic Workflow

1. Stage your changes as usual:

   git add <files>
   

2. Run Komet:

   komet
   

3. Copy and commit with the suggested message:

   git commit -m '<generated-message>'
   

Environment Setup

Komet requires a Groq API key. Set it up once:

# Temporary (current session only)
export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx

# Permanent (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
echo 'export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

---

🏗️ How It Works

1. Git Diff Extraction: Komet uses GitPython to read your staged changes (git diff --cached)
2. Context Preparation: The diff is sent to Groq's LLM with a carefully crafted system prompt
3. AI Analysis: The LLM analyzes the code changes and generates a Conventional Commit message
4. Formatted Output: The result is displayed with usage instructions

Conventional Commit Format

Komet generates messages following this structure:

<type>(<optional-scope>): <short-description>

<optional-body>

<optional-footer>

Supported types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

---

🛠️ Technology Stack

Technology	Purpose
Python 3.10+	Core programming language
Poetry	Dependency management and packaging
Typer	Modern CLI framework with beautiful output
GitPython	Git repository interaction
Groq SDK	LLM API integration (Llama 3.3 70B)

---

📁 Project Structure

Komet/
├── src/
│   └── komet/
│       ├── __init__.py          # Package initialization
│       └── main.py              # Core application logic
├── pyproject.toml               # Poetry configuration & dependencies
└── README.md                    # Project documentation

---

🔧 Configuration

Model Selection

Komet uses llama-3.3-70b-versatile by default. You can modify main.py to use other Groq models:

• llama-3.3-70b-versatile - Best quality & speed balance (default)
• mixtral-8x7b-32768 - Cheaper alternative, still excellent quality

Diff Size Limits

Large diffs are automatically truncated to 15,000 characters to fit within LLM context windows. Adjust in main.py.

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is open source and available under the MIT License.

---

👤 Author

Abdelali Jabri

• LinkedIn: Linkedin
• GitHub: @ajabrii
• Email: [e-mail]

---

🙏 Acknowledgments

• Conventional Commits - For the commit message specification
• Groq - For providing lightning-fast LLM inference
• Typer - For the excellent CLI framework

---

🌟 Why Komet?

In professional software development, clear commit history is crucial for:

• Code Reviews: Understanding what changed and why
• Debugging: Using git bisect to find when bugs were introduced
• Documentation: Auto-generating changelogs from commits
• Team Collaboration: Maintaining consistency across team members

Komet automates best practices, ensuring every commit tells a clear story.

---

Made with ❤️ by Abdelali Jabri