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 — 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.gitcd adclippython3.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 statusadclip formatsadclip routesadclip routes --modality imageadclip route-recommend image --text-heavyadclip estimate examples/01-dtc-skincare/brief.jsonadclip email --helpadclip performance --help

Routed creative generation

# Route defaultsadclip run brief.json
# Task-specific selectionadclip run brief.json \  --image-route text-heavy \  --video-route premium
# Explicit provider/model overrides remain authoritativeadclip 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 locallyadclip 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 fixtureadclip 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 onlyadclip 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-compatibleexport ADCLIP_TEXT_MODEL=qwen2.5:14bexport ADCLIP_OPENAI_BASE_URL=http://127.0.0.1:11434/v1export ADCLIP_RUNTIME_MODE=offlineadclip 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_routesadclip_recommend_media_routeadclip_email_generate_campaignadclip_email_renderadclip_email_lintadclip_email_patch_htmladclip_email_patch_messageadclip_performance_link_metaadclip_performance_deploymentsadclip_performance_sync_metaadclip_performance_reportadclip_performance_compareadclip_experiment_createadclip_experimentsadclip_experiment_evaluateadclip_experiment_next_test

Runtime and billing safety

Supported runtime modes:

onlinerestricted_networkofflineair_gapped

External generation providers are refused offline/air-gapped. Loopback text inference remains available. Potentially paid generation requires:

ADCLIP_ALLOW_LIVE_APIS=1

The Meta performance connector is a separate read-only network adapter and does not use the generation-spend authorization flag.

Tests

The project test suite is designed to run without paid APIs or live marketing accounts:

python -m pytestpython -m compileall src/adclip

Current status and next milestones

The current core includes generation, email authoring, exact creative lineage, read-only Meta performance ingestion, attribution-safe reporting, explicit experiments, and next-test recommendations.

The largest remaining product gaps are:

1. SQLite/migrations as authoritative state, content-addressed artifacts, and durable resumable jobs;
2. BrandKit and SourceLibrary;
3. bundled local browser workbench;
4. creative-attribute extraction and experiment-aware controlled generation;
5. Google Ads, TikTok, and ESP performance adapters;
6. fatigue/change-point analysis and richer CPA/ROAS evidence;
7. separately authorized draft/paused deployment workflows.

See Standalone architecture for the roadmap.