Simulator domain model
Purpose
MTA-SIM owns the fundamental dataclasses used by simulation. They have no runtime import from any downstream repository. Configuration objects describe how to generate data; domain objects describe advertising entities and observations that were generated. The stable file contract is the integration boundary for downstream consumers.
Provider and capabilities
Provider identifies the source platform independently of ad product. ProviderCapabilities declares the provider-level ceiling for format, placement, creative, and interaction visibility. FieldAvailability preserves AVAILABLE, NOT_APPLICABLE, NOT_PROVIDED, UNKNOWN, and REDACTED as distinct meanings.
Touchpoint
Purpose
Touchpoint is the structured, provider-aware advertising interaction. It is not fundamentally a colon-joined string.
Fields
provider
The source platform.
ad_product
The provider's advertising product.
format
The canonical advertising format. Legacy ad_type or inventory_type maps here during configuration loading.
placement, creative, and interaction_type
Optional observed values whose precise absence reason is carried by TouchpointFieldAvailability.
Serialization
touchpoint_to_five_segment_key() and touchpoint_from_five_segment_key() are the only authoritative compatibility converters. The representation omits Provider and collapses detailed placement/creative missingness to UNSPECIFIED, so it is intentionally lossy.
Product and ProductEconomics
Product separates business identity and sku_id from Provider-specific advertising identifiers, inventory, and salable state. ProductEconomics records currency, price, Cost of Goods Sold, an optional aggregate variable unit cost, separate fulfillment/platform-fee/other variable unit costs, contribution margin, and whether the margin was explicit or derived. Aggregate and component values may coexist only when they agree. Missing economics remain None; they are never rewritten as observed zero values.
Campaign, AdGroup, and CampaignProductLink
Campaign identifies a Provider campaign and its ad product. AdGroup belongs to one Campaign. CampaignProductLink represents the many-to-many product relationship. Legacy configurations receive deterministic default objects, so they do not require new sections.
ReportingScope and observations
ReportingScope identifies account, marketplace, currency, and inclusive window. BudgetObservation keeps configured budget distinct from actual spend. DeliveryObservation records interaction-specific delivery and cost. OutcomeObservation keeps total, organic, and incremental outcomes distinct; simulator-only causal truth never appears in ordinary Provider-observed rows.
DataLineage and SimulationRun
DataLineage identifies a source/configuration digest and seed. SimulationRun records the effective Provider, Product, Campaign, Touchpoint, and budget-experiment snapshot used for one reproducible generation.
Semantic alignment
Names, availability meanings, identifiers, currencies, and non-negative value rules align with the downstream canonical model where the same concept exists. The Python classes are intentionally independent. Simulator-only Provider profiles, latent truth, generation parameters, and run snapshots do not become downstream predictive inputs merely because the simulator can represent them.