ai_qc/backend/README.md

Visual AI QC - AI-Powered Quality Control Platform

AI-driven visual quality control system for marketing materials, advertisements, and design assets

Overview

Visual AI QC is an intelligent quality control platform that uses advanced AI (OpenAI GPT-4o and Google Gemini 2.5 Pro) to automatically analyze visual and video content against brand guidelines, technical specifications, and design best practices. The system provides comprehensive feedback, scoring, and recommendations for improving assets across 75 specialized QC checks, 14 profiles, and 8 clients.

Key Features

• AI-Powered Analysis: Leverages both OpenAI GPT-4o and Google Gemini 2.5 Pro for comprehensive visual analysis
• Video QC: Native video analysis using Gemini's video understanding (mp4, mov, avi, webm)
• OCR Layout Measurement: Tesseract OCR provides pixel-level measurements for margin, alignment, and spacing checks
• Multi-Client Platform: 8 client workspaces (Diageo, Unilever, L'Oreal, Amazon, Boots, Dow Jones, Honda, General)
• 14 QC Profiles: Brand-specific and general-purpose profiles with weighted scoring
• Real-Time Progress Tracking: Live analysis progress with batch-based parallel processing
• PDF Brand Guidelines: Upload multi-page PDF guidelines with automatic LLM summarization
• Media Plan Integration: Upload Excel media plans for automatic asset spec validation
• Enterprise Authentication: Microsoft Azure AD with MSAL/PKCE and silent token refresh
• User Access Control: Default-deny per-user client access. Admins grant/revoke client visibility; all changes audit-logged
• Admin Panel: Platform-wide usage analytics, user tracking, cost estimation, and user-access management
• Client-Scoped Reporting: Per-client usage dashboards with date range filtering
• Profile Versioning: Automatic version control when profiles are edited

System Architecture

Visual AI QC Platform
+-- Authentication Layer (MSAL/Azure AD with silent refresh)
|   +-- JWT Token Validator (jwt_validator.py)
|   +-- Auth Middleware (auth_middleware.py)
|   +-- httpOnly Cookie Sessions
+-- Web Interface (web_ui.html)
+-- API Server (api_server.py) - Parallel batch processing
+-- LLM Engine (llm_config.py)
|   +-- OpenAI GPT-4o (image analysis)
|   +-- Gemini 2.5 Pro (image + video analysis)
+-- OCR Engine (ocr_measurement.py) - Tesseract pixel measurements
+-- QC Check Modules (visual_qc_apps/) - 75 checks
+-- Profile System (profiles/) - 14 profiles
+-- Client Config (client_config.py) - 8 clients
+-- Brand Guidelines DB (brand_guidelines/)
+-- Media Plan Processor (media_plan_processor.py)
+-- PDF Processor (pdf_processor.py)
+-- Usage Tracker (usage_tracker.py)
+-- Output Reports (output/)

Quick Start

Prerequisites

• Python 3.8+
• OpenAI API Key
• Google AI API Key
• Microsoft Azure AD account (for authentication)
• Tesseract OCR (optional, for pixel-level measurements): brew install tesseract (macOS) or sudo apt install tesseract-ocr (Ubuntu)

Installation

1. Clone and Setup:

   cd ai_qc/backend
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

2. Configure Development Environment:

   cp config/.env.template config/development.env
   # Edit config/development.env with your API keys and Azure AD config
   

3. Start Development Server:

   ./scripts/run-local.sh
   # Access at http://localhost:7183
   

Deploying to Dev / Prod

The dev server (optical-dev.oliver.solutions/ai_qc/) tracks the develop branch. Prod will track tagged releases on main. Both use the same deploy scripts; only the mode argument differs.

ssh <server>
cd /opt/ai_qc

# Deploy
backend/scripts/deploy.sh dev                   # pulls develop
backend/scripts/deploy.sh prod v1.2.0           # checks out tag v1.2.0
backend/scripts/deploy.sh dev --dry-run         # preview only

# Recover
backend/scripts/rollback.sh last                # revert last deploy
backend/scripts/rollback.sh <commit-hash>       # revert to specific commit

# Check
backend/scripts/health-check.sh                 # exits 0 if healthy

The deploy script captures a rollback checkpoint before applying, re-runs pip install only if requirements.txt changed, restarts the systemd service, and auto-rolls back on smoke-test failure.

See CLAUDE.md for full environment and branch strategy.

Clients

Client	Profiles	Description
Diageo	diageo_key_visual, diageo_packaging, static_general, video_general	Spirits brand visual and packaging QC
Unilever	unilever_key_visual, unilever_packaging, static_general, video_general	FMCG key visual and packaging QC with zero-score logic
L'Oreal	loreal_static, static_general, video_general	Beauty brand static QC with strict grading (any check <6 = Fail)
Amazon	amazon_static, static_general, video_general	ASD 2025 design compliance with OCR measurements
Boots	boots_static, static_general, video_general	Retail promotional artwork compliance
Dow Jones	dow_jones_static, marketwatch_static, wsj_static, static_general, video_general	Corporate + sub-brand QC for DJ, MarketWatch, WSJ
Honda	static_general, video_general	Automotive marketing QC
General / Other	static_general, video_general, inclusive_accessibility	General-purpose and accessibility checks

QC Profiles

Static Profiles

Profile	Checks	Scale	Description
General Check	10	100-point	General-purpose QC with even weighting
Static General	10	100-point	Baseline digital static asset QC used by all clients
Unilever Key Visual	15	120-point	Unilever brand guidelines with bonus check zero-scoring
Unilever Packaging	17	100-point	Unilever packaging design standards
Diageo Key Visual	11	100-point	Diageo brand guidelines for key visuals
Diageo Packaging	13	100-point	Diageo packaging design standards
L'Oreal Static	4	100-point	Focused L'Oreal QC (any check <6 = overall Fail)
Amazon Static	6	100-point	ASD 2025 compliance with OCR support
Boots Static	5	100-point	Retail compliance (any check <6 = overall Fail)
Dow Jones Static	5	100-point	Corporate brand QC
MarketWatch Static	6	100-point	MarketWatch sub-brand QC
WSJ Static	6	100-point	Wall Street Journal sub-brand QC
Inclusive Accessibility	2	100-point	Accessibility and inclusive design

Video Profile

Profile	Checks	Scale	Description
Video General	4	100-point	Video QC using Gemini native video analysis

Video checks: video_visual_quality, video_brand_consistency, video_text_legibility, video_pacing_flow

Video analysis uses Gemini's File Upload API to process the full video (motion, transitions, temporal flow) rather than just extracting frames. Gemini is automatically selected for video files regardless of profile LLM setting.

Amazon QC Checks (with OCR)

The 6 Amazon checks have clearly defined scope boundaries to prevent cross-check penalization:

Check	Scope	OCR Enhanced
amazon_required_elements	Element presence only (not content correctness)	No
amazon_logo_country	Locale/country URL and logo correctness	No
amazon_typography	Font, size ratios, leading, tracking, spacing, ligatures	Yes
amazon_headline_layout	Alignment, prominence, positioning, line breaks	Yes
amazon_margins	Margin distances, left-alignment consistency	Yes
amazon_element_placement	Box positioning, cropping rules, tape visibility	No

OCR provides Tesseract pixel-level measurements to the 3 layout-sensitive checks. Checks gracefully fall back to visual estimation when OCR is unavailable.

Scoring System

Individual Check Scores

• Each check scores 1-10
• 8-10: Pass (Green)
• 5-7: Adequate (Yellow)
• 1-4: Fail (Red)

Overall Score

• Weighted average scaled to 100 points
• Weights defined per-profile
• Special rules: L'Oreal and Boots profiles fail overall if any individual check scores below 6

Grades

• A (85-100): Excellent
• B (70-84): Good
• C (50-69): Adequate
• D (35-49): Poor
• F (0-34): Fail

Supported File Types

Input

• Images: PNG, JPG, JPEG, BMP, WebP, GIF, TIFF
• PDFs: First page extracted as image for analysis
• Video: MP4, MOV, AVI, WebM, MKV, WMV, FLV (Gemini only)

Brand Guidelines

• PDF: Multi-page with automatic text extraction and LLM summarization
• Images: PNG, JPG, GIF, JPEG
• Excel: XLSX/XLS for media plans and localization matrices

Output

• HTML Reports: Visual reports with expandable sections and scoring
• JSON Data: Raw analysis data for programmatic processing

Authentication

Azure AD with MSAL

• PKCE security flow for single-page applications
• httpOnly cookie session management
• Silent token refresh every 45 minutes (sessions last full workday)
• Proactive + reactive refresh to prevent session expiry
• localStorage-based MSAL cache for cross-tab persistence

Admin Panel

Two tabs — Usage Overview and User Access:

• Usage Overview: platform-wide stats (users, analyses, cost) + per-user breakdown
• User Access: search users, toggle per-client visibility, promote/demote admins

Admin role and per-user client grants live in backend/user_access.json (bootstrapped on first start with nick.viljoen@brandtech.plus as the sole admin). All grant/revoke/promote/demote actions are logged as access_change events in backend/usage_logs/.

User Access Control

New users default to the General client only. Admins grant per-client visibility through the admin panel. Client-scoped endpoints enforce access server-side (403 with code: "client_access_denied" on denied requests), so frontend filtering alone isn't the security boundary. Revocation during an active session bounces the user back to the client picker with a toast.

API Endpoints

Authentication

Method	Endpoint	Description
POST	/auth/login	Validate MSAL token, create session
POST	/auth/logout	Clear session
GET	/auth/status	Check auth status, log user visit

Analysis

Method	Endpoint	Description
POST	/api/start_analysis	Start async analysis (auth required)
GET	/api/progress/{session_id}	Get real-time progress
POST	/api/process_file	Direct file processing (auth required)

Profiles & Guidelines

Method	Endpoint	Description
GET	/api/profiles	List profiles for client
POST	/api/profiles	Create new profile (auto-versioned)
PUT	/api/profiles/{id}	Edit profile (creates new version)
POST	/api/brand_guidelines	Upload brand guideline
GET	/api/brand_guidelines/{id}/status	Check PDF processing status

Admin & Reporting

Method	Endpoint	Description
GET	/api/admin/check	Check if user is admin
GET	/api/admin/users	Get all platform users (admin only)
GET	/api/admin/user_access	List users with their client grants (admin only)
PUT	/api/admin/user_access/<email>	Set client list for a user (admin only)
POST	/api/admin/user_access/<email>/promote	Grant admin role (admin only)
POST	/api/admin/user_access/<email>/demote	Remove admin role (admin only; blocked if last admin)
GET	/api/client_usage_stats	Client-scoped usage report

Media Plans

Method	Endpoint	Description
POST	/api/media_plan	Upload Excel media plan
GET	/api/media_plan?client={id}	Get client's media plan
DELETE	/api/media_plan/{client_id}	Remove media plan

Configuration

Environment Variables

OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key
AZURE_TENANT_ID=your_tenant_id
AZURE_CLIENT_ID=your_client_id
SECRET_KEY=your_flask_secret
FLASK_PORT=7183
DEBUG_MODE=false
ENVIRONMENT=development  # or production

Adding New QC Checks

1. Create directory: visual_qc_apps/{check_name}/
2. Create app.py using flask_app_template.py as base
3. Add check to relevant profile JSON files
4. Restart server

Adding New Clients

Add entry to CLIENT_PROFILES in client_config.py:

'client_id': {
    'name': 'Client Name',
    'profiles': ['static_general', 'video_general'],
    'display_name': 'Client Name',
    'description': 'Description of client QC needs'
}

Documentation

• CLAUDE.md - Full development guide and system documentation
• CLAUDE_AMAZON.md - Amazon check details and prompt tuning history
• CLAUDE_BOOTS.md - Boots check details
• CLAUDE_DOW_JONES.md - Dow Jones / MarketWatch / WSJ check details
• CLAUDE_LOREAL.md - L'Oreal check details and prompt tuning history
• DEV_PROD_SETUP.md - Development and production environment guide
• backend/USAGE_REPORTS.md - Usage reporting CLI tool guide
• backend/PROFILE_MANAGEMENT.md - Profile versioning and visibility guide

License

This project is proprietary software. All rights reserved.

---

Visual AI QC Platform - Ensuring quality through intelligent automation