Skip to main content

Candidate Selection System Overview

The package scores vehicle configurations for a dealer and model. A SelectionPipeline returns the highest-ranked candidates as recommendations.

Component responsibilities​

ComponentResponsibilityDetails
PipelineConfigValidate configuration and select component classesPipeline
create_pipeline()Build the context and pipelinePipeline
Dataset loaders and IcebergContextAssemblerRead inputs for the requested scopeContext Layer
CandidateNormalizerConvert OEM inputs to candidate pools and inventory candidatesNormalization
ContextStoreProvide candidates and scoring inputs; update supply after confirmationContext Layer
SupplyModelCompute and update the supply matrixContext Layer
ScoringModuleProduce score columns for candidatesScoring and Selection
SelectionStrategyCombine scores and select recommendationsScoring and Selection

Loaders and normalizers handle differences in OEM input schemas. Scorers read normalized attributes and datasets from a context store. A new scorer can reuse existing loaders when they already provide its required inputs.

TakeRateContextStore supports configured dataset loaders and supplied DataFrames. DerivedLayerContextStore receives inputs already filtered to one dealer and model. Its supply model uses the same arrival-estimation functions as callers that estimate arrival for a whole partition.

Architectural constraints​

  • Keep source queries and external I/O in loaders and assemblers. Context data access during scoring must use loaded inputs. TakeRateContextStore.from_config() is an assembly entry point that calls loaders before constructing the store.
  • Keep source field mappings and OEM normalization in loaders and normalizers. Scorers and selection strategies must not branch on OEM names or interpret OEM payloads. They consume normalized candidates and the ContextStore interface.
  • Put supply-matrix updates in SupplyModel and direct-rate updates in SupplyTakeRateProvider. Context stores maintain inventory mappings and caches and delegate supply calculations to those components. Scope changes must preserve confirmed-order supply state.
  • Use the ContextStore interface for scorer and strategy inputs. The factory selects concrete stores and loaders. DemandSupplyGapScorer names TakeRateContextStore in its type annotation, but its calculation uses the normalized take-rate methods. Source access must remain outside scorers.
  • Keep scoring modules independent. Each scorer declares its output columns and returns scores in [0, 1]. Selection strategies combine those columns; a scorer must not call another scorer or apply the selection strategy's weights.

These boundaries allow OEM integrations and scoring algorithms to change independently. A new input source must provide the data existing scorers require; a new scorer may require additional datasets without changing other scorers.

Extension points​

To addImplement and configure
OEM integrationSupply loaders and a CandidateNormalizer for the OEM inputs. Add them to AnyDatasetLoader and AnyCandidateNormalizer. Create a configuration selecting those components and suitable scorers. Reuse existing components when their input requirements are met.
Dataset sourceImplement DatasetLoader.load_bulk(scopes) and declare a type: Literal["..."] field. Add the class to AnyDatasetLoader and configure it under datasets with the dataset name expected by consumers.
Candidate normalizerImplement the CandidateNormalizer interface, declare its type, and add it to AnyCandidateNormalizer. Set candidates_normalizer.type in the configuration. See Normalization.
ScorerImplement ScoringModule.output_columns() and score(context) on a Pydantic model. Declare its type, add it to AnyScoringModule, and include it under scorers. Configure selection weights or masks using its output column names.
Supply modelImplement SupplyModel on a Pydantic model. Declare its type, add it to AnySupplyModel, and set supply_model.type. Choose a rate provider that can consume its output.
Selection strategyImplement SelectionStrategy on a Pydantic model. Declare its approach, add it to AnySelectionStrategy, and set selection.approach.

The unions are defined in the corresponding package modules: data_loaders, normalizers, scorers, supply_models, and strategies. Configuration uses Pydantic discriminated unions; adding a class requires updating its union. Declare the discriminator as a Literal field: type for most components and approach for selection strategies. config.tenant identifies the tenant; it does not select component classes.

Two Dates in SelectionScope​

FieldMeaningUse
dateThe analysis date, in ISO formatIceberg reads select this partition. MatrixSupplyModel measures day offsets from this date.
production_dateThe expected production date of a candidate order, in ISO formatMatrixSupplyModel uses it to calculate the candidate's arrival curve. rescope() sets it on a new pipeline.

The Mercedes configuration uses MatrixSupplyModel and MatrixDerivedProvider. The provider weights each inventory vehicle by the overlap between its on-lot probability curve and the candidate's curve. It derives attribute supply rates from those weights. DemandSupplyGapScorer compares the supply rates with demand rates to score candidates.

For a pipeline with an April 26 analysis date and June 1 production date, call pipeline.rescope("2026-07-01") to evaluate July 1 production. When the returned pipeline scores candidates, it calculates a new candidate arrival curve and on-lot curve. The different overlap weights can change supply rates and recommendation rankings. The returned pipeline shares the original supply model and inventory, including confirmed orders. It evaluates the new production date against that shared supply state.

Date requirements depend on the configured components. MLCDFSupplyModel uses a stored aggregate sale curve for new orders. SimulationSupplyModel uses its configured or estimated arrival offset. These models do not calculate the new order's curve from production_date.

See Data Models for the remaining types and Pipeline for state shared by pipelines created with rescope().