igny8/docs/plans/4th-jan-refactor/IMAGE_MODELS_IMPLEMENTATION_PLAN.md

📋 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

{
    "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

{
    "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

{
    "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:

   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:

   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

• All 3 models configured with correct AIR IDs
• Parameter presets documented and selectable
• Image sizes correctly mapped per model
• No duplicate in-article images (unique storage)
• Modal width increased by 50%
• Mobile options removed from UI
• Alternating square/landscape pattern working
• Content template displays images per layout rules
• 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