{
  "markdown": "# adclip\n\n<!-- mcp-name: io.github.dreliq9/adclip -->\n\n**An open, standalone, model-routed marketing creative and learning engine.**\n\nadclip turns campaign intent into policy-checked copy, static creative,\nshort-form video, and responsive email; preserves exact creative lineage; reads\nperformance back from deployed creative; and structures that evidence into\nexplicit experiments and next-test recommendations.\n\n```text\nbrief\n  -> copy / image / video / email\n  -> exact creative artifacts + provenance\n  -> deployment lineage\n  -> performance observations\n  -> experiment evidence\n  -> next test\n```\n\nMCP is one interface into adclip, not the architecture. The same application\nservices are available to the standalone CLI and are intended to back a future\nlocal browser workbench.\n\n## Why adclip exists\n\nMost AI marketing stacks split the workflow across a copy tool, image/video\ngenerators, an email platform, ad-platform dashboards, and creative analytics.\nadclip's goal is to keep the **campaign model, creative lineage, and learning\nloop portable**, while letting model providers and delivery platforms remain\nreplaceable adapters.\n\nCore principles:\n\n- **Model-neutral:** workflows request capabilities/routes rather than hard-code\n  one model vendor.\n- **Standalone:** CLI workflows do not require an MCP host.\n- **Local-first:** local command and OpenAI-compatible inference can run offline\n  or air-gapped when configured appropriately.\n- **Portable:** campaign artifacts, email HTML/text, manifests, deployment\n  mappings, observations, and experiments remain inspectable files.\n- **Evidence-aware:** observational rankings are not silently presented as\n  causal lift.\n- **Spend-safe:** paid generation is opt-in and route fallbacks are not silently\n  executed.\n\n## Start here\n\n- **[Quickstart](docs/QUICKSTART.md)** — zero-cost DTC creative, email, and learning walkthrough.\n- **[Examples](examples/README.md)** — marketer-facing campaign portfolio.\n- **[Documentation index](docs/README.md)** — architecture and capability docs.\n- **[LLM guidance](LLM.md)** — model-neutral contributor/agent contract.\n\nInstall from PyPI:\n\n```bash\npipx install adclip\n```\n\nThe PyPI release can lag the current repository. For the exact `main` feature\nset documented here, install from source:\n\n```bash\ngit clone https://github.com/dreliq9/adclip.git\ncd adclip\npython3.11 -m venv .venv\n.venv/bin/pip install -e \".[dev]\"\n```\n\nPython 3.11+ is required.\n\n## Five-minute zero-cost demo\n\nGenerate a fictional DTC skincare launch across Meta, Reels/TikTok, and Google\nusing only fake creative providers:\n\n```bash\nadclip run examples/01-dtc-skincare/brief.json \\\n  --text-provider fake \\\n  --image-provider fake \\\n  --video-provider fake\n```\n\nRender the matching checked-in launch email without a model call:\n\n```bash\nadclip email render \\\n  examples/01-dtc-skincare/email_brief.json \\\n  examples/01-dtc-skincare/email_message.json \\\n  --output-dir ./adclip_skincare_email_render\n```\n\nBuild a complete synthetic creative-test bundle:\n\n```bash\npython examples/06-creative-experiment/build_demo.py\n```\n\nThen inspect the evidence:\n\n```bash\nadclip performance report ./adclip_creative_test_demo \\\n  --since 2026-08-01 \\\n  --until 2026-08-07 \\\n  --action-report-time conversion\n```\n\nThe builder prints an experiment ID that can be passed to\n`experiment-evaluate` and `next-test`. None of the commands above need a paid\nmodel API or live ad account.\n\n## Example portfolio\n\nThe repository examples are organized around marketing problems rather than\ninternal subsystems:\n\n| Example | Marketing workload | Main surfaces |\n| --- | --- | --- |\n| `01-dtc-skincare` | Product launch / first purchase | Meta, Reels, TikTok, Google, email |\n| `02-b2b-saas-lead-gen` | Qualified demo generation | LinkedIn, Google Search |\n| `03-local-service-lead-gen` | Local direct-response leads | Meta, Google Search |\n| `04-subscription-winback` | Lifecycle retention | Email |\n| `05-mobile-app-acquisition` | Free-trial acquisition | TikTok, Reels, Shorts, Meta |\n| `06-creative-experiment` | Controlled hook learning | Synthetic Meta observations |\n\nSee [examples/README.md](examples/README.md) for the business goal, audience,\nhypothesis, and commands behind each case.\n\n## Current capability map\n\n| Area | Current capability |\n| --- | --- |\n| Campaign briefs | Structured `AdBrief`, formats, policy constraints, cost estimation |\n| Copy | Provider-neutral generation, filtering, scoring, healing/judge compatibility |\n| Images | Task routes over fal/direct OpenAI/fake adapters with model-family schemas |\n| Video | Routed fal/fake generation for short-form formats |\n| Model selection | Explicit route/provider/model/options separation and bake-offs |\n| Email | Sequence generation, structured blocks, responsive HTML/text, headers, lint, patching |\n| Lineage | Stable campaign IDs and artifact-bound creative IDs |\n| Performance | Explicit deployment mappings and read-only Meta Insights sync |\n| Reporting | Attribution-safe exact windows and descriptive creative comparison |\n| Experiments | Control/treatment artifacts, changed factor, thresholds, rate confidence intervals |\n| Learning | Supported/contradicted/inconclusive evidence and deterministic next-test actions |\n| Interfaces | CLI + MCP over shared application services |\n| Safety | Runtime network modes, paid-generation gate, read-only Meta connector |\n\n## Standalone CLI\n\nUseful discovery commands:\n\n```bash\nadclip status\nadclip formats\nadclip routes\nadclip routes --modality image\nadclip route-recommend image --text-heavy\nadclip estimate examples/01-dtc-skincare/brief.json\nadclip email --help\nadclip performance --help\n```\n\n### Routed creative generation\n\n```bash\n# Route defaults\nadclip run brief.json\n\n# Task-specific selection\nadclip run brief.json \\\n  --image-route text-heavy \\\n  --video-route premium\n\n# Explicit provider/model overrides remain authoritative\nadclip run brief.json \\\n  --image-route general \\\n  --image-provider openai \\\n  --image-model gpt-image-2 \\\n  --video-route budget \\\n  --video-provider fal \\\n  --video-model wan-2.7\n```\n\nCompatibility aliases remain:\n\n```text\n--llm          -> --text-provider\n--llm-model    -> --text-model\n--image        -> --image-provider\n--video        -> --video-provider\n```\n\n## Current media routes\n\n| Modality | Route | Primary | Purpose |\n| --- | --- | --- | --- |\n| Image | `general` | fal / `gpt-image-2` medium | General marketing creative |\n| Image | `text-heavy` | fal / `gpt-image-2` high | Readable text/layout work |\n| Image | `bulk` | fal / `flux-2-pro` | Cost-controlled batches |\n| Image | `draft` | fal / `nano-banana-2-lite` | Fast exploration |\n| Image | `brand-control` | fal / `flux-2-flex` | Palette/layout control |\n| Image | `premium` | direct OpenAI / `gpt-image-2` high | Premium general render |\n| Video | `general` | fal / `kling-o3-standard` | General social/performance video |\n| Video | `premium` | fal / `veo-3.1` | Cinematic/native-audio work |\n| Video | `multi-shot` | fal / `seedance-2-fast` | Directed multi-shot storytelling |\n| Video | `budget` | fal / `wan-2.7` | Lower-cost exploration |\n\nReference-image, vector, multi-reference, image-animation, and footage-edit\nroutes are cataloged but remain non-executable until their required input\ncontracts/adapters exist. See [Model routing](docs/MODEL_ROUTING.md).\n\n## Email campaigns and HTML editing\n\nEmail is native campaign state rather than a wrapper around one ESP.\n\n```bash\n# Render the canonical launch message locally\nadclip email render \\\n  examples/01-dtc-skincare/email_brief.json \\\n  examples/01-dtc-skincare/email_message.json \\\n  --output-dir ./rendered-email\n\n# Apply stable block-level edits to a generic fixture\nadclip email patch-message \\\n  examples/email_message.json \\\n  examples/email_patches.json \\\n  --output ./message-edited.json\n```\n\nGenerated campaigns contain portable message JSON, responsive HTML, plain text,\nheaders, lint reports, and a manifest. Sequence generation uses a configured\ntext provider; the generic `fake` text provider is a copy-generation fixture,\nnot an email-sequence generator. Sending, consent, suppression, and ESP account\nstate remain connector responsibilities.\n\nSee [Email campaigns](docs/EMAIL_CAMPAIGNS.md).\n\n## Performance and creative learning\n\nadclip can map an exact local creative to an existing Meta ad and read Insights\nback without adding Meta mutation methods.\n\n```bash\nadclip performance link-meta ./campaign \\\n  --variant-id v01 \\\n  --account-id act_123456 \\\n  --ad-id 987654321\n\nexport ADCLIP_META_ACCESS_TOKEN=...\n\nadclip performance sync-meta ./campaign \\\n  --since 2026-08-01 \\\n  --until 2026-08-07 \\\n  --action-report-time conversion\n```\n\nMeasurement windows are keyed by `(since, until, action_report_time)`, so\nconversion- and impression-attributed rows for the same dates are not silently\ncombined.\n\nDescriptive comparison:\n\n```bash\nadclip performance compare ./campaign \\\n  --since 2026-08-01 \\\n  --until 2026-08-07 \\\n  --action-report-time conversion \\\n  --metric ctr\n```\n\nSee [Performance learning](docs/PERFORMANCE_LEARNING.md).\n\n## Explicit creative experiments\n\nThe checked-in demo uses a familiar paid-social question: does vivid problem\nframing beat a plain product-benefit hook?\n\n```bash\npython examples/06-creative-experiment/build_demo.py\n```\n\nOr declare your own experiment before interpreting results:\n\n```bash\nadclip performance experiment-create ./campaign \\\n  --name \"Hook CTR test\" \\\n  --hypothesis \"Problem framing increases CTR\" \\\n  --changed-factor hook \\\n  --control-variant v01 \\\n  --treatment-variant v02 \\\n  --control-value \"plain benefit\" \\\n  --treatment-value \"problem framing\" \\\n  --metric ctr\n```\n\nCurrent inferential verdicts are deliberately limited to rate metrics with\nexplicit aggregate numerators/denominators: CTR, outbound CTR, and action rate.\nCPA and ROAS remain descriptive without variance/event-level evidence.\nObservational comparisons remain inconclusive by design, and experiment outputs\ncurrently keep `causal_claim: false`.\n\nSee [Experiment contract](docs/EXPERIMENTS.md).\n\n## Recurring model bake-offs\n\nDefaults should be promoted by evidence rather than reputation.\n\n```bash\n# Dry-run plan only\nadclip bakeoff \\\n  --modality image \\\n  --routes general,text-heavy,bulk,draft \\\n  --output-dir ./image-bakeoff\n```\n\nLive execution requires both `--execute` and normal paid-provider authorization.\nResults record route, provider, model, options, latency, estimated cost,\nartifact SHA-256, failures, evaluation dimensions, and human-review fields.\n\n## Text providers\n\n| Provider | Intended use |\n| --- | --- |\n| `claude-cli` | Subscription-authenticated compatibility default |\n| `openai-compatible` | Local or hosted `/v1/chat/completions` endpoint |\n| `command` | Local executable over stdin/stdout |\n| `sampling` | Sampling-capable MCP host |\n| `anthropic` | Direct opt-in Anthropic API |\n| `fake` | Deterministic copy tests/examples |\n\nLocal HTTP inference:\n\n```bash\nexport ADCLIP_TEXT_PROVIDER=openai-compatible\nexport ADCLIP_TEXT_MODEL=qwen2.5:14b\nexport ADCLIP_OPENAI_BASE_URL=http://127.0.0.1:11434/v1\nexport ADCLIP_RUNTIME_MODE=offline\nadclip copy examples/01-dtc-skincare/brief.json\n```\n\nSee [Model providers](docs/MODEL_PROVIDERS.md).\n\n## MCP\n\nExample local registration:\n\n```json\n{\n  \"mcpServers\": {\n    \"adclip\": {\n      \"command\": \"adclip-mcp\"\n    }\n  }\n}\n```\n\nThe MCP surface exposes the same campaign, routing, email, performance, and\nexperiment application services used by the CLI. Important newer tools include:\n\n```text\nadclip_list_media_routes\nadclip_recommend_media_route\nadclip_email_generate_campaign\nadclip_email_render\nadclip_email_lint\nadclip_email_patch_html\nadclip_email_patch_message\nadclip_performance_link_meta\nadclip_performance_deployments\nadclip_performance_sync_meta\nadclip_performance_report\nadclip_performance_compare\nadclip_experiment_create\nadclip_experiments\nadclip_experiment_evaluate\nadclip_experiment_next_test\n```\n\n## Runtime and billing safety\n\nSupported runtime modes:\n\n```text\nonline\nrestricted_network\noffline\nair_gapped\n```\n\nExternal generation providers are refused offline/air-gapped. Loopback text\ninference remains available. Potentially paid generation requires:\n\n```bash\nADCLIP_ALLOW_LIVE_APIS=1\n```\n\nThe Meta performance connector is a separate read-only network adapter and does\nnot use the generation-spend authorization flag.\n\n## Tests\n\nThe project test suite is designed to run without paid APIs or live marketing\naccounts:\n\n```bash\npython -m pytest\npython -m compileall src/adclip\n```\n\n## Current status and next milestones\n\nThe current core includes generation, email authoring, exact creative lineage,\nread-only Meta performance ingestion, attribution-safe reporting, explicit\nexperiments, and next-test recommendations.\n\nThe largest remaining product gaps are:\n\n1. SQLite/migrations as authoritative state, content-addressed artifacts, and\n   durable resumable jobs;\n2. BrandKit and SourceLibrary;\n3. bundled local browser workbench;\n4. creative-attribute extraction and experiment-aware controlled generation;\n5. Google Ads, TikTok, and ESP performance adapters;\n6. fatigue/change-point analysis and richer CPA/ROAS evidence;\n7. separately authorized draft/paused deployment workflows.\n\nSee [Standalone architecture](docs/STANDALONE_ARCHITECTURE.md) for the roadmap.\n",
  "bytes": 13327,
  "sha": "525750de5416691dad940c1bae06ec2275a3185f813e678d7c9eb5995c55c260",
  "repo_slug": "dreliq9/adclip",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dreliq9_adclip_9ce0a864/readme"
}