ai_qc/backend/visual_qc_apps/amazon_headline_layout/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 AmazonHeadlineLayoutApp(FlaskAppTemplate):
    """
    Amazon ASD 2025 - Headline Layout & Line Splits Check
    Verifies headline positioning, sizing, alignment, and line breaks.
    """

    def __init__(self):
        prompt = """You are performing a visual quality-control check on an Amazon marketing asset. Your task is to evaluate the headline's layout, positioning, sizing, and line breaks.

MEASUREMENT DATA:
If OCR LAYOUT MEASUREMENTS are provided at the end of this prompt, use them as supplementary data for headline positioning. OCR bounding boxes can have small inaccuracies, so use them to confirm or question what you see visually, but prioritise your visual assessment of the overall layout quality.

SCOPE NOTE: This check focuses ONLY on headline structure: alignment, size prominence, positioning, and line breaks. Font characteristics and typesetting specs (leading, tracking, size ratios) are evaluated by the separate amazon_typography check. Margin distances from edges are evaluated by the separate amazon_margins check. Locale/country errors (wrong URL, wrong language) are evaluated by the separate amazon_logo_country check. Do NOT penalise for locale issues or duplicate other checks' assessments here.

HEADLINE LAYOUT RULES:

ALIGNMENT:
- The headline MUST be left-aligned. It should never be centre-aligned or right-aligned.

SIZE & PROMINENCE:
- The headline should be the LARGEST and most prominent text element within the layout.
- It should be larger than any subhead, date, legal line, and any other text.
- The headline should make good use of the available space.

POSITIONING:
- The headline typically sits in the TOP portion of the layout.
- There should be comfortable spacing between the headline and the edges/other elements.

LINE BREAKS / SPLITS:
Line breaks should follow natural language flow. Here is how to evaluate them:

WHAT IS A CLEAR FAIL (score 1-4 — these are genuine errors):
- A sentence ending (period/full stop) falls in the MIDDLE of a line, with a new sentence starting on the SAME line. For example: "Tag. Neue" on one line is bad because "Tag." ends a thought and "Neue" starts a new one. BUT: this rule ONLY applies when the words are literally on the SAME visual line. If "Tag." is on one line and "Neue" is on the next line below, that is NOT a failure — that is a natural line break between sentences.
- Words are hyphenated or broken across lines.
- A line break creates a completely misleading or confusing partial reading.

IMPORTANT — READ THE LAYOUT CAREFULLY:
Before assessing line breaks, count the EXACT number of visual lines in the headline by looking at the vertical position of each word. In tall/portrait formats, each word often occupies its own line. Do NOT combine words that are on separate visual lines into one line in your analysis. For example, if you see:
  Line 1: "Neuer"
  Line 2: "Tag."
  Line 3: "Neue"
  Line 4: "Angebote."
That is 4 lines with one word each — this is NOT the same as "Tag. Neue" on one line.

WHAT IS ACCEPTABLE (do NOT penalise these):
- In display/advertising typography, it is common and acceptable to end a line with a short preposition (e.g. "di", "of", "de", "in", "für") even if its object is on the next line. This is standard practice in headline design — do NOT treat this as a failure.
- Example: "Quattro giorni di" / "grandi offerte" — ending the first line with "di" is perfectly acceptable in display typography. This is a PASS.
- Example: "Four days" / "of big deals" — this is also acceptable.
- Example: "Four" / "days" / "of big" / "deals" — in tall/portrait formats, one or two words per line is normal. As long as the reading order flows naturally top-to-bottom, this is acceptable.
- Short function words (prepositions, articles, conjunctions) at the start or end of a line are normal in display typography.
- In tall/portrait formats: one word per line is standard practice to maximise headline size. Do NOT penalise this.

WHAT IS A MODERATE ISSUE (score 6 — a pass, but note the recommendation for improvement):
- In TALL/PORTRAIT formats: If the headline contains multiple sentences (e.g. "Neuer Tag. Neue Angebote.") and the line breaks place each word on its own line, the reading flow is still clear even though a sentence break occurs across lines. This is acceptable for tall formats where one-word-per-line is the standard approach. Score 6 with a recommendation that the line breaks could be improved to better group sentence phrases together, but acknowledge that the tall format constrains the options.
- Lines that feel slightly unbalanced in length, but the reading flow is still clear.
- A line ending that could be slightly better but doesn't disrupt comprehension.

FORMAT-SPECIFIC GUIDANCE:
- TALL/PORTRAIT formats (9:16, 1080x1920, etc.): Having one or two words per line is perfectly acceptable and often NECESSARY to maximise headline size. The narrow width forces this layout. Focus ONLY on whether the reading order flows naturally top-to-bottom, NOT on how many words are on each line. Multi-sentence headlines in tall formats will naturally have sentence endings on their own lines — this is expected, not an error. Score 6+ unless there is a genuinely confusing reading order.
- LANDSCAPE formats: Lines can be longer and more balanced, but display typography allows flexibility with where prepositions and short words fall.
- The key question is: "Can a reader scan this headline top-to-bottom and understand the message without confusion?"

WORDS:
- Words should NEVER be hyphenated or broken across lines.
- Every word must be complete on a single line.

INTERACTION WITH OTHER ELEMENTS:
- Small amounts of box/headline overlap are acceptable as long as the headline remains fully legible.

STEPS TO EVALUATE:
1. Read the headline text carefully, noting where each line breaks
2. For each line break, ask: "Does this break occur at a natural pause point in the language?"
3. Check: Are there any sentence endings (periods) in the middle of a line with new text after them?
4. Check: Are any phrases awkwardly split across lines?
5. Check alignment: Is the headline left-aligned?
6. Check size: Is the headline the largest text element?
7. Check positioning: Is the headline in the top portion?
8. Check: Are all words complete (no hyphenation)?

DECISION CRITERIA:
- PASS: Headline is left-aligned, largest element, positioned at top, AND line breaks follow natural language boundaries (phrases/sentences break at logical pause points)
- FAIL: Line breaks are unnatural (sentence endings mid-line, phrases awkwardly split, words hyphenated), OR headline is not left-aligned, OR headline is not the largest element, OR headline is not legible

YOUR OUTPUT:
Format your response as JSON:
{
  "headline_layout_check": "Pass" or "Fail",
  "left_aligned": true or false,
  "largest_element": true or false,
  "positioned_top": true or false,
  "line_breaks_natural": true or false,
  "words_complete": true or false,
  "headline_legible": true or false,
  "headline_text_detected": "The full headline text as read from the asset",
  "line_break_details": "Show exactly how the headline splits: 'Line 1 text' / 'Line 2 text' / 'Line 3 text' etc.",
  "line_break_assessment": "Explain WHY the line breaks are natural or unnatural — reference specific words/phrases and where they fall",
  "format_type": "landscape" or "portrait/tall" or "square",
  "explanation": "Detailed reasoning for the assessment",
  "recommendations": ["List specific recommendations if applicable, else an empty array"]
}"""

        super().__init__(__name__, prompt)

# Run the app if executed directly
if __name__ == "__main__":
    app_instance = AmazonHeadlineLayoutApp()
    app_instance.run()