Dealer Video Prompt Engine — AI Automotive Dealer Creative Engine

Generates optimized Veo prompts for dealer promotional videos.

Quick Start

from engine import full_pipeline, CampaignObjective, AdConcept

result = full_pipeline(
    objective=CampaignObjective.ENQUIRY,
    ad_concept=AdConcept.PRESENTER_LED,
    car_model="Creta",
    car_colour="abyss black",
    brand="Hyundai",
)

print(result["prompt"])          # Ready-to-paste Veo prompt
print(result["validation"])      # Validation report
print(result["repair_log"])      # What the engine auto-repaired
print(result["blueprint"])       # The strict CreativeBlueprint object (ONE dominant action…)

Architecture

Brief (Hyundai wants more enquiries)
  ↓
Creative Director      campaign objective → ad concept → presenter → hook → timeline
  ↓
Scene Planner          shot composition → camera → action → location → lighting → ad timeline
  ↓
Script Engine          hook → offer → product → benefit → CTA (+ speech duration estimate)
  ↓
Offer Engine            verified claims only — no hallucinated numbers
  ↓
Reference Engine       person / vehicle / environment profiles → Veo Ingredients block
  ↓
Creative Blueprint     ONE strict internal object — Campaign · Presenter · Vehicle · Shot
                       · Action (ONE dominant + micro + background) · Script · Audio · Post
  ↓
Compiler               Blueprint → narrative Veo prompt (canonical payload) + structured form
  ↓
Validator              12 checks (camera count, action count, dialogue fit, text risk, offer claims…)
  ↓
Repair Loop            auto-trims/rewrites the plans → Blueprint rebuilt → recompiled
  ↓
Final Veo Prompt       9:16 · 8s · native audio · ONE dominant action, no competing intents

Modules

Module	Responsibility
creative_director.py	Business objective → creative strategy (concept, presenter, hook, ad timeline)
scene_planner.py	Builds ScenePlan: shot type, camera, action, location, lighting, timeline
script_engine.py	Generates structured scripts (hook/offer/product/benefit/CTA), estimates speech duration, compresses to fit 8s
offer_engine.py	Offer claims. Unverified offers render only generic wording — never invented numbers
reference_engine.py	Reference profiles for Veo 3.1 Ingredients-to-Video (person/vehicle/environment locks)
camera_engine.py	Shot-specific composition: headroom, hand visibility, safe zones, vehicle position
audio_engine.py	Voice/music/ambience/SFX/mixing priority; dialogue fit estimation
brand_engine.py	Per-OEM policy: approved models, terminology, no invented claims, logo handling
prompt_compiler.py	build_blueprint() folds every plan into a CreativeBlueprint; compilers render narrative + structured prompts from it
validator.py	12 automated checks — camera move count, action count, verb density, dialogue word count, estimated speech duration, subject count, reference integrity, frame safety, offer claim validation, text-generation risk
repair.py	Auto-fixes: collapses multiple camera moves, trims dialogue to fit, reduces actions

Example: Hyundai Enquiry Reel

Creative Director input:

objective=ENQUIRY
concept=PRESENTER_LED
→ "Salesperson-led finance-offer Reel. Salesperson beside Creta. One slow push-in.
   Salesperson speaks directly to camera. CTA: showroom visit."

Generated script (with speech duration estimates):

hook     (2.3s) Aapke liye ek khaas offer laaye hain.
offer    (2.0s) Ismein special finance options available hain.
product  (1.7s) Ye hamari best-selling SUV hai.
benefit  (1.7s) Comfort aur safety dono milegi.
cta      (1.7s) Aaj hi showroom visit kijiye.
→ 28 words ≈ 9.4s → auto-compressed to fit 8s

Final prompt (simplified):

Cinematography: medium presenter shot with a slow push-in
Subject: salesperson in branded Hyundai uniform
Secondary subject: abyss black Creta
Action: presenter speaks directly to camera while standing beside the car
Context: premium Hyundai dealership showroom. bright showroom track LEDs, warm and even.
Style: photorealistic commercial, shallow depth of field, professional energetic delivery
Audio: Dialogue: Aapke liye ek khaas offer laaye hain. Ismein special finance
  options available hain. Ye hamari best-selling SUV hai. Comfort aur safety dono.
  Music: upbeat professional (soft, behind dialogue). Ambient: soft showroom hum.
  SFX: subtle whoosh on camera move. CTA emphasis: final spoken line, clear and prominent
Brand: Hyundai (official dealership setting). Approved terminology: SmartSense
  safety, BlueLink connectivity, e-CALL (SOS), Panoramic Sunroof. No invented claims,
  no altered vehicle geometry. Do not generate readable logos or model-name text
Composite after generation (do not render in Veo): Offer card — central_safe_zone,
  CTA overlay — lower_third
Format: 9:16 vertical, 8 seconds (Veo 3.1)

Offer Truth Layer

Never hallucinate offer numbers.

# ⛔ Wrong:
offer = create_unverified_offer(OfferType.FINANCE_RATE)
offer.to_safe_text()  # → "Special finance offers available hain"

# ✅ When real data exists:
offer = create_verified_offer(
    offer_type=OfferType.EXCHANGE_BONUS,
    numeric_value=25000,
    unit="₹",
    validity="31 Dec 2026",
    model="Creta",
    source="dealer memo #142",
)
offer.to_safe_text()  # → "₹25,000 exchange bonus" + validity

The validator runs check_offer_claims() — if an unverified offer appears alongside specific numbers in the script, it flags hallucination risk.

Speech Duration Fit

Veo's native dialogue is real — the engine uses one canonical SpeechModel (words-per-second per language + a safe budget of 85% of ad duration, so an 8s ad targets ~6.5-7.0s of speech):

from engine import SpeechModel, ScriptLanguage
r = SpeechModel.fit_report("28-word script...", 8, ScriptLanguage.HINDI)
# {'word_count': 28, 'estimated_seconds': 8.8, 'fits_at_all': False, ...}

Scripts that overflow are rewritten/condensed by repair.py before compilation — trimming is budget-first (product → benefit → hook → offer → CTA), never a mid-sentence chop, and never strips unverified superlatives into the void.

Reference Intelligence (Veo 3.1 Ingredients)

ref = create_reference_profile(
    vehicle_model="Creta", vehicle_colour="abyss black",
    person_hair="black", person_skin_tone="warm",
    person_clothing="dark blue dealership uniform",
)
reference_to_ingredients_block(ref)
# "Reference images: Vehicle reference: abyss black Creta…; Person reference: …; Environment reference: …"

Vehicle identity (model, colour, trim) stays immutable; camera attributes (position, orientation) are mutable and free to move during generation; a scale graph pins presenter-to-vehicle proportions.

Brands Supported

Hyundai, Maruti Suzuki, Mahindra, Kia, Tata (each with approved models + variant-level feature checks, e.g. Panoramic Sunroof only on SX(O) trims). Unknown brands fall back to a strict generic policy.

Generation Modes

• A Text → Video (single shot, default)
• B Reference → Video (Veo 3.1 Ingredients)
• C MULTI_SHOT_TIMED — timestamped segments from actually-fitted script timing
• D validate_duration() enforces Veo 3.1's 4s/6s/8s clip lengths

Requirements

• Engine: Python 3.9+, no external dependencies (run python3 tests/run_all.py).
• Agent layer (agent/): Python 3.12+, langgraph (see requirements.txt). LLM provider SDKs (openai / anthropic / google-generativeai) are optional and lazily imported. Run ./.venv/bin/python tests/run_agent_all.py.

Agent Engine (agent/)

A LangGraph multi-agent loop on top of the deterministic engine. The Blueprint stays canonical — agents never write prompt text directly, they emit bounded typed mutations the engine applies and re-compiles:

user brief
  ↓
Strategist   proposes initial creative surface (hook/offer/benefit/CTA/voice/pacing/duration/ad_concept)
  ↓
Compile      engine builds the canonical Blueprint + narrative/structured prompts
  ↓
Critic       10-dim rubric (one dominant action, dialogue fit, offer integrity, frame safety …)
  ↺  gate fails → Modifier → engine re-compiles → Critic
  ↓
Finalize     best engine-valid candidate  (accepted only if engine validation passed + rubric gate ≥ target)

• Constrained mutation targets (agent/mutations.py): hooks/offers/benefits/CTAs are short strings; voice_style/pacing/ad_concept are enums; duration ∈ [4, 8] (Veo 3.1 clip lengths). objective, brand, model, car_colour, offer, reference are immutable anchors.
• Dialogue audit: the actual fitted script is compared to the requested creative lines. A proposed line that is silently dropped/altered (speech-budget fit) fails the dialogue_fit dimension, so the loop can never accept a prompt where a requested hook didn't land.
• Audit trail: every round is logged to agent_runs/<run_id>/trail.jsonl + a final.json (deterministic keys, inputs, outputs, scores, rejected mutations).
• Providers: openai (gpt-4o), anthropic (claude-sonnet-4-20250514), gemini (gemini-2.0-flash), and an offline deterministic fake for tests/demos.

.venv/bin/python examples/run_agent.py        # offline fake-LLM demo -> accepted prompt + audit trail
VEO_AGENT_PROVIDER=openai VEO_AGENT_API_KEY=... .venv/bin/python examples/run_agent.py

Customize via env vars: VEO_AGENT_MODEL, VEO_AGENT_MAX_ITERATIONS (default 3), VEO_AGENT_TARGET_SCORE (default 85), VEO_AGENT_AUDIT_DIR.