Metadata-Version: 2.4
Name: ikomet
Version: 0.1.1
Summary: AI-powered Conventional Commit message generator using your staged changes
Author: ajabri 
Author-email: abdelalijabri76@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: gitpython (>=3.1.43,<4.0.0)
Requires-Dist: groq (>=1.0.0,<2.0.0)
Requires-Dist: typer[all] (>=0.12.0,<0.13.0)
Project-URL: Homepage, https://github.com/ajabrii/Komet
Project-URL: Repository, https://github.com/ajabrii/Komet
Description-Content-Type: text/markdown

# 🚀 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.

[![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
- Poetry (Python dependency management)
- Git repository
- Groq API key ([Get it here](https://console.groq.com/keys))

### Install via Poetry

```bash
# 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

```bash
# 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:
   ```bash
   git add <files>
   ```

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

3. **Copy and commit** with the suggested message:
   ```bash
   git commit -m '<generated-message>'
   ```

### Environment Setup

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

```bash
# 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**
