lenskit.data.schema#

Pydantic models for LensKit data schemas. These models define define the data schema in memory and also define how schemas are serialized to and from configuration files. See Data Model for details.

Note

The schema does not specify data types directly — data types are inferred from the underlying Arrow data structures. This reduces duplication of type information and the opportunity for inconsistency.

Functions

`check_name`(name)	Check if a name is valid.
`id_col_name`(name)
`num_col_name`(name)

Classes

`AllowableTroolean`(value[, names, module, ...])	Three-way enumeration for storing both whether a feature is allowed and is used.
`AttrLayout`(value[, names, module, qualname, ...])
`ColumnSpec`(*[, layout, vector_size])
`DataSchema`(*[, name, default_interaction, ...])	Description of the entities and layout of a dataset.
`EntitySchema`(*[, id_type, attributes])	Entity class definitions in the dataset schema.
`RelationshipSchema`(*, entities[, ...])	Relationship class definitions in the dataset schema.

lenskit.data.schema.check_name(name)#

Check if a name is valid.

Raises:: ValueError – when the name is invalid.
Parameters:: name (str)
Return type:: None

class lenskit.data.schema.AllowableTroolean(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Three-way enumeration for storing both whether a feature is allowed and is used. For convenience, in serialized data or configuration files these values may be specified either as strings or as booleans, in which case False is FORBIDDEN and True is ALLOWED. They are always serialized as strings.

FORBIDDEN = 'forbidden'#: The feature is forbidden.

ALLOWED = 'allowed'#: The feature is allowed, but no records using it are present.

PRESENT = 'present'#: The feature is used by instances in the data.

property is_allowed: bool#: Query whether the feature is allowed.

property is_forbidden: bool#: Query whether the feature is forbidden.

property is_present: bool#: Query whether the feature is present (used in recorded instances).

class lenskit.data.schema.AttrLayout(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

SCALAR = 'scalar'#: Scalar (non-list, non-vector) attribute value.

LIST = 'list'#: Homogenous, variable-length list of attribute values.

VECTOR = 'vector'#: Homogenous, fixed-length vector of numeric attribute values.

SPARSE = 'sparse'#: Homogenous, fixed-length sparse vector of numeric attribute values.

class lenskit.data.schema.DataSchema(**data)#

Bases: BaseModel

Description of the entities and layout of a dataset.

Parameters:

data (Any)
name (str | None)
default_interaction (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))] | None)
entities (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))], EntitySchema])
relationships (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))], RelationshipSchema])

name: str | None#: The dataset name.

default_interaction: Name | None#: The default interaction type.

entities: dict[Name, EntitySchema]#: Entity classes defined for this dataset.

relationships: dict[Name, RelationshipSchema]#: Relationship classes defined for this dataset.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class lenskit.data.schema.EntitySchema(**data)#

Bases: BaseModel

Entity class definitions in the dataset schema.

Parameters:

data (Any)
id_type (Literal['int', 'str'] | None)
attributes (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))], ColumnSpec])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id_type: Literal['int', 'str'] | None#: The data type for identifiers in this entity class.

attributes: dict[Name, ColumnSpec]#: Entity attribute definitions.

class lenskit.data.schema.RelationshipSchema(**data)#

Bases: BaseModel

Relationship class definitions in the dataset schema.

Parameters:

data (Any)
entities (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))], Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))] | None])
interaction (bool)
repeats (AllowableTroolean)
attributes (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=re.compile('^[\\w_]+$'))], ColumnSpec])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

entities: dict[Name, Name | None]#: Define the entity classes participating in the relationship. For aliased entity classes (necessary for self-relationships), the key is the alias, and the value is the original entity class name.

interaction: bool#: Whether this relationship class records interactions.

repeats: AllowableTroolean#: Whether this relationship supports repeated interactions.

attributes: dict[Name, ColumnSpec]#: Relationship attribute definitions.

class lenskit.data.schema.ColumnSpec(*, layout=AttrLayout.SCALAR, vector_size=None)#

Bases: BaseModel

Parameters:

layout (AttrLayout)
vector_size (int | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

layout: AttrLayout#: The attribute layout (whether and how multiple values are supported).

vector_size: int | None#: The dimensionality of the vector, for sparse and vector columns.