Research configuration and scale profiles

All sections on this page are optional. A configuration written before these features existed still receives deterministic default Provider, Product, Campaign, Ad Group, Product link, and single 1.0× budget-level objects. The existing extends and touchpoint_overrides composition rules remain active.

Providers

providers selects observation profiles. Each entry names provider, supported_ad_products, and optional availability ceilings for format, placement, creative, and interaction_type. Built-in profiles include an Amazon-compatible profile, a synthetic full profile, a synthetic profile that omits creative, and a synthetic profile that omits placement and creative. Synthetic profiles are research constructs, not descriptions of commercial application programming interfaces.

Products

Each products entry may define product_id, sku_id, Provider-specific advertising identifiers, name, category, brand, status, inventory, salable state, organic daily units, and organic daily growth. Its economics entries are currency-specific and may carry unit price, Cost of Goods Sold, an aggregate variable cost per unit, separate fulfillment/platform-fee/other variable unit costs, contribution margin, and margin source. Aggregate and component costs cannot contradict. Missing economics remain null.

Campaigns and Ad Groups

Each campaigns entry identifies Provider, ad product, status, baseline daily budget, and related Touchpoint identifiers. Each ad_groups entry belongs to one Campaign and may carry its own initial daily budget. Explicit campaign_product_links represent the many-to-many Product relationship. References are validated after inheritance and overrides are resolved.

Budget experiment

budget_experiment.multipliers defines repeated levels around every Campaign's baseline budget. spend_capacity_multiplier controls delivery capacity, so actual_spend may be below configured_budget. saturation_spend controls the transparent response curve:

$$\text{incremental units}=20(1-e^{-\text{actual spend}/\text{saturation spend}})$$

Its marginal return decreases as spend grows. The simulator also retains organic/no-ad units and revenue separately from incremental units and revenue; only total Provider-visible outcomes enter ordinary observations. Organic and incremental fields are evaluation-only causal truth.

Reproducibility snapshots

Every run hashes the fully resolved configuration and records its seed. effective_configuration.json carries the future-run configuration surface. CSV mode additionally writes simulation_research.json, whose observations carry run_id and budget level. PostgreSQL mode stores the same lineage in mta_simulation_run and related foreign-keyed tables.

Local 10,000-observation profile

examples/research-10k.json uses Campaign × marketplace × day × budget level as its primary grain and produces exactly 10,000 records through ordinary CSV mode. The established three CSV filenames and schemas remain unchanged.

Direct 100,000-observation profile

examples/research-100k-postgresql.json expands the same mechanism to exactly 100,000 primary records. Use --storage postgresql --postgres-batch-size 1000 to insert directly. Add --reset-database only when intentionally replacing the simulator-owned tables; no startup path resets the database automatically.

Composed multi-entity example

examples/multi-provider-products.toy.json extends the unchanged baseline toy configuration and demonstrates two Providers, two Products, explicit Campaign and Ad Group records, Campaign-Product links, granular unit economics, organic demand parameters, and repeated budget levels in one small corpus.