# AI Multimodal Campaign Architect

**Agentic Workflow · Model Context Protocol**

An agentic MCP workflow that plans, writes, illustrates, and voices a full marketing campaign — with a human checkpoint before the expensive part.
<p align="center">
  <img src="public/pipeline.png" width="800">
</p>

Give it one prompt — *"Launch a bold sneaker line targeting Gen Z"* — and it runs an agentic pipeline of MCP tools that generates copy, a moodboard, a voiceover, a presentation pitch, and a final campaign image, with automated guardrails and a hard budget cap along the way.

**[See how it works : https://ai-multimodal-campaign-architect-gl808c9v7-nibha-dongre.vercel.app/  ](https://ai-multimodal-campaign-architect-gl808c9v7-nibha-dongre.vercel.app/)**

---

## What it does

1. **Generate copy** — Gemini produces a headline, body copy, target audience, core message, a detailed visual concept, and a ~15s voiceover script from a single campaign prompt.
2. **Fan out in parallel** (`asyncio.gather`, bounded by the slowest call, not their sum):
   - Build a **moodboard** from Unsplash to validate visual direction cheaply, before spending on image generation
   - Synthesize a **voiceover** from the script (gTTS)
   - Draft a **presentation pitch** — target audience, core message, CTA, design rationale
   - Run **guardrail checks** — a rule-based pass (banned terms, length limits) and an LLM-based pass (unverifiable claims, tone alignment)
3. **Human-in-the-loop checkpoint** — a person reviews the moodboard and confirms (or overrides) the visual direction before the pipeline spends anything on image generation.
4. **Generate the final image** via Pollinations.ai, using the confirmed visual concept.
5. **Bounded auto-critique** — any field that fails a guardrail check gets exactly one automated rewrite pass. No retry loops, no runaway cost — failures are logged for manual follow-up instead.

## Pipeline

```
RECEIVE BRAND REQUIREMENT ──▶ GENERATE COPY ──┬──▶ BUILD MOODBOARD ─────┐
                                               ├──▶ GENERATE AUDIO ──────┤
                                               ├──▶ CREATE PITCH ────────┼──▶ HUMAN IN THE LOOP ──▶ GENERATE IMAGE
                                               └──▶ RUN GUARDRAILS ──────┘
                                               (parallel batch — asyncio.gather)
```

## Tech stack

| Layer | Stack |
|---|---|
| MCP server | Python, [FastMCP](https://github.com/jlowin/fastmcp), Pydantic (typed tool schemas) |
| Copy / pitch / guardrails | Gemini API (`gemini-flash-lite-latest`) |
| Moodboard | Unsplash API |
| Image generation | Pollinations.ai (free, no key required) |
| Voiceover | gTTS |
| Frontend | Next.js (App Router), TypeScript, Tailwind CSS |

Only Gemini and Unsplash calls cost anything — both have generous free tiers, and a per-session budget cap enforces a hard ceiling regardless (see [Cost & budget controls](#cost--budget-controls)).

## Project structure

```
.
├── server.py              # MCP server — exposes each pipeline step as a typed tool
├── client.py               # MCP transport client
├── orchestrator.py         # Pipeline DAG: sequencing, parallel fan-out, budget enforcement
├── run_demo.py              # Runs the 4 showcase campaigns end-to-end, writes campaign_outputs/
├── requirements.txt
├── .env.example
│
├── app/                    # Next.js app router pages
├── components/              # DemoGrid, DemoModal, PipelineDiagram, ByokPanel, etc.
├── data/
│   ├── demos.ts             # Auto-generated by scripts/build-demo-data.mjs — do not hand-edit
│   └── features.ts
├── public/
│   ├── demo.gif
│   └── demos/                # Campaign assets copied in at build time
├── scripts/
│   └── build-demo-data.mjs   # Reads campaign_outputs/, populates data/demos.ts + public/demos/
└── package.json
```

> Adjust this tree if your repo splits the Python backend and Next.js frontend into separate subfolders rather than a shared root.

## MCP tools exposed

| Tool | Purpose | Cost |
|---|---|---|
| `generate_copy` | Headline, body copy, visual concept, voiceover script — the context source every other tool depends on | Gemini (small) |
| `generate_moodboard` | Unsplash search for reference imagery — a cheap way to validate direction before paid image generation | Free |
| `generate_image` | Final campaign image from a confirmed visual concept | Free (Pollinations.ai) |
| `generate_audio_asset` | Text-to-speech voiceover from the campaign script | Free (gTTS) |
| `create_presentation_pitch` | Target audience, core message, CTA, design rationale | Gemini (small) |
| `refine_content` | Regenerates a single field (headline / body copy / audio script) in isolation, keeping everything else fixed | Gemini (small) |
| `run_guardrail_check` | Rule-based screening: banned terms, headline/script length limits | Free |
| `run_llm_guardrail_check` | Model-based screening: unverifiable claims, tone alignment against brand context | Gemini (small) |
| `retrieve_brand_context` | RAG-style retrieval of brand voice/guidelines to ground copy generation | Free (stub — real embedding search is a planned extension) |

## Cost & budget controls

`CampaignOrchestrator` tracks real, reported cost per call and enforces a hard per-session cap (`budget_cap_usd`, default `$0.50`). Once the cap is reached, further **paid** calls are refused outright — the pipeline doesn't crash, it just stops spending. Free tools (moodboard, audio, rule-based guardrails) are never blocked by the cap.

## Getting started

### Prerequisites

- Python 3.10+
- Node.js 18+
- Free API keys: [Gemini](https://ai.google.dev/) and [Unsplash](https://unsplash.com/developers)

### 1. Generate campaign data (Python backend)

```bash
git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
pip install -r requirements.txt

cp .env.example .env
# fill in GEMINI_API_KEY and UNSPLASH_ACCESS_KEY in .env
```

In one terminal, start the MCP server:

```bash
python server.py
```

In another, run the demo campaigns:

```bash
python run_demo.py               # all campaigns
python run_demo.py --campaign 1  # just one
```

This writes each campaign's output to `campaign_outputs/campaign_N/`.

### 2. Build and run the frontend

```bash
npm install
npm run build:demo-data   # reads campaign_outputs/, populates data/demos.ts + public/demos/
npm run dev
```

Open [http://localhost:3000](http://localhost:3000).

### Running the pipeline (BYOK)

The deployed site ships with pre-generated demo campaigns baked in at build time — no backend runs in production. Anyone can clone this repo and run the same pipeline against their own API keys following the steps above; no paid account, credit card, or approval process is required for either key.

## Deployment

Only the Next.js frontend needs deploying — the Python backend is a local generation tool, not a runtime dependency of the deployed site. See [`components/ByokPanel.tsx`](components/ByokPanel.tsx) for the in-app version of the run-it-yourself instructions.

Deployed on [Vercel](https://vercel.com): import the repo, framework auto-detects as Next.js, no environment variables required for the frontend build.

## License

[MIT](LICENSE)

## Author

Built by **Nibha S Dongre** — an agentic MCP pipeline, end to end.

[View on GitHub [→](https://github.com/YOUR_USERNAME/YOUR_REPO](https://github.com/nibhasdongre/AI-Multimodal-Campaign-Architect))