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.