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
| Component | Responsibility | Details |
|---|---|---|
PipelineConfig | Validate configuration and select component classes | Pipeline |
create_pipeline() | Build the context and pipeline | Pipeline |
Dataset loaders and IcebergContextAssembler | Read inputs for the requested scope | Context Layer |
CandidateNormalizer | Convert OEM inputs to candidate pools and inventory candidates | Normalization |
ContextStore | Provide candidates and scoring inputs; update supply after confirmation | Context Layer |
SupplyModel | Compute and update the supply matrix | Context Layer |
ScoringModule | Produce score columns for candidates | Scoring and Selection |
SelectionStrategy | Combine scores and select recommendations | Scoring 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
ContextStoreinterface. - Put supply-matrix updates in
SupplyModeland direct-rate updates inSupplyTakeRateProvider. Context stores maintain inventory mappings and caches and delegate supply calculations to those components. Scope changes must preserve confirmed-order supply state. - Use the
ContextStoreinterface for scorer and strategy inputs. The factory selects concrete stores and loaders.DemandSupplyGapScorernamesTakeRateContextStorein 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 add | Implement and configure |
|---|---|
| OEM integration | Supply 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 source | Implement 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 normalizer | Implement the CandidateNormalizer interface, declare its type, and add it to AnyCandidateNormalizer. Set candidates_normalizer.type in the configuration. See Normalization. |
| Scorer | Implement 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 model | Implement 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 strategy | Implement 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
| Field | Meaning | Use |
|---|---|---|
date | The analysis date, in ISO format | Iceberg reads select this partition. MatrixSupplyModel measures day offsets from this date. |
production_date | The expected production date of a candidate order, in ISO format | MatrixSupplyModel 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().