Data Models
types.py defines Patito models for DataFrame schemas and Pydantic models for
pipeline inputs and results. TakeRateContextStore.get(key, schema) validates a
dataset against the supplied Patito model.
PipelineStatus
MatrixSupplyModel uses PipelineStatus to choose an inventory projection.
MercedesDealerInventoryLoader maps Netstar status codes to these values.
| Value | Meaning | Netstar codes |
|---|---|---|
ON_LOT | Available on the dealer lot | INV |
IN_PRODUCTION | In production | IP |
IN_TRANSIT | In transit to the dealer | OTW, PNS |
AT_PROCESSING | At a vehicle processing center | VPC |
See MatrixSupplyModel for the probability calculations.
DataFrame Models
DealerInventory
One row per inventory vehicle.
| Column | Type | Meaning |
|---|---|---|
order_id | str | Unique vehicle order identifier |
model_id | str | Model identifier |
model_year | str | Model year |
production_date | str | ISO-format production date |
order_status | str | A PipelineStatus value |
days_in_status | int | Days in the current status |
MatrixSupplyModel uses the status and elapsed time to choose and condition each
vehicle's probability curve.
ModelDol
Days-on-lot distribution parameters, with one row per model.
| Column | Type | Meaning |
|---|---|---|
model_id | str | Unique model identifier |
weibull_shape | float | Weibull shape parameter |
weibull_scale | float | Weibull scale parameter |
CategoryDit
Arrival distribution parameters, with one row per model.
| Column | Type | Meaning |
|---|---|---|
model_id | str | Unique model identifier |
burr12_c | float | Burr Type XII c parameter |
burr12_d | float | Burr Type XII d parameter |
burr12_loc | float | Burr Type XII location parameter |
burr12_scale | float | Burr Type XII scale parameter |
AttributeScoringStats
Demand take rates, with one row per
(dealer_id, model_id, attribute_type, attribute_value).
| Column | Type | Meaning |
|---|---|---|
dealer_id | str | Dealer identifier |
model_id | str | Model identifier |
attribute_type | str | Attribute type |
attribute_value | str | Attribute value |
demand_take_rate | float | None | Demand take rate for the attribute |
DemandSupplyGapScorer reads these rates. Contribution margins use the separate
attribute_contribution_margin dataset.
AttributeWeights
Scoring weights, with one row per (model_id, attribute_type).
| Column | Type | Meaning |
|---|---|---|
model_id | str | Model identifier |
attribute_type | str | Attribute type |
attribute_weight | float | Weight for this attribute type |
Pydantic Models
SelectionScope
The dealer and model being scored, with optional analysis and production dates.
| Field | Type | Meaning |
|---|---|---|
dealer_code | str | The OEM's dealer code, such as Stellantis 24028 |
model_id | str | Model identifier |
date | str | None | ISO-format analysis date; day zero for inventory curves |
production_date | str | None | ISO-format expected production date of the candidate order |
MatrixSupplyModel.compute() requires date. Its candidate-curve calculation
also requires production_date. DirectRateProvider does not use either date.
For a configuration with iceberg_tables, the pipeline looks up dealer_code in
the dealers table, <oem>/<market>/consolidated/dealers. It filters every table
keyed by dealer on the dealer_id that the lookup returns. The BigQuery datasets of
the other configurations name the OEM dealer code dealer_id. The pipeline filters
those datasets by comparing that column to dealer_code, without a lookup.
NormalizedCandidate and CandidateAttribute
See Normalization for candidate fields and source mappings.
CandidateOption
An option line item attached to a recommendation after selection.
| Field | Type | Default | Meaning |
|---|---|---|---|
option_id | str | Required | The feature's option_code |
name | str | None | None | Display name |
price | float | None | None | Option price |
subcategory | str | None | None | Source subcategory |
is_configurable | bool | None | None | Source configurable flag |
shown_on_order | bool | None | None | Source shown-on-order flag |
is_elective | bool | True | Whether the dealer can select the option |
RecommendationMetadata
Diagnostics for one recommendation, requested through include_metadata=True.
| Field | Type | Meaning |
|---|---|---|
dealer_code | str | The scope's OEM dealer code |
dealer_id | str | None | The dealer's key in consolidated/dealers; None for a configuration without iceberg_tables |
model_id | str | The scope's model |
production_date | str | None | The scope's production date |
candidate_id | str | Recommended candidate |
candidate_attributes | list[RecommendationAttribute] | Take rates for each attribute of the candidate |
misalignment_by_attribute_type | list[MisalignmentByAttributeType] | Sum of the absolute demand-supply differences per attribute type |
final_score | float | Combined selection score |
scorer_outputs | list[ScorerOutput] | Each scorer's score and rank |
cnt_pre_restriction_prune | int | Number of candidates before rescope removed the ones that its production restrictions exclude |
cnt_post_restriction_prune | int | Number of candidates that remain after rescope |
production_restrictions | list[AttributeRestriction] | The production restrictions passed to rescope |
RecommendationAttribute
Attribute statistics in RecommendationMetadata.candidate_attributes, with one
row per (attribute_type, attribute_value) on the selected candidate.
| Field | Type | Meaning |
|---|---|---|
attribute_type | str | Attribute type |
attribute_value | str | Attribute value |
supply_take_rate | float | None | Attribute supply take rate |
demand_take_rate | float | None | Attribute demand take rate |
attribute_weight | float | None | Attribute type's weight |
rank | int | None | Rank within the type by descending demand-supply gap, starting at one |
num_values_in_type | int | None | Number of codes for this type |
Recommendation
One result per selected candidate.
| Field | Type | Meaning |
|---|---|---|
candidate | NormalizedCandidate | Selected candidate |
iteration | int | Selection round; WeightedAverageSelection sets it to one |
score | float | Combined selection score |
module_scores | list[ModuleScore] | Each scorer's output column name and raw score |
metadata | RecommendationMetadata | None | Diagnostics requested through include_metadata=True |
SupplyMatrix
Daily supply estimates for inventory vehicles. MatrixSupplyModel and
SimulationSupplyModel estimate on-lot probabilities. MLCDFSupplyModel uses
clip(1 - sale_CDF(d), 0, 1), the probability that a vehicle has not sold. See the
MLCDFSupplyModel design.
| Field | Type | Meaning |
|---|---|---|
model_id | str | Model identifier |
horizon_start | int | First day offset |
horizon_days | int | Number of daily probability columns |
matrix | pl.DataFrame | One row per vehicle, identified by order_id; day_<offset> columns contain probabilities |