ollamadiffuser 1.0.0__tar.gz → 1.1.0__tar.gz

ollamadiffuser-1.1.0/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [1.1.0] - 2024-12-XX
+
+### 🚀 Major Features Added
+
+#### ⚡ Lazy Loading Architecture
+- **Instant Startup**: Application now starts immediately without downloading ControlNet models
+- **On-Demand Loading**: ControlNet preprocessors initialize only when actually needed
+- **Performance Boost**: `ollamadiffuser --help` runs in milliseconds instead of 30+ seconds
+- **Memory Efficient**: No unnecessary model downloads for users who don't use ControlNet
+
+#### 🎛️ Complete ControlNet Integration
+- **6 ControlNet Models**: SD 1.5 and SDXL variants (canny, depth, openpose, scribble)
+- **10 Control Types**: canny, depth, openpose, hed, mlsd, normal, lineart, lineart_anime, shuffle, scribble
+- **Advanced Preprocessors**: Full controlnet-aux integration with graceful fallbacks
+- **Web UI Integration**: File upload, preprocessing, and side-by-side result display
+- **REST API Support**: Complete API endpoints for ControlNet generation and preprocessing
+
+#### 🔄 Enhanced LoRA Management
+- **Web UI Integration**: Download LoRAs directly from Hugging Face in the browser
+- **Alias Support**: Create custom names for your LoRAs
+- **Strength Control**: Adjust LoRA influence with intuitive sliders
+- **Real-time Loading**: Load/unload LoRAs without restarting the application
+
+### 🛠️ Technical Improvements
+
+#### ControlNet Preprocessor Manager
+- **Lazy Initialization**: `ControlNetPreprocessorManager` with `is_initialized()`, `is_available()`, `initialize()` methods
+- **Automatic Fallback**: Basic OpenCV processors when advanced ones fail
+- **Error Handling**: Robust validation and graceful degradation
+- **Status Tracking**: Real-time initialization and availability status
+
+#### Web UI Enhancements
+- **ControlNet Section**: Dedicated controls with status indicators
+- **Initialization Button**: Manual preprocessor initialization for faster processing
+- **File Upload**: Drag-and-drop control image upload with validation
+- **Responsive Design**: Mobile-friendly interface with adaptive layouts
+- **Real-time Status**: Live model, LoRA, and ControlNet status indicators
+
+#### API Improvements
+- **New Endpoints**: `/api/controlnet/initialize`, `/api/controlnet/preprocessors`, `/api/controlnet/preprocess`
+- **File Upload Support**: Multipart form data handling for control images
+- **Status Endpoints**: Check ControlNet availability and initialization status
+- **Error Handling**: Comprehensive error responses with helpful messages
+
+### 📦 Dependencies Updated
+- **controlnet-aux**: Added `>=0.0.7` for advanced preprocessing capabilities
+- **opencv-python**: Added `>=4.8.0` for basic image processing fallbacks
+- **diffusers**: Updated to `>=0.26.0` for ControlNet compatibility
+
+### 🎨 User Experience Improvements
+
+#### Startup Performance
+- **Before**: 30+ seconds startup time, 1GB+ automatic downloads
+- **After**: Instant startup, downloads only when needed
+- **User Control**: Choose when to initialize ControlNet preprocessors
+
+#### Web UI Experience
+- **Status Indicators**: Clear visual feedback for all system states
+- **Progressive Loading**: Initialize components as needed
+- **Error Messages**: Helpful guidance for common issues
+- **Mobile Support**: Responsive design works on all devices
+
+#### CLI Experience
+- **Fast Commands**: All CLI commands run instantly
+- **Lazy Loading**: ControlNet models load only when generating
+- **Status Commands**: Check system state without triggering downloads
+
+### 🔧 Configuration Changes
+- **setup.py**: Added ControlNet dependencies
+- **pyproject.toml**: Updated dependency specifications
+- **Model Registry**: Enhanced with ControlNet model definitions
+
+### 📚 Documentation Updates
+- **CONTROLNET_GUIDE.md**: Comprehensive 400+ line guide with examples
+- **README.md**: Updated with lazy loading features and ControlNet quick start
+- **API Documentation**: Complete endpoint reference with examples
+
+### 🐛 Bug Fixes
+- **Startup Crashes**: Fixed 404 errors from non-existent model repositories
+- **Memory Leaks**: Improved cleanup of ControlNet preprocessors
+- **Device Compatibility**: Better handling of CPU/GPU device switching
+- **Error Handling**: More graceful failure modes with helpful messages
+
+### ⚠️ Breaking Changes
+- **Import Behavior**: `controlnet_preprocessors` module no longer auto-initializes
+- **API Changes**: Some ControlNet endpoints require explicit initialization
+
+### 🔄 Migration Guide
+For users upgrading from v1.0.x:
+
+1. **No Action Required**: Lazy loading is automatic and transparent
+2. **Web UI**: ControlNet preprocessors initialize automatically when uploading images
+3. **API Users**: Call `/api/controlnet/initialize` for faster subsequent processing
+4. **Python API**: Use `controlnet_preprocessor.initialize()` for batch processing
+
+### 🎯 Performance Metrics
+- **Startup Time**: Reduced from 30+ seconds to <1 second
+- **Memory Usage**: Reduced baseline memory footprint by ~2GB
+- **First Generation**: Slightly slower due to lazy loading, then normal speed
+- **Subsequent Generations**: Same performance as before
+
+## [1.0.0] - 2024-11-XX
+
+### Added
+- Initial release with core functionality
+- Support for Stable Diffusion 1.5, SDXL, SD3, and FLUX models
+- Basic LoRA support
+- CLI interface
+- REST API server
+- Web UI interface
+- Model management system
+
+### Features
+- Model downloading and management
+- Image generation with various parameters
+- Multiple interface options (CLI, API, Web UI)
+- Hardware optimization (CUDA, MPS, CPU)
+- Safety checker bypass for creative freedom
+
+---
+
+## Development Notes
+
+### Version Numbering
+- **Major** (X.0.0): Breaking changes, major feature additions
+- **Minor** (1.X.0): New features, significant improvements
+- **Patch** (1.1.X): Bug fixes, minor improvements
+
+### Release Process
+1. Update version in `__init__.py`
+2. Update CHANGELOG.md with new features
+3. Update documentation
+4. Create release tag
+5. Deploy to package repositories 

ollamadiffuser-1.1.0/PKG-INFO

@@ -0,0 +1,485 @@
+Metadata-Version: 2.4
+Name: ollamadiffuser
+Version: 1.1.0
+Summary: 🎨 Local AI Image Generation with Ollama-style CLI for Stable Diffusion, FLUX.1, and LoRA support
+Home-page: https://github.com/ollamadiffuser/ollamadiffuser
+Author: OllamaDiffuser Team
+Author-email: OllamaDiffuser Team <ollamadiffuser@gmail.com>
+License: MIT
+Project-URL: Homepage, https://www.ollamadiffuser.com/
+Project-URL: Website, https://www.ollamadiffuser.com/
+Project-URL: Repository, https://github.com/ollamadiffuser/ollamadiffuser
+Project-URL: Issues, https://github.com/ollamadiffuser/ollamadiffuser/issues
+Project-URL: Documentation, https://www.ollamadiffuser.com/
+Project-URL: Bug Reports, https://github.com/ollamadiffuser/ollamadiffuser/issues
+Project-URL: Feature Requests, https://github.com/ollamadiffuser/ollamadiffuser/issues
+Project-URL: Source Code, https://github.com/ollamadiffuser/ollamadiffuser
+Keywords: diffusion,image-generation,ai,machine-learning,lora,ollama,stable-diffusion,flux,local-ai,controlnet,web-ui,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1.0
+Requires-Dist: diffusers>=0.26.0
+Requires-Dist: transformers>=4.35.0
+Requires-Dist: accelerate>=0.25.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.23.0
+Requires-Dist: huggingface-hub>=0.16.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: protobuf>=3.20.0
+Requires-Dist: sentencepiece>=0.1.99
+Requires-Dist: safetensors>=0.3.0
+Requires-Dist: python-multipart>=0.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: peft>=0.10.0
+Requires-Dist: controlnet-aux>=0.0.7
+Requires-Dist: opencv-python>=4.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# OllamaDiffuser 🎨
+
+[![PyPI version](https://badge.fury.io/py/ollamadiffuser.svg)](https://badge.fury.io/py/ollamadiffuser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+## Local AI Image Generation with OllamaDiffuser
+
+**OllamaDiffuser** simplifies local deployment of **Stable Diffusion**, **FLUX.1**, and other AI image generation models. An intuitive **local SD** tool inspired by **Ollama's** simplicity - perfect for **local diffuser** workflows with CLI, web UI, and LoRA support.
+
+🌐 **Website**: [ollamadiffuser.com](https://www.ollamadiffuser.com/) | 📦 **PyPI**: [pypi.org/project/ollamadiffuser](https://pypi.org/project/ollamadiffuser/)
+
+---
+
+## ✨ Features
+
+- **🚀 Fast Startup**: Instant application launch with lazy loading architecture
+- **🎛️ ControlNet Support**: Precise image generation control with 10+ control types
+- **🔄 LoRA Integration**: Dynamic LoRA loading and management
+- **🌐 Multiple Interfaces**: CLI, Python API, Web UI, and REST API
+- **📦 Model Management**: Easy installation and switching between models
+- **⚡ Performance Optimized**: Memory-efficient with GPU acceleration
+- **🎨 Professional Results**: High-quality image generation with fine-tuned control
+
+## 🚀 Quick Start
+
+### Option 1: Install from PyPI (Recommended)
+```bash
+# Install from PyPI
+pip install ollamadiffuser
+
+# Pull and run a model (4-command setup)
+ollamadiffuser pull flux.1-schnell
+ollamadiffuser run flux.1-schnell
+
+# Generate via API
+curl -X POST http://localhost:8000/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "A beautiful sunset"}' \
+  --output image.png
+```
+
+### Option 2: Development Installation
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/ollamadiffuser.git
+cd ollamadiffuser
+
+# Install dependencies
+pip install -e .
+```
+
+### Basic Usage
+```bash
+# Install a model
+ollamadiffuser pull stable-diffusion-1.5
+
+# Load the model
+ollamadiffuser load stable-diffusion-1.5
+
+# Generate an image
+ollamadiffuser generate "a beautiful sunset over mountains"
+
+# Start web interface
+ollamadiffuser --mode ui
+```
+
+### ControlNet Quick Start
+```bash
+# Install ControlNet model
+ollamadiffuser pull controlnet-canny-sd15
+
+# Load ControlNet model
+ollamadiffuser load controlnet-canny-sd15
+
+# Generate with control image
+curl -X POST http://localhost:8000/api/generate/controlnet \
+  -F "prompt=a beautiful landscape" \
+  -F "control_image=@your_image.jpg"
+```
+
+---
+
+## 🎯 Supported Models
+
+Choose from a variety of state-of-the-art image generation models:
+
+| Model | License | Quality | Speed | Commercial Use |
+|-------|---------|---------|-------|----------------|
+| **FLUX.1-schnell** | Apache 2.0 | High | **4 steps** (12x faster) | ✅ Commercial OK |
+| **FLUX.1-dev** | Non-commercial | High | 50 steps | ❌ Non-commercial |
+| **Stable Diffusion 3.5** | CreativeML | Medium | 28 steps | ⚠️ Check License |
+| **Stable Diffusion 1.5** | CreativeML | Fast | Lightweight | ⚠️ Check License |
+
+### Why Choose FLUX.1-schnell?
+- **Apache 2.0 license** - Perfect for commercial use
+- **4-step generation** - Lightning fast results  
+- **Commercial OK** - Use in your business
+
+---
+
+## 🎛️ ControlNet Features
+
+### ⚡ Lazy Loading Architecture
+**New in v1.1.0**: ControlNet preprocessors use intelligent lazy loading:
+
+- **Instant Startup**: `ollamadiffuser --help` runs immediately without downloading models
+- **On-Demand Loading**: Preprocessors initialize only when actually needed
+- **Automatic Initialization**: Seamless loading when uploading control images
+- **User Control**: Manual initialization available for pre-loading
+
+### Available Control Types
+- **Canny Edge Detection**: Structural control with edge maps
+- **Depth Estimation**: 3D structure control with depth maps
+- **OpenPose**: Human pose and body position control
+- **Scribble/Sketch**: Artistic control with hand-drawn inputs
+- **Advanced Types**: HED, MLSD, Normal, Lineart, Anime Lineart, Content Shuffle
+
+### ControlNet Models
+```bash
+# SD 1.5 ControlNet Models
+ollamadiffuser pull controlnet-canny-sd15
+ollamadiffuser pull controlnet-depth-sd15
+ollamadiffuser pull controlnet-openpose-sd15
+ollamadiffuser pull controlnet-scribble-sd15
+
+# SDXL ControlNet Models
+ollamadiffuser pull controlnet-canny-sdxl
+ollamadiffuser pull controlnet-depth-sdxl
+```
+
+## 🔄 LoRA Support
+
+### Dynamic LoRA Management
+```bash
+# Download LoRA from Hugging Face
+ollamadiffuser lora pull "openfree/flux-chatgpt-ghibli-lora"
+
+# Load LoRA with custom strength
+ollamadiffuser lora load ghibli --scale 1.2
+
+# Unload LoRA
+ollamadiffuser lora unload
+```
+
+### Web UI LoRA Integration
+- **Easy Download**: Enter Hugging Face repository ID
+- **Strength Control**: Adjust LoRA influence with sliders
+- **Real-time Loading**: Load/unload LoRAs without restarting
+- **Alias Support**: Create custom names for your LoRAs
+
+## 🌐 Multiple Interfaces
+
+### Command Line Interface
+```bash
+# Generate with advanced parameters
+ollamadiffuser generate \
+  "a futuristic cityscape" \
+  --negative-prompt "blurry, low quality" \
+  --steps 30 \
+  --guidance 7.5 \
+  --width 1024 \
+  --height 1024
+```
+
+### Web UI
+```bash
+# Start web interface
+ollamadiffuser --mode ui
+# Open http://localhost:8001
+```
+
+Features:
+- **Responsive Design**: Works on desktop and mobile
+- **Real-time Status**: Model and LoRA loading indicators
+- **ControlNet Integration**: File upload with preprocessing
+- **Parameter Controls**: Intuitive sliders and inputs
+
+### REST API
+```bash
+# Start API server
+ollamadiffuser --mode api
+
+# Generate image
+curl -X POST http://localhost:8000/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "a beautiful landscape", "width": 1024, "height": 1024}'
+```
+
+### Python API
+```python
+from ollamadiffuser.core.models.manager import model_manager
+
+# Load model
+model_manager.load_model("stable-diffusion-1.5")
+engine = model_manager.loaded_model
+
+# Generate image
+image = engine.generate_image(
+    prompt="a beautiful sunset",
+    width=1024,
+    height=1024
+)
+image.save("output.jpg")
+```
+
+## 📦 Supported Models
+
+### Base Models
+- **Stable Diffusion 1.5**: Classic, reliable, fast
+- **Stable Diffusion XL**: High-resolution, detailed
+- **Stable Diffusion 3**: Latest architecture
+- **FLUX.1**: State-of-the-art quality
+
+### ControlNet Models
+- **SD 1.5 ControlNet**: 4 control types (canny, depth, openpose, scribble)
+- **SDXL ControlNet**: 2 control types (canny, depth)
+
+### LoRA Support
+- **Hugging Face Integration**: Direct download from HF Hub
+- **Local LoRA Files**: Support for local .safetensors files
+- **Dynamic Loading**: Load/unload without model restart
+- **Strength Control**: Adjustable influence (0.1-2.0)
+
+## ⚙️ Configuration
+
+### Model Configuration
+Models are automatically configured with optimal settings:
+- **Memory Optimization**: Attention slicing, CPU offloading
+- **Device Detection**: Automatic CUDA/MPS/CPU selection
+- **Precision Handling**: FP16/BF16 support for efficiency
+- **Safety Features**: NSFW filter bypass for creative freedom
+
+### Performance Tuning
+```bash
+# Enable verbose logging
+ollamadiffuser -v generate "test prompt"
+
+# Check system status
+ollamadiffuser status
+
+# Monitor memory usage
+ollamadiffuser info
+```
+
+## 🔧 Advanced Usage
+
+### ControlNet Parameters
+```python
+# Fine-tune ControlNet behavior
+image = engine.generate_image(
+    prompt="architectural masterpiece",
+    control_image=control_img,
+    controlnet_conditioning_scale=1.2,  # Strength (0.0-2.0)
+    control_guidance_start=0.0,         # When to start (0.0-1.0)
+    control_guidance_end=1.0            # When to end (0.0-1.0)
+)
+```
+
+### Batch Processing
+```python
+from ollamadiffuser.core.utils.controlnet_preprocessors import controlnet_preprocessor
+
+# Pre-initialize for faster processing
+controlnet_preprocessor.initialize()
+
+# Process multiple images
+for image_path in image_list:
+    control_img = controlnet_preprocessor.preprocess(image, "canny")
+    result = engine.generate_image(prompt, control_image=control_img)
+    result.save(f"output_{i}.jpg")
+```
+
+### API Integration
+```python
+import requests
+
+# Initialize ControlNet preprocessors
+response = requests.post("http://localhost:8000/api/controlnet/initialize")
+
+# Check available preprocessors
+response = requests.get("http://localhost:8000/api/controlnet/preprocessors")
+print(response.json()["available_types"])
+
+# Generate with file upload
+with open("control.jpg", "rb") as f:
+    response = requests.post(
+        "http://localhost:8000/api/generate/controlnet",
+        data={"prompt": "beautiful landscape"},
+        files={"control_image": f}
+    )
+```
+
+## 📚 Documentation & Guides
+
+- **[ControlNet Guide](CONTROLNET_GUIDE.md)**: Comprehensive ControlNet usage and examples
+- **[LoRA Guide](LORA_GUIDE.md)**: LoRA management and best practices
+- **[API Reference](API_REFERENCE.md)**: Complete API documentation
+- **[Website Documentation](https://www.ollamadiffuser.com/)**: Complete tutorials and guides
+
+## 🚀 Performance & Hardware
+
+### Minimum Requirements
+- **RAM**: 8GB system RAM
+- **Storage**: 10GB free space
+- **Python**: 3.8+
+
+### Recommended Hardware
+- **GPU**: 8GB+ VRAM (NVIDIA/AMD)
+- **RAM**: 16GB+ system RAM
+- **Storage**: SSD with 50GB+ free space
+
+### Supported Platforms
+- **CUDA**: NVIDIA GPUs (recommended)
+- **MPS**: Apple Silicon (M1/M2/M3)
+- **CPU**: All platforms (slower but functional)
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Slow Startup
+If you experience slow startup, ensure you're using the latest version with lazy loading:
+```bash
+git pull origin main
+pip install -e .
+```
+
+#### ControlNet Not Working
+```bash
+# Check preprocessor status
+python -c "
+from ollamadiffuser.core.utils.controlnet_preprocessors import controlnet_preprocessor
+print('Available:', controlnet_preprocessor.is_available())
+print('Initialized:', controlnet_preprocessor.is_initialized())
+"
+
+# Manual initialization
+curl -X POST http://localhost:8000/api/controlnet/initialize
+```
+
+#### Memory Issues
+```bash
+# Use smaller image sizes
+ollamadiffuser generate "test" --width 512 --height 512
+
+# Enable CPU offloading (automatic)
+# Close other applications
+# Use basic preprocessors instead of advanced ones
+```
+
+### Debug Mode
+```bash
+# Enable verbose logging
+ollamadiffuser -v run model-name
+
+# Check system information
+ollamadiffuser info
+
+# Validate installation
+ollamadiffuser doctor
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+```bash
+# Clone repository
+git clone https://github.com/yourusername/ollamadiffuser.git
+cd ollamadiffuser
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Run linting
+flake8 ollamadiffuser/
+black ollamadiffuser/
+```
+
+## 🤝 Community & Support
+
+### Quick Actions
+
+- **🐛 [Report a Bug](https://github.com/ollamadiffuser/ollamadiffuser/issues)** - Found an issue? Let us know
+- **💡 [Feature Request](https://github.com/ollamadiffuser/ollamadiffuser/issues)** - Have an idea? Share it with us  
+- **💬 [Join Discussions](https://github.com/ollamadiffuser/ollamadiffuser/discussions)** - Community discussion
+- **⭐ [Star on GitHub](https://github.com/ollamadiffuser/ollamadiffuser)** - Show your support
+
+### Community Driven
+
+OllamaDiffuser is an open-source project that thrives on community feedback. Every suggestion, bug report, and contribution helps make it better for everyone.
+
+**Open Source** • **Community Driven** • **Actively Maintained**
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Stability AI**: For Stable Diffusion models
+- **Hugging Face**: For model hosting and diffusers library
+- **ControlNet Team**: For ControlNet architecture
+- **Community**: For feedback and contributions
+
+## 📞 Support
+
+- **Documentation**: [Full documentation](docs/)
+- **Issues**: [GitHub Issues](https://github.com/yourusername/ollamadiffuser/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/ollamadiffuser/discussions)
+
+---
+
+**Ready to get started?** Install from PyPI: `pip install ollamadiffuser` or visit [ollamadiffuser.com](https://www.ollamadiffuser.com/) 🎨✨