docs/creative_inventor.md

# Creative Inventor: Self-Generating Ad Angles, Concepts, Visuals & Triggers

The **Creative Inventor** is a system that generates new ad angles, concepts, visual directions, and psychological triggers by itself—either as part of the extensive flow or standalone for export/review.

## How It Works

1. **Inputs**: Niche, target audience, offer; optional trend context, competitor insights, or existing strategy reference (to diverge from).
2. **LLM**: A single structured call invents `n` “essentials,” each with:
   - **Psychology trigger** – e.g. validation before solution, future regret, justified scarcity.
   - **Angles** – reasons to care; reframes (e.g. biology not willpower, last first day).
   - **Concepts** – execution/storyline (e.g. crossed-out labels, progress bar + social proof).
   - **Visual directions** – concrete visual ideas (e.g. “progress bar 87% full”, “grid of crossed-out DAY 1s”).
   - **Hooks** – scroll-stopping headline phrases.
   - **Visual styles** – short scene descriptions for image prompts.
3. **Output**: List of `InventedEssential` used by the extensive flow or returned by the API.

## Where It’s Used

### 1. Inside the Extensive Flow (default)

When you run **extensive generation** with `use_creative_inventor=True` (default):

- **Step 1** is “Invent new ad angles, concepts, visuals, and psychological triggers” (Creative Inventor).
- The invented essentials are converted to the same shape as the researcher output and passed to the **creative director**.
- Rest of the flow is unchanged: retrieve knowledge → creative director → designer → copywriter → image generation.

So the extensive flow can **create new angles/concepts/visuals/triggers by itself** instead of relying only on the fixed researcher step.

### 2. Standalone “Invent Only”

- **API**: `POST /extensive/invent`  
  Body: `niche`, `target_audience`, `offer`, `n`, optional `trend_context`, `export_as_text`.  
  Returns: `essentials` (JSON) and optionally `export_text` (human-readable markdown).
- **Code**: `creative_inventor_service.invent(...)` and `creative_inventor_service.invent_and_export(...)` in `services/creative_inventor.py`.

Use this to generate ideas for review, export to docs, or to feed into other tools without generating ads.

### 3. Researcher-Only Flow

Set `use_creative_inventor=False` in the extensive generator (or send `use_creative_inventor: false` in the API). Step 1 is then the original **researcher** (psychology triggers, angles, concepts from the existing prompt), and the rest of the pipeline is unchanged.

## API Summary

| Endpoint | Purpose |
|----------|--------|
| `POST /extensive/generate` | Full extensive run; by default uses Creative Inventor in step 1. Supports `use_creative_inventor`, `trend_context`. |
| `POST /extensive/invent` | Invent only; returns `essentials` (+ optional `export_text`). No ad generation. |

## Files

- **`services/creative_inventor.py`** – `CreativeInventorService`, `InventedEssential`, `invent()`, `invent_and_export()`.
- **`services/third_flow.py`** – `get_essentials_via_inventor()`, `_invented_to_essentials()`; converts inventor output to `ImageAdEssentials` for the creative director.
- **`services/generator.py`** – `generate_ad_extensive(..., use_creative_inventor=True, trend_context=...)`; when True, step 1 calls the inventor instead of the researcher.
- **`api/routers/extensive.py`** – Extensive job run with inventor/researcher switch; `POST /extensive/invent`.
- **`api/schemas.py`** – `ExtensiveGenerateRequest` (with `use_creative_inventor`, `trend_context`), `InventOnlyRequest`, `InventedEssentialSchema`, `InventOnlyResponse`.

## Optional: Seeding or Constraining the Inventor

You can pass:

- **`existing_reference`** – Short summary of existing strategies so the inventor can diverge and avoid repeating.
- **`trend_context`** – e.g. “New Year”, “Valentine’s Day”; used for relevance.
- **`competitor_insights`** – e.g. notes from competitor ad analysis; used to differentiate.

These are supported in `creative_inventor_service.invent(...)` and can be wired through the API or generator if you add the corresponding request fields.