poprox_storage.concepts.manifest#

Experiment Manifest Parser

This module provides functionality for parsing and validating experiment manifest files in TOML format anf converting them into domain concept objects. The manifest files define experiment configurations including phases, user groups, recommenders, and assignments.

Functions

`convert_duration`(duration)	Convert duration string to timedelta object.
`manifest_to_experiment`(manifest)	Convert parsed manifest file to domain concept objects.
`parse_manifest_toml`(manifest_file)	Takes raw TOML content as a string, parses it, and restructures the phases section to match the expected ManifestFile schema.

Classes

`ManifestExperiment`(*, id, description, duration)	Experiment metadata and configuration.
`ManifestFile`(*, experiment, owner, users, ...)	Parses and validates experiment manifest files that have been converted from TOML to Dict[str,Any] (e.g. using tomli).
`ManifestGroupSpec`(*, groups)	Specification of user groups for the experiment.
`ManifestPhase`(*, duration, assignments)	Configuration for a single experiment phase.
`ManifestPhaseAssignment`(*, recommender[, ...])	Assignment of a group to a recommender during a phase.
`ManifestPhases`(*, sequence, phases)	Container for experiment phase configuration.
`ManifestRecommender`(*, url)	Configuration for a recommender system.
`ManifestTeam`(*, team_id, team_name, members)	Information of the team that owns and manages the experiment, including team id and members.
`ManifestUserGroup`(*[, minimum_size, ...])	Specification for a single user group.

class poprox_storage.concepts.manifest.ManifestFile(**data)#

Bases: BaseModel

Parses and validates experiment manifest files that have been converted from TOML to Dict[str,Any] (e.g. using tomli).

Parameters:

data (Any)
experiment (ManifestExperiment)
owner (ManifestTeam)
users (ManifestGroupSpec)
recommenders (dict[str, ManifestRecommender])
phases (ManifestPhases)

experiment#

Experiment metadata and configuration

Type:: poprox_storage.concepts.manifest.ManifestExperiment

owner#

Experiment team owner

Type:: poprox_storage.concepts.manifest.ManifestTeam

users#

Specification of user groups participating in the experiment

Type:: poprox_storage.concepts.manifest.ManifestGroupSpec

recommenders#

Dictionary mapping recommender names to their configurations

Type:: dict[str, poprox_storage.concepts.manifest.ManifestRecommender]

phases#

Sequence of experiment phases

Type:: poprox_storage.concepts.manifest.ManifestPhases

class poprox_storage.concepts.manifest.ManifestExperiment(*, id, description, duration, start_date=None)#

Bases: BaseModel

Experiment metadata and configuration.

Defines the basic properties of an experiment including its id, description, duration, and optional start date.

Parameters:

id (UUID)
description (str)
duration (str)
start_date (date | None)

id#

Unique identifier for the experiment

Type:: uuid.UUID

description#

Human-readable description of the experiment

Type:: str

duration#

Experiment duration in string format (e.g., “2 weeks”, “5 days”)

Type:: str

start_date#

Optional start date. If None, defaults to tomorrow

Type:: datetime.date | None

class poprox_storage.concepts.manifest.ManifestTeam(*, team_id, team_name, members)#

Bases: BaseModel

Information of the team that owns and manages the experiment, including team id and members.

Parameters:

team_id (UUID)
team_name (str)
members (list[UUID])

team_id#

Unique identifier for the team

Type:: uuid.UUID

team_name#

Human-readable team name

Type:: str

members#

List of UUIDs representing team members

Type:: list[uuid.UUID]

class poprox_storage.concepts.manifest.ManifestPhases(**data)#

Bases: BaseModel

Container for experiment phase configuration.

Manages the sequence of phases and their individual configurations.

Parameters:

data (Any)
sequence (list[str])
phases (dict[str, ManifestPhase])

sequence#

List of phase names

Type:: list[str]

phases#

Dictionary mapping phase names to their configurations

Type:: dict[str, poprox_storage.concepts.manifest.ManifestPhase]

class poprox_storage.concepts.manifest.ManifestPhase(**data)#

Bases: BaseModel

Configuration for a single experiment phase.

Defines the duration and group assignments for a specific phase of the experiment.

Parameters:

data (Any)
duration (str)
assignments (dict[str, ManifestPhaseAssignment])

duration#

Phase duration in string format (e.g., “1 week”, “3 days”)

Type:: str

assignments#

Dictionary mapping group names to their phase assignments

Type:: dict[str, poprox_storage.concepts.manifest.ManifestPhaseAssignment]

class poprox_storage.concepts.manifest.ManifestPhaseAssignment(*, recommender, template=None)#

Bases: BaseModel

Assignment of a group to a recommender during a phase.

Specifies which recommender a particular group will use during a phase, along with optional template configuration.

Parameters:

recommender (str)
template (str | None)

recommender#

Name of the recommender to use for this assignment

Type:: str

template#

Optional template specification for the recommender

Type:: str | None

class poprox_storage.concepts.manifest.ManifestRecommender(*, url)#

Bases: BaseModel

Configuration for a recommender system.

Parameters:: url (str)

url#

URL endpoint for the recommender

Type:: str

class poprox_storage.concepts.manifest.ManifestGroupSpec(**data)#

Bases: BaseModel

Specification of user groups for the experiment.

Parameters:

data (Any)
groups (dict[str, ManifestUserGroup])

groups#

Dictionary mapping group names to their specifications

Type:: dict[str, poprox_storage.concepts.manifest.ManifestUserGroup]

class poprox_storage.concepts.manifest.ManifestUserGroup(*, minimum_size=None, identical_to=None)#

Bases: BaseModel

Specification for a single user group.

Defines the configuration for a user group, including size constraints and the ability to create identical copies of existing groups.

Parameters:

minimum_size (Annotated[int, Gt(gt=0)] | None)
identical_to (str | None)

minimum_size#

Optional minimum number of users required in the group

Type:: int | None

identical_to#

Optional name of another group to copy configuration from

Type:: str | None

poprox_storage.concepts.manifest.manifest_to_experiment(manifest)#

Convert parsed manifest file to domain concept objects.

Resolves manifest fields into their corresponding domain fields, including duration into dates and identical groups into copies. Doesn’t assign users to groups, which would require additional information about the state of the system beyond what’s contained in the manifest.

Parameters:: manifest (ManifestFile) – A parsed experiment manifest as a Pydantic model
Returns:: A transformed version of the manifest file as a domain object
Return type:: Experiment

poprox_storage.concepts.manifest.convert_duration(duration)#

Convert duration string to timedelta object.

Supported formats: - “N week” or “N weeks” (where N is an integer) - “N day” or “N days” (where N is an integer)

Parameters:: duration (str) – Duration on string format (e.g., “2 weeks”, “5 days”)
Returns:: Equvalent timedelta object
Return type:: timedelta

poprox_storage.concepts.manifest.parse_manifest_toml(manifest_file)#

Takes raw TOML content as a string, parses it, and restructures the phases section to match the expected ManifestFile schema.

Parameters:: manifest_file (str) – Raw TOML content as a string
Returns:: Validated and parsed manifest file object
Return type:: ManifestFile