Publish the privacy-safe Ad Video Engine

Author: EmilianoOnTheRunn

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e '.[dev]'
+      - run: pytest -q

.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+runs/
+briefs/

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Contributions should keep the engine inspectable and provider-independent.
+
+1. Create a focused branch.
+2. Add or update tests for behavioral changes.
+3. Run `pytest -q`.
+4. Do not commit briefs, outputs, credentials, client material, or paid-provider responses.
+5. Open a pull request explaining the user-facing effect and the validation performed.
+
+New planning or rendering providers must preserve the existing campaign and `AdSpec` output contracts.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emiliano Ruiz Gomez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,100 @@
+# 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.
+
+![Ad Video Engine workflow](assets/architecture.svg)
+
+## 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.
+
+```bash
+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:
+
+```text
+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:
+
+```bash
+adgen create \
+  --brief examples/brief.yaml \
+  --planner ollama \
+  --ollama-model llama3:latest \
+  --skip-render
+```
+
+## Brief contract
+
+```yaml
+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
+
+```bash
+pytest -q
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.
+
+## License
+
+[MIT](LICENSE)

ad_video_engine/__init__.py

@@ -0,0 +1,3 @@
+"""Cinematic social ad video engine."""
+
+__version__ = "0.1.0"

ad_video_engine/cli.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .errors import AdGenError
+from .io import copy_brief, create_run_dir, load_brief, write_json
+from .models import AdSpec, assert_asset_paths_exist
+from .outputs import manifest, posting_copy, qa_report
+from .planner import DemoPlanner, OllamaPlanner, build_campaign
+from .providers import provider_from_name
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "create":
+            return create(args)
+        parser.error("Unknown command")
+    except AdGenError as exc:
+        print(f"adgen: error: {exc}", file=sys.stderr)
+        return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="adgen", description="Create cinematic social ad videos from promotion briefs.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    create_parser = subparsers.add_parser("create", help="Generate a campaign and render ads.")
+    create_parser.add_argument("--brief", required=True, type=Path, help="Path to promotion brief YAML.")
+    create_parser.add_argument("--root", type=Path, default=Path.cwd(), help="Project root containing runs/ output.")
+    create_parser.add_argument("--planner", choices=["ollama", "demo"], default="ollama", help="Planning backend.")
+    create_parser.add_argument("--ollama-base-url", default="http://localhost:11434/v1", help="OpenAI-compatible Ollama base URL.")
+    create_parser.add_argument("--ollama-model", default="llama3:latest", help="Ollama model for planning.")
+    create_parser.add_argument("--provider", choices=["mock"], default="mock", help="Public-edition render adapter.")
+    create_parser.add_argument("--skip-render", action="store_true", help="Write campaign/ad specs without rendering videos.")
+    create_parser.add_argument("--no-asset-check", action="store_true", help="Do not verify optional asset paths exist.")
+    return parser
+
+
+def create(args: argparse.Namespace) -> int:
+    brief_path = args.brief.expanduser().resolve()
+    if not brief_path.exists():
+        raise AdGenError(f"Brief file not found: {brief_path}")
+
+    brief = load_brief(brief_path)
+    if not args.no_asset_check:
+        assert_asset_paths_exist(brief, brief_path)
+
+    run_dir = create_run_dir(args.root.resolve(), brief.product_name)
+    copy_brief(brief_path, run_dir)
+
+    planner = (
+        OllamaPlanner(base_url=args.ollama_base_url, model=args.ollama_model)
+        if args.planner == "ollama"
+        else DemoPlanner()
+    )
+    campaign = build_campaign(brief, planner)
+    write_json(run_dir / "campaign.json", campaign)
+
+    ad_specs = [
+        AdSpec(**raw)
+        for raw in campaign["selected_ads"]
+    ]
+    for spec in ad_specs:
+        write_json(run_dir / "ad_specs" / f"{spec.id}.json", spec.to_dict())
+
+    rendered = []
+    if not args.skip_render:
+        provider = provider_from_name(args.provider)
+        for spec in ad_specs:
+            rendered.append(provider.render(spec, run_dir / "renders"))
+
+    (run_dir / "posting_copy.md").write_text(posting_copy(ad_specs), encoding="utf-8")
+    (run_dir / "qa_report.md").write_text(qa_report(ad_specs, rendered), encoding="utf-8")
+    write_json(run_dir / "manifest.json", manifest(run_dir, campaign, rendered))
+
+    print(f"Run complete: {run_dir}")
+    for item in rendered:
+        print(f"Rendered {item.ad_id}: {item.path}")
+    if args.skip_render:
+        print("Render skipped. Ad specs are ready for paid rendering.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ad_video_engine/errors.py

@@ -0,0 +1,14 @@
+class AdGenError(Exception):
+    """Base application error with user-facing message."""
+
+
+class BriefValidationError(AdGenError):
+    """Raised when a promotion brief is missing required fields."""
+
+
+class PlannerError(AdGenError):
+    """Raised when the planning backend cannot generate a campaign."""
+
+
+class RenderError(AdGenError):
+    """Raised when video rendering fails."""

ad_video_engine/io.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models import PromotionBrief
+
+
+def load_brief(path: Path) -> PromotionBrief:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError("Brief YAML must contain a mapping.")
+    return PromotionBrief.from_dict(data)
+
+
+def write_yaml(path: Path, data: dict[str, Any]) -> None:
+    path.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", value.lower()).strip("-")
+    return slug[:60] or "campaign"
+
+
+def create_run_dir(root: Path, product_name: str) -> Path:
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    run_dir = root / "runs" / f"{timestamp}-{slugify(product_name)}"
+    (run_dir / "ad_specs").mkdir(parents=True, exist_ok=False)
+    (run_dir / "renders").mkdir(parents=True, exist_ok=True)
+    return run_dir
+
+
+def copy_brief(source: Path, target_dir: Path) -> Path:
+    target = target_dir / "brief.yaml"
+    shutil.copyfile(source, target)
+    return target