Models

Core data structures for building expert scorecards. ExpertScorecard is natively sklearn-compatible.

Scorecard

class risk_kit.expert_scorecard.models.ExpertScorecard(features, validation_registry=None)

Bases: BaseEstimator, RegressorMixin

__init__(features, validation_registry=None)

validate()

property feature_names_: list[str]

Sklearn-compatible feature names property.

get_params(deep=True)

Get parameters for this estimator.

fit(X, y=None, **fit_params)

Fit is a no-op for expert scorecards - they are pre-trained.

predict(X)

Calculate risk scores for input data (sklearn-compatible).

predict_single(X)

Score a single record (original interface for backward compatibility).

score(X, y)

Return the predicted scores (sklearn-compatible).

get_table_data()

get_score_range()

Features

class risk_kit.expert_scorecard.models.BaseFeature(*, name, family, description, buckets, weight, default_score=0.0)

Bases: BaseModel, ABC

Base class for all feature types.

name: str

family: str

description: str

buckets: list[NumericBucket] | list[ObjectBucket]

weight: float

default_score: float

get_score(value)

Get the score for a given value.

get_score_range()

Get the range of scores for a given feature.

order_buckets()

has_overlapping_buckets()

Check if any buckets in this feature overlap with each other

get_overlapping_buckets()

Get all pairs of overlapping buckets in this feature

get_feature_rows()

Get table rows for visualization purposes.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class risk_kit.expert_scorecard.models.NumericFeature(*, name, family, description, buckets, weight, default_score=0.0)

Bases: BaseFeature

Feature for numeric values using NumericBucket instances.

buckets: list[NumericBucket]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class risk_kit.expert_scorecard.models.ObjectFeature(*, name, family, description, buckets, weight, default_score=0.0)

Bases: BaseFeature

Feature for categorical/string values using ObjectBucket instances.

buckets: list[ObjectBucket]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Buckets

class risk_kit.expert_scorecard.models.Bucket(*, definition, score)

Bases: BaseModel, ABC, Generic[T]

Abstract base class for all bucket types. bucket types can be whatever you want them to be. We have two concrete implementations: NumericBucket and ObjectBucket. Subclasses must implement get_score get_sort_key and overlaps_with methods. TODO: Can we do away with sort keys and display_definition or make them nicer/easier to work with since it is only a visual thing? TODO: think about whether an ABC is the best way to go here. Do we need BaseModel?

definition: BucketDefinitionType

score: float

abstractmethod contains(value)

Check if this bucket contains the given value

abstractmethod get_sort_key()

Generate a sort key for natural ordering of buckets

abstractmethod overlaps_with(other)

Check if this bucket overlaps with another bucket of the same type

abstractmethod display_definition()

Return a human-readable string representation of the bucket definition

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class risk_kit.expert_scorecard.models.NumericBucket(*, definition, score, left_inclusive=True, right_inclusive=False)

Bases: Bucket[NumericBucket]

Implementation of a Bucket class for numeric values. Numerical buckets are made up of ranges or exact values. Usually exact values are used for “special cases” such as a number than has a special meaning like 99999 or 0. Ranges are used for “normal cases” such as 18-25, 26-65, 66-100.

definition: NumericDefinitionType

left_inclusive: bool

right_inclusive: bool

contains(value)

Check if this bucket contains the given value

get_sort_key()

Sort ranges first by lowest score, then exact values

overlaps_with(other)

Check if this numeric bucket overlaps with another numeric bucket

display_definition()

Return a human-readable string representation of the bucket definition

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class risk_kit.expert_scorecard.models.ObjectBucket(*, definition, score)

Bases: Bucket[ObjectBucket]

Bucket for string/categorical values. Supports single strings or lists of strings.

definition: ObjectDefinitionType

contains(value)

Check if this bucket contains the given value

get_sort_key()

Sort lists before strings

overlaps_with(other)

Check if this object bucket overlaps with another object bucket

display_definition()

Return a human-readable string representation of the bucket definition

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].