# AdJuice: AI-Native Creative Intelligence & Retail Performance Agent
[](LICENSE)
[](https://www.python.org/)
[](tests/)
[](.agents/skills/adjuice/)
[]()
[](CONTRIBUTING.md)
> **Disclaimer**: This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
`AdJuice` is an **AI-Native Creative Intelligence & Retail Performance Agent** engineered for DTC e-commerce brands, performance marketers, and creative directors. It bridges retail data harvesting and creative execution by deconstructing thousands of competitor YouTube video ads, reviews, and try-on hauls into **actionable 15-second direct-response (PAS) ad scripts** and **self-contained executive HTML dashboards**.
With native **AI Agent Skill support (`/adjuice`)**, non-technical marketers and media buyers can converse directly in natural language to perform market scoping, benchmark direct competitors, decode consumer objections, and generate production-ready creative briefs without touching complex terminal commands.
---
## ๐๏ธ System Architecture
```
[Conversational AI Agent Gateway / `/adjuice` Skill]
โ (Two-Stage Progressive Interactive Q&A)
โผ
[Multi-Track Query Generator & Sub-Category Splitter]
โ
โผ
[YouTube Data API / Scraper Engine]
โ
โผ
[WebRTC VAD Speech Gate] โโ(Silent / BGM)โโโบ [Drop Video (<10ms)]
โ (Valid Dialogue)
โผ
[Faster-Whisper ASR + OpenCV Vision Sampling]
โ
โผ
[Agnostic LLM Client (Gemini / OpenAI / Claude / Ollama)]
โ
โผ
[14-Section Composable DAG Compiler]
โ
โผ
[Self-Contained Interactive HTML Dashboard] (reports/YYYYMMDD_Brand_Region_Category_report.html)
```
---
## ๐ Key Features & AI Agent Capabilities
- **๐ค AI-Native Agent Skill (`.agents/skills/adjuice/`)**:
Empowers non-technical operators to run full retail intelligence sweeps simply by calling `/adjuice` in AI coding environments (Gemini Code Assist, Cursor, Cline, Claude Code, Antigravity).
- **๐ฌ Two-Stage Progressive Interactive Scoping Q&A**:
- **Stage 1 (Strategic Scoping)**: Solicits Target Brand, Category, and Output Language (`en`/`zh`). Automatically discovers the core Domain Taxonomy (e.g., Fashion vs. Athletic) and recommends direct DTC competitors.
- **Stage 2 (Tactical Parameters)**: Calibrates Timeframe, Sample Scale (450โ600 queries), Paid vs. UGC filter, and Regional Market Localization (US, UK, DE, JP, etc.).
- **๐ Compound Category Multi-Track Decomposition**:
Automatically parses compound category terms (e.g., *โPlus Size Sweaters & Cardigansโ*) into isolated sub-track queries (*โPlus Size Sweatersโ* and *โPlus Size Cardigansโ*), preventing keyword dilution while unifying insights into a single executive dashboard.
- **๐ก๏ธ Smart Adaptive Protocol (Levels 0โ5)**:
- **Level 0 (Paid Promotion Auto-Fallback)**: Intelligently drops `--video-paid-only` during off-season lulls to capture authentic organic UGC try-ons.
- **Level 1 (Momentum Floor Relaxation)**: Dynamically scales viral velocity thresholds from 100 to 0 to safeguard niche category data density.
- **Level 2 (Domain Harmonization)**: Auto-corrects positioning drift (e.g. preventing Vivaia from benchmarking Nike running shoes).
- **Level 3 (Competitor Long-Tail Immunity)**: Protects competitor SOV and Style DNA cards even under strict filters.
- **Level 4 (Graceful Metadata Fallback)**: Resilient fallback to audio transcripts and metadata when video downloads face rate limits.
- **Level 5 (Brand-Balanced Brief Capping)**: Enforces equal top-3 quotas per competitor to prevent mega-brands from monopolizing analysis cards.
- **๐๏ธ 5-Tab Interactive Architecture & Smooth Auto-Scroll**:
- Dynamically routes 14 canonical sections into 5 clear executive tabs: **๐ Executive Pitch**, **๐ฆ Product & Market Demand**, **๐ฅ Creator Matrix**, **๐ก Creative & 15s PAS Scripts**, and **๐ Methodology**.
- Supports `--tab-order` customization, Expand All toggle mode, and automatic smooth scrolling to top when switching tabs.
- **๐๏ธ WebRTC VAD + Whisper ASR Gate**:
Eliminates transcription overhead by dropping silent or BGM-only video ads in `< 10ms`.
- **๐ Zero-API Cost Offline Recompilation (`scripts/compile_report.py`)**:
Re-render interactive reports or modify CSS visual themes from cached JSON datasets in `< 1s` with zero incremental API consumption.
- **๐ Model-Agnostic LLM Client (`engine/llm_client.py`)**:
Zero vendor lock-in with native support for **Google Gemini**, **OpenAI GPT-4o**, **Anthropic Claude 3.5**, and local offline **Ollama / vLLM** instances.
---
## ๐ The 14 Canonical Report Sections
| Section ID | Name | Core Marketing & Business Value |
| :--- | :--- | :--- |
| **`1`** | Executive BLUF & Strategic Directives | High-level executive summary, audience split, and immediate ad spend guidance. |
| **`2`** | Competitor Share of Voice & Benchmarks | Peer-group SOV, top-3 video averages, and competitor Style DNA benchmarks. |
| **`3`** | Category Attribute Demand & Google Trends Matrix | 30-day search momentum paired with YouTube seeding velocity. |
| **`4`** | ๐ฏ High-Converting Ad Angles & Hit Product Matrix | High-intent search terms mapped directly to live DTC landing pages. |
| **`5`** | Trending Marketing Slang & Buzzword SOV | High-frequency consumer vernacular and cultural keywords. |
| **`6`** | High-Potential Products & Sub-Category Matrix | Category-specific product winners and market opportunity gaps. |
| **`7`** | Benchmark Video Deep Deconstruction & Creative Library | Multimodal reverse-engineering of top competitor hooks, angles, and friction busters. |
| **`8`** | Trending Brands Share of Voice | Category-wide brand penetration and volume distribution. |
| **`9`** | Traffic Mechanics & Master DR Brief Golden Formulas | Executive formulas for direct-response ad creative production. |
| **`10`** | Niche Consumption Scenarios & 15s PAS Ad Scripts | Ready-to-film Problem-Agitate-Solution scripts across top usage scenarios. |
| **`11`** | Product Attributes & Consumer Sentiment Mining | Pain point extraction, common brand practices, and blue ocean opportunities. |
| **`12`** | ๐ข Recommended Growth Creators (Black Horse List) | High-engagement organic creators with verified contact info for seeding. |
| **`13`** | ๐ด Competitor-Affiliated & Sponsored Creator List | Intelligence on creators actively partnering with competitors. |
| **`14`** | Appendix: Mathematical Models & Methodology | Complete transparency on formulas, VAD gating, and scoring algorithms. |
---
## ๐ Repository Structure
```
.
โโโ .agents/ # AI Agent skill definitions and domain references
โ โโโ AGENTS.md # Defensive coding & engineering invariants
โ โโโ skills/adjuice/ # Portable agent gateway (SKILL.md & references/)
โโโ config/ # Noise filtering & threshold configuration
โโโ engine/ # Core analytical engine & HTML/SVG rendering SDK
โ โโโ analyzer.py # Momentum scoring & SOV distribution matrices
โ โโโ asr_client.py # WebRTC VAD gate & Faster-Whisper ASR integration
โ โโโ html_engine.py # 14-section 5-tab responsive HTML compiler
โ โโโ llm_client.py # Decoupled agnostic LLM client (Gemini/OpenAI/Claude/Ollama)
โ โโโ synthesizer.py # Pydantic schema synthesis & PAS ad copy generation
โโโ prompts/ # LLM prompt templates (attribute mining & brief synthesis)
โโโ scripts/ # Orchestration CLI entrypoints
โ โโโ compile_report.py # Idempotent 14-section offline DAG report compiler
โ โโโ run_pipeline.py # Real-time YouTube scraper & multimodal worker pipeline
โ โโโ ... # (google_trends_loader, cache_manager, verify_report_output)
โโโ tests/ # 66-case automated pytest regression suite (100% Green)
โโโ CONTRIBUTING.md # Contribution guidelines & CLA instructions
โโโ CODE_OF_CONDUCT.md # Contributor Covenant Code of Conduct
โโโ LICENSE # Apache 2.0 Open Source License
โโโ README.md # Canonical English documentation (This file)
โโโ README_CN.md # Comprehensive Chinese user guide
```
---
## ๐ Quick Start
### 1. Non-Technical / Conversational Usage (Recommended)
Simply install the skill or open your AI Agent environment and run:
```text
/adjuice
```
The agent will initiate the **Two-Stage Interactive Q&A Modal**, recommend competitors, auto-split compound queries, and deliver the finalized bilingual HTML dashboard directly to your workspace.
---
### 2. Developer / CLI Setup
#### A. Clone & Install Dependencies
```bash
git clone https://github.com/google/adjuice.git
cd adjuice
pip install -r requirements.txt
```
#### B. Configure Environment
Copy `.env.example` to `.env` and set your preferred keys:
```bash
cp .env.example .env
```
```env
# Required for YouTube video metadata scraping
YOUTUBE_API_KEY=your_youtube_api_key_here
# Choose your preferred LLM Provider:
# Option A: Google Gemini
LLM_PROVIDER=gemini
GEMINI_API_KEY=your_gemini_api_key_here
# Option B: OpenAI
# LLM_PROVIDER=openai
# OPENAI_API_KEY=your_openai_api_key_here
# Option C: Local Offline LLM (Ollama - 100% Free & Private)
# LLM_PROVIDER=ollama
# OLLAMA_API_BASE=http://localhost:11434/v1
```
#### C. Run the Pipeline
```bash
python3 scripts/run_pipeline.py --brand "Bloomchic" --category-name "Plus Size Sweaters & Cardigans" --region "US" --lang "en" --competitors "Cider,SHEIN,Halara,Torrid" --enabled-sections "1,2,3,4,5,6,7,8,9,10,11,12,13,14" --script-lang en --fetch-limit 600 --max-results 45 --min-momentum 100
```
#### D. Zero-API Cost Offline Recompilation
Re-compile reports from cached JSON datasets in `< 1s` without API quota:
```bash
python3 scripts/compile_report.py scratch/build_cache/your_dataset.json reports --script-lang en --tab-order "pitch,product,creator,creative,appendix"
```
---
## ๐งช Testing & Verification
AdJuice includes a comprehensive automated test suite covering VAD silence rejection, thread safety, short-circuit capabilities, compound category splitting, 5-tab DOM hierarchy, and deterministic rendering:
```bash
PYTHONPATH=. pytest tests/ -v
```
All **66 / 66 test cases** pass cleanly with 100% green coverage.
---
## ๐ค Contributing
Contributions, bug reports, and feature proposals are welcome! Please review [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting pull requests.
---
## ๐ License
Distributed under the **Apache 2.0 License**. See [LICENSE](LICENSE) for full terms.
---
## โ๏ธ Disclaimer
*This is not an officially supported Google product. It is an open-source research and engineering toolkit maintained by contributors.*