Dealer Preferences
Infers per-dealer must-have (MH) and must-not-have (MNH) preferences from observed take rates, and syncs the option-code subset to the MongoDB collection the ordering app reads.
Two components, both writing under <oem>/<market>/acceptance/:
| Component | Output | Purpose |
|---|---|---|
DealerPreferencesComponent | acceptance/dealer_rules (Iceberg) | Inference |
DealerPreferencesMongoComponent | acceptance/<name> (no table) | MongoDB sync |
Inference
DealerPreferencesComponent classifies each (dealer_id, base_model_id, attribute_type, attribute_value) cell:
- take rate ≥
must_have_threshold→ MH - take rate ≤
must_not_have_threshold→ MNH - otherwise no rule is emitted
must_have_threshold and must_not_have_threshold are required config and must
be disjoint. A cell is only classified when its group observation count clears
NOBS_MIN
(ai_dagster.derived.dealer_preferences_columns) and its rate is finite; otherwise the
cell is treated as no-signal rather than as a zero. Sentinel NO_* codes are never marked MH —
they encode absence.
Two rule paths, two universes
Attribute rules and option-code rules run through the same classifier, but draw their signal and their eligible universe from different places:
- Attribute rules read the recency-weighted
sales_hl90_take_rateoff the configuredattribute_statsasset, which groups the statistics by dealer and model. Each value's rate covers only the value's choice years (see Rates over the model years in which a value was a choice). Attribute rules zero-fill against the mapped attribute universe fromfeaturization/features. Of a value's choice years, the rate counts sales of model years at or after the partition year. Withstock_and_ordersset, the rate also counts the dealer's stock and open orders (see Stock and orders in rule rates). - Option-code rules compute a share of the dealer's vehicles that have each
raw option code, from
consolidated/inventory×consolidated/features, and zero-fill against the raw option-code universe. The share covers only the model years that offer the code and in which the code was a choice (see Option-code rates cover the model years that offer the code). Withoutstock_and_orders, the share is unweighted. Withstock_and_ordersset, a vehicle sold in the window weighs its recency weight at the half-life ofsales_hl90, and a vehicle in inventory, whether in stock or on order, weighs1 / divisor. Any other vehicle is left out of the share, ofdemand_nobsand of the vehicle count thatELIGIBLE_NOBS_MINapplies to. Withstock_and_ordersset,DealerPreferencesComponentalso readsinferred_sold_date,is_sold_in_windowandis_in_inventoryfromconsolidated/inventory. It raises unlessinferred_sold_dateis aDate.
Each path renames its metric into demand_rate on the way in, so the classifier
reads one column that has no indication of its source. Because the two metrics are on
different scales, oc_must_have_threshold and oc_must_not_have_threshold are
required config: the option-code path always runs, and allowed_attribute_types
governs only the attribute path.
Each rule also has two observation counts. demand_nobs must be at least
NOBS_MIN for the cell to be classified. rate_nobs is the count that
demand_rate is a share of. On the option-code path the two are equal unless
stock_and_orders is set. With stock_and_orders set, rate_nobs is the weighted
count, and demand_nobs counts the same vehicles unweighted. On the attribute path,
demand_nobs is the attribute_stats column that attribute_nobs_column names,
and rate_nobs is the recency-weighted sales_hl90_group_nobs, which matches
sales_hl90_take_rate. With stock_and_orders set, rate_nobs also includes the
weighted count of the dealer's stock and open orders.
attribute_nobs_column must count the vehicles that sales_hl90_take_rate is a
share of, unweighted. Audi, Mercedes and Stellantis set
sales_recent_my_group_nobs. It is the count of the sales_recent_my statistic,
which has the same model-year filter as sales_hl90.
A count over a wider population than the rate lets a dealer reach NOBS_MIN with
many sales of earlier model years and only one or two sales of the current model
year. The classifier would then emit a rule from a rate over those one or two
vehicles.
allowed_attribute_classes lists attribute classes, BINARY or MULTICLASS. Every attribute
type that the featurization schemes assign one of these classes is allowed in addition to
allowed_attribute_types. With [BINARY], as Audi, Mercedes and Stellantis set it, a rule
can require or exclude a binary attribute such as DASHCAM, whose values are TRUE and FALSE.
Zero-filling is what lets a never-observed code surface as MNH. On the attribute
path it applies only to dealer×model pairs that already have stats; pairs
excluded upstream stay excluded. On the option-code path it applies to every
dealer×model pair with vehicles in a model year that offers the code.
Eligibility is conditioned on national observation so model-year-transition
options (configurable but not yet sold anywhere) don't flood in as zero-rate
MNH candidates. An option code is eligible when the dealers that took it have,
together, at least ELIGIBLE_NOBS_MIN vehicles of the model years that offer it.
Option-code rates cover the model years that offer the code
A code is offered in a model year when a consolidated/features row of that
model year and base model has the code. A code's rate for a dealer and base
model counts only the dealer's vehicles of the model years that offer the code,
in both the numerator and the denominator. That count is the rule's
demand_nobs, and it must be at least NOBS_MIN. A dealer without enough vehicles
of those model years gets no rule for the code.
A typical case is a model-year transition that replaces paint codes. A dealer with vehicles of only earlier model years never had the chance to choose a paint code introduced in the latest model year, so those vehicles are no evidence against that code. A code offered in earlier model years and never taken still becomes MNH.
Attribute must-haves need a newest-model-year feature
An attribute must-have is kept only if a vehicle of the base model's newest model year can be assigned the attribute. At least one feature of that model year must:
- have the attribute in
featurization/features, and - be configurable (
is_configurableonconsolidated/features).
DealerPreferencesComponent applies the is_configurable filter whatever the value of
configurable_only on featurization/inventory.
Otherwise the must-have is demoted. A must-not-have for the same attribute is dropped when the attribute is not a choice in the newest model year (see A rule's value must be a choice in the newest model year).
A typical demoted must-have comes from a feature that is configurable in one model year and standard equipment in the next. Vehicles of the older model year are assigned the attribute, and their sales produce the must-have. No vehicle of the newest model year is assigned the attribute.
Feed-scoped code groups
feature_type_rules assigns a set of consolidated feature_type values to their
own attribute_type and thresholds, separate from the default OPTION_CODE
group. A rule's population names a boolean column present on both
consolidated/inventory and consolidated/features. That column scopes four
things to the rows it marks:
- the group's denominator,
- its numerator,
- its eligible-code universe, and
- the model years that offer a code.
A feature type no rule claims stays in the default group against the full population.
This is how accessories become MH/MNH rules for Mercedes. Accessories are only
orderable through the private (netstar) feed, so a vehicle seen only in the public
feed never has one. Scoring against every vehicle would use a denominator that
includes vehicles the accessory can never appear on. The OEM derives a
private_feed_exists column on both entities from its own source-presence flags,
and the rule scopes the ACCESSORY feature type to it. A code the private feed
never publishes is never eligible for the group, so it is never zero-filled as MNH.
Code rules on orderable codes only
Inventory lists every code on a built vehicle. That includes these codes, which a dealer cannot order:
- the contents of a package
- the standard equipment a package replaces
- production codes that the OMS does not show
A rule on such a code still filters candidates, because a candidate's codes come from the same build data. Such a rule can exclude candidates for a choice the dealer never made. For example, an MH on standard equipment that a package replaces excludes every candidate with that package, even when the dealer's sales of that equipment come from a model year in which no package replaced it.
orderable_code_columns names boolean columns of consolidated/features. When it is
set, a code-based rule is kept only if a feature of the base model's newest model year
has the rule's code and is true in at least one of the columns. A null counts as false.
The filter applies to MH and MNH rules alike. Audi sets it to order_guides_exists and
accessaudi_exists, so its rules cover only codes that the order guide or AccessAudi
lists.
Rates over the model years in which a value was a choice
The ways to get a value change between model years. A value can be fixed equipment in one model year and configurable in the next. It can come with only one package in one model year and with several packages in the next. In the earlier model year, the dealer's sales of the value show whether the dealer bought the equipment or the package, not whether the dealer wants the value. For example, if acoustic glass comes only with the top package, a dealer that never takes the top package has a 0% rate on acoustic glass. If acoustic glass then comes with two cheaper packages, that rate makes acoustic glass an MNH, and the MNH excludes every candidate with either package.
A model year is a choice year for a value when a configurable feature of that year has the value standalone, or when at least two distinct packages include it:
- A package's own code is standalone.
- An attribute that featurization gives a package feature counts as included in that package.
FALSEof a binary attribute is a choice in every model year in whichTRUEis.
Both rule paths count only the dealer's vehicles of a value's choice years. This applies to the numerator and to the denominator of the value's rate. A value with no choice year gets no rule.
- On the option-code path, the model years that offer a code are limited to the code's choice years.
- On the attribute path,
attribute_stats_assetmust name theattribute_statsstatistics grouped bydealer_idandmodel_id. The weighted counts and the observation counts of each value's choice years are added up, so the recency weighting is the same as inattribute_stats. An eligible value that a dealer never took gets a zero rate over the dealer's vehicles of its choice years.
A value that is content of two packages keeps its rule. If each package is on 48% of a dealer's vehicles and no vehicle has both, the content is on 96% of them. That rate makes the content an MH, and the MH keeps candidates with either package.
A rule's value must be a choice in the newest model year
Dealer preferences are applied to candidates of a base model's newest model year, as the
must-have filters above assume. DealerPreferencesComponent keeps a rule only when the newest
model year is a choice year of its value. Every inferred rule's value has a choice year
(see
Rates over the model years in which a value was a choice),
so the check drops the rules whose choice years are all earlier model years. Both rule
paths apply it:
- The attribute path checks each value against the choice years that
attribute_choice_yearscomputes. - The option-code path checks each code against the choice years that
code_choice_yearscomputes. It checks the rules of every code group, whatever the rule's attribute type.
Manual overrides are not checked.
Without the check, a rule from an earlier model year can require or exclude a package. For example, Audi's MY2026 Q7 offers the surround view camera as a standalone option and in several packages. In MY2027, only the Prestige package includes it, so MY2027 is not a choice year for it. The rate therefore covers MY2026 alone. A dealer that took the camera on all of its MY2026 sales gets an MH, and the MH keeps only MY2027 candidates with Prestige.
Stock and orders in rule rates
Until a dealer sells vehicles of the newest model year, the dealer's stock and open orders are the only record of the values the dealer takes for that model year. Package contents change between model years, so a rule from the earlier model year's sales can exclude candidates with a value that the dealer now orders. For example, a dealer whose buyers rarely took the head-up display in the earlier model year gets an MNH on it, even when the dealer orders it on most vehicles of the newest model year.
stock_and_orders has a statistic and a divisor. On both paths, a vehicle in the
dealer's stock or on order counts as 1 / divisor of a sale in demand_rate and
rate_nobs. This is the weight that a divisor-blend layer's inventory_divisor gives
the layer's inventory prior. Without
stock_and_orders, the attribute path reads sales only, and the option-code path
counts every vehicle unweighted.
On the attribute path, the statistic names a statistic of attribute_stats_asset
that counts the dealer's stock and open orders. DealerPreferencesComponent blends the
statistic's take rate into each model year's sales rate. The choice years then apply
as they do to sales. DealerPreferencesComponent raises when a row of
attribute_stats_asset with a sales_hl90_group_nobs has no count of the statistic,
as in a partition written before the statistic was configured.
On the attribute path, stock and open orders never count toward demand_nobs, so
only sales clear NOBS_MIN. Stock and orders change an attribute rule's rate, but
they never make an attribute rule on their own. Inventory includes the orders that
the ordering service places. A rule from those orders alone would constrain the next
orders by the previous ones.
Each path counts the stock and orders of the model years whose sales it counts. The
statistic must have the model-year filter of sales_hl90. Audi's
inventory_recent_my counts the vehicles in inventory whose model year is at or after
the partition year, as sales_recent_my counts sales. The inventory statistic that
the smoother reads has no model-year filter. On 1 January the rate stops counting
sales of the previous model year. With the inventory statistic, the rate would
still count that model year's unsold stock.
The option-code path weights each sale by its recency weight at the half-life of
sales_hl90, as the attribute path does. The option-code path has no model-year
filter. A code's rate counts every model year that offers the code. After 1 January
the rate still counts sales of the previous model year at their recency weight, so it
also counts that model year's stock.
Configuration
Only the attribute_stats keys are configurable — AttributeStatisticsComponent
has both a configurable name and configurable aggregation keys. Every other
upstream (featurization/features, consolidated/models, consolidated/inventory,
consolidated/features, consolidated/dealers) has a fixed key derived from
(oem, market).
type: ai_dagster.components.DealerPreferencesComponent
attributes:
start_date: "{{ start_date }}"
attribute_stats_asset: stellantis/us/attribute_stats/country_by_dealer_model
global_attribute_stats_asset: stellantis/us/attribute_stats/country_by_country_base_model
attribute_nobs_column: sales_recent_my_group_nobs
must_have_threshold: 0.92
must_not_have_threshold: 0.05
oc_must_have_threshold: 0.60
oc_must_not_have_threshold: 0.20
allowed_attribute_types: [PAINT_COLOR, ...]
allowed_attribute_classes: [BINARY]
feature_type_rules:
- attribute_type: ACCESSORY
feature_types: [ACCESSORY]
population: private_feed_exists
must_have_threshold: 0.6
must_not_have_threshold: 0.1
Audi also sets orderable_code_columns and stock_and_orders:
orderable_code_columns: [order_guides_exists, accessaudi_exists]
stock_and_orders:
statistic: inventory_recent_my
divisor: 1
The divisor of 1 matches the inventory_weight of 1 in Audi's
smoothed_demand_take_rates: each inventory vehicle counts as one sale in the dealer
layer's count.
overrides pins a rule by hand, winning over inference on key conflict:
overrides:
- dealer_filter: {dealer_code: "44394"}
attribute_type: TRANSMISSION_TYPE
attribute_value: MANUAL
rule: must_not_have
MongoDB sync
DealerPreferencesMongoComponent upserts the code-based rules with a verdict into
collection, one document per (dealer_id, model_key, attribute_type, attribute_value), which is also the unique index it ensures. attribute_types
names the code attribute_type values to sync, defaulting to [OPTION_CODE].
Attribute-path rules stay in Iceberg and are never pushed to the ordering app. The
internal hashed dealer_id is resolved to the OEM-facing identifier named by
dealer_id_field. An unresolvable dealer raises rather than writing a null-keyed
document. Each document has the rule's demand_rate and rate_nobs as
observed_rate and observed_nobs. The
ordering app orders the rules by them when it vets them (see
AcceptanceScorer),
and ignores them on a document with isDealerSet: true.
type: ai_dagster.components.DealerPreferencesMongoComponent
attributes:
name: option_code_rules_mongo
start_date: "{{ start_date }}"
collection: dealer_rules
base_model_id_fields: [model_code, trim_identifier]
attribute_types: [OPTION_CODE, ACCESSORY]
active_dealers_column: dc_active_first_seen
Setting active_dealers_column restricts the sync to dealers with that column
non-null on consolidated/inventory, and scopes retirement to them. Leaving it
unset syncs every dealer present in the rules frame.
Dealer locks and retirement
A document with isDealerSet: true has been edited in the app and is never
overwritten: the upsert filter carries isDealerSet: {$ne: true}, so a locked
document fails to match and the resulting duplicate-key error is counted as a
skip rather than a failure.
Every document written in a run is tagged with that run's sync_batch_id.
After upserting, any non-dealer-set document in scope whose sync_batch_id
differs is deleted — that is how a rule that went neutral, or a code that fell
out of the eligible universe, disappears. A document carrying no sync_batch_id
at all is retired the same way.
The connection comes from the mongo resource
(ai_dagster.resources.mongo.MongoResource), which resolves its URI from
MONGO_PPM_URI in prod and MONGO_PPM_URI_DEV on branch deployments.