hm_ai_qc_report_tool/README.md

Unified HM QC Platform

Version: 2.1.0 Status: Production (Deployed) Deployed at: https://ai-sandbox.oliver.solutions/hm-ai-qc-report

A comprehensive quality control platform for H&M marketing assets with AI-powered validation, video matching, and consolidated reporting.

---

Overview

The platform integrates six tools into a single web application:

1. Reporting - Consolidated QC reports from Box.com with search history
2. HM QC - AI-powered image quality control (text legibility, language, quality, pricing)
3. Video QC - AI-powered video quality control (frame-by-frame analysis)
4. Video Master Adot - Campaign-based master-to-adaptation video matching via Box
5. Campaigns - Campaign presentation and media plan management for QC reference
6. Usage Dashboard - API usage tracking, token counts, and cost estimates

Key Features

• Unified tabbed interface with H&M branding
• Local username/password authentication
• Multi-provider AI: OpenAI GPT-4o and Google Gemini 2.5 Flash
• Campaign presentation & media plan upload for guideline-based QC validation
• Global pricing reference for currency symbol/format validation per country
• Real-time progress tracking (SSE + polling)
• Docker deployment with Apache reverse proxy
• Usage tracking with estimated costs per API call

---

Deployment

Docker (Production)

# Clone from Bitbucket
git clone git@bitbucket.org:zlalani/hm_ai_qc_report_tool.git /opt/hm-qc-app
cd /opt/hm-qc-app

# Configure environment
cp .env.example .env
# Edit .env with production values (see .env.example)
# Generate password: python3 deploy/generate_password.py

# Build and start
docker compose build
docker compose up -d

# Create database tables
docker exec hm-qc-app python3 -c "from app import app; from core.models.database import db; app.app_context().push(); db.create_all(); print('Tables created')"

The app runs on 127.0.0.1:5050 inside Docker. Configure Apache or Nginx as reverse proxy — see deploy/ for config snippets.

Common Commands

docker compose logs -f              # Tail logs
docker compose restart              # Quick restart
docker compose down && docker compose up -d --build  # Rebuild after code changes
git pull && docker compose down && docker compose up -d --build  # Deploy update

---

Modules

1. Reporting

Consolidated QC report search from Box.com and local database.

Features:

• Job number search (single or comma-separated for multi-job)
• Async search with real-time progress bar
• Box reports saved locally for instant re-viewing (no re-fetch)
• Previous Box Reports section with View/Delete
• Dashboard with designer-friendly error display
• Export: HTML and CSV (full or errors-only)

Workflow: Search job number -> Progress bar -> Dashboard with aggregated results

2. HM QC

AI-powered image quality control for marketing assets.

Profile: H&M Image Check (3 checks)

• Filename Parse (30%) - Flexibly extracts country code, language, dimensions, campaign number from multiple H&M naming conventions (Display, DOOH, OOH, SOME STATIC, Social, POS)
• Image Quality (40%) - AI visual assessment with strict text legibility rules; validates against campaign presentation guidelines when available
• Price/Currency (30%) - Validates currency symbol/format against global pricing reference; validates actual prices against campaign media plan when available

AI Quality Check evaluates:

• Text & title legibility (CRITICAL - illegible text = automatic fail)
• Language word validation (avoids false positives like "Rock" = German for skirt)
• Campaign guideline compliance (typography, layout, copy, logo placement)
• Image quality, color, composition
• Logo and branding clarity

Features:

• Single and batch file upload (up to 100 files)
• LLM provider choice: OpenAI GPT-4o or Google Gemini 2.5 Flash
• Campaign presentation dropdown to validate against campaign guidelines
• Previous QC Reports with View/Delete and Download
• HTML report generation with per-check scoring
• Usage tracking (tokens + estimated cost)

Workflow: Upload -> Configure (provider + campaign + job number) -> Execute -> Results

3. Video QC

AI-powered video quality control with frame-by-frame analysis.

Checks:

• Visual Quality (50%) - Language consistency + text legibility across all frames
• Censorship (50%) - Body coverage compliance (only for _CEN market files, skipped otherwise)

How it works:

1. Extracts 1 frame per second from the video
2. Stitches frames into a labeled grid image
3. Sends grid to AI for analysis (1 API call per check)
4. Language check includes false-positive prevention (e.g., "Rock" = skirt in German)

Features:

• LLM provider choice (OpenAI / Google Gemini)
• CEN market auto-detection from filename
• Previous Video QC Reports with View/Delete
• Usage tracking

Workflow: Upload video -> Configure -> Execute (frame extraction + AI) -> Results

4. Video Master Adot

Campaign-based master-to-adaptation video matching using Box.com integration.

How it works:

1. User enters campaign name
2. System searches Box for campaign folder, finds Global Masters and Regional Masters
3. Preview shows: master count, countries, adaptation count
4. Phase 1: Downloads each master temporarily, fingerprints it (~50KB), deletes video
5. Phase 2: Downloads each adaptation temporarily, matches against fingerprints, deletes video
6. Results: per-master adaptation mapping, unmatched items, match rate

Matching Engine (4-tier cascade):

• Stage 0: Metadata filtering (80-95% reduction)
• Tier 1: Perceptual hash matching
• Tier 2: AKAZE feature verification
• Tier 3: AI Vision fallback (smart triggering)

Storage: Only fingerprints (~50KB/master) stored permanently. Videos deleted after processing.

Box Folder Structure:

CAMPAIGNS/{campaign_name}/
├── Global Masters/          (various casing)
│   ├── DOOH/
│   ├── DS/
│   ├── OLV/
│   └── ... (video files with MASTER in name)
└── Regional Masters/        (various casing)
    ├── DE/ (country code folders)
    ├── FR/
    └── ...

5. Campaigns

Campaign presentation and pricing reference management.

Purpose: Upload campaign-specific documents that QC checks reference when validating assets.

Document Types:

• Campaign Presentation (PDF) - Creative guidelines with typography specs, layout rules, copy text, ratio-specific mockups. Parsed via LlamaParse (text + page images).
• Media Plan / Price Sheet (Excel .xlsx) - Product names, prices, and currency per country/language. Parsed via openpyxl into structured text.
• Global Pricing Reference (PDF) - Single document mapping all countries to currency symbol, position, and format. Parsed once into storage/reference/global_pricing.json.

Workflow:

1. Upload campaign presentation PDF for a campaign (e.g., 1022B) — leave "has pricing" unchecked
2. Upload media plan Excel for the same campaign ID — check "Contains campaign-specific pricing"
3. Both documents are linked by Campaign ID and loaded together during QC
4. On HM QC or Video QC configure page, select the campaign from the dropdown

Features:

• Multiple documents per campaign (guidelines + media plan)
• Auto-polling: status updates in-place when parsing completes
• View parsed content and page images
• Global pricing reference upload (format-only, not actual prices)
• API endpoints for QC modules: /campaigns/api/list, /campaigns/api/<campaign_id>

6. Usage Dashboard

API usage tracking across all tools.

Displays:

• Summary cards: total API calls, tokens used, estimated cost (USD)
• Breakdowns: by provider, model, tool, user
• Recent API calls table with full details
• Time filters: All Time, 30 Days, 7 Days, Today

Cost estimates based on per-model token pricing (GPT-4o, Gemini 2.5 Flash, etc.)

---

Configuration

Environment Variables (.env)

# Authentication
AUTH_USERS=admin:pbkdf2:sha256:600000$$salt$$hash

# Session
SESSION_COOKIE_PATH=/hm-ai-qc-report

# Box
BOX_CONFIG_PATH=config/box_config.json
BOX_REPORT_FOLDER_ID=133295752718
BOX_CAMPAIGNS_FOLDER_ID=156182880490

# Flask
SECRET_KEY=<generate-random-key>
FLASK_ENV=production

# Database (use absolute path for Docker)
DATABASE_URI=sqlite:////app/database/qc_platform.db

# LLM Providers
OPENAI_API_KEY=<your-key>
GOOGLE_API_KEY=<your-key>

Note: $$ in AUTH_USERS hash is required for Docker Compose (escapes $).

---

Architecture

Tech Stack

• Backend: Flask 3.0, SQLAlchemy, Gunicorn
• Frontend: Bootstrap 5, Vanilla JS, Server-Sent Events
• AI: OpenAI GPT-4o, Google Gemini 2.5 Flash (via google-generativeai)
• Video: FFmpeg, OpenCV (AKAZE), Chromaprint
• Storage: Box.com (JWT auth), SQLite
• Deployment: Docker, Apache reverse proxy

Directory Structure

hm_ai_qc_report_tool/
├── app.py                    # Application factory
├── config.py                 # Configuration
├── Dockerfile                # Docker image
├── docker-compose.yml        # Docker services
├── deploy/                   # Deployment scripts & configs
│
├── core/                     # Shared infrastructure
│   ├── auth/                 # Session-based authentication
│   ├── models/               # Database models (QCReport, UsageLog, CampaignPresentation)
│   ├── services/             # LLM config, Box client
│   └── utils/                # Progress tracker, report parser
│
├── modules/
│   ├── hm_qc/               # HM QC (checks, executor, profiles)
│   ├── video_qc/            # Video QC (executor, frame extraction)
│   ├── video_master/         # Video Master (matching engine, campaign matcher)
│   ├── campaigns/            # Campaign presentations & pricing reference
│   ├── reporting/            # Reporting (aggregator, Box search, cache)
│   └── usage/                # Usage dashboard
│
├── templates/                # Shared templates (base.html, login.html)
├── static/                   # CSS, JavaScript
├── database/                 # SQLite database
└── storage/                  # Reports, fingerprints, campaigns, reference

---

Security

• Local username/password auth with PBKDF2/scrypt hashing
• Session-based with before_request login enforcement
• No hardcoded API keys (all from environment)
• Docker container binds to 127.0.0.1 only (not exposed to internet)
• HTTPS via Apache with wildcard SSL certificate
• httpOnly, Secure, SameSite=Lax cookies

---

License

Proprietary - H&M Hennes & Mauritz AB