# Warning System Guide

Warning categories, severity levels, and model-specific warnings for prompt validation.

---

## Warning Structure

```json
{
  "category": "safety|quality|technical|optimization",
  "severity": "high|medium|low",
  "message": "Description of the issue",
  "recommendation": "How to fix it"
}
```

---

## Category 1: Safety Warnings (Severity: High)

Issues that may violate content policies or cause harmful output.

| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Copyright concern | Copyrighted character names, branded content without transformative context | "Consider a generic description or ensure fair use context" |
| Celebrity likeness | Real person names used for fictional scenarios | "Use generic descriptions instead of specific names" |
| Sensitive content | Violence, explicit material, illegal activities | "Modify to comply with content policies" |
| Harmful stereotypes | Biased or stereotypical representations | "Consider more respectful, nuanced representation" |
| Political sensitivity | Political figures, propaganda-style imagery | "Ensure balanced, non-inflammatory representation" |
| Religious sensitivity | Religious figures or symbols in potentially disrespectful context | "Consider cultural sensitivity and context" |

**Note:** Safety tolerance settings differ by model:
- Flux 2: 1–5 scale (default 2)
- Nano Banana Pro: 1–6 scale (default 4)
- GPT Image 1.5: Fixed policies, no user control
- Others: Provider-dependent

---

## Category 2: Quality Warnings (Severity: Medium)

Issues that will reduce output quality.

| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Vague description | Uses "beautiful", "nice", "good" without specifics | "Replace with concrete descriptors: lighting type, material, specific style" |
| Conflicting styles | Contradictory keywords ("photorealistic anime") | "Choose one style direction or specify intentional fusion" |
| Missing lighting | No lighting information specified | "Add lighting direction and quality: 'golden hour', 'soft studio lighting'" |
| Missing composition | No framing or angle specified | "Add composition: 'close-up', 'wide shot', 'eye-level perspective'" |
| Overly complex | 100+ keywords or contradictory multi-subject instructions | "Simplify to core elements. Complex scenes may confuse the model." |
| Underspecified subject | Subject lacks material/color/size details | "Add specifics: 'matte black', 'full-grain leather', 'vintage brass'" |
| Missing style | No artistic direction provided | "Specify style: 'photorealistic', 'watercolor', 'flat illustration', etc." |

---

## Category 3: Technical Warnings (Severity: Medium-High)

Model capability mismatches and parameter issues.

### Universal Technical Warnings

| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Resolution mismatch | Requested resolution exceeds model limit | "Use [alternative model] for this resolution, or reduce to [max]" |
| Unsupported feature | Requesting feature model doesn't support | "This feature is not available on [model]. Consider [alternative]" |
| Aspect ratio unavailable | Requested ratio not in model's options | "Closest available: [ratio]. Or use [model] which supports it." |

### Model-Specific Technical Warnings

**GPT Image 1.5:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Resolution limit | Any request above 1536px | "GPT Image 1.5 max is 1536px. For higher resolution, use Nano Banana Pro (4K) or Flux 2 (4MP)." |
| Fixed sizes only | Custom dimensions requested | "Only 3 sizes available: 1024×1024, 1024×1536, 1536×1024. Choose the closest match." |
| Rate limit awareness | High-volume batch request | "Tier 1: 5 images/min. Consider other providers for batch work." |
| No negative prompts | Negative prompt provided | "GPT Image 1.5 does not support negative prompts. Rephrase as positive instructions." |
| OpenAI only | User expects Fal.ai availability | "GPT Image 1.5 is only available through OpenAI API and Microsoft Foundry." |

**Grok Imagine:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Limited controls | Guidance scale or steps specified | "Grok Imagine has no guidance scale or steps parameters. Prompt quality is your primary control lever." |
| No seed | Reproducibility requested | "No visible seed parameter. Results may vary between runs." |
| No negative prompt | Negative prompt provided | "Not supported. Adjust the positive prompt to avoid unwanted elements." |
| New model caveat | Any request | "Grok Imagine is new with limited community benchmarks. Results may be less predictable." |

**Nano Banana Pro:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| No fine-tuning | Guidance or steps requested | "Nano Banana Pro has no guidance scale or steps control. Adjust prompt wording instead." |
| Resolution tier | Specific pixel dimensions requested | "Use resolution tiers: 1K, 2K, or 4K. Exact dimensions set by aspect ratio." |

**Flux 2:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| 4MP limit | Dimensions exceeding 4MP total | "Max output is 4MP (e.g., 2048×2048). Reduce dimensions." |
| Variant mismatch | Using Klein for quality-critical work | "Klein (9B) is fast but trades quality. Use Flex or Pro for production work." |
| Prompt expansion conflict | Very precise prompt with expansion enabled | "Disable prompt expansion if you need exact control over every keyword." |

**Recraft V4:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| No editing | Edit request | "Recraft V4 does not support prompt-based editing. Generate variations instead." |
| No style creation | Custom style request | "Style creation not yet available in V4. Use style description in prompt." |
| Variant selection | Vector output requested without vector variant | "Switch to 'vector' or 'pro-vector' variant for SVG output." |
| Slow Pro Vector | Time-sensitive request with Pro Vector | "Pro Vector takes ~45s. Use standard Vector (~15s) if speed matters." |

**Ideogram 3.0:**
| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Unquoted text | Text-in-image request without quotes | "Put text in quotes within the prompt for reliable rendering: \"YOUR TEXT\"" |
| Character ref limit | Multiple character references | "Ideogram 3.0 supports only 1 character reference image. Use Flux 2 for multi-reference." |
| Style code format | Invalid style code format | "Style codes must be 8-character hex strings." |

---

## Category 4: Optimization Warnings (Severity: Low)

Opportunities to improve output quality.

| Warning | Trigger | Recommendation |
|---------|---------|---------------|
| Better model available | Use case doesn't match selected model | "Consider [model] for [use case]: [reason]" |
| Underutilized features | Model has unused relevant capabilities | "This model supports [feature] — consider using it for better results" |
| Missing quality boosters | No model-specific quality keywords | "Add: [specific keywords for model]" |
| Keyword ordering | Important details buried at end of prompt | "Move key subject details to the beginning — models weight early tokens more" |
| Negative prompt available | Using Ideogram 3.0 without negative prompt | "Ideogram supports negative prompts — add exclusions for cleaner output" |
| Style codes available | Consistency needed without style codes | "Save Ideogram style codes (8-char hex) for consistent results across a campaign" |
| Color palette available | Brand colors mentioned without palette param | "Use Ideogram's color_palette parameter with hex codes and weights for precise color control" |
| Multi-reference available | Consistency needed without references | "Flux 2 supports up to 10 reference images for character/style consistency" |
| Resolution upgrade | Low resolution for print use case | "Consider Nano Banana Pro at 4K for print-quality output" |
| Vector suggestion | Logo/icon request on raster model | "Recraft V4 Vector can produce editable SVG — better for logos and icons" |

---

## Warning Priority

When multiple warnings apply, present them in this order:
1. **Safety** (always first — may block generation)
2. **Technical** (affects whether generation will succeed)
3. **Quality** (affects output quality)
4. **Optimization** (nice-to-have improvements)

Limit warnings to the most impactful 3–5 per prompt to avoid overwhelming the user.
