Adclip

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](docs/QUICKSTART.md) — zero-cost DTC creative, email, and learning walkthrough.
• [Examples](examples/README.md) — marketer-facing campaign portfolio.
• [Documentation index](docs/README.md) — architecture and capability docs.
• [LLM guidance](LLM.md) — 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

Current inferential verdicts are deliberately limited to rate metrics with explicit aggregate numerators/denominators: CTR, outbound CTR, and action rate. CPA and ROAS remain descriptive without variance/event-level evidence. Observational comparisons remain inconclusive by design, and experiment outputs currently keep causal_claim: false.

See Experiment contract.

Recurring model bake-offs

Defaults should be promoted by evidence rather than reputation.

# Dry-run plan only

adclip bakeoff \ --modality image \ --routes general,text-heavy,bulk,draft \ --output-dir ./image-bakeoff

Live execution requires both --execute and normal paid-provider authorization. Results record route, provider, model, options, latency, estimated cost, artifact SHA-256, failures, evaluation dimensions, and human-review fields.

Text providers

Local HTTP inference:

export ADCLIP_TEXT_PROVIDER=openai-compatible

export ADCLIP_TEXT_MODEL=qwen2.5:14b export ADCLIP_OPENAI_BASE_URL=http://127.0.0.1:11434/v1 export ADCLIP_RUNTIME_MODE=offline adclip copy examples/01-dtc-skincare/brief.json

See Model providers.

MCP

Example local registration:

{

"mcpServers": { "adclip": { "command": "adclip-mcp" } } }

The MCP surface exposes the same campaign, routing, email, performance, and experiment application services used by the CLI. Important newer tools include:

adclip_list_media_routes

adclip_recommend_media_route adclip_email_generate_campaign adclip_email_render adclip_email_lint adclip_email_patch_html adclip_email_patch_message adclip_performance_link_meta adclip_performance_deployments adclip_performance_sync_meta adclip_performance_report adclip_performance_compare adclip_experiment_create adclip_experiments adclip_experiment_evaluate adclip_experiment_next_test

Runtime and billing safety

Supported runti