adjuice

name	adjuice
description	Master orchestrator and creative intelligence engine for YouTube retail trend analysis, audience objection decoding, 15s PAS ad scriptwriting, and executive slide deck generation.
license	Apache-2.0
compatibility	Requires Python 3.9+

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)
   • : Niche Consumption Scenarios, Target Audience & Ad Scripts (, , , )

---

🛠️ Key Command Reference

# 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.