Metadata-Version: 2.4
Name: smart-commit-cli
Version: 0.1.0
Summary: AI-powered Git commit automation
Author: Smart Commit Contributors
License: MIT
Keywords: ai,automation,commit,conventional-commits,git,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Requires-Dist: gitpython>=3.1.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: networkx>=3.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: typer[all]>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.0.100; extra == 'dev'
Description-Content-Type: text/markdown

# Smart Commit v2

**The equivalent of Prettier for Git history**

Stop thinking about staging files, commit boundaries, and writing messages. Smart Commit analyzes your changes, proposes logical commits, and lets you review before executing.

![Smart Commit Preview](https://via.placeholder.com/800x400?text=Smart+Commit+Preview)

## Vision

```
Your Changes
    ↓
Smart Commit Analysis
    ↓
Logical Commit Groups
    ↓
High-Quality Messages
    ↓
Your Review
    ↓
Perfect Git History
```

## Features

- **🤖 AI-Powered Grouping**: Uses embeddings and ML to understand which files belong together
- **📝 Automatic Messages**: Generates Conventional Commits without manual writing
- **👁️ Interactive Preview**: Review all proposed commits before executing
- **🔄 Multi-Provider LLM**: Works with OpenRouter, OpenAI, Anthropic, Gemini, Groq, Azure, and more
- **⚡ Local Embeddings**: Uses efficient local embeddings for semantic analysis
- **🔐 Safety First**: Never modifies history without approval
- **↩️ Undo Support**: Easily revert the last Smart Commit session
- **🧩 Plugin System**: Extensible architecture with language-specific plugins
- **⚙️ Offline Mode**: Works without LLM for pure ML-based clustering
- **🎯 Conventional Commits**: Automatic type detection (feat, fix, docs, etc.)

## Installation

### Requirements
- Python 3.12+
- Git

### From PyPI (Coming Soon)

```bash
pip install smart-commit
```

### From Source

```bash
git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
pip install -e .
```

## Quick Start

### 1. Initialize

```bash
smart-commit init
```

### 2. Configure LLM (Optional)

```bash
smart-commit config --provider openrouter --model anthropic/claude-sonnet --api-key YOUR_KEY
```

Or set environment variables:

```bash
export SMART_COMMIT_PROVIDER=openrouter
export SMART_COMMIT_MODEL=anthropic/claude-sonnet
export SMART_COMMIT_API_KEY=your-api-key
```

### 3. Run

```bash
smart-commit run
```

## Pipeline

Smart Commit processes changes through 10 stages:

```mermaid
flowchart TD
    A["🔍 Git Status"] --> B["📋 Read Diffs"]
    B --> C["🔎 Static Analysis"]
    C --> D["🌳 AST Analysis"]
    D --> E["📝 Summaries"]
    E --> F["🧠 Embeddings"]
    F --> G["🔗 Similarity Graph"]
    G --> H["🎯 Semantic Clustering"]
    H --> I["✨ LLM Review"]
    I --> J["💬 Commit Messages"]
    J --> K["👁️ Preview UI"]
    K --> L["✅ Git Commit"]
    
    style A fill:#e1f5ff
    style H fill:#f3e5f5
    style I fill:#fff3e0
    style L fill:#e8f5e9
```

## Commands

```bash
# Analyze and create commits
smart-commit run

# Preview without executing
smart-commit preview

# Undo last session
smart-commit undo

# Show configuration
smart-commit config --show

# Diagnostic checks
smart-commit doctor

# List plugins
smart-commit plugins

# Show version
smart-commit version
```

### Advanced Options

```bash
smart-commit run --yes              # Skip confirmation
smart-commit run --dry-run          # Preview only
smart-commit run --no-ai            # Disable LLM
smart-commit run --offline          # Use only local analysis
smart-commit run --model gpt-4      # Override model
smart-commit run --provider openai  # Override provider
```

## Configuration

Smart Commit looks for configuration in this order:

1. **CLI Options** (`--model`, `--provider`)
2. **Environment Variables** (`SMART_COMMIT_*`)
3. **Configuration File** (`~/.smart_commit/config.yaml`)
4. **Defaults**

### Example config.yaml

```yaml
# LLM Settings
provider: openrouter
model: anthropic/claude-sonnet
api_key: your-api-key

# Embedding
embedding_model: all-MiniLM-L6-v2

# Clustering
clustering_method: agglomerative
similarity_threshold: 0.5
max_files_per_commit: 8

# Behavior
interactive: true
auto_push: false
conventional_commits: true
use_local_embeddings: true
```

## Safety & Trust

### Safety Features

- ✅ **Never** modifies history without approval
- ✅ **Always** shows preview before executing
- ✅ **Always** supports undo with `smart-commit undo`
- ✅ **Validates** all file paths and commit messages
- ✅ **Warns** about protected branches (main, master, production)

### Preview Example

```
Commit 1
feat(auth): improve login validation and session handling
Files: 3
  ✏️ src/auth/login.ts
  ✏️ src/auth/jwt.ts
  ✏️ src/middleware/auth.ts

Commit 2
docs: update README with auth changes
Files: 1
  ✏️ README.md

Proceed? [y]es [n]o [d]ry-run [e]dit
```

## Plugin System

Plugins provide framework-specific knowledge for better clustering.

### Built-in Plugins

- **React**: Component/style grouping
- **Django**: Model/view/migration grouping

### Creating a Plugin

```python
from smart_commit.plugins import Plugin

class MyPlugin(Plugin):
    name = "MyFramework"
    version = "0.1.0"
    description = "Custom framework support"
    
    def get_ignored_files(self):
        return ["node_modules/**", "venv/**"]
    
    def get_commit_hints(self, file_diffs):
        hints = {}
        for file_diff in file_diffs:
            if "service" in file_diff.file_path:
                hints[file_diff.file_path] = "service"
        return hints
```

## Supported LLM Providers

Smart Commit uses [LiteLLM](https://github.com/BerriAI/litellm) for provider agnostic access:

| Provider | Model Format | Example |
|----------|--------------|---------|
| OpenRouter | `anthropic/claude-sonnet` | `smart-commit run --provider openrouter --model anthropic/claude-sonnet` |
| OpenAI | `gpt-4` | `smart-commit run --provider openai --model gpt-4` |
| Anthropic | `claude-sonnet` | `smart-commit run --provider anthropic --model claude-sonnet` |
| Google | `gemini-pro` | `smart-commit run --provider google --model gemini-pro` |
| Groq | `mixtral-8x7b-32768` | `smart-commit run --provider groq --model mixtral-8x7b-32768` |
| Azure | `gpt-4` | `smart-commit run --provider azure --model gpt-4` |
| Local (Ollama) | `llama2` | `smart-commit run --provider ollama --model llama2` |

## Architecture

### Project Structure

```
smart_commit/
├── __init__.py
├── cli.py                    # Command-line interface
├── config.py                 # Configuration management
├── constants.py              # Constants and enums
├── exceptions.py             # Custom exceptions
├── logger.py                 # Logging setup
├── models.py                 # Data models
├── utils.py                  # Utilities
│
├── git/                      # Git operations
│   ├── scanner.py            # Repository scanning
│   ├── service.py            # Git commands
│   └── safety.py             # Safety checks
│
├── analysis/                 # Code analysis
│   ├── diff_parser.py        # Diff parsing
│   └── summarizer.py         # Summary generation
│
├── embeddings/               # Semantic embeddings
│   ├── generator.py          # Embedding generation
│   └── similarity.py         # Similarity graph
│
├── clustering/               # File clustering
│   ├── semantic.py           # ML-based clustering
│   └── heuristic.py          # Rule-based clustering
│
├── ai/                       # LLM integration
│   ├── client.py             # LiteLLM wrapper
│   └── reviewer.py           # Cluster review
│
├── preview/                  # UI and preview
│   └── renderer.py           # Rich UI rendering
│
├── execution/                # Commit execution
│   └── committer.py          # Commit and sessions
│
└── plugins/                  # Plugin system
    └── base.py               # Plugin base classes
```

### Module Responsibilities

Each module has a single, clear responsibility:

- **git/scanner.py** - Repository state snapshots
- **analysis/diff_parser.py** - Structured diff extraction
- **analysis/summarizer.py** - Concise change summaries
- **embeddings/generator.py** - Local semantic embeddings
- **embeddings/similarity.py** - Weighted similarity graph
- **clustering/semantic.py** - ML-based file grouping
- **clustering/heuristic.py** - Rule-based fallback
- **ai/client.py** - Multi-provider LLM access
- **ai/reviewer.py** - LLM cluster analysis
- **preview/renderer.py** - Rich terminal UI
- **execution/committer.py** - Safe commit creation

## Development

### Setup

```bash
git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest -v
pytest --cov=smart_commit
```

### Format Code

```bash
black smart_commit tests
ruff check --fix smart_commit tests
```

### Check Types

```bash
mypy smart_commit
```

## Example Workflow

### Before Smart Commit

```bash
$ git status
On branch main
modified: src/auth/login.ts
modified: src/auth/jwt.ts
modified: src/api/routes.ts
modified: docs/README.md

$ git add src/auth/login.ts
$ git add src/auth/jwt.ts
$ git commit -m "feat(auth): improve login validation"

$ git add src/api/routes.ts
$ git commit -m "fix(api): prevent duplicate requests"

$ git add docs/README.md
$ git commit -m "docs: update README"

# Total time: 15-30 minutes
```

### With Smart Commit

```bash
$ smart-commit run

Step 1: Scanning repository...
  ✓ Found 4 changed file(s)
  ✓ +150 additions, -25 deletions
  ✓ Branch: main

Step 2: Analyzing changes...
  ✓ Processed 4 file(s)

Step 3: Grouping related changes...
  ✓ Created 2 commit group(s)

Step 4: AI review...
  ✓ AI review complete

Step 5: Generating commit messages...
  ✓ Generated messages for 2 commit(s)

Step 6: Preview
[Commit 1 preview]
[Commit 2 preview]

Proceed? [y]es [n]o [d]ry-run
y

Step 7: Creating commits...
✓ Success!
  Created 2 commit(s)
    1. abc1234
    2. def5678

# Total time: 30 seconds
```

## Roadmap

- [ ] Interactive commit editing
- [ ] Learning mode (observes user edits)
- [ ] IDE extensions (VS Code, JetBrains)
- [ ] Pull request generation
- [ ] Changelog generation
- [ ] Team configurations
- [ ] Analytics dashboard
- [ ] GitHub Actions integration
- [ ] Semantic history visualization

## Contributing

Contributions are welcome! Areas for help:

- [ ] Language-specific AST parsers
- [ ] Framework plugins (Next.js, FastAPI, etc.)
- [ ] IDE extensions
- [ ] Documentation
- [ ] Testing and bug reports

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - See [LICENSE](LICENSE) file.

## Support

- 📖 Documentation: [docs/](docs/)
- 🐛 Issues: [GitHub Issues](https://github.com/hamxa296/Smart-Commit/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/hamxa296/Smart-Commit/discussions)

## Acknowledgments

Smart Commit builds on:
- [GitPython](https://gitpython.readthedocs.io/) for git operations
- [Typer](https://typer.tiangolo.com/) for CLI
- [Rich](https://rich.readthedocs.io/) for terminal UI
- [Sentence Transformers](https://www.sbert.net/) for embeddings
- [LiteLLM](https://github.com/BerriAI/litellm) for LLM access
- [scikit-learn](https://scikit-learn.org/) for clustering

---

**Made with ❤️ to make Git history beautiful**

## Installation

### Requirements
- Python 3.12+
- Git

### From PyPI (Coming Soon)

```bash
pip install smart-commit
```

### From Source

```bash
git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
pip install -e .
```

### Install Dependencies

```bash
pip install -r requirements.txt
```

## Quick Start

### Initialize Smart Commit

```bash
smart-commit init
```

### Configure Your LLM

```bash
smart-commit config --provider openrouter --model anthropic/claude-sonnet --api-key YOUR_KEY
```

Or set environment variables:

```bash
export SMART_COMMIT_PROVIDER=openrouter
export SMART_COMMIT_MODEL=anthropic/claude-sonnet
export SMART_COMMIT_API_KEY=your-api-key
```

### Run Smart Commit

```bash
smart-commit run
```

This will:
1. Detect all changed files
2. Analyze diffs and create summaries
3. Generate semantic embeddings
4. Cluster related files
5. Display a preview of proposed commits
6. Execute commits upon confirmation

## Commands

```bash
# Analyze and create commits
smart-commit run

# Preview without executing
smart-commit preview

# Undo last session
smart-commit undo

# Configure settings
smart-commit config --show

# Diagnostic checks
smart-commit doctor

# Show version
smart-commit version

# Initialize repository
smart-commit init
```

## Architecture

The tool follows a modular pipeline:

```
Repository
    ↓
Git Scanner (git_service.py)
    ↓
Diff Parser (diff_parser.py)
    ↓
File Summarizer (summarizer.py)
    ↓
Embedding Generator (embeddings.py)
    ↓
Semantic Clustering (clustering.py)
    ↓
LLM Cluster Review (ai.py)
    ↓
Commit Message Generator (commit_messages.py)
    ↓
Interactive Preview (preview.py)
    ↓
Git Commit Executor (committer.py)
```

## Configuration

Smart Commit looks for configuration in this order:

1. `~/.smart_commit/config.yaml`
2. Environment variables (`SMART_COMMIT_*`)
3. Default values

### Example config.yaml

```yaml
provider: openrouter
model: anthropic/claude-sonnet
embedding_model: all-MiniLM-L6-v2
max_files_per_commit: 8
interactive: true
auto_push: false
conventional_commits: true
use_local_embeddings: true
```

## Supported LLM Providers

Smart Commit uses [LiteLLM](https://github.com/BerriAI/litellm) to support:

- OpenRouter
- OpenAI
- Anthropic
- Gemini
- Groq
- Azure OpenAI
- Local models (Ollama, LM Studio, etc.)

## Development

### Project Structure

```
smart_commit/
├── __init__.py
├── cli.py                    # Command-line interface
├── config.py                 # Configuration management
├── models.py                 # Data models
├── utils.py                  # Utility functions
├── git_service.py            # Git operations
├── diff_parser.py            # Diff parsing
├── summarizer.py             # Summary generation
├── embeddings.py             # Embedding generation
├── clustering.py             # File clustering
├── ai.py                     # LLM analysis
├── commit_messages.py        # Message generation
├── preview.py                # Interactive UI
└── committer.py              # Commit execution
tests/
├── __init__.py
├── test_git_service.py
├── test_diff_parser.py
└── test_clustering.py
pyproject.toml
README.md
```

### Development Setup

```bash
# Clone the repository
git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check smart_commit tests
black --check smart_commit tests

# Format code
black smart_commit tests
ruff check --fix smart_commit tests
```

## Milestones

### Milestone 1: ✅ Foundation (Complete)
- Repository detection
- Changed file discovery
- Git wrapper
- Deliverable: Basic repository scanner

### Milestone 2: In Progress
- Diff parser
- Structured diff representation
- Deliverable: Readable summaries of code changes

### Milestone 3: Planned
- Rule-based grouping
- Conventional Commit generation
- Terminal preview
- Deliverable: Working MVP

### Milestone 4: Planned
- Embedding generation
- Semantic clustering
- Deliverable: Cross-folder logical commit grouping

### Milestone 5: Planned
- LLM cluster refinement
- AI-generated commit messages
- Deliverable: High-quality commit history

### Milestone 6: Planned
- Interactive editing
- Undo support
- Session management
- Deliverable: Production-ready CLI

### Milestone 7: Planned
- Learning mode
- Plugins
- IDE integration
- PR generation
- PyPI packaging
- Deliverable: Polished, extensible developer tool

## Why Smart Commit?

### Without Smart Commit
```
$ git status
modified: src/auth/login.ts
modified: src/api/routes.ts
modified: README.md
modified: src/auth/jwt.ts

$ git add src/auth/login.ts
$ git add src/auth/jwt.ts
$ git commit -m "feat(auth): improve login validation"
# 15 min later...
```

### With Smart Commit
```
$ smart-commit run
Found 4 changed files

✓ Proposed commits:
  1. feat(auth): improve login validation and session handling
  2. docs: update README

$ [accept] to execute, [e]dit to modify, [s]plit to separate
# 30 seconds later...
```

## Contributing

We welcome contributions! Areas where help is needed:

- [ ] Improve diff parsing for different languages
- [ ] Add support for more LLM providers
- [ ] Implement learning mode for user preferences
- [ ] Create IDE extensions (VS Code, JetBrains)
- [ ] Optimize clustering algorithm
- [ ] Add comprehensive test coverage
- [ ] Documentation improvements

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - See [LICENSE](LICENSE) file for details.

## Authors

- Smart Commit Contributors

## Support

- 📖 Documentation: See [docs/](docs/) directory
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: support@smartcommit.dev

## Roadmap

- [ ] Interactive commit editing
- [ ] Learning mode for user preferences
- [ ] Framework-specific plugins (React, Django, Next.js, etc.)
- [ ] IDE extensions (VS Code, Cursor, Windsurf, JetBrains)
- [ ] Pull request generation
- [ ] CI/CD integration
- [ ] Team mode with shared configurations
- [ ] Analytics and insights

---

**Made with ❤️ for better Git workflows**

