Metadata-Version: 2.4
Name: commitlm
Version: 1.0.5
Summary: AI-powered Git Documentation & Commit Messages
Author-email: Sin Liang Lee <sinlianglee110@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/LeeSinLiang/commitLM
Project-URL: Repository, https://github.com/LeeSinLiang/commitLM
Project-URL: Issues, https://github.com/LeeSinLiang/commitLM/issues
Project-URL: Changelog, https://github.com/LeeSinLiang/commitLM/releases
Keywords: git,commit,documentation,ai,llm,automation,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: gitpython
Requires-Dist: transformers>=4.35.0
Requires-Dist: torch>=2.0.0
Requires-Dist: accelerate
Requires-Dist: optimum[cpu]
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: jinja2
Requires-Dist: rich
Requires-Dist: python-dotenv
Requires-Dist: watchdog
Requires-Dist: google-genai
Requires-Dist: google-api-core
Requires-Dist: anthropic
Requires-Dist: openai
Requires-Dist: InquirerPy
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# CommitLM — AI-powered Git Documentation & Commit Messages

**Automated Documentation and Commit Message Generation for Every Git Commit**

CommitLM is an AI-native tool that automatically generates comprehensive documentation for your code changes and creates conventional commit messages. It integrates seamlessly with Git through hooks to analyze your changes and provide intelligent documentation and commit messages, streamlining your workflow and improving your project's maintainability.

## Features

### Core Capabilities
- **📝 Automatic Commit Messages**: AI-generated conventional commit messages via `prepare-commit-msg` hook
- **📚 Automatic Documentation**: Comprehensive docs generated after every commit via `post-commit` hook
- **🎯 Task-Specific Models**: Use different models for commit messages vs documentation generation
- **📁 Organized Documentation**: All docs saved in `docs/` folder with timestamps and commit hashes

### Multi-Provider Support
- **☁️ Cloud APIs**: Google Gemini, Anthropic Claude, OpenAI GPT support
- **🏠 Local Models**: HuggingFace models (Qwen2.5-Coder, Phi-3, TinyLlama) - no API keys required
- **🔄 Fallback Options**: Configure fallback to local models if API fails
- **⚙️ Flexible Configuration**: Mix and match providers for different tasks

### Performance & Optimization
- **⚡ GPU/CPU Auto-detection**: Automatically uses NVIDIA GPU, Apple Silicon, or CPU
- **💾 Memory Optimization**: Toggleable 8-bit quantization for systems with limited RAM
- **🎯 Extended Context**: YaRN support for Qwen models (up to 131K tokens)

## Quick Start

### 1. Clone and Install

```bash
git clone <repository-url>
cd commitlm
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
```

### 2. Initialize Configuration

```bash
# Interactive setup (recommended) - guides you through provider, model, and task selection
commitlm init

# Setup with specific provider and model
commitlm init --provider gemini --model gemini-2.0-flash-exp
commitlm init --provider anthropic --model claude-3-5-haiku-latest
commitlm init --provider openai --model gpt-4o-mini
commitlm init --provider huggingface --model qwen2.5-coder-1.5b
```

#### Interactive Setup Flow

When you run `commitlm init`, you'll be guided through:

1. **Provider Selection**: Choose between local (HuggingFace) or cloud (Gemini, Anthropic, OpenAI)
2. **Model Selection**: Pick from provider-specific models
3. **Task Configuration**: Enable commit messages, documentation, or both
4. **Task-Specific Models** (optional): Use different models for different tasks
5. **Fallback Configuration**: Set up fallback to local models if API fails

Example interactive session:
```
? Select LLM provider › gemini
? Select model › gemini-2.0-flash-exp
? Which tasks do you want to enable? › both
? Do you want to use different models for specific tasks? › Yes
  ? Select provider for commit_message › huggingface
  ? Select model › qwen2.5-coder-1.5b
? Enable fallback to a local model if the API fails? › Yes
```

#### Provider Options

**Local Models (HuggingFace)** - No API keys required:
- `qwen2.5-coder-1.5b` - **Recommended** - Best performance/speed ratio, YaRN support (1.5B params)
- `phi-3-mini-128k` - Long context (128K tokens), excellent for large diffs (3.8B params)
- `tinyllama` - Minimal resource usage (1.1B params)

**Cloud APIs** - Faster, more capable:
- **Gemini**: `gemini-2.0-flash-exp`, `gemini-1.5-pro`, `gemini-1.5-flash` (requires `GEMINI_API_KEY`)
- **Anthropic**: `claude-3-5-sonnet-latest`, `claude-3-5-haiku-latest` (requires `ANTHROPIC_API_KEY`)
- **OpenAI**: `gpt-4o`, `gpt-4o-mini` (requires `OPENAI_API_KEY`)

### 3. Install Git Hooks

CommitLM provides two powerful git hooks:

```bash
# Install both hooks (recommended)
commitlm install-hook

# Install only commit message generation
commitlm install-hook message

# Install only documentation generation
commitlm install-hook docs
```

**What each hook does**:

**`prepare-commit-msg` hook** (Commit Messages):
1. Runs before commit editor opens
2. Analyzes staged changes (`git diff --cached`)
3. Generates conventional commit message
4. Pre-fills commit message in editor

**`post-commit` hook** (Documentation):
1. Runs after commit completes
2. Extracts commit diff
3. Generates comprehensive documentation
4. Saves to `docs/commit_<hash>_<timestamp>.md`

Example workflow:
```bash
# Make your code changes
git add .

# Option 1: Use hook to generate message
git commit
# Editor opens with AI-generated message pre-filled
# Edit if needed, save and close

# Option 2: Use git alias (see below)
git c  # Stages, generates message, commits in one step

# Documentation is automatically generated after commit completes
# docs/commit_abc1234_2025-01-15_14-30-25.md
```

#### Alternative: Git Alias Workflow

Set up a convenient git alias for one-command commits:

```bash
commitlm set-alias
# Creates 'git c' alias (or custom name)

# Now use it:
git add .
git c  # Automatically generates message and commits
```

### 4. Validate Setup

```bash
# View configuration and hardware info
commitlm status
```

## System Requirements

### Minimum Requirements
- Python 3.9+
- 4GB RAM (with memory optimization enabled)
- 2GB disk space (for model downloads)

### Recommended Requirements  
- Python 3.10+
- 8GB+ RAM
- NVIDIA GPU with 4GB+ VRAM (optional, auto-detected)
- SSD storage

## Configuration

### Environment Variables

Set API keys for cloud providers:

```bash
# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GEMINI_API_KEY="your-gemini-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export OPENAI_API_KEY="your-openai-api-key"
```

### Task-Specific Models

Use different models for different tasks:

```bash
# Enable task-specific models during init
commitlm init
# Select "Yes" when prompted "Do you want to use different models for specific tasks?"

# Or configure later
commitlm enable-task

# Change model for specific task
commitlm config change-model commit_message
commitlm config change-model doc_generation
```

**Example use case**: Use fast local model (Qwen) for commit messages, powerful cloud API (Claude) for documentation.

### Configuration File

Configuration is stored in `.commitlm-config.json` at your git repository root:

```json
{
  "provider": "gemini",
  "model": "gemini-2.0-flash-exp",
  "commit_message_enabled": true,
  "doc_generation_enabled": true,
  "commit_message": {
    "provider": "huggingface",
    "model": "qwen2.5-coder-1.5b"
  },
  "doc_generation": {
    "provider": "gemini",
    "model": "gemini-1.5-pro"
  },
  "fallback_to_local": true
}
```

## Hardware Support (Local Models)

When using HuggingFace local models, the tool automatically detects and uses the best available hardware:

1. **NVIDIA GPU** (CUDA) - Uses GPU acceleration with `device_map="auto"`
2. **Apple Silicon** (MPS) - Uses Apple's Metal Performance Shaders
3. **CPU** - Falls back to optimized CPU inference

### Memory Optimization

Memory optimization is **enabled by default** for local models and includes:
- 8-bit quantization (reduces memory by ~50%)
- float16 precision
- Automatic model sharding

Disable for better quality (requires more RAM):
```bash
commitlm init --provider huggingface --no-memory-optimization
```

## Usage Examples

### Using Commit Message Hook

```bash
# Make changes
echo "def new_feature(): pass" >> src/app.py
git add .

# Commit without message - hook generates it
git commit
# Editor opens with pre-filled message:
# feat(app): add new feature function

# Review, edit if needed, save and close
```

### Using Git Alias

```bash
# Set up alias once
commitlm set-alias

# Use it for every commit
git add .
git c  # Generates message and commits automatically
```

### Using Documentation Hook

After installing the `post-commit` hook:

```bash
# Make changes
echo "console.log('new feature')" >> src/app.js
git add .
git commit -m "feat: add logging feature"

# Documentation automatically generated at:
# docs/commit_a1b2c3d_2025-01-15_14-30-25.md
```

### Manual Generation (Testing/Debugging)

```bash
# Test documentation generation with sample diff
commitlm generate "fix: resolve memory leak
- Fixed session cleanup
- Added event listener removal"

# Test commit message generation
echo "function test() {}" > test.js
git add test.js
commitlm generate --short-message

# Use specific provider/model for testing
commitlm generate --provider gemini --model gemini-2.0-flash-exp "your diff here"
```

### Advanced: YaRN Extended Context (Local Models)

For HuggingFace Qwen models, YaRN enables extended context lengths:

```bash
# Enable YaRN during initialization
commitlm init --provider huggingface --model qwen2.5-coder-1.5b --enable-yarn

# YaRN with memory optimization (64K context)
commitlm init --provider huggingface --model qwen2.5-coder-1.5b --enable-yarn --memory-optimization

# YaRN with full performance (131K context)
commitlm init --provider huggingface --model qwen2.5-coder-1.5b --enable-yarn --no-memory-optimization
```

**YaRN Benefits:**
- Extended context up to 131K tokens (vs 32K default)
- Better handling of large git diffs without truncation
- Automatic scaling based on memory optimization settings

## Commands

### Primary Commands

| Command | Description |
| --- | --- |
| `commitlm init` | Initializes the project with an interactive setup guide. |
| `commitlm install-hook` | Installs the Git hooks for automation. |
| `commitlm status` | Shows the current configuration and hardware status. |
| `commitlm validate` | Validates the configuration and tests the LLM connection. |

### Secondary Commands

| Command | Description |
| --- | --- |
| `commitlm generate` | Manually generate a commit message or documentation. |
| `commitlm uninstall-hook` | Removes the Git hooks. |
| `commitlm set-alias` | Sets up a Git alias for easier commit message generation. |
| `commitlm config get [KEY]` | Gets a configuration value. |
| `commitlm config set <KEY> <VALUE>` | Sets a configuration value. |
| `commitlm config change-model <TASK>` | Changes the model for a specific task. |
| `commitlm enable-task` | Enables or disables tasks. |

## Troubleshooting

### API Key Issues
```bash
# Verify environment variables are set
echo $GEMINI_API_KEY
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

# Add to shell profile if missing
export GEMINI_API_KEY="your-key-here"
```

### Model Download Issues (Local Models)
Models are downloaded automatically on first use to `~/.cache/huggingface/`. Ensure you have internet connection and sufficient disk space.

### Memory Errors (Local Models)
```bash
# Enable memory optimization (default)
commitlm init --provider huggingface --memory-optimization

# Try a smaller model
commitlm init --provider huggingface --model tinyllama

# Or switch to cloud API
commitlm init --provider gemini
```

### Performance Issues (Local Models)
```bash
# Check hardware detection
commitlm status

# Disable memory optimization for better quality
commitlm init --provider huggingface --no-memory-optimization

# Switch to cloud API for faster generation
commitlm config change-model default
# Select cloud provider (Gemini/Anthropic/OpenAI)
```

### Hook Not Working
```bash
# Verify hooks are installed
ls -la .git/hooks/

# Reinstall hooks
commitlm install-hook --force

# Check which tasks are enabled
commitlm config get commit_message_enabled
commitlm config get doc_generation_enabled

# Enable/disable tasks
commitlm enable-task
```

### CUDA/GPU Issues (Local Models)
```bash
# Check GPU detection
commitlm status

# Force CPU usage if GPU causes issues
# Edit .commitlm-config.json and set "device": "cpu"
```
