adclip

adclip

オープンで独立した、モデルルーティング型のマーケティングクリエイティブ・学習エンジンです。

adclip はキャンペーンの意図を、ポリシーに準拠したコピー、静止画クリエイティブ、 ショート動画、レスポンシブメールに変換します。クリエイティブの正確な系譜を保持し、 配信済みのクリエイティブからパフォーマンスを読み取り、 そのエビデンスを明示的な実験と次のテストに関する推奨事項として構造化します。

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

MCP は adclip へのインターフェースの1つであり、アーキテクチャそのものではありません。同じアプリケーション サービスはスタンドアロンの CLI からも利用でき、今後のローカルなブラウザーワークベンチを支えることを 想定しています。

adclip が生まれた理由

多くの AI マーケティングスタックでは、ワークフローがコピー作成ツール、画像・動画生成ツール、メールプラットフォーム、 広告プラットフォームのダッシュボード、クリエイティブ分析ツールに分断されています。 adclip の目標は、モデルプロバイダーや配信プラットフォームを交換可能なアダプターとして維持しながら、 キャンペーンモデル、クリエイティブの系譜、学習ループをポータブルに保つことです。

基本原則：

• モデル中立： ワークフローでは、単一のモデルベンダーをハードコードするのではなく、 能力やルートを指定します。
• スタンドアロン： CLI ワークフローに MCP ホストは必要ありません。
• ローカル優先： 適切に設定すれば、ローカルコマンドと OpenAI 互換の推論をオフライン環境または エアギャップ環境で実行できます。
• ポータブル： キャンペーンのアーティファクト、メールの HTML／テキスト、マニフェスト、配信マッピング、 観測結果、実験は、引き続き確認可能なファイルとして保存されます。
• エビデンス重視： 観察に基づくランキングを、因果的なリフトであるかのように暗黙のうちに提示しません。
• 支出に配慮： 有料の生成はオプトイン方式で、ルートのフォールバックが暗黙のうちに実行されることはありません。

まずはこちら

• クイックスタート — 費用ゼロで DTC のクリエイティブ、メール、学習を試す手順です。
• 例 — マーケター向けキャンペーンポートフォリオです。
• ドキュメント一覧 — アーキテクチャと機能のドキュメントです。
• LLM ガイダンス — モデル中立なコントリビューター／エージェント向けの規約です。

PyPI からインストールします：

pipx install adclip

PyPI のリリースは、現在のリポジトリより古い場合があります。ここで説明している正確な main の機能を利用するには、 ソースからインストールしてください：

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

Python 3.11 以降が必要です。

5分でできる費用ゼロのデモ

架空の DTC スキンケア製品のローンチを、偽のクリエイティブプロバイダーだけを使って Meta、Reels／TikTok、Google 向けに生成します：

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

モデルを呼び出さずに、リポジトリに含まれるローンチメールをレンダリングします：

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

クリエイティブテスト用の完全な合成バンドルを作成します：

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

次に、エビデンスを確認します：

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

ビルダーは、experiment-evaluate と next-test に渡せる実験 ID を出力します。上記のどのコマンドにも、 有料のモデル API や稼働中の広告アカウントは必要ありません。

例のポートフォリオ

リポジトリ内の例は、内部サブシステムではなく、マーケティング上の課題を中心に構成されています：

例	マーケティングの目的	主な配信面
01-dtc-skincare	製品ローンチ／初回購入	Meta、Reels、TikTok、Google、メール
02-b2b-saas-lead-gen	質の高いデモの獲得	LinkedIn、Google 検索
03-local-service-lead-gen	地域密着型のダイレクトレスポンスによるリード獲得	Meta、Google 検索
04-subscription-winback	ライフサイクル維持	メール
05-mobile-app-acquisition	無料トライアルの獲得	TikTok、Reels、Shorts、Meta
06-creative-experiment	フックの統制された学習	合成 Meta 観測データ

各ケースのビジネス目標、オーディエンス、仮説、コマンドについては、 examples/README.md を参照してください。

現在の機能マップ

領域	現在の機能
キャンペーンブリーフ	構造化された AdBrief、フォーマット、ポリシー制約、コスト見積もり
コピー	プロバイダーに依存しない生成、フィルタリング、スコアリング、修正／判定との互換性
画像	モデルファミリーのスキーマを使った fal／OpenAI 直接接続／fake アダプター向けのタスクルート
動画	ショートフォーム形式向けの fal／fake 生成ルート
モデル選択	ルート／プロバイダー／モデル／オプションを明確に分離し、比較評価に対応
メール	シーケンス生成、構造化ブロック、レスポンシブ HTML／テキスト、ヘッダー、リント、パッチ適用
系譜	安定したキャンペーン ID と、アセットに紐付くクリエイティブ ID
パフォーマンス	明示的なデプロイ対応付けと、読み取り専用の Meta Insights 同期
レポート	アトリビューションに配慮した正確な期間と、記述的なクリエイティブ比較
実験	コントロール／トリートメントアセット、変更要因、しきい値、率の信頼区間
学習	裏付けあり／反証あり／結論不能のエビデンスと、決定論的な次のテストアクション
インターフェース	共有アプリケーションサービス上の CLI と MCP
安全性	ランタイムのネットワークモード、有料生成のゲート、読み取り専用の Meta コネクター

スタンドアロン CLI

便利な確認コマンド：

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

ルーティングされたクリエイティブ生成

# 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

互換性エイリアスも引き続き利用できます：

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

現在のメディアルート

モダリティ	ルート	主要モデル	用途
画像	general	fal / gpt-image-2 medium	一般的なマーケティングクリエイティブ
画像	text-heavy	fal / gpt-image-2 high	読みやすいテキスト／レイアウト制作
画像	bulk	fal / flux-2-pro	コストを抑えたバッチ処理
画像	draft	fal / nano-banana-2-lite	高速な探索
画像	brand-control	fal / flux-2-flex	パレット／レイアウトの制御
画像	premium	OpenAI 直接接続 / gpt-image-2 high	高品質な汎用レンダリング
動画	general	fal / kling-o3-standard	一般的なソーシャル／パフォーマンス動画
動画	premium	fal / veo-3.1	映画的な作品／ネイティブ音声の制作
動画	multi-shot	fal / seedance-2-fast	演出付きのマルチショットストーリーテリング
動画	budget	fal / wan-2.7	低コストな探索

参照画像、ベクター、複数参照、画像アニメーション、映像編集の各ルートはカタログに登録されていますが、必要な入力コントラクト／アダプターが用意されるまでは実行できません。モデルルーティングを参照してください。

メールキャンペーンと HTML 編集

メールは、単一の 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

生成されたキャンペーンには、ポータブルなメッセージ JSON、レスポンシブ HTML、プレーンテキスト、ヘッダー、リントレポート、マニフェストが含まれます。シーケンス生成では、設定済みのテキストプロバイダーを使用します。汎用の fake テキストプロバイダーはコピー生成用のフィクスチャであり、メールシーケンスジェネレーターではありません。送信、同意、抑制、ESP アカウントの状態は、引き続きコネクターが担います。

メールキャンペーンを参照してください。

パフォーマンスとクリエイティブ学習

adclip は、既存の Meta 広告にローカルのクリエイティブを正確に対応付け、Meta の変更メソッドを追加することなく Insights を読み戻せます。

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

測定期間は (since, until, action_report_time) をキーとしているため、同じ日付のコンバージョンアトリビューション行とインプレッションアトリビューション行が、暗黙のうちに結合されることはありません。

記述的な比較：

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

パフォーマンス学習を参照してください。

明示的なクリエイティブ実験

チェックイン済みのデモでは、よくある有料ソーシャルの問いを扱っています。鮮明な問題提起は、シンプルな製品メリットのフックを上回るでしょうか？

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

または、結果を解釈する前に、独自の実験を定義してください：

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

現在の推論による判定は、分子／分母を明示した集計値を持つ率指標、つまり CTR、アウトバウンド CTR、アクション率に意図的に限定されています。CPA と ROAS は、分散やイベントレベルのエビデンスがない場合、引き続き記述的な指標として扱われます。観察に基づく比較は設計上、結論不能のままであり、実験の出力では現在 causal_claim: false が維持されています。

実験コントラクトを参照してください。

定期的なモデル比較

デフォルトは評判ではなく、根拠に基づいて採用すべきです。

# Dry-run plan only
adclip bakeoff \
  --modality image \
  --routes general,text-heavy,bulk,draft \
  --output-dir ./image-bakeoff

ライブ実行には、--execute と通常の有料プロバイダー認証の両方が必要です。 結果には、ルート、プロバイダー、モデル、オプション、レイテンシ、推定コスト、 成果物の SHA-256、失敗、評価項目、人間によるレビュー用フィールドが記録されます。

テキストプロバイダー

プロバイダー	想定用途
claude-cli	サブスクリプション認証を使用する互換性のあるデフォルト
openai-compatible	ローカルまたはホスト型の /v1/chat/completions エンドポイント
command	標準入力／標準出力を使用するローカル実行ファイル
sampling	サンプリング対応の MCP ホスト
anthropic	明示的にオプトインする Anthropic API への直接接続
fake	決定論的なコピーのテスト／例

ローカル HTTP 推論：

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

モデルプロバイダーを参照してください。

MCP

ローカル登録の例：

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

MCP サーフェスは、CLI で使用されるキャンペーン、ルーティング、メール、 パフォーマンス、実験のアプリケーションサービスと同じものを公開します。 最近追加された重要なツールには、次のものがあります。

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

ランタイムと課金の安全性

サポートされているランタイムモード：

online
restricted_network
offline
air_gapped

外部の生成プロバイダーは、オフライン／エアギャップ環境では拒否されます。 ループバックによるテキスト推論は引き続き利用できます。有料となる可能性がある生成には、 次のものが必要です。

ADCLIP_ALLOW_LIVE_APIS=1

Meta パフォーマンスコネクターは、独立した読み取り専用のネットワークアダプターであり、 生成費用の認可フラグは使用しません。

テスト

このプロジェクトのテストスイートは、有料 API やライブのマーケティングアカウントを使わずに 実行できるように設計されています。

python -m pytest
python -m compileall src/adclip

現在の状況と次のマイルストーン

現在のコア機能には、生成、メール作成、正確なクリエイティブの系譜、 読み取り専用の Meta パフォーマンス取り込み、アトリビューションに配慮したレポート、 明示的な実験、次のテストに関する推奨が含まれます。

残る大きなプロダクト上の課題は次のとおりです。

1. 権威ある状態管理としての SQLite／マイグレーション、コンテンツアドレス可能な成果物、 永続的で再開可能なジョブ；
2. BrandKit と SourceLibrary；
3. バンドルされたローカルブラウザーワークベンチ；
4. クリエイティブ属性の抽出と、実験を考慮した制御生成；
5. Google Ads、TikTok、ESP のパフォーマンスアダプター；
6. 疲労度／変化点分析と、より充実した CPA／ROAS の根拠；
7. 個別に認可される、下書き／一時停止状態でのデプロイワークフロー。

ロードマップについては、スタンドアロンアーキテクチャを参照してください。