Auto-grouping AdManage Rules

We automatically detect ad creative formats (e.g. 1x1, 9x16, 4x5) from filenames, normalize them, and group related media files together (e.g. feed + story + square versions of the same ad).

Core Flow:

1. Detect format — using 20+ regex patterns for common naming conventions (_9x16, (Feed), -S, etc.).
2. Normalize filename — clean suffixes, unify separators, lowercase everything, and strip format tags.
3. Group files — combine variations (e.g. feed, story, square,reel) into sets of 2–3 files per group, ensuring unique formats.
4. Classify format — map dimensions or codes into categories:
   • square → 1x1
   • portrait → 4x5
   • vertical → 9x16
   • reel → 9x16
   • landscape → 16x9
5. Validate — enforce group size (2–3), unique formats, and mixed categories (not all vertical).
6. Detect file type — based on file extension (image vs video).

Goal:

Ensure consistent media grouping and reliable automated creative uploads for multi-placement ad campaigns.

Filename Normalization Rules

Pre-Processing

1. Upload Suffix Removal: Remove 4-character upload suffixes (e.g., _btLP, _ijCA) before format detection
   • Exception: Keep if it's a meaningful word: main, test, prod, beta, demo, live, sale
   • Exception: Keep if all letters and same case (likely a word, not random suffix)

Version/Variant Preservation

1. Version Suffix Preservation: Preserve date-like version patterns (e.g., 250905-6, _250905_3)
   • Normalization: Convert underscores to hyphens
   • Purpose: Keep different versions separate
2. Trailing Number Preservation: Preserve trailing variant numbers before extension
   • Purpose: Keep different numbered variants separate

Format Removal

1. Primary Format Removal: Remove the detected format string
2. Additional Format Cleanup:
   • Remove explicit format dimensions: _4x5, _9x16 (before extension)
   • Remove format dimensions in parentheses: (4X5), (9X16)
   • Remove format dimensions with 4-char hash: _4x5_ZKce, _9x16_ntv1
3. Upload Suffix Removal (Post-Format):
   • Remove 4-character upload suffixes after format removal
   • Same exceptions as pre-processing (meaningful words, same-case words)

Special Handling

1. Instagram Story/Post: Don't remove the number from Instagram story/post patterns (needed for grouping)

Normalization

1. Separator Normalization:
   • Unify various separators to hyphens
   • Collapse multiple hyphens to single hyphen
   • Remove leading/trailing hyphens
2. Case Normalization: Convert to lowercase
3. Extension Handling:
   • Ensure extension is present and lowercase
   • Remove trailing dots
4. Fallback: If name becomes empty or just extension, create fallback from original name
5. Re-append Preserved Elements:
   • Re-append version suffix if preserved
   • Re-append trailing number if preserved (normalize separator to hyphen)

Grouping Rules

Group Key Generation

1. Placement-Based Files:
   • Detection: Files with feed, story, or stories keywords with separators/spaces
   • Group Key: Remove placement keywords, normalize separators
   • Purpose: Group files like thebest_feed.png and thebest_stories.png together
2. Platform-Prefixed Files:
   • Detection: Files starting with insta or facebook prefix
   • Group Key: Remove platform prefix, keep trailing numbers
   • Purpose: Group files like Insta content 1_9x16, Insta content 1_4x5 as content-1
3. Standard Format-Based Grouping

Group Assignment Rules

1. Type Matching: Items must have the same type (image or video) to be in the same group
   • If types don't match, create new group with counter suffix
2. Maximum Group Size: Maximum 3 items per group
   • If group is full, create new group with counter suffix
3. Format Uniqueness: Each format can only appear once per group
   • If format already exists in group, create new group with counter suffix
4. Unique Key Generation: Use preview URL, fallback to url, fallback to name_index

Format Normalization Rules

Short Code Mapping

1. Square Formats:
   • 11, 1x1, sq, g → square
2. Vertical Formats:
   • 916, 9x16, vt, story, s → vertical
3. Landscape Formats:
   • 169, 16x9 → landscape
4. Portrait Formats:

Dimension Mapping

1. Common Pixel Dimensions:
   • 1080x1080 → square
   • 1080x1920 → vertical
   • 1080x1350 → portrait
   • 1080x1440 → portrait (3:4 ratio)
   • 1920x1080 → landscape
   • 1200x628 → landscape
   • 628x1200 → vertical
   • 1350x1080 → landscape

Ratio-Based Classification

1. Aspect Ratio Rules (for any NxN format):
   • Square: ratio ≈ 1 (0.9 to 1.1)
   • Vertical: ratio ≤ 0.7 (e.g., 9:16 = 0.56)
   • Portrait: 0.7 < ratio < 0.9 (e.g., 4:5 = 0.8)
   • Landscape: ratio ≥ 1.5 (e.g., 16:9 = 1.77)
   • Default Landscape: 1.1 ≤ ratio < 1.5 (e.g., 4:3 = 1.33)

Format Conversion

1. Separator Normalization: Convert N_N, N:N, N-N to NxN

Validation Rules

Group Size Validation

1. Minimum Size: Group must have at least 2 items
2. Maximum Size: Group must have at most 3 items

Format Validation

1. Format Detection: All items must have a determinable format
2. Format Uniqueness: Each item must have a different format (no duplicates)
3. Format Count: Must have at least 2 different valid formats

Category Validation

1. Category Requirements:
   • Special Case: Square + Portrait/Vertical + Landscape combination is always valid
   • General Rule: Must have formats from at least 2 different categories
   • Categories: portrait, vertical, square, landscape
2. Category Validation: Formats must belong to more than one category
   • All items cannot be the same category (e.g., all vertical)

File Type Detection Rules

Image Extensions

• png, jpg, jpeg, gif, webp, heic, heif, svg, bmp, tiff

Video Extensions

• mov, mp4, m4v, avi, mkv, webm, flv, wmv, mpeg, mpg

Return Values

• Returns 'image', 'video', or 'unknown' based on file extension

Notes

• Pattern matching is done on both cleaned and original filenames
• Patterns are evaluated in order (highest priority first)
• Grouping uses normalized base names to create group keys
• Format normalization converts various formats to standard categories: square, vertical, portrait, landscape