Ad Video Engine

Turn a structured promotion brief into a reviewable short-form video campaign: themes, hooks, scripts, production prompts, posting copy, and render-ready specifications.

The engine grew from a practical marketing problem: creative work becomes difficult to repeat when the brief, strategic reasoning, production prompt, and quality checks live in separate tools. Ad Video Engine makes that process explicit and inspectable.

What it does

1. Validates a YAML promotion brief.
2. Plans six campaign concepts with a local Ollama model or an intentionally simple offline demo planner.
3. Passes concepts through a replaceable ranking boundary; the public edition preserves model order rather than publishing a production scoring policy.
4. Selects three ads and writes stable JSON specifications.
5. Produces posting copy, a QA report, and a run manifest.
6. Optionally hands specifications to a renderer interface; the public edition ships only a local mock adapter.

The default planning route uses a local model. The deliberately simple demo route is useful for tests, CI, and reviewing the complete output contract without model access.

Quick start

Requires Python 3.11 or newer.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

adgen create \
  --brief examples/brief.yaml \
  --planner demo \
  --skip-render

The command creates a timestamped directory under runs/ containing:

campaign.json
ad_specs/ad_01.json
ad_specs/ad_02.json
ad_specs/ad_03.json
posting_copy.md
qa_report.md
manifest.json

For local-model planning, start Ollama and provide the installed model:

adgen create \
  --brief examples/brief.yaml \
  --planner ollama \
  --ollama-model llama3:latest \
  --skip-render

Brief contract

product_name: Northstar Workflow
product_description: A fictional workspace for repeatable operational workflows.
target_audience: Small teams that want a reviewable campaign package.
offer_or_cta: Explore the fictional product brief.
pain_points:
  - Manual research and content work consumes hours every week.
proof_points:
  - Turns one clear brief into reusable campaign artifacts.
brand_tone: Sharp, practical, and confident.
assets:
  logos: []
  screenshots: []

Required fields are checked before planning. Optional asset paths are verified unless --no-asset-check is supplied.

Design decisions

• Brief first: generation cannot begin without an explicit audience, offer, pain, and proof.
• Stable artifacts: every run is written to files that can be reviewed, versioned, or sent to another rendering system.
• Local planning option: Ollama keeps early creative development local and makes the model replaceable.
• Deterministic CI: the demo planner exercises the campaign and artifact contracts without network or model dependencies.
• Private strategy boundary: the ranking protocol is injectable; production weights and competitive heuristics are intentionally not included.
• Private provider boundary: VideoProvider defines the integration contract, while authenticated paid-provider adapters remain private.
• Safety at the prompt boundary: known celebrity and entertainment-IP references are removed before a render prompt leaves the engine.

Current boundary

The repository proves brief validation, production-quality structured prompting, replaceable ranking and rendering boundaries, artifact generation, and QA output. It does not disclose a production ranking policy or authenticated provider adapter, does not claim generated campaigns outperform human creative direction, and contains no real client data.

Development

pytest -q

See CONTRIBUTING.md for the contribution workflow.

License

MIT