# 📋 COMPREHENSIVE IMAGE MODELS IMPLEMENTATION PLAN

## Model Reference Summary

| Model | AIR ID | Tier | Supported Dimensions (Square/Landscape) |
|-------|--------|------|----------------------------------------|
| **Hi Dream Full** | `runware:97@1` | Basic/Cheap | 1024×1024, 1280×768 (general diffusion) |
| **Bria 3.2** | `bria:10@1` | Good Quality | 1024×1024, 1344×768 (16:9) or 1216×832 (3:2) |
| **Nano Banana** | `google:4@2` | Premium | 1024×1024, 1376×768 (16:9) or 1264×848 (3:2) |

---

## TASK 1: Image Generation Progress Modal Width Increase

**Files to modify:**
- ImageQueueModal.tsx

**Changes:**
1. Locate the modal container `max-w-*` or width class
2. Increase width by 50% (e.g., `max-w-2xl` → `max-w-4xl`, or explicit width)
3. Ensure responsive behavior is maintained for smaller screens

---

## TASK 2: Fix Duplicate In-Article Image Names (Unique Field Storage)

**Files to modify:**
- Backend: models.py (Images model)
- Backend: generate_images.py
- Backend: ai_processor.py

**Issue:** First 2 in-article images may have duplicate field names causing overwrite

**Changes:**
1. Ensure `position` field is properly enforced (0, 1, 2, 3) for in-article images
2. Update image creation logic to use unique combination: `content_id + image_type + position`
3. Add validation to prevent duplicate position values for same content
4. Ensure image storage generates unique filenames (timestamp + uuid + position)

---

## TASK 3: Image Settings Configuration - Remove Mobile Options

**Files to modify:**
- Frontend: Settings.tsx (Site Settings)
- Frontend: Integration.tsx
- Backend: global_settings_models.py

**Changes:**
1. Remove `mobile_enabled` option from settings UI
2. Remove `mobile_image_size` option
3. Remove `IMAGE_TYPE_CHOICES` → `mobile` option
4. Clean up related state and form fields
5. Update `ImageSettings` interface to remove mobile fields

---

## TASK 4: Fixed Image Sizes Configuration

**Specification:**
- **Featured Image:** Fixed size (use primary model's best landscape dimension)
- **In-Article Images:**
  - 2 × Square: `1024×1024`
  - 2 × Landscape: `1280×768` (for Hi Dream) / `1344×768` (for Bria/Nano Banana)

**Files to modify:**
- Backend: global_settings_models.py
- Backend: ai_core.py
- Backend: AI functions for image generation

**Changes:**
1. Add constants for fixed sizes:
   ```
   FEATURED_SIZE = "1792x1024" (landscape, prominent)
   SQUARE_SIZE = "1024x1024"
   LANDSCAPE_SIZE = model-dependent (see model config)
   ```
2. Remove user-selectable size options where fixed
3. Update global settings with fixed defaults

---

## TASK 5: Update AI Function Calls - Alternating Square/Landscape Pattern

**Files to modify:**
- Backend: generate_images.py
- Backend: ai_core.py (generate_image method)

**Pattern:** Request 4 in-article images alternating:
- Image 1 (position 0): **Square** 1024×1024
- Image 2 (position 1): **Landscape** 1280×768 or model-specific
- Image 3 (position 2): **Square** 1024×1024
- Image 4 (position 3): **Landscape** 1280×768 or model-specific

**Changes:**
1. Modify `extract_image_prompts` to include size specification per image
2. Update batch generation to pass correct dimensions based on position
3. Store `aspect_ratio` or `dimensions` in Images model for template use

---

## TASK 6: Content View Template - Image Layout Rules

**Files to modify:**
- Frontend: frontend/src/pages/Writer/components/ContentViewTemplate.tsx or similar template file

**Layout Rules:**
| Image Shape | Layout Style |
|-------------|--------------|
| **Single Square** | 50% content width, centered or left-aligned |
| **Single Landscape** | 100% content width |
| **2 Square Images** | Side by side (50% each) |
| **Square + Landscape** | Display individually per above rules |

**Changes:**
1. Add `aspect_ratio` or `dimensions` detection from image record
2. Create layout wrapper components:
   - `SingleSquareImage` (max-w-1/2)
   - `SingleLandscapeImage` (w-full)
   - `TwoSquareImages` (grid-cols-2)
3. Update in-article image rendering to use layout rules
4. Group consecutive square images for side-by-side display

---

## TASK 7: Backend AI Model Configuration Update

### 7A. Update Model Definitions in Database/Admin

**Files to modify:**
- Backend: models.py (AIModelConfig)
- Backend: admin (Admin configuration)
- Backend: New migration file

**Changes:**
1. **Add/Update AIModelConfig records for 3 models:**
   
   | Model | Display Name | AIR ID | Tier |
   |-------|--------------|--------|------|
   | Hi Dream Full | "Hi Dream Full - Basic" | `runware:97@1` | Basic |
   | Bria 3.2 | "Bria 3.2 - Quality" | `bria:10@1` | Good |
   | Nano Banana | "Nano Banana - Premium" | `google:4@2` | Premium |

2. **Add new fields to AIModelConfig:**
   - `parameter_preset` (CharField with dropdown): quick config presets
   - `supported_sizes` (JSONField): checkboxes for valid dimensions
   - `one_liner_description` (CharField): brief model explainer

### 7B. Correct Parameter Configuration Per Model

**Based on Runware Documentation:**

#### **Hi Dream Full (runware:97@1)** - General Diffusion Model
```python
{
    "model": "runware:97@1",
    "steps": 20,  # Default, adjustable 1-100
    "CFGScale": 7,  # Default
    "scheduler": "Euler",  # Default model scheduler
    "supported_dimensions": [
        "1024x1024",  # 1:1 square
        "1280x768",   # ~5:3 landscape (close to 16:9)
        "768x1280",   # ~3:5 portrait
    ]
}
```

#### **Bria 3.2 (bria:10@1)** - Commercial-Ready
```python
{
    "model": "bria:10@1",
    "steps": 8,  # Bria default: 4-10
    "supported_dimensions": [
        "1024x1024",  # 1:1
        "1344x768",   # 16:9 landscape
        "768x1344",   # 9:16 portrait
        "1216x832",   # 3:2 landscape
        "832x1216",   # 2:3 portrait
    ],
    "providerSettings": {
        "bria": {
            "promptEnhancement": true,
            "enhanceImage": true,
            "medium": "photography",  # or "art"
            "contentModeration": true
        }
    }
}
```

#### **Nano Banana (google:4@2)** - Premium Quality
```python
{
    "model": "google:4@2",
    "supported_dimensions": [
        # 1K tier (default)
        "1024x1024",  # 1:1
        "1376x768",   # 16:9 landscape (1K)
        "768x1376",   # 9:16 portrait (1K)
        "1264x848",   # 3:2 landscape (1K)
        # 2K tier (optional)
        "2048x2048",  # 1:1 2K
        "2752x1536",  # 16:9 2K
    ],
    "resolution": "1k"  # or "2k", "4k"
}
```

### 7C. Admin Interface Enhancements

**Files to modify:**
- Backend: backend/igny8_core/admin/billing_admin.py or similar

**Changes:**
1. **Add model edit form with:**
   - Dropdown for `parameter_preset` with explainer tooltip
   - Checkboxes for `supported_sizes` (multi-select)
   - TextField for `one_liner_description`

2. **Preset Dropdown Options:**
   ```
   - "Speed Optimized" (fewer steps, lighter scheduler)
   - "Balanced" (default settings)
   - "Quality Focused" (more steps, CFG tuning)
   ```

3. **Size Checkboxes:**
   ```
   ☑ 1024×1024 (Square)
   ☑ 1280×768 (Landscape)
   ☐ 768×1280 (Portrait)
   ☑ 1344×768 (Wide Landscape)
   ```

### 7D. Global Integration Settings Update

**Files to modify:**
- Backend: global_settings_models.py

**Changes:**
1. Update `RUNWARE_MODEL_CHOICES`:
   ```python
   RUNWARE_MODEL_CHOICES = [
       ('runware:97@1', 'Hi Dream Full - Basic'),
       ('bria:10@1', 'Bria 3.2 - Quality'),
       ('google:4@2', 'Nano Banana - Premium'),
   ]
   ```

2. Add landscape size mapping per model:
   ```python
   MODEL_LANDSCAPE_SIZES = {
       'runware:97@1': '1280x768',
       'bria:10@1': '1344x768',
       'google:4@2': '1376x768',
   }
   ```

3. Add `default_square_size` = "1024x1024" (universal)

### 7E. AI Core Provider Settings

**Files to modify:**
- Backend: ai_core.py

**Changes:**
1. Update `_generate_image_runware` to handle provider-specific settings
2. Add Bria-specific parameters when model is `bria:*`
3. Add Google-specific handling for `google:*` models
4. Implement model-aware dimension validation

---

## TASK 8: Frontend Integration Settings UI

**Files to modify:**
- Frontend: Integration.tsx
- Frontend: Settings.tsx

**Changes (for user override capability):**
1. **Model Selection Dropdown:**
   - Hi Dream Full (Basic - Fast & Cheap)
   - Bria 3.2 (Quality - Commercial Safe)
   - Nano Banana (Premium - Best Quality)

2. **Image Size Selection (if override enabled):**
   - Square: 1024×1024 (all models)
   - Landscape: Auto-detected based on model OR user override

3. **Remove options:**
   - Remove desktop/mobile toggle
   - Remove custom size inputs
   - Use fixed sizes from configuration

---

## MIGRATION FILE REQUIREMENTS

Create migration: `0024_update_image_models_and_settings.py`

**Operations:**
1. Add `parameter_preset`, `supported_sizes`, `one_liner_description` to AIModelConfig
2. Update existing model records with new data
3. Remove deprecated fields (mobile_image_size, etc.)
4. Set default values for new fields

---

## EXECUTION ORDER

1. **Phase 1 - Backend Models & Config** (Tasks 7A, 7B, 7D, 7E) ✅
2. **Phase 2 - Backend Logic** (Tasks 2, 5) ✅
3. **Phase 3 - Frontend Settings** (Tasks 3, 8) ✅
4. **Phase 4 - UI Components** (Tasks 1, 6) ✅
5. **Phase 5 - Testing & Migration** (Run migrations in Docker)

---

## VALIDATION CHECKLIST

- [x] All 3 models configured with correct AIR IDs
- [x] Parameter presets documented and selectable
- [x] Image sizes correctly mapped per model
- [x] No duplicate in-article images (unique storage)
- [x] Modal width increased by 50%
- [x] Mobile options removed from UI
- [x] Alternating square/landscape pattern working
- [x] Content template displays images per layout rules
- [x] Global settings updated
- [ ] Admin interface has model config dropdowns (optional enhancement)

--- 

Completed: *Create comprehensive implementation plan* (1/1)

This plan is ready for execution. The key technical findings are:

**Model Specifications Confirmed:**
| Model | AIR ID | Square | Landscape | Steps |
|-------|--------|--------|-----------|-------|
| Hi Dream Full | `runware:97@1` | 1024×1024 | 1280×768 | 20 |
| Bria 3.2 | `bria:10@1` | 1024×1024 | 1344×768 | 20 (min 20, max 50) |
| Nano Banana | `google:4@2` | 1024×1024 | 1376×768 | Auto |