ALwrity/docs/image studio/IMAGE_STUDIO_EDITING_UI_REQUIREMENTS.md

Image Studio Editing - UI Requirements for Model Selection

Date: Current Session
Status: 📋 Requirements Document
Purpose: Define UI requirements for model selection, education, and auto-routing

---

🎯 Core Requirements

1. Model Selection UI

1.1 Model Selector Component

• Location: Edit Studio sidebar or main panel
• Type: Dropdown/Select with search capability
• Display:
  • Model name
  • Cost per edit
  • Quality tier badge (Budget/Mid/Premium)
  • Quick info icon (tooltip)

1.2 Model Information Panel

• Trigger: Click on info icon or "Learn More" button
• Content:
  • Model description
  • Use cases
  • Cost details
  • Max resolution
  • Special features (multi-image, typography, etc.)
  • Comparison with other models

1.3 Model Comparison View

• Trigger: "Compare Models" button
• Display: Side-by-side comparison table
• Columns: Model name, Cost, Max Res, Features, Best For
• Filter: By tier (Budget/Mid/Premium), by use case

---

🔄 Auto-Detection & Routing

2.1 Default Behavior (No Model Selected)

• Auto-select: Best model based on:
  1. Operation type: Match model capabilities to operation
  2. Image resolution: Select model that supports input resolution
  3. User tier: Prefer budget models for free users, premium for pro users
  4. Cost optimization: Default to lowest cost model that meets requirements

2.2 Smart Recommendations

• Display: "Recommended for you" badge on auto-selected model
• Reason: Show why this model was selected (e.g., "Best quality for 4K images")

2.3 Fallback Logic

• If no model matches: Use first available model
• If model unavailable: Show error with alternative suggestions
• If user has insufficient credits: Suggest budget alternative

---

📚 User Education

3.1 Model Information Cards

Each model should display:

┌─────────────────────────────────────┐
│ [Model Name] [Tier Badge]          │
│                                     │
│ 💰 Cost: $0.02 per edit            │
│ 📐 Max Resolution: 1536×1536        │
│ ⭐ Best For:                        │
│   • Quick edits                     │
│   • Budget-conscious projects       │
│   • Multi-image editing             │
│                                     │
│ ✨ Features:                        │
│   • ControlNet support             │
│   • Bilingual (CN/EN)              │
│   • Up to 3 reference images        │
│                                     │
│ [Learn More] [Select]               │
└─────────────────────────────────────┘

3.2 Use Case Examples

For each model, show:

• Example prompts: "Change background to beach", "Add text overlay"
• Before/After examples: Visual examples (if available)
• When to use: Clear guidance on when this model is best

3.3 Cost Transparency

• Show estimated cost: Before processing
• Cost breakdown: Per operation
• Subscription impact: How many edits user can make with current credits
• Cost comparison: "This costs 2x more but provides 4K quality"

---

🎨 UI Components Needed

4.1 ModelSelector Component

interface ModelSelectorProps {
  operation: string;
  imageResolution?: { width: number; height: number };
  userTier?: 'free' | 'pro' | 'enterprise';
  onModelSelect: (modelId: string) => void;
  selectedModel?: string;
}

Features:

• Search/filter models
• Group by tier
• Show recommendations
• Display cost and features

4.2 ModelInfoCard Component

interface ModelInfoCardProps {
  model: EditingModel;
  isSelected: boolean;
  isRecommended: boolean;
  onSelect: () => void;
  onLearnMore: () => void;
}

Features:

• Model details
• Cost display
• Feature badges
• Comparison button

4.3 ModelComparisonDialog Component

interface ModelComparisonDialogProps {
  models: EditingModel[];
  open: boolean;
  onClose: () => void;
  onSelect: (modelId: string) => void;
}

Features:

• Side-by-side comparison
• Filterable table
• Sortable columns
• Quick select

4.4 ModelRecommendationBadge Component

interface ModelRecommendationBadgeProps {
  reason: string;
  model: EditingModel;
}

Features:

• Show recommendation reason
• Link to model info
• Dismissible

---

🔧 Backend API Requirements

5.1 Get Available Models Endpoint

GET /api/image-studio/edit/models
Query params:
  - operation?: string (filter by operation type)
  - tier?: 'budget' | 'mid' | 'premium'
  - min_resolution?: number
  - max_cost?: number

Response:
{
  "models": [
    {
      "id": "qwen-edit-plus",
      "name": "Qwen Image Edit Plus",
      "cost": 0.02,
      "tier": "budget",
      "max_resolution": [1536, 1536],
      "capabilities": ["general_edit", "multi_image"],
      "description": "...",
      "use_cases": ["...", "..."],
      "features": ["ControlNet", "Bilingual"]
    }
  ],
  "recommended": {
    "model_id": "qwen-edit-plus",
    "reason": "Best quality for budget tier"
  }
}

5.2 Get Model Recommendations Endpoint

POST /api/image-studio/edit/recommend
Body:
{
  "operation": "general_edit",
  "image_resolution": { "width": 1024, "height": 1024 },
  "user_tier": "free",
  "preferences": {
    "prioritize_cost": true,
    "prioritize_quality": false
  }
}

Response:
{
  "recommended_model": "qwen-edit",
  "reason": "Lowest cost option that supports your image resolution",
  "alternatives": [
    {
      "model_id": "qwen-edit-plus",
      "reason": "Better quality for $0.02 more"
    }
  ]
}

---

📊 Model Data Structure

6.1 EditingModel Interface

interface EditingModel {
  id: string;
  name: string;
  description: string;
  cost: number;
  cost_8k?: number; // For models with tiered pricing
  tier: 'budget' | 'mid' | 'premium';
  max_resolution: [number, number];
  capabilities: string[];
  use_cases: string[];
  features: string[];
  supports_multi_image: boolean;
  supports_controlnet: boolean;
  languages: string[];
  api_params: {
    uses_size: boolean;
    uses_aspect_ratio: boolean;
    uses_resolution: boolean;
    supports_guidance_scale: boolean;
    supports_seed: boolean;
  };
}

---

🎯 User Experience Flow

7.1 First-Time User

1. User opens Edit Studio
2. System auto-selects recommended model
3. Shows "Recommended for you" badge with explanation
4. User can click "Why this model?" to learn more
5. User can change model if desired

7.2 Returning User

1. User opens Edit Studio
2. System remembers last selected model (if applicable)
3. Shows last used model as default
4. User can change model anytime

7.3 Model Selection Flow

1. User clicks model selector
2. Sees list of available models grouped by tier
3. Can filter by cost, resolution, features
4. Can click "Compare" to see side-by-side
5. Selects model
6. System shows estimated cost
7. User confirms and proceeds

---

📝 Implementation Checklist

Backend

• Create /api/image-studio/edit/models endpoint
• Create /api/image-studio/edit/recommend endpoint
• Add model metadata to WaveSpeedEditProvider.get_available_models()
• Implement recommendation logic
• Add model selection to EditStudioService

Frontend

• Create ModelSelector component
• Create ModelInfoCard component
• Create ModelComparisonDialog component
• Create ModelRecommendationBadge component
• Integrate into EditStudio.tsx
• Add model selection to request payload
• Display cost estimate before processing
• Show model info tooltips

Documentation

• Create model comparison guide
• Add use case examples for each model
• Document recommendation algorithm
• Create user guide for model selection

---

🎨 Design Considerations

8.1 Visual Hierarchy

• Primary: Selected model (highlighted)
• Secondary: Recommended model (badge)
• Tertiary: Other available models

8.2 Information Density

• Compact view: Model name, cost, tier badge
• Expanded view: Full details, use cases, features
• Comparison view: Side-by-side table

8.3 Accessibility

• Keyboard navigation
• Screen reader support
• Clear labels and descriptions
• Color contrast for badges

---

Ready for implementation - Backend API and recommendation logic should be completed first