adjuice

# AdJuice: Master Skill & Creative Intelligence Gateway (Global) `AdJuice` is the single-word master skill for YouTube retail trend analysis, 1:1 competitor benchmarking, audience objection decoding, and 15s PAS ad script synthesis. --- ## 🧭 1. Overview & Capability Gateway When invoked, `AdJuice` automates the 5-stage multimodal processing pipeline: 1. **Stage 0: Pre-flight AI Scoping**: Competitor mapping and interactive parameters setup. 2. **Stage 1: Multi-threaded Harvesting**: Scraping YouTube metadata, views, likes, comments, and subscriber counts. 3. **Stage 2: Denoising & Time-Decay Momentum Scoring**: Filtering noise and calculating trend velocity. 4. **Stage 3: Buzzword Clustering**: Single-batch LLM clustering on trending retail attributes. 5. **Stage 4: Multimodal Briefing**: Audio transcription, 5-frame video keyframe extraction, comment sentiment decoding, and script synthesis. 6. **Stage 5: Dashboard & Slide Generation**: Executive HTML reports, CSV export, and Google Slides deck creation. --- ## 📌 2. The 1..14 Canonical Section Architecture & 5-Tab Executive Structure The AdJuice report compiler operates as a **declarative 14-Section Composable DAG mapped into a modern 5-Tab Executive Navigation Architecture**, completely eliminating legacy `--mode` presets (`sales_pitch`, `ideation`, `trend`). Users control which sections to compute and render via `--enabled-sections`, and their layout sequence via `--tab-order`: ### 🗂️ 5-Tab Executive Domain Mapping 1. **`pitch` (🚀 Executive Pitch)**: - **`1`**: Executive BLUF & Strategic Recommendations (`METADATA`) - **`2`**: Competitor Share of Voice & Trend Benchmarks (`METADATA`, `TRANSCRIPTS`, `COMMENTS`, `VISION_FRAMES`) 2. **`product` (📦 Product & Market Demand)**: - **`3`**: Category Attribute Trends & Demand Matrix (`METADATA`) - **`4`**: 🎯 High-Converting Ad Keywords & Hit Product Matrix (PiPiADS) (`METADATA`) - **`5`**: Trending Buzzwords & Marketing Slang Share of Voice (`METADATA`) - **`6`**: High-Potential Products & Sub-Category Matrix (`METADATA`) - **`8`**: Trending Brands Share of Voice (`METADATA`) - **`11`**: Core Product Attributes & Consumer Sentiment Mining (`METADATA`, `TRANSCRIPTS`, `COMMENTS`) 3. **`creator` (👥 Creator Matrix)**: - **`12`**: 🟢 Recommended Growth Creators (Black Horse List) (`METADATA`, `CHANNELS`) - **`13`**: 🔴 Competitor-Affiliated & Sponsored Creators (`METADATA`, `CHANNELS`) 4. **`creative` (💡 Creative & 15s PAS Scripts)**: - **`7`**: Benchmark Video Deep Deconstruction & Creative Library (`METADATA`, `TRANSCRIPTS`, `COMMENTS`, `VISION_FRAMES`) - **`9`**: Traffic Mechanics & Content Golden Formulas + `Master DR Brief` (`METADATA`) - **`10`**: Niche Consumption Scenarios, Target Audience & Ad Scripts (`METADATA`, `TRANSCRIPTS`, `COMMENTS`, `VISION_FRAMES`) 5. **`appendix` (📑 Methodology & Models)**: - **`14`**: Appendix: Data Collection Methodology, VAD Gating & Mathematical Models (`METADATA`) --- ## 🛠️ Key Command Reference ```bash # 1. Run pre-flight scoping python3 scripts/preflight_only.py --brand {brand} --category-name {category_name} # 2. Run full AdJuice pipeline (all 14 canonical sections & 5-tab navigation enabled by default) python3 scripts/run_pipeline.py \ --query "{query}" \ --brand {brand} \ --competitors "{comp1},{comp2},{comp3},{comp4}" \ --region {region} \ --lang {lang} \ --script-lang {script_lang} \ --fetch-limit 450 \ --max-results 45 \ --enabled-sections "1,2,3,4,5,6,7,8,9,10,11,12,13,14" \ --tab-order "pitch,product,creator,creative,appendix" # 3. Offline compilation from existing cached dataset python3 scripts/compile_report.py \ --input-json scratch/build_cache/{dataset}.json \ --brand {brand} \ --competitors "{comp1},{comp2},{comp3},{comp4}" \ --enabled-sections "1..14" \ --tab-order "pitch,product,creator,creative,appendix" \ --script-lang zh ``` --- ## 🧩 3. Domain Reference Manuals When working on specific sub-systems within AdJuice, consult the authoritative domain reference manuals in `references/`: 1. **`references/scoping.md`**: Pre-flight scoping protocols, competitor pool discovery, and parameter configuration rules. 2. **`references/engineering.md`**: Backend pipeline orchestration, rate limit retries, SQLite WAL concurrency, ASR-VAD gates, and FFmpeg frame extraction. 3. **`references/designer.md`**: Executive HTML report styling, SVG layout templates, CSS column synchronization, and responsive design systems. --- ## 📊 4. Standard Creator / KOL Tier Definitions When categorizing YouTube creators and generating creator distribution insights, you MUST strictly adhere to the following standard subscriber count tiers: * **Micro Creators**: 1,000 to 300,000 subscribers (1K - 300K) * **Torso Creators (Mid/Body)**: 300,000 to 1,000,000 subscribers (300K - 1M) * **Mega Creators**: 1,000,000+ (1M+) subscribers --- ## 📈 5. Google Trends Official CSV Zero-Rename Injection Standard 1. **Zero-Rename Auto-Discovery**: Use `from scripts.google_trends_loader import find_and_parse_gtrends_csv` to automatically scan `reports/` for `multiTimeline*.csv` (or `*.csv`). The loader sniffs column headers (e.g. `Callie: (Germany)` vs. `Callie: (France)`) to bind the CSV to the target region (`DE` vs. `FR`). 2. **Mandatory Goto Link at Scoping Confirmation**: Whenever the agent presents the Option Confirmation Table after pre-flight scoping, the agent **MUST generate and present a clickable Google Trends Explore URL (Goto Link)** (`https://trends.google.com/trends/explore?date=today%20{span}&geo={region}&q={brand},{comp1},{comp2},{comp3},{comp4}`) comparing the Target Brand and up to 4 Competitors in the target region. (Note: `{span}` MUST be mapped to Google Trends parameters: 30d -> `1-m`, 90d -> `3-m`, 180d -> `6-m`, 365d -> `12-m`, e.g., `date=today%203-m`). Instruct the user to click the link, download `multiTimeline.csv`, and place it into `reports/` for automatic Zero-Rename CSV Injection. 3. **Conditional Rendering (Zero Hallucination)**: * **If `gtrends_data` exists (`is_authentic == True`)**: Render the full **Executive All-Peers Interactive SVG Dashboard & Search vs. YouTube SOV Matrix Table** in Section 3. Ensure the timeframe label displays the natural CSV span (`{days_span}` days), aligned with the landscape fetch days. * **If `gtrends_data` is `None` (No CSV mounted)**: Silently omit the Google Trends chart. Never render placeholder errors or synthetic/hallucinated trend curves. --- ## 🛡️ 6. Report Guardian: Low Sample (< 5 Conversions) Smart Adaptive Protocol ### 🚨 Core Problem & Trigger In non-English localized markets (e.g. `FR`, `DE`, `ES`), default strict filtering may result in fewer than 5 high-converting DR Creative Brief cards (`valid_cards < 5`). ### ⛔ Absolute Prohibitions (Zero-Tolerance Rules) 1. **FORBIDDEN: NEVER use Evergreen Videos to pad card counts!** - Relying on 2~5 year-old historical videos destroys current report timeliness, misleads marketers with obsolete aesthetic styles, and poisons DR ad script recommendations. 2. **FORBIDDEN: NEVER enable `--include-non-commercial` blindly!** - Do not inject non-commercial prank, movie clip, or irrelevant noise just to fill table slots. ### ✅ High-Order Strategy: Smart Adaptive Protocol When `valid_cards < 5`, the pipeline MUST execute the following adaptive levers in order while strictly maintaining **Recent Timeliness** and **Commercial Purity (`is_genuine=True`)**: 0. **Lever 0: Paid Promotion Adaptive Fallback (`--video-paid-only` -> `paid = False`)** - If `--video-paid-only` was originally enabled and the conversion cards fail to reach sufficiency (`valid_cards < 5`, e.g., due to off-season lulls such as summer sweater hauls or niche regional unflagged sponsorships), the pipeline MUST automatically fall back from `paid = True` to `paid = False` (capturing all authentic organic UGC try-on reviews + commercial hauls). 1. **Lever 1: Semantic Top-of-Funnel Breadth Expansion** - Automatically expand search query breadth from single-brand terms to broader category-wide commercial gifting/unboxing queries (e.g., `Idée cadeau femme avis`, `bijoux personnalisés haul`) to enlarge the recent candidate pool. 2. **Lever 2: Dynamic KOC Subscriber Threshold Relaxation** - Dynamically relax KOC follower thresholds from `>= 500` down to `>= 200` or `>= 100` to unlock authentic, highly-converting local nano-KOC seeding accounts. 3. **Lever 3: Momentum Score Relaxation** - Relax `--min-momentum` from `100` down to `10`, `3`, or `1` to capture steady recent commercial reviews that have not yet reached viral scale. ### 🎯 Pragmatic Success Criterion (> 5 Deduplicated Valid Cards) - If deduplicated, valid commercial cards reach **`> 5`** (e.g., 6~15 cards) and are richer than the initial sparse run, **STOP relaxation and accept the dataset as complete.** - Always document any threshold relaxation in the report's `meta_info` table for complete transparency. --- ## ⚖️ 7. Unbiased Multi-Track Query Cleaning Rule (0% Brand Bias Standard) When constructing search queries in Stage 1 (`build_unbiased_multitrack_queries`), the base category root keyword MUST be 100% pure and stripped of any Target Brand or Competitor Brand names: 1. **Category Keyword Purity**: Always use the pure category keyword (e.g., `Plus Size Dresses` or `plus size dress try on haul`) as the base (`pure_cat`). Automatically strip out `--brand` and `--competitors` names from the base keyword if present. 2. **Track Separation (30% / 50% / 20% Model)**: - **20% Own Brand Track**: `f"{brand} {pure_cat} {suffix}"` (e.g., `Bloomchic Plus Size Dresses review`). - **50% Competitor Track**: `f"{competitor} {pure_cat} {suffix}"` (e.g., `Torrid Plus Size Dresses review`). NEVER include the target brand in competitor queries. - **30% Generic Track**: `f"{pure_cat} {suffix}"` (e.g., `Plus Size Dresses review`). NEVER include any brand or competitor names in generic queries. 3. **Why**: Prevents brand-polluted searches from biasing SOV calculations and missing authentic competitor or generic market videos. 4. **Dynamic Full Competitor Coverage (Top 4 Competitors Standard)**: To ensure 100% equal opportunity across all competitors without truncation, allocate exactly 2 queries (`review` + `unboxing`) per competitor (`len(competitors) * 2`). Strictly cap competitors at Top 4 (`1 Own Brand + 4 Competitors = 5 Brands total`) to seamlessly align with Google Trends' 5-entity hard limit, prevent long-tail SOV dilution, and maintain optimal 5-column Executive UI/UX layouts. 5. **Compound Category Sub-Track Decomposition (`&` / `,` Splitting Standard)**: - When a compound category is provided (e.g., `Plus Size Sweaters & Cardigans`, `Sustainable Sneakers & Casual Flats`), the query builder MUST automatically split the compound root into natural, targeted sub-categories (`Plus Size Sweaters`, `Plus Size Cardigans`), preserving qualifying prefixes (e.g., `Plus Size`). - Generates dedicated sub-track queries across Own Brand, Competitors, and Generic tracks to avoid over-long 6-word queries that suppress YouTube API recall, while ensuring rich multi-product try-on representation inside the same unified report. --- ## ⚡ 8. Dynamic Pipeline Control & Composable DAG Architecture Instead of rigid mode presets (`mode`), the AdJuice pipeline operates as a **declarative 14-Section Composable DAG**. - **Dynamic Short-Circuiting**: Pass `--enabled-sections <ids>` (e.g., `--enabled-sections "3,9"`). When requested sections only require lightweight metadata/channel capabilities (`METADATA`, `CHANNELS`, `TRENDS_CSV`), the pipeline automatically short-circuits Stage 4 visual/transcript deconstruction (`VISION_FRAMES`, `TRANSCRIPTS`, `COMMENTS`), reducing execution time from 15 minutes to seconds. - **All-Sections Parameter Mapping**: When configuring sections via in-chat scoping, selecting All Sections passes `--enabled-sections "1,2,3,4,5,6,7,8,9,10,11,12,13,14"` for a full 14-section Executive Report. Individual sections or tabs (`pitch`, `product`, `creator`, `creative`, `appendix`) can also be customized. Note: Section 2 (PEER-GROUP SOV) requires Deep Analysis (`VISION_FRAMES`, `TRANSCRIPTS`, `COMMENTS`) because it is calculated exclusively over the commercially verified converting video pool (`is_genuine=True`). --- ## 🧭 9. The 5-Tab Dynamic Navigation & Ordering System The AdJuice Executive Report renders all enabled sections inside a unified 5-Tab container with native smooth scrolling to top on tab switch: - **`--tab-order` Control**: Allows marketers and executives to customize the narrative structure of the HTML dashboard (e.g., `--tab-order "pitch,product,creator,creative,appendix"` for standard executive flow, or `--tab-order "creator,creative,product,pitch,appendix"` for influencer-first marketing review). - **Auto-Suppression of Empty Tabs**: If no enabled sections belong to a given tab, that tab button is automatically suppressed from the UI header without throwing rendering errors. - **Section ID Idempotency**: Section numbering remains strictly sequential (1, 2, 3...) regardless of the custom tab display order.