README.md

---
title: AI Digital Marketing Plan Generator
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# AI Digital Marketing Plan Generator

Generate a detailed, customized digital marketing plan from a product description, budget, and available manpower.

**This is a free tool. All LLM calls are billed to your own Hugging Face token**, which you paste into a password-style input box in the UI. Your token is used in-memory for the duration of your request only — it is never logged, stored, or persisted by this Space.

## What it does

1. **Keyword research** — derives seed keywords from your product description and looks up real search volume/CPC/related terms via a four-tier fallback chain, each tier used only if the one above it is unavailable:
   1. **Google Ads API** (`KeywordPlanIdeaService.GenerateKeywordIdeas`) — official Google search volume and CPC bid ranges, read-only, configured via the operator's own credentials (see below). This tier runs on one shared account (Basic access: 15,000 operations/day total), so each user (identified by their own hashed HF token — there's no other user identity in this app) is capped at 25 uses/day; beyond that they fall back to tier 2 for the rest of the day.
   2. **Keyword Surfer scrape** — headless Chromium with the Keyword Surfer browser extension loaded, reading the volume widget it injects into Google search results.
   3. **Google Autocomplete + Google Trends** — free, unauthenticated public endpoints; relative interest, not absolute volume.
   4. **LLM-estimated volumes/CPC** — a clearly labeled guess, only if all three real data sources are unavailable.

   Every result is tagged with which tier produced it, and the generated plan states this explicitly.
2. **SEO plan** — keyword clusters, a content calendar, an on-page/technical checklist, a link-building plan, and a step-by-step implementation guide, sized to your team.
3. **Organic social media plan** — platform mix, content pillars, a first-30-days posting calendar, engagement tactics, and a step-by-step setup guide, backed by real per-platform engagement rate, posting frequency, best-posting-time, and audience demographic data (`data/social_benchmarks.json`, curated from 2026 Socialinsider/Rival IQ/DataReportal/Sprout Social reports) instead of general impressions of platform popularity. Kept separate from paid social spend, which lives in the ads plan.
4. **Paid advertising plan** — a channel mix and budget split across Search/Display/Meta/LinkedIn/TikTok/YouTube, projected from published industry benchmark data (CPC/CTR/CVR) — and, for Search, real per-keyword CPC data from the Google Ads API when that tier is configured — sized to your budget and manpower.
5. **Grounded strategy (RAG)** — SEO, social, and ads plans are each grounded against their own topic-partitioned slice of a local knowledge base (SEO/social/ads/general), plus a fifth, whole-corpus retrieval for the final composed plan. The knowledge base is built from 79 digital marketing books and ~28,000 crawled articles across those four categories. Retrieved context is meant to *guide* the plan, not limit it — the model is expected to draw on its own broader expertise too — and is cited only as **"Source 1", "Source 2", …**, never by title, author, or URL.
6. **Composed plan** — everything above is synthesized into one markdown plan (exec summary, positioning, SEO, content, paid ads, social, email, measurement/KPIs, 90-day roadmap, team task allocation), viewable in the UI and downloadable.

Each of the four content-generating modules (SEO / social / ads / composer) defaults to its own best-fit LLM — see the `RECOMMENDED_MODEL` comment in `modules/seo.py`, `modules/social.py`, `modules/ads.py`, and `DEFAULT_MODEL` in `modules/llm.py` for the reasoning behind each pick. The UI's model dropdown defaults to "Auto" (each module uses its own pick) but can be overridden to force one model for everything.

## Using it

1. Get a Hugging Face access token with **Inference Providers** billing enabled: https://huggingface.co/settings/tokens
2. Open the Space, paste your token into the token box, fill in your product description / budget / manpower / industry / geography, pick a model (or leave on Auto), and click **Generate Plan**.
3. Download the resulting plan as markdown.

Nothing you enter is stored server-side once your session ends.

## Optional: Google Ads API (tier 1 keyword data)

Without this configured, keyword research still works — it just falls back to tier 2 (Keyword Surfer). To enable real Google-sourced keyword data, the Space operator sets five environment variables (as Space secrets in production, or a local `.env` file for development — never commit either):

```
GOOGLE_ADS_DEVELOPER_TOKEN=...
GOOGLE_ADS_CLIENT_ID=...
GOOGLE_ADS_CLIENT_SECRET=...
GOOGLE_ADS_REFRESH_TOKEN=...
GOOGLE_ADS_LOGIN_CUSTOMER_ID=...   # the manager (MCC) account's 10-digit ID, no dashes
```

These are the operator's own Google Ads API credentials, obtained once via a Google Ads manager account + developer token application + OAuth2 setup. End users of the Space never see or supply these — they're unrelated to the per-user HF token.

## How the knowledge base is built (not run on the Space)

The RAG knowledge base (`rag_index/`) is **built entirely on a contributor's local machine**, never on the Space itself, and is sourced from a sibling crawler project rather than this repo's own `crawled/`/`books/` folders:

1. The sibling project crawls ~600 digital-marketing/SEO/social-media/online-advertising sources (categorized) plus a local folder of digital marketing books, storing extracted page text in a local SQLite database.
2. `scripts/build_index_from_crawler.py` reads that database directly, classifies each document into one of four categories (`seo` / `social_media` / `online_ads` / `general` — by crawl-source category for articles, by filename keywords for books), chunks the text (800 tokens, 100 overlap), embeds it with `BAAI/bge-small-en-v1.5` (GPU-accelerated if CUDA is available), and writes a ChromaDB collection to `rag_index/`.
3. Each chunk carries **only its category tag and raw text — no titles, authors, URLs, or domains** — the category tag is a coarse topical bucket, not identifying information, so it doesn't weaken the "Source N" anonymization guarantee. This is what makes that guarantee possible.
4. `modules/rag.py`'s `retrieve()` accepts an optional category filter, so `seo.py`/`social.py`/`ads.py` each draw from their own category (+ `general`), while `composer.py` draws from the whole corpus.

Current index: 104,117 chunks (general: 42,054 · seo: 25,127 · social_media: 20,818 · online_ads: 16,118), already built and present in `rag_index/`.

> **Legacy pipeline**: `scripts/crawl_sources.py`, `scripts/build_index.py`, `scripts/extract_books.py`, `scripts/ocr_book.py`, and the `*_sources.json` files are an earlier, superseded approach (crawling this repo's own `crawled/`/`books/` folders, and not checking robots.txt). They're kept for reference but are no longer the build path — use `build_index_from_crawler.py` instead.

## Architecture

```
User inputs (product, budget, manpower, industry, geo, HF token, model)
    │
    ├─ Keyword module (Google Ads API → Keyword Surfer → Autocomplete+Trends → LLM est.)
    │       │
    │       ├─→ SEO module      (+ RAG: seo/general)                              ─┐
    │       ├─→ Social module   (+ RAG: social_media/general, social_benchmarks.json) ├─→ Composer (+ RAG: whole corpus) → final plan
    │       └─→ Ads module      (+ RAG: online_ads/general,                        │
    │             ad_benchmarks.json, real per-keyword CPC)                       ─┘
```

## Disclaimers

- Keyword volumes/CPC are real Google data when the Google Ads API tier is configured; otherwise they're estimates from third-party public data — treat unlabeled figures as directional, not guaranteed. Ad benchmark figures (CTR/CVR, and CPC for non-Search channels) and social platform benchmarks (engagement rate, posting frequency/timing, demographics) are curated from published 2026 industry reports, not live data — see the `disclaimer` field in `data/ad_benchmarks.json` and `data/social_benchmarks.json` for exact sources.
- LLM generation costs are billed to the Hugging Face token you supply — check current Inference Providers pricing before large runs.