README.md

metadata

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.