dv360-bidkit

Turn DV360 report data into verified, high-performance custom bidding algorithms without guesswork, AST syntax errors, or platform rejections.

dv360-bidkit is an open-source, agent-ready programmatic bidding engine engineered for Google Display & Video 360 (DV360). It lints custom bidding scripts against Google's 2026 DSL specification, runs deterministic local simulations without eval()/exec(), checks Google S2 training readiness (500 advertiser / 50 line-item positives), and compiles structured rulesets into production-grade Python scripts.

Quickstart: Inspectable Demo in 1 Command

dv360-bidkit includes realistic synthetic display report fixtures requiring zero external Google Cloud or DV360 API credentials. Install and run an inspectable pre-flight evaluation pass in a single command:

# Install from PyPI:
pip install dv360-bidkit

# Run instant diagnostic simulation:
bidkit demo

Inspectable Terminal Output:

                       DV360 BidKit Open-Core Demo Simulation                        
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric                ┃ Observed Value ┃ Google S2 / Health Standard              ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Total Impressions     │        273,146 │ Historical baseline sample               │
│ Positive Impressions  │         93,878 │ ≥ 500 required by Google S2              │
│ Positive Scoring Rate │          34.4% │ Target: 5% – 40% for active bidding      │
│ Weighted Mean Score   │           2.41 │ Scale baseline                           │
│ Gini Inequality       │          0.712 │ 0 = flat, 1 = extreme concentration      │
│ Max-to-Median Ratio   │           1.3x │ ≤ 20.0x prevents DSP pacing starvation   │
│ Readiness Status      │ MEETS_MINIMUM_HISTORY │ Google Custom Bidding training readiness │
└───────────────────────┴────────────────┴──────────────────────────────────────────┘

✓ Demo bundle successfully generated in: demo
  • Report: demo/report.csv
  • Mapping: demo/mapping.json
  • Rules: demo/rules.json
  • Policy: demo/policy.json
  • Compiled Script: demo/script.py
  • Diagnostics JSON: demo/diagnostics.json
  • Pro Config: demo/campaign.json

The 4 Fatal Pitfalls of DV360 Custom Bidding

DV360 custom bidding models replace Google's standard click/conversion heuristics with a custom machine-learning reward function. However, four subtle pitfalls routinely undermine live campaigns:

1. Small-Sample Winner's Curse (Publisher Noise)

• The Pitfall: Long-tail domains with small impression samples (e.g., 3/3 viewable impressions $= 100%$) receive maximum bid multipliers under naive scoring rules, wasting budget on unverified tail traffic.
• The Solution: Never bid on raw empirical rates. dv360-bidkit-pro applies Empirical Bayes shrinkage towards the campaign's baseline viewability ($\lambda_i = \frac{n_i}{n_i + k^*}$), pulling low-volume publishers toward the global mean while granting full confidence only to high-volume domains.

2. Score Mass Domination (Objective Dilution)

• The Pitfall: In multi-objective funnels blending purchases with proxy signals (e.g. Add-to-Cart or Clicks), high-frequency proxy signals can inadvertently capture $90%+$ of total score mass ($M = \sum N_k w_k$). Google's bidding algorithm optimizes purely for the proxy and ignores primary conversions.
• The Solution: Enforce transition-bounded econometric caps ($w_{\text{proxy}} \le w_{\text{macro}} \times P(\text{Macro} \mid \text{Proxy})$) and allocate at least $65%$ of expected score mass to primary conversions using bidkit-pro weights.

3. Pacing Starvation from Outlier Spikes

• The Pitfall: Uncapped continuous metrics (e.g., e-commerce transaction values or duration) create extreme score spikes. If the ratio of maximum score to positive median ($\max / \text{median}$) exceeds $20\times$, DV360's dual pacing controller ($\alpha_t$) destabilizes, causing immediate bid starvation.
• The Solution: Apply 95th-percentile Winsorization caps emitted as DV360-compliant ternary expressions (cap if val > cap else val).

4. Model Training Exclusion vs. Ad-Serving Blocks

• The Pitfall: Returning None in a custom bidding script (return None) excludes an impression from model training; it does NOT block the ad from serving.
• The Solution: Programmatic traders must maintain a strict separation between algorithm exclusions (return None for model health) and ad-serving blocks. dv360-bidkit exports targeting_block_request.csv as an actionable checklist for trafficking into DV360 Line Item targeting.

Community (Open-Source Core) vs. Pro

dv360-bidkit (Open-Source Core) is the Safety and Execution Rail: it ensures scripts are syntactically valid, budget-compliant, and accurately simulated.
dv360-bidkit-pro (Commercial) is the Econometric Brain: it eliminates manual weight guessing, calculates optimal proxy weights, shrinks long-tail publisher noise, and exports complete production bundles.

Command Line Interface (CLI)

# 1. Generate synthetic benchmark data and starter rules
bidkit demo --out-dir ./demo

# 2. Lint an existing script against the 2026.1 signal registry
bidkit lint script.py --format text

# 3. Compile a structured RuleSet and inventory policy into a DV360 script
bidkit compile --rules rules.json --policy policy.csv --out script.py

# 4. Simulate a script against historical DV360 report data
bidkit evaluate script.py --report report.csv --mapping mapping.json --out diagnostics.json

# 5. Render evaluation diagnostics to an HTML visual report
bidkit report diagnostics.json --out audit.html

Python SDK Quickstart

import json
from dv360_bidkit import (
    load_report,
    load_inventory_policy,
    compile_script,
    evaluate_script,
    lint_script,
    ReportMapping,
    RuleSet,
    Rule,
    RuleCondition,
    AggregationMode,
)

# 1. Define custom bidding rules
ruleset = RuleSet(
    aggregation_mode=AggregationMode.FIRST_MATCH,
    rules=[
        Rule(
            id="premium_news",
            conditions=[RuleCondition(field="domain", operator="in", value=["spiegel.de", "zeit.de"])],
            score=10.0,
        ),
        Rule(
            id="mobile_web",
            conditions=[
                RuleCondition(field="device_type", operator="==", value=2),
                RuleCondition(field="environment", operator="==", value=1),
            ],
            score=5.0,
        ),
    ],
    fallback_score=1.0,
)

# 2. Compile to production DV360 Python DSL
comp_result = compile_script(ruleset)
print(comp_result.script_code)

# 3. Validate against syntax and signal registry
lint_rep = lint_script(comp_result.script_code)
assert lint_rep.is_valid

# 4. Pre-flight simulation on customer report
mapping = ReportMapping(
    canonical_field_map={
        "impressions": "Impressions",
        "domain": "App/URL",
        "device_type": "Device Type",
        "environment": "Environment",
        "line_item_id": "Line Item ID",
    },
    date_window="30d",
)
data = load_report("dv360_report.csv", mapping=mapping)
eval_rep = evaluate_script(comp_result.script_code, data, history_window_days=30)

print(f"Readiness: {eval_rep.readiness.status.value}")
print(f"Positively Scored Impressions: {eval_rep.metrics.positive_score_impressions:,}")

Core Data Contracts

1. Report Mapping (ReportMapping)

Maps raw DV360 Standard or Instant Report column headers (English or German) to canonical fields:

{
  "canonical_field_map": {
    "impressions": "Impressions",
    "measurable_impressions": "Active View: Measurable Impressions",
    "viewable_impressions": "Active View: Viewable Impressions",
    "domain": "App/URL",
    "device_type": "Device Type",
    "environment": "Environment",
    "line_item_id": "Line Item ID",
    "advertiser_id": "Advertiser ID",
    "clicks": "Clicks",
    "conversions": "Total Conversions"
  },
  "denominators": {
    "viewable_impressions": "measurable_impressions",
    "measurable_impressions": "impressions"
  },
  "row_grain": "homogeneous_aggregate",
  "date_window": "30d"
}

2. Customer Inventory Policy (InventoryPolicy)

Customer-defined domain and site lists specifying score overrides, training exclusions, or ad-serving block requests:

entity_type,entity_value,action,source,as_of,expiry,score,label
domain,fraud-network.com,exclude_from_training,audit_2026,2026-01-01,,0.0,Excluded from model
domain,direct-partner.com,set_score,pmp_deal,2026-01-01,2026-12-31,25.0,Preferred Deal Floor
domain,toxic-site.com,targeting_block_request,safety,2026-01-01,,0.0,Block Ad Serving

🤖 Agentic Custom Bidding Skill (dv360-custom-bidding)

dv360-bidkit ships with an Antigravity / Cursor / Claude Code agent skill: skills/dv360-custom-bidding/SKILL.md.

Equipped with this skill, AI coding assistants can:

1. Parse client DV360 report files and generate exact ReportMapping definitions.
2. Formulate multi-vector scoring algorithms and verify them against the DV360 signal registry.
3. Simulate positive score density to prevent READINESS_STATE_INSUFFICIENT_DATA launch failures.
4. Call bidkit-pro weights and bidkit-pro build to export production campaign bundles.

Install directly via skills.sh into Cursor, Claude Code, Antigravity, Copilot, and other agent environments:

npx skills add flovv/dv360-bidkit

Documentation & AI Retrieval Index

• Documentation Source: docs/
• Algorithmic Research Foundations: docs/algorithmic_research_foundations.md
• LLM Summary Index: docs/llms.txt
• Full Technical Reference: docs/llms-full.txt

License

dv360-bidkit is open-source software licensed under the MIT License.
Commercial Pro extensions (dv360-bidkit-pro) are available under proprietary commercial licenses via Polar.sh.