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