adclip

An open, standalone, model-routed marketing creative and learning engine.

adclip turns campaign intent into policy-checked copy, static creative, short-form video, and responsive email; preserves exact creative lineage; reads performance back from deployed creative; and structures that evidence into explicit experiments and next-test recommendations.

brief
  -> copy / image / video / email
  -> exact creative artifacts + provenance
  -> deployment lineage
  -> performance observations
  -> experiment evidence
  -> next test

MCP is one interface into adclip, not the architecture. The same application services are available to the standalone CLI and are intended to back a future local browser workbench.

Why adclip exists

Most AI marketing stacks split the workflow across a copy tool, image/video generators, an email platform, ad-platform dashboards, and creative analytics. adclip's goal is to keep the campaign model, creative lineage, and learning loop portable, while letting model providers and delivery platforms remain replaceable adapters.

Core principles:

• Model-neutral: workflows request capabilities/routes rather than hard-code one model vendor.
• Standalone: CLI workflows do not require an MCP host.
• Local-first: local command and OpenAI-compatible inference can run offline or air-gapped when configured appropriately.
• Portable: campaign artifacts, email HTML/text, manifests, deployment mappings, observations, and experiments remain inspectable files.
• Evidence-aware: observational rankings are not silently presented as causal lift.
• Spend-safe: paid generation is opt-in and route fallbacks are not silently executed.

Start here

• Quickstart — zero-cost DTC creative, email, and learning walkthrough.
• Examples — marketer-facing campaign portfolio.
• Documentation index — architecture and capability docs.
• LLM guidance — model-neutral contributor/agent contract.

Install from PyPI:

pipx install adclip

The PyPI release can lag the current repository. For the exact main feature set documented here, install from source:

git clone https://github.com/dreliq9/adclip.git
cd adclip
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Python 3.11+ is required.

Five-minute zero-cost demo

Generate a fictional DTC skincare launch across Meta, Reels/TikTok, and Google using only fake creative providers:

adclip run examples/01-dtc-skincare/brief.json \
  --text-provider fake \
  --image-provider fake \
  --video-provider fake

Render the matching checked-in launch email without a model call:

adclip email render \
  examples/01-dtc-skincare/email_brief.json \
  examples/01-dtc-skincare/email_message.json \
  --output-dir ./adclip_skincare_email_render

Build a complete synthetic creative-test bundle:

python examples/06-creative-experiment/build_demo.py

Then inspect the evidence:

adclip performance report ./adclip_creative_test_demo \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion

The builder prints an experiment ID that can be passed to experiment-evaluate and next-test. None of the commands above need a paid model API or live ad account.

Example portfolio

The repository examples are organized around marketing problems rather than internal subsystems:

See examples/README.md for the business goal, audience, hypothesis, and commands behind each case.

Current capability map

Standalone CLI

Useful discovery commands:

adclip status
adclip formats
adclip routes
adclip routes --modality image
adclip route-recommend image --text-heavy
adclip estimate examples/01-dtc-skincare/brief.json
adclip email --help
adclip performance --help

Routed creative generation

# Route defaults
adclip run brief.json

# Task-specific selection
adclip run brief.json \
  --image-route text-heavy \
  --video-route premium

# Explicit provider/model overrides remain authoritative
adclip run brief.json \
  --image-route general \
  --image-provider openai \
  --image-model gpt-image-2 \
  --video-route budget \
  --video-provider fal \
  --video-model wan-2.7

Compatibility aliases remain:

--llm          -> --text-provider
--llm-model    -> --text-model
--image        -> --image-provider
--video        -> --video-provider

Current media routes

Reference-image, vector, multi-reference, image-animation, and footage-edit routes are cataloged but remain non-executable until their required input contracts/adapters exist. See Model routing.

Email campaigns and HTML editing

Email is native campaign state rather than a wrapper around one ESP.

# Render the canonical launch message locally
adclip email render \
  examples/01-dtc-skincare/email_brief.json \
  examples/01-dtc-skincare/email_message.json \
  --output-dir ./rendered-email

# Apply stable block-level edits to a generic fixture
adclip email patch-message \
  examples/email_message.json \
  examples/email_patches.json \
  --output ./message-edited.json

Generated campaigns contain portable message JSON, responsive HTML, plain text, headers, lint reports, and a manifest. Sequence generation uses a configured text provider; the generic fake text provider is a copy-generation fixture, not an email-sequence generator. Sending, consent, suppression, and ESP account state remain connector responsibilities.

See Email campaigns.

Performance and creative learning

adclip can map an exact local creative to an existing Meta ad and read Insights back without adding Meta mutation methods.

adclip performance link-meta ./campaign \
  --variant-id v01 \
  --account-id act_123456 \
  --ad-id 987654321

export ADCLIP_META_ACCESS_TOKEN=...

adclip performance sync-meta ./campaign \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion

Measurement windows are keyed by (since, until, action_report_time), so conversion- and impression-attributed rows for the same dates are not silently combined.

Descriptive comparison:

adclip performance compare ./campaign \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion \
  --metric ctr

See Performance learning.

Explicit creative experiments

The checked-in demo uses a familiar paid-social question: does vivid problem framing beat a plain product-benefit hook?

python examples/06-creative-experiment/build_demo.py

Or declare your own experiment before interpreting results:

adclip performance experiment-create ./campaign \
  --name "Hook CTR test" \
  --hypothesis "Problem framing increases CTR" \
  --changed-factor hook \
  --control-variant v01 \
  --treatment-variant v02 \
  --control-value "plain benefit" \
  --treatment-value "problem framing" \
  --metric ctr