Add comprehensive LoRA training guide and documentation

README.md

@@ -22,14 +22,30 @@ Transform your architectural renders with AI-powered enhancement using Stable Di
 - 🎭 Photographic post-processing
 - ⚙️ Configurable parameters
 - 🚀 GPU-accelerated inference
+- 🎓 **Custom LoRA training** (local only)
 
 ## Usage
 
 1. Upload an architectural render
-2. Adjust enhancement settings (optional)
-3. Click "Enhance Image"
-4. Wait 30-60 seconds for processing
-5. Download your enhanced result
+2. Add custom prompt details (optional)
+3. Adjust enhancement settings (optional)
+4. Click "Enhance Image"
+5. Wait for processing (2-5 minutes on CPU, ~30 seconds on GPU)
+6. Download your enhanced result
+
+## 🎓 Custom LoRA Training
+
+Want to train the AI on your specific architectural style? Check out the complete training guide:
+
+**📖 [LoRA Training Guide](./TRAINING_GUIDE.md)**
+
+Learn how to:
+- Prepare training image pairs
+- Train custom LoRA models locally
+- Fine-tune for your specific rendering style
+- Deploy your custom model
+
+**Note**: Training requires running the backend locally due to computational requirements.
 
 ## Technical Details
 

TRAINING_GUIDE.md

@@ -0,0 +1,326 @@
+# 🎓 LoRA Training Guide - Architecture AI Enhancer
+
+This guide explains how to train custom LoRA (Low-Rank Adaptation) models to specialize the AI enhancer for your specific architectural style.
+
+## 📖 What is LoRA Training?
+
+LoRA allows you to fine-tune the Stable Diffusion model with a small set of your own images (10-50 pairs) to learn your specific architectural style, lighting preferences, or rendering aesthetic without retraining the entire model.
+
+### Benefits:
+- ✅ **Fast Training**: Only a few hundred training steps needed
+- ✅ **Small Models**: LoRA weights are ~10-50 MB vs. full model (4+ GB)
+- ✅ **Style Consistency**: Learn your specific rendering style
+- ✅ **Efficient**: Works on consumer GPUs or even CPU (slower)
+
+---
+
+## 🚀 Quick Start
+
+### Step 1: Prepare Your Training Data
+
+You need **image pairs**:
+- **Input Image**: Your base architectural render (before enhancement)
+- **Target Image**: The desired enhanced result (your ideal output)
+
+**Requirements:**
+- Minimum: 10 pairs (recommended: 20-50 pairs)
+- Format: PNG or JPG
+- Resolution: 512x512 to 1024x1024 recommended
+- Naming convention: `{pair_id}_input.png` and `{pair_id}_target.png`
+
+**Example:**
+```
+training_data/
+  inputs/
+    building_001_input.png
+    building_002_input.png
+    office_003_input.png
+  targets/
+    building_001_target.png
+    building_002_target.png
+    office_003_target.png
+```
+
+### Step 2: Start the Backend Server (Local Training)
+
+The current HF Spaces deployment **does not include training capabilities** due to resource constraints. Training must be done locally.
+
+```bash
+cd architecture-ai-enhancer/backend
+uvicorn main:app --host 0.0.0.0 --port 8000
+```
+
+Access the API documentation at: `http://localhost:8000/docs`
+
+### Step 3: Upload Training Pairs
+
+Use the `/training/upload_pair` endpoint:
+
+```python
+import requests
+
+# Upload a training pair
+files = {
+    'input_image': open('building_001_input.png', 'rb'),
+    'target_image': open('building_001_target.png', 'rb')
+}
+response = requests.post('http://localhost:8000/training/upload_pair', files=files)
+print(response.json())
+```
+
+Or use the interactive docs at `/docs` to upload via the UI.
+
+### Step 4: Start Training
+
+Once you have uploaded all pairs, start training:
+
+```python
+import requests
+
+training_config = {
+    "train_steps": 1000,      # Number of training iterations
+    "learning_rate": 1e-4,    # Learning rate (lower = more stable)
+    "lora_rank": 8,           # LoRA rank (higher = more capacity)
+    "batch_size": 1           # Batch size (increase if you have enough VRAM)
+}
+
+response = requests.post(
+    'http://localhost:8000/training/start',
+    json=training_config
+)
+print(response.json())
+```
+
+**Training Parameters Guide:**
+- `train_steps`: 500-2000 (more steps = better learning, but risk overfitting)
+- `learning_rate`: 1e-4 to 1e-5 (lower for subtle changes, higher for dramatic)
+- `lora_rank`: 4-16 (higher = more model capacity, but slower)
+- `batch_size`: 1-4 (depends on your GPU memory)
+
+### Step 5: Monitor Training Progress
+
+Check training status:
+
+```python
+response = requests.get('http://localhost:8000/training/status')
+print(response.json())
+```
+
+Training typically takes:
+- **GPU (RTX 3080+)**: 10-30 minutes for 1000 steps
+- **CPU**: 2-4 hours for 1000 steps
+
+### Step 6: Use Your Trained LoRA
+
+Once training completes, the model is automatically saved to `models/lora/office_style.safetensors`.
+
+The enhancement pipeline will automatically detect and use the trained LoRA model for all future enhancements.
+
+---
+
+## 🎨 Advanced Tips
+
+### Creating Quality Training Data
+
+1. **Consistency is Key**
+   - Use similar lighting conditions across pairs
+   - Maintain consistent camera angles
+   - Keep architectural styles related
+
+2. **Variety Matters**
+   - Include different views (exterior, interior, details)
+   - Mix daytime and nighttime scenes
+   - Vary weather/lighting conditions
+
+3. **Quality Over Quantity**
+   - 20 high-quality pairs > 100 mediocre pairs
+   - Ensure target images represent your desired style accurately
+   - Avoid blurry or poorly composed targets
+
+### Optimal Training Parameters by Use Case
+
+**Learning Subtle Enhancements:**
+```json
+{
+  "train_steps": 500,
+  "learning_rate": 5e-5,
+  "lora_rank": 4
+}
+```
+
+**Learning Dramatic Style Changes:**
+```json
+{
+  "train_steps": 1500,
+  "learning_rate": 1e-4,
+  "lora_rank": 12
+}
+```
+
+**Balanced Training (Recommended Start):**
+```json
+{
+  "train_steps": 1000,
+  "learning_rate": 1e-4,
+  "lora_rank": 8
+}
+```
+
+### Troubleshooting
+
+**Problem: Training loss not decreasing**
+- Solution: Increase learning rate or train for more steps
+- Check: Ensure training pairs are properly aligned
+
+**Problem: Model overfitting (memorizing training images)**
+- Solution: Reduce train_steps or increase dataset size
+- Try: Lower lora_rank
+
+**Problem: Out of memory errors**
+- Solution: Reduce batch_size to 1
+- Try: Use gradient checkpointing (enabled by default)
+
+**Problem: Results don't match training targets**
+- Solution: Increase train_steps
+- Check: Ensure sufficient variety in training data
+
+---
+
+## 🔄 Deploying Your Custom LoRA
+
+### Option 1: Local Deployment
+
+Your trained LoRA is automatically used by the local FastAPI backend.
+
+### Option 2: HF Spaces Deployment
+
+To use your custom LoRA on HF Spaces:
+
+1. Upload your LoRA file to Hugging Face Hub
+2. Modify `hf_deployment/backend/config.py`:
+   ```python
+   LORA_MODEL_NAME = "your_lora_model.safetensors"
+   ```
+3. Add code to download the LoRA from HF Hub on startup
+4. Redeploy to HF Spaces
+
+---
+
+## 📊 Example Training Script
+
+Complete Python script for training workflow:
+
+```python
+import requests
+import time
+from pathlib import Path
+
+BASE_URL = "http://localhost:8000"
+
+def upload_training_pairs(input_dir, target_dir):
+    """Upload all training pairs from directories"""
+    input_files = sorted(Path(input_dir).glob("*_input.*"))
+    
+    for input_file in input_files:
+        pair_id = input_file.stem.replace("_input", "")
+        target_file = Path(target_dir) / f"{pair_id}_target{input_file.suffix}"
+        
+        if not target_file.exists():
+            print(f"Warning: No target for {input_file.name}")
+            continue
+        
+        files = {
+            'input_image': open(input_file, 'rb'),
+            'target_image': open(target_file, 'rb')
+        }
+        
+        response = requests.post(f"{BASE_URL}/training/upload_pair", files=files)
+        
+        if response.status_code == 200:
+            print(f"✓ Uploaded pair: {pair_id}")
+        else:
+            print(f"✗ Failed: {pair_id} - {response.text}")
+
+def start_training(steps=1000, lr=1e-4, rank=8):
+    """Start LoRA training"""
+    config = {
+        "train_steps": steps,
+        "learning_rate": lr,
+        "lora_rank": rank,
+        "batch_size": 1
+    }
+    
+    response = requests.post(f"{BASE_URL}/training/start", json=config)
+    print(f"Training started: {response.json()}")
+
+def monitor_training():
+    """Monitor training progress"""
+    while True:
+        response = requests.get(f"{BASE_URL}/training/status")
+        status = response.json()
+        
+        print(f"Status: {status['status']} - {status['message']}")
+        
+        if status['status'] in ['completed', 'failed']:
+            break
+        
+        time.sleep(30)  # Check every 30 seconds
+
+# Main workflow
+if __name__ == "__main__":
+    # 1. Upload training data
+    print("Uploading training pairs...")
+    upload_training_pairs("training_data/inputs", "training_data/targets")
+    
+    # 2. Start training
+    print("\nStarting training...")
+    start_training(steps=1000, lr=1e-4, rank=8)
+    
+    # 3. Monitor progress
+    print("\nMonitoring training...")
+    monitor_training()
+    
+    print("\n✓ Training complete! Your LoRA is ready to use.")
+```
+
+---
+
+## 🤔 FAQ
+
+**Q: Can I train on HF Spaces?**  
+A: No, the free CPU tier doesn't have enough resources. Training must be done locally or on a paid GPU space.
+
+**Q: How many images do I need?**  
+A: Minimum 10 pairs, recommended 20-50 pairs for best results.
+
+**Q: Can I use photos instead of renders?**  
+A: Yes! You can train input=render, target=photo to learn photorealistic enhancement.
+
+**Q: How long does training take?**  
+A: On GPU: 10-30 min. On CPU: 2-4 hours for 1000 steps.
+
+**Q: Can I train multiple LoRAs?**  
+A: Yes, but only one can be active at a time. Rename your LoRA files accordingly.
+
+**Q: Will this work with other Stable Diffusion models?**  
+A: The code uses SD 1.5. For SDXL or SD 2.x, you'll need to modify the training engine.
+
+---
+
+## 📚 Additional Resources
+
+- [LoRA Paper](https://arxiv.org/abs/2106.09685) - Original research
+- [Diffusers Documentation](https://huggingface.co/docs/diffusers/) - Hugging Face Diffusers library
+- [PEFT Library](https://github.com/huggingface/peft) - Parameter-Efficient Fine-Tuning
+
+---
+
+## 💡 Next Steps
+
+1. ✅ Prepare your training dataset
+2. ✅ Run the backend locally
+3. ✅ Upload and train your LoRA
+4. ✅ Test enhancements with your custom style
+5. ✅ Iterate and refine
+
+**Happy Training! 🚀**