Skip to main content

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/:

ComponentOutputPurpose
DealerPreferencesComponentacceptance/dealer_rules (Iceberg)Inference
DealerPreferencesMongoComponentacceptance/<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_rate off the configured attribute_stats asset, 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 from featurization/features. Of a value's choice years, the rate counts sales of model years at or after the partition year. With stock_and_orders set, 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). Without stock_and_orders, the share is unweighted. With stock_and_orders set, a vehicle sold in the window weighs its recency weight at the half-life of sales_hl90, and a vehicle in inventory, whether in stock or on order, weighs 1 / divisor. Any other vehicle is left out of the share, of demand_nobs and of the vehicle count that ELIGIBLE_NOBS_MIN applies to. With stock_and_orders set, DealerPreferencesComponent also reads inferred_sold_date, is_sold_in_window and is_in_inventory from consolidated/inventory. It raises unless inferred_sold_date is a Date.

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_configurable on consolidated/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.
  • FALSE of a binary attribute is a choice in every model year in which TRUE is.

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_asset must name the attribute_stats statistics grouped by dealer_id and model_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 in attribute_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_years computes.
  • The option-code path checks each code against the choice years that code_choice_years computes. 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.