ikomet 0.1.1__tar.gz

ikomet-0.1.1/PKG-INFO

@@ -0,0 +1,250 @@
+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**

ikomet-0.1.1/README.md

@@ -0,0 +1,230 @@
+# 🚀 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**

ikomet-0.1.1/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "ikomet"
+version = "0.1.1"
+description = "AI-powered Conventional Commit message generator using your staged changes"
+authors = ["ajabri  <abdelalijabri76@gmail.com>"]
+readme = "README.md"
+packages = [{include = "komet", from = "src"}]
+homepage = "https://github.com/ajabrii/Komet"
+repository = "https://github.com/ajabrii/Komet"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+typer = {extras = ["all"], version = "^0.12.0"}
+gitpython = "^3.1.43"
+groq = "^1.0.0"
+
+[tool.poetry.scripts]
+komet = "komet.main:app"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

ikomet-0.1.1/src/komet/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ikomet-0.1.1/src/komet/main.py

@@ -0,0 +1,161 @@
+# src/komet/main.py
+
+import os
+import sys
+from pathlib import Path
+
+import git                         # GitPython library to interact with git
+from groq import Groq               # Official Groq SDK for calling their API
+import typer                        # Modern, beautiful CLI framework (like Click but nicer)
+
+# Create the main Typer application
+# name="komet"   → the command will be called "komet"
+# help=...       → shown when user runs: komet --help
+app = typer.Typer(
+    name="komet",
+    help="Generate a Conventional Commit message from staged changes using Groq LLM",
+    add_completion=False,           # disables shell completion (we don't need it yet)
+)
+
+
+def get_staged_diff() -> str:
+    """
+    Read the staged changes (what `git diff --cached` would show).
+    Returns the diff as string or exits with error message.
+    """
+    # Try to open the current directory (or parent) as git repo
+    try:
+        repo = git.Repo(Path.cwd(), search_parent_directories=True)
+    except git.InvalidGitRepositoryError:
+        typer.secho("Error: Not inside a git repository.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    # Check if there are actually staged changes
+    if not repo.is_dirty(index=True):           # index=True → checks staged area
+        typer.secho("No staged changes found.", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=0)
+
+    # Get the actual diff of staged files
+    diff = repo.git.diff("--cached")            # same as: git diff --cached
+
+    # Safety: if somehow diff is empty
+    if not diff.strip():
+        typer.secho("Staged changes are empty.", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=0)
+
+    # Optional: prevent sending huge diffs (Groq has large context, but still good practice)
+    MAX_DIFF_CHARS = 15000
+    if len(diff) > MAX_DIFF_CHARS:
+        diff = diff[:MAX_DIFF_CHARS] + "\n\n# ... (diff was truncated to fit context)"
+
+    return diff
+
+
+def generate_commit_message(diff_text: str, api_key: str) -> str:
+    """
+    Send the diff to Groq LLM and ask it to create a Conventional Commit message.
+    Returns only the generated message string.
+    """
+    client = Groq(api_key=api_key)
+
+    # This is the most important part — controls quality a lot
+    system_prompt = """You are a senior software engineer who writes **perfect, team-friendly Conventional Commits** every time.
+
+MANDATORY RULES — follow exactly or the output is invalid:
+
+1. Type must be one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+2. Add scope in (parentheses) when it adds clarity (db, api, auth, ui, cli, config, tests, …)
+3. Subject line: imperative mood ("add feature", "fix bug", "refactor class") — NEVER past tense
+4. Subject line length: maximum 72 characters (including type and scope)
+5. No period at the end of the subject line
+6. If the change affects public API / breaks compatibility → add footer: BREAKING CHANGE: one sentence explanation
+7. Optional body: after one blank line — explain WHAT changed and WHY (keep under 4 lines)
+8. Use bullet points in body only if it really helps readability
+9. Never include:
+   - Emojis
+   - Markdown formatting
+   - ``` fences
+   - Explanations outside the message
+   - "Here is the commit message:"
+10. Output **ONLY** the final commit message — nothing else
+
+Few perfect examples:
+
+feat: add password reset flow
+fix: correct JWT token validation on refresh
+
+docs(readme): update installation instructions with poetry commands
+
+refactor(cli): extract diff parsing to separate function
+    - Improves testability
+    - Reduces main.py complexity
+
+BREAKING CHANGE: removed deprecated --old-flag option
+
+Your turn — analyze the diff and create the message.
+"""
+
+    user_prompt = f"""Analyze these staged code changes and write the commit message:
+
+{diff_text}
+"""
+
+    try:
+        response = client.chat.completions.create(
+            model="llama-3.3-70b-versatile",          # good balance of quality & speed on Groq
+            # model="mixtral-8x7b-32768",             # cheaper & still very good
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user",   "content": user_prompt},
+            ],
+            temperature=0.15,           # low = more consistent & deterministic
+            max_tokens=180,             # enough for message + body
+            top_p=0.9,
+        )
+
+        message = response.choices[0].message.content.strip()
+        return message
+
+    except Exception as e:
+        typer.secho(f"Groq API error: {str(e)}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def main():
+    """
+    Main command — called when user just types: komet
+    """
+    # Get Groq API key from environment (most secure & common way)
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        typer.secho(
+            "Error: GROQ_API_KEY environment variable is not set.\n"
+            "Get your key at: https://console.groq.com/keys\n"
+            "Then run: export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx",
+            fg=typer.colors.RED,
+            err=True
+        )
+        raise typer.Exit(code=1)
+
+    # 1. Read staged changes
+    diff = get_staged_diff()
+
+    # 2. Ask LLM to generate message
+    message = generate_commit_message(diff, api_key)
+
+    # 3. Print nicely
+    typer.echo("\nSuggested commit message:\n")
+    typer.secho(message, fg=typer.colors.GREEN, bold=True)
+    typer.echo("\nUse it like this:")
+    typer.echo(f"  git commit -m '{message.splitlines()[0]}'")
+    # If message has body → show full multi-line version
+    if "\n" in message:
+        typer.echo("\nFull version:")
+        typer.echo(message)
+
+
+if __name__ == "__main__":
+    # This makes the script runnable directly: python -m komet
+    # But normally you'll run it via poetry run komet or after pipx install
+    app()