ikomet 0.1.2
AI-powered Conventional Commit message generator using your staged changes
Requires Python: <4.0,>=3.10

# 🚀 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](https://www.conventionalcommits.org/) formatted commit messages from your staged git changes. Say goodbye to bland commit messages and hello to consistent, meaningful version control history.

[![PyPI](https://img.shields.io/pypi/v/ikomet)](https://pypi.org/project/ikomet/)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Poetry](https://img.shields.io/badge/poetry-dependency%20management-blueviolet)](https://python-poetry.org/)
[![Groq](https://img.shields.io/badge/powered%20by-Groq%20LLM-orange)](https://groq.com/)

---

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

```bash
# 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
- Git repository
- Groq API key ([Get it here](https://console.groq.com/keys))

### Quick Install from PyPI (Recommended)

Install globally using **pipx** (recommended for CLI tools):

```bash
# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install ikomet
pipx install ikomet

# Now use it anywhere!
komet
```

Or install with **pip**:

```bash
pip install ikomet
```

### Install from Source

For development or contributing:

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

# Install with poetry
poetry install

# Run Komet
poetry run komet
```

---

## 📖 Usage

### Basic Workflow

1. **Stage your changes** as usual:
   ```bash
   git add <files>
   ```

2. **Run Komet**:
   ```bash
   komet
   ```

3. **Copy and commit** with the suggested message:
   ```bashGet yours for free at [console.groq.com/keys](https://console.groq.com/keys).

Set it up once:

```bash
# Linux/macOS - Temporary (current session only)
export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx

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

# Windows (PowerShell)
$env:GROQ_API_KEY="gq_xxxxxxxxxxxxxxxx"

# Windows - Permanent (System Environment Variables)
setx GROQ_API_KEY "gq_xxxxxxxxxxxxxxxx"
# 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](src/komet/main.py#L79) 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](src/komet/main.py#L42).

---

## 🤝 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](LICENSE).

---

## 👤 Author

**Abdelali Jabri**
- LinkedIn: [Linkedin](https://www.linkedin.com/in/abdelali-jabri-51729b2b0/)
- GitHub: [@ajabrii](https://github.com/ajabrii)
- Email: abdelalijabri76@gmail.com

---

## 🙏 Acknowledgments

- [Conventional Commits](https://www.conventionalcommits.org/) - For the commit message specification
- [Groq](https://groq.com/) - For providing lightning-fast LLM inference
- [Typer](https://typer.tiangolo.com/) - 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**