diffron 0.1.0__tar.gz

diffron-0.1.0/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to Diffron will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Planned
+- Pre-commit hook for linting suggestions
+- Custom model selection per repository
+- Multi-language commit message support
+- Integration with GitHub CLI for auto PR creation
+
+---
+
+## [0.1.0] - 2026-03-28
+
+### Added
+
+#### Core Features
+- **Lemonade Integration**
+  - Auto-detection of Lemonade server via `LEMONADE_SERVER_URL` environment variable
+  - Fallback port scanning (8020, 8000, 8001, 8080, etc.)
+  - Support for custom model configuration via `DIFFRON_MODEL`
+  - Default model: `qwen2.5-it-3b-FLM`
+  - Uses `lemonade-python-sdk` for API communication
+
+- **Git Hooks**
+  - `prepare-commit-msg` hook for automatic commit message generation
+  - Global installation (`~/.diffron-hooks`)
+  - Per-repository installation (`.git/hooks/`)
+  - Windows-compatible shell wrapper for GitHub Desktop 3.5.5+
+  - Smart skip logic for merges, rebases, and amend commits
+  - Silent failure when Lemonade is unavailable (doesn't block commits)
+
+- **Commit Message Generation**
+  - Conventional Commits format enforcement
+  - Configurable diff size limit (default: 4000 characters)
+  - Temperature control for response creativity
+  - Automatic cleanup of quotes and markdown in responses
+
+- **PR Description Generation**
+  - Branch diff analysis
+  - Commit log summarization
+  - TITLE + DESCRIPTION format output
+  - GitHub CLI integration for auto PR creation
+
+- **Python API**
+  - `DiffronClient` class for unified interface
+  - `LemonadeClient` for direct Lemonade API access
+  - `generate_commit_message()` function
+  - `generate_pr_description()` function
+  - `install_hooks()` / `uninstall_hooks()` functions
+  - `is_hooks_installed()` verification
+
+- **CLI Commands**
+  - `diffron-install-hooks` - Install Git hooks
+  - `diffron-uninstall-hooks` - Remove Git hooks
+  - `diffron-pr` - Generate PR description
+  - `diffron-status` - Check Lemonade and hooks status
+
+#### Documentation
+- `README.md` - Project overview and quick start
+- `docs/SETUP.md` - Complete Windows installation guide
+- `docs/HOOKS.md` - Git hooks architecture documentation
+- `docs/USAGE.md` - Detailed usage examples
+- `docs/PLAN.md` - Project roadmap and architecture
+- `docs/PYPI_RELEASE.md` - PyPI release checklist
+
+#### Testing
+- Unit tests for `lemonade.py`
+- Unit tests for `commit_gen.py`
+- Unit tests for `pr_gen.py`
+- Unit tests for `git_hooks.py`
+- Unit tests for `utils.py`
+
+#### Developer Experience
+- Type hints throughout codebase (`.pyi` stub files)
+- `pyproject.toml` configuration
+- `pytest` test suite
+- `black` and `isort` configuration
+- `mypy` type checking configuration
+
+### Technical Details
+
+#### Dependencies
+- `openai>=1.0.0` - Lemonade API client
+- `psutil>=5.9.0` - Port scanning
+
+#### Supported Platforms
+- Windows 10/11 (primary target)
+- GitHub Desktop 3.5.5+ (hooks support)
+- Python 3.9, 3.10, 3.11, 3.12
+
+#### Architecture
+- Modular package structure
+- Separation of concerns (lemonade, hooks, commit_gen, pr_gen)
+- Environment variable configuration
+- Graceful error handling
+
+### Known Issues
+- Model auto-detection via API not supported by Lemonade (uses default)
+- Requires `LEMONADE_SERVER_URL` environment variable for reliable detection
+- Global hooks require Git configuration (`core.hooksPath`)
+
+---
+
+## Version History
+
+| Version | Date | Status |
+|---------|------|--------|
+| 0.1.0 | 2026-03-28 | Initial Release |
+
+---
+
+*Last updated: 2026-03-28*

diffron-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diffron Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diffron-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include requirements.txt
+include pyproject.toml
+
+recursive-include diffron *.py *.pyi py.typed
+recursive-include docs *.md
+recursive-include hooks *.py
+
+exclude tests
+exclude hooks/prepare-commit-msg
+exclude hooks/prepare-commit-msg-global.py
+exclude hooks/prepare-commit-msg.py
+exclude *.bat
+exclude *.code-workspace
+exclude sync-*.txt
+exclude .gitignore
+exclude .sorana

diffron-0.1.0/PKG-INFO

@@ -0,0 +1,373 @@
+Metadata-Version: 2.4
+Name: diffron
+Version: 0.1.0
+Summary: Git commit message and PR description generator using Lemonade
+Home-page: https://github.com/diffron/diffron
+Author: Diffron Contributors
+Author-email: Diffron Contributors <diffron@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/diffron/diffron
+Project-URL: Documentation, https://github.com/diffron/diffron/docs
+Project-URL: Repository, https://github.com/diffron/diffron
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+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: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: git
+Requires-Dist: gitpython>=3.1.0; extra == "git"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Diffron
+
+Git commit message and PR description generator using AMD Lemonade via lemonade-python-sdk.
+
+**This is a demo project showcasing the lemonade-python-sdk - submitted to the AMD Lemonade Developer Challenge 2026.**
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+![Python](https://img.shields.io/badge/python-3.9+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)
+
+---
+
+## Features
+
+- 🤖 **Auto Commit Messages** - Generates Conventional Commits format messages from your staged changes
+- 📝 **PR Descriptions** - Creates detailed PR titles and descriptions from branch diffs
+- 🔌 **Lemonade Integration** - Works with your local Lemonade LLM server (no cloud required)
+- 🪟 **Windows Ready** - Fully compatible with GitHub Desktop 3.5.5+ hooks support
+- ⚡ **Auto-Detection** - Automatically finds your running Lemonade instance
+- 🎯 **Model Flexible** - Use any Lemonade-compatible model (default: qwen2.5-it-3b-FLM)
+
+---
+
+## Quick Start
+
+### 1. Install AMD Lemonade Server
+
+**Lemonade is AMD's local LLM server for Ryzen AI PCs.**
+
+1. Download the installer from [AMD Lemonade Releases](https://github.com/AMD-AI-Software/lemonade/releases)
+2. Run `Lemonade_Server_Installer.exe`
+3. Launch Lemonade Server from the desktop shortcut
+4. Download a model via the Lemonade UI (e.g., `qwen2.5-it-3b-FLM`)
+
+📚 **Documentation:** [AMD Ryzen AI - Lemonade Setup](https://ryzenai.docs.amd.com/en/latest/llm/server_interface.html)
+
+### 2. Install lemonade-python-sdk
+
+**Our Python SDK for AMD Lemonade API:**
+
+```bash
+pip install lemonade-sdk
+```
+
+🔗 **Source:** [github.com/Tetramatrix/lemonade-python-sdk](https://github.com/Tetramatrix/lemonade-python-sdk)
+
+### 3. Configure Environment
+
+**Set Lemonade Server URL (Permanent):**
+1. System Properties → Environment Variables
+2. New User Variable:
+   - Name: `LEMONADE_SERVER_URL`
+   - Value: `http://localhost:8020`
+
+**Or Temporary (current session):**
+```cmd
+set LEMONADE_SERVER_URL=http://localhost:8020
+```
+
+### 4. Install Diffron
+
+```bash
+pip install diffron
+```
+
+### 5. Install Git Hooks
+
+```bash
+python -c "from diffron.git_hooks import install_hooks; install_hooks(global_install=True)"
+```
+
+### 6. Test It
+
+```bash
+# Make a change
+echo "test" > test.txt
+git add test.txt
+
+# Commit - hooks generate the message automatically!
+git commit -m "anything"
+```
+
+Expected output:
+```
+[master abc123] feat: add test.txt file
+ 1 file changed, 1 insertion(+)
+```
+
+---
+
+## Installation
+
+### Requirements
+
+| Software | Version | Purpose |
+|----------|---------|---------|
+| Python | 3.9+ | Runtime |
+| Git | 2.0+ | Version control |
+| GitHub Desktop | 3.5.5+ | Git GUI (Windows) |
+| lemonade-sdk | Latest | AMD Lemonade API client |
+| Lemonade | Latest | Local LLM server |
+
+### Full Installation Guide
+
+See [docs/SETUP.md](docs/SETUP.md) for detailed Windows-specific instructions.
+
+---
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Install hooks globally
+python -c "from diffron.git_hooks import install_hooks; install_hooks(global_install=True)"
+
+# Generate PR description
+python -c "from diffron import generate_pr_description; pr = generate_pr_description(); print(pr.format_output())"
+
+# Check status
+python -c "from diffron import is_lemonade_running, is_hooks_installed; print('Lemonade:', is_lemonade_running()); print('Hooks:', is_hooks_installed(check_global=True))"
+```
+
+### Python API
+
+```python
+from diffron import DiffronClient
+
+# Create client
+client = DiffronClient()
+
+# Generate commit message
+msg = client.generate_commit_message()
+print(msg)  # "feat: add user authentication"
+
+# Generate PR description
+pr = client.generate_pr_description(branch="feature/my-feature")
+print(f"TITLE: {pr.title}")
+print(f"DESCRIPTION: {pr.description}")
+
+# Install hooks
+client.install_hooks(global_install=True)
+```
+
+### GitHub Desktop Workflow
+
+1. Make changes to your files
+2. Open GitHub Desktop
+3. Enter any commit message (e.g., "auto")
+4. Click "Commit to main"
+5. **Diffron replaces** your message with AI-generated message
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LEMONADE_SERVER_URL` | `http://localhost:8020` | Lemonade server URL |
+| `DIFFRON_MODEL` | `qwen2.5-it-3b-FLM` | Model name to use |
+| `DIFFRON_MAX_DIFF_CHARS` | `4000` | Max diff characters |
+
+### Change Model
+
+```cmd
+# System-wide
+setx DIFFRON_MODEL "qwen2.5-coder-7b"
+
+# Current session
+set DIFFRON_MODEL=qwen2.5-coder-7b
+```
+
+### Python API
+
+```python
+from diffron import DiffronClient
+
+# Use different model
+client = DiffronClient(model="your-model-name")
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [SETUP.md](docs/SETUP.md) | Complete installation guide for Windows |
+| [HOOKS.md](docs/HOOKS.md) | Git hooks architecture and internals |
+| [USAGE.md](docs/USAGE.md) | Detailed usage examples |
+
+---
+
+## Related Projects
+
+### Tetramatrix Projects
+
+| Project | Description |
+|---------|-------------|
+| **lemonade-python-sdk** | 🍋 **AMD Lemonade Challenge Submission** - Python SDK for AMD Lemonade API |
+| **Diffron** | Demo project showcasing lemonade-python-sdk (this repo) |
+| **Aicono** | AI Assistant (Desktop App) |
+| **TabNeuron** | Browser Connector / Memory |
+| **Sorana** | Advanced AI Interface |
+| **RyzenPilot** | Hardware Optimization |
+
+**Note:** Lemonade is AMD's local LLM server for Ryzen AI PCs. Diffron uses `lemonade-python-sdk` to communicate with Lemonade's API.
+
+🏆 **AMD Lemonade Developer Challenge 2026:** This project demonstrates the capabilities of lemonade-python-sdk as a real-world application built on AMD Lemonade.
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. User makes changes and runs: git commit              │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 2. Git hook executes prepare-commit-msg                 │
+│    - Location: C:/Users/Name/.diffron-hooks/            │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 3. Hook reads staged diff: git diff --cached            │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 4. Hook calls Lemonade API                              │
+│    - URL: http://localhost:8020/api/v1                  │
+│    - Model: qwen2.5-it-3b-FLM                           │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 5. AI generates Conventional Commit message             │
+│    - "feat: add user authentication module"             │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 6. Git opens editor with generated message              │
+│    - User can review/modify before saving               │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Troubleshooting
+
+### Lemonade Not Detected
+
+```bash
+# Start Lemonade
+lemonade serve qwen2.5-it-3b-FLM
+
+# Verify URL
+echo %LEMONADE_SERVER_URL%
+```
+
+### Hooks Not Working
+
+```bash
+# Check GitHub Desktop version (must be 3.5.5+)
+# Help → About
+
+# Verify hooks path
+git config --global core.hooksPath
+
+# Reinstall hooks
+python -c "from diffron.git_hooks import install_hooks; install_hooks(global_install=True)"
+```
+
+### Model Not Found (404)
+
+```bash
+# Download model
+lemonade pull qwen2.5-it-3b-FLM
+
+# Verify model name
+set DIFFRON_MODEL=qwen2.5-it-3b-FLM
+```
+
+See [docs/SETUP.md](docs/SETUP.md) for complete troubleshooting guide.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Contributing
+
+Contributions welcome! This is an open source project.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests
+5. Submit a pull request
+
+### Development Setup
+
+```bash
+git clone https://github.com/diffron/diffron.git
+cd diffron
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+pytest tests/
+```
+
+---
+
+## Acknowledgments
+
+- **Lemonade** - Local LLM server by the Lemonade team
+- **GitHub Desktop** - Git GUI with hooks support (3.5.5+)
+- **Conventional Commits** - Commit message format specification
+
+---
+
+*Version: 0.1.0 | Last updated: 2026-03-28*