| 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:
- Stage 0: Pre-flight AI Scoping: Competitor mapping and interactive parameters setup.
- Stage 1: Multi-threaded Harvesting: Scraping YouTube metadata, views, likes, comments, and subscriber counts.
- Stage 2: Denoising & Time-Decay Momentum Scoring: Filtering noise and calculating trend velocity.
- Stage 3: Buzzword Clustering: Single-batch LLM clustering on trending retail attributes.
- Stage 4: Multimodal Briefing: Audio transcription, 5-frame video keyframe extraction, comment sentiment decoding, and script synthesis.
- 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
pitch (🚀 Executive Pitch):
1: Executive BLUF & Strategic Recommendations (METADATA)2: Competitor Share of Voice & Trend Benchmarks (METADATA, TRANSCRIPTS, COMMENTS, VISION_FRAMES)
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)
creator (👥 Creator Matrix):
12: 🟢 Recommended Growth Creators (Black Horse List) (METADATA, CHANNELS)13: 🔴 Competitor-Affiliated & Sponsored Creators (METADATA, CHANNELS)
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
python3 scripts/preflight_only.py --brand {brand} --category-name {category_name}
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"
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/:
references/scoping.md: Pre-flight scoping protocols, competitor pool discovery, and parameter configuration rules.references/engineering.md: Backend pipeline orchestration, rate limit retries, SQLite WAL concurrency, ASR-VAD gates, and FFmpeg frame extraction.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
- 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).
- 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.
- 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)
- 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.
- 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):
- 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).
- 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.
- 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.
- 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:
- 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.
- 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.
- Why: Prevents brand-polluted searches from biasing SOV calculations and missing authentic competitor or generic market videos.
- 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.
- 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.
