---
title: Content Generation Agent
emoji: ✍️
colorFrom: indigo
colorTo: purple
sdk: streamlit
sdk_version: 1.38.0
app_file: app.py
pinned: false
---

# ✍️ Content Generation Agent (MVP)

A production-shaped AI marketing agent that turns a founder's raw product update note into polished, grounded, and guardrailed marketing copy for **LinkedIn**, **Instagram**, and **WhatsApp**, along with a downloadable branded **PowerPoint deck**.

Built as a **Streamlit** app. Run it fully offline in **Mock Mode** for a zero-cost interactive demo, or connect a **Groq** / **OpenRouter** API key to crawl and generate copy for your live product.

---

## 🚀 Live Demo Quick Start

### 1. Local Setup
Ensure you have Python 3.10+ installed. Run the following commands in your terminal:

```bash
# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows (PowerShell):
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Run Tests
Verify the pipeline works with the offline mock runner:
```bash
python -m tests.test_pipeline
```

### 3. Launch UI
Launch the Streamlit web application:
```bash
streamlit run app.py
```
This will automatically open the application at **[http://localhost:8501](http://localhost:8501)** in your browser.

---

## 🛠️ Offline Mock Mode vs. Live Mode

The application supports two execution modes, switchable dynamically from the sidebar settings:

### 🟢 Mock Mode (Default)
* **API Key Required**: None ($0 cost).
* **Behavior**: Uses deterministic mock responses to simulate the pipeline.
* **Use Case**: Perfect for testing the UI, inspecting formatting, and running demo sessions offline.

### 🔵 Live Mode
* **API Key Required**: A valid **Groq** or **OpenRouter** key (pasted into the sidebar or set via `.env`).
* **Behavior**: Active crawler scrapes website content, and the selected LLM (e.g., Llama 3.3, Claude 3.5 Sonnet, Gemini Flash) generates live copy.

---

## 📐 Pipeline Architecture

The agent is designed as a structured pipeline to prevent hallucinations, enforce constraints, and rank generated copy:

```mermaid
graph TD
    A[Product Website] -->|Crawler| B(Crawled Pages)
    B -->|Brand Brain LLM| C[🧠 Brand Brain]
    C -->|Prompt Suggestions| D[Founder Input]
    D -->|Brief Builder LLM| E[📋 Structured Brief]
    C & E -->|Fact Pack Builder LLM| F[📦 Fact Pack]
    F -->|LinkedIn Writer LLM| G1[LinkedIn Copy]
    F -->|Instagram Writer LLM| G2[Instagram Copy]
    F -->|WhatsApp Writer LLM| G3[WhatsApp Copy]
    G1 & G2 & G3 -->|Guardrail Layer| H[Claim Checking + Lints + Policy]
    H -->|Ranker Heuristics| I[🏆 Scored & Badged Output]
    F & E -->|python-pptx| J[📊 Branded PPT Deck]
```

---

## 🔒 Grounded Guardrails & Robustness

To ensure enterprise-level reliability, the agent implements several production safety features:

1. **Untrusted Data Handling**: Scraped website content is treated strictly as raw context/data. The system prompts instruct LLM writers to ignore any instructions embedded in crawled HTML (preventing prompt injection).
2. **Fact Pack Grounding**: Writers never see raw crawled HTML; they only write copy using the curated **Fact Pack** approved facts to prevent hallucinations.
3. **Deterministic Guardrails**:
   * **Claim Checker**: Flags numerical values, compliance assertions, and superlatives (like "guaranteed") that cannot be verified in the Fact Pack.
   * **Lints**: Enforces strict word count, character, and hashtag limits per channel.
   * **Policy Filter**: Flags offensive, inappropriate, or out-of-bounds language.
4. **Resilient Website Crawler**:
   * **Sitemap-First BFS**: Prioritizes crawling specific entered seed URLs before falling back to sitemap links.
   * **Browser Emulation**: Bypasses bot protections using standard Chrome headers.
   * **SSL Verification Fallback**: Retries unverified connections, allowing development and local test sites to be crawled.
5. **Unicode Surrogate Repair**: Automatically sanitizes emoji surrogate code points from API models to prevent web client encoding crashes.

---

## 📂 Codebase Layout

```
content_agent/
├── app.py                 # Streamlit UI & Interactive Interface
├── core/
│   ├── config.py          # Environment, Settings & Model Registry
│   ├── crawler.py         # Resilient Web Scraper (requests + bs4)
│   ├── brand_brain.py     # Brand Brain builder from scraped corpus
│   ├── brief.py           # Structurer for the founder brief
│   ├── fact_pack.py       # Grounded Fact Pack builder
│   ├── writers.py         # Multi-channel copywriting templates
│   ├── guardrails.py      # Claim, policy, and formatting validation
│   ├── ranker.py          # Score evaluation for variants
│   ├── ppt.py             # PowerPoint rendering engine (python-pptx)
│   ├── llm.py             # OpenAI-compatible API client & parser
│   ├── mock_backend.py    # Offline simulation database
│   └── schemas.py         # Strict dataclasses for pipeline state
├── tests/
│   └── test_pipeline.py   # Complete integration & test suite
└── Dockerfile             # Deployment config
```

---

## 🐳 Docker Deployment

To deploy in any cloud environment:
```bash
docker compose up --build
```
The app will bind to port `8501`.