ai_qc/backend/visual_qc_apps/visual_readability_contrast/app.py

import os
import sys

# Add parent directory to path to import shared modules
sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))

from visual_qc_apps.flask_app_template import FlaskAppTemplate

class VisualReadabilityContrastApp(FlaskAppTemplate):
    """
    Visual Readability & Contrast Check - Combined check for digital assets.
    Merges text readability and background contrast evaluation into a single LLM call.
    """

    def __init__(self):
        prompt = """You are performing a visual quality control check on a digital marketing asset. Your task is to evaluate BOTH the readability of marketing text AND the contrast/visibility of key design elements against the background in a single comprehensive assessment.

CRITICAL: Evaluate only the MARKETING/ADVERTISING TEXT added to the creative (headlines, slogans, CTAs, promotional text). DO NOT evaluate text that is part of product packaging, labels, or bottles shown in the image. Product packaging text is not within the scope of this check.

=== PART 1: TEXT READABILITY ===

STEPS TO EVALUATE:
1. Identify marketing text elements:
   a. Headlines and main messages
   b. Slogans and taglines
   c. Calls to action (CTAs)
   d. Promotional or descriptive text added to the creative
   e. EXCLUDE: Text on product packaging, bottles, labels, or boxes

2. Examine marketing text clarity and presentation:
   a. Text size - Is it large enough to be comfortably read on digital screens?
   b. Font choice - Is the font clear, modern, and easily readable (not overly decorative)?
   c. Contrast - Does the text stand out clearly against its background?
   d. Spacing - Is there sufficient spacing between letters, words, and lines?

3. Check for overlapping and obstruction issues (CRITICAL):
   a. Text overlapping with images, making it hard to read
   b. Text overlapping with product photos where it blends into busy backgrounds
   c. Text overlapping with other text elements
   d. Elements obscuring or partially covering marketing text
   e. Text extending beyond visible boundaries
   f. Text placed over complex/busy backgrounds that reduce readability

4. Assess potential readability problems:
   a. Decorative fonts that sacrifice legibility for style
   b. Poor contrast that makes text blend into the background
   c. Text that is too small or too condensed
   d. Awkward text placement that interferes with other elements
   e. Text color that doesn't provide sufficient contrast with its background
   f. Text placed over images without proper background treatment (shadows, overlays, etc.)

5. Evaluate overall text hierarchy and layout:
   a. Headlines should be clearly distinguishable from body text
   b. Important text should be prioritized visually
   c. All marketing text should be fully visible and unobstructed
   d. Text should not compete with product images for attention

=== PART 2: BACKGROUND CONTRAST ===

6. Identify primary visual elements:
   a. Brand logo (extra scrutiny for brand consistency and visibility)
   b. Product shots or key imagery (overall product visibility, not text on packaging)
   c. Main marketing text, headlines, slogans, and calls to action

7. Check clarity and visibility:
   a. Ensure each element is immediately recognizable and legible
   b. Verify that no elements are blending into or getting lost in the background
   c. Check for text overlapping with backgrounds or images that reduce visibility

8. Evaluate color and brightness contrast:
   a. Visually verify that each key element "pops" against the background
   b. Pay special attention to the brand logo. Any condition that makes the logo less than immediately recognizable is grounds for failing
   c. If any key element (product, marketing text, logo) is difficult to distinguish from the background, consider contrast insufficient

9. Check for color conflicts:
   a. Ensure marketing text doesn't blend with similar-colored backgrounds
   b. Verify that products are clearly visible against their background
   c. Confirm the logo maintains its visibility across the entire design

10. CRITICAL - Product-background blending check (evaluate EACH product individually):
    a. Examine EVERY product in the image separately, not as a group
    b. Check if any individual product's dominant color matches or is very similar to the background color behind it
    c. Dark-colored products (black, dark grey, dark brown) on dark backgrounds = FAIL
    d. Light-colored products (white, cream, pale) on light backgrounds = FAIL
    e. A product whose edges, outline, or silhouette are hard to distinguish from the background = FAIL
    f. Even if most products have good contrast, a SINGLE product blending into the background means the product check FAILS
    g. Products should have a clear, visible boundary/edge separation from the background at all points

11. Assess overall visual hierarchy:
    a. Important elements should stand out clearly
    b. Background should support, not compete with, key content

=== PASS/FAIL CRITERIA ===

TEXT READABILITY:
- "Pass" if ALL marketing text elements are clear, readable, properly spaced, free from overlapping issues, and not competing with background elements.
- "Fail" if ANY marketing text is difficult to read, overlapping with images/backgrounds in a way that reduces legibility, obscured, poorly contrasted, cut off, or placed awkwardly over complex backgrounds.

BACKGROUND CONTRAST:
- "Pass" only if ALL key marketing elements (logo, EVERY individual product, marketing text) are sharp, legible, and clearly distinct from the background.
- "Fail" if ANY single product blends into the background (e.g., dark product on dark background, light product on light background, edges not clearly distinguishable).
- "Fail" if any critical element has low contrast, appears to blend in, overlaps poorly with background, or is difficult to see.
- IMPORTANT: Evaluate each product INDIVIDUALLY. If there are 3 products and 1 blends into the background, the result is FAIL even if the other 2 are fine.

OVERALL:
- "Pass" only if BOTH text readability AND background contrast pass.
- "Fail" if EITHER text readability OR background contrast fails.

YOUR OUTPUT MUST BE a JSON code block with this structure:

{
  "visual_readability_contrast": "Pass" or "Fail",
  "text_readability": {
    "result": "Pass" or "Fail",
    "readability_score": "High", "Medium", or "Low",
    "analysis_details": "Detailed explanation of which marketing text elements were checked and what issues were found",
    "issues_found": ["List specific problems"]
  },
  "background_contrast": {
    "result": "Pass" or "Fail",
    "analysis_details": "Detailed explanation of what was checked and findings for logo, each product, and marketing text",
    "elements_checked": {
      "logo": "Pass/Fail - Brief explanation",
      "product_1": "Pass/Fail - [Product name/description]: explain contrast with background",
      "product_2": "Pass/Fail - [Product name/description]: explain contrast with background",
      "marketing_text": "Pass/Fail - Brief explanation"
    }
  },
  "recommendations": [
    "Specific recommendation 1",
    "Specific recommendation 2"
  ]
}

CRITICAL:
1. Always provide detailed analysis for BOTH text readability and background contrast
2. Focus ONLY on marketing/advertising text, NOT product packaging text
3. Specifically call out overlapping issues if text is placed over images or backgrounds
4. If there is NO marketing text in the asset, state "No marketing text found - N/A"
5. Never return just "Pass" or "Fail" without detailed explanation
6. The overall visual_readability_contrast result must be "Fail" if either subsection fails"""

        super().__init__(__name__, prompt)


if __name__ == "__main__":
    app = VisualReadabilityContrastApp()
    app.run(debug=True)