Implementation:Interpretml Interpret Powerlift Schema

Knowledge Sources	Interpretml Interpret
Domains	Benchmarking, Database, ORM
Last Updated	2026-02-07 12:00 GMT

Overview

SQLAlchemy ORM schema defining the core entity models (Experiment, Trial, Task, MeasureOutcome, Wheel) used by the Powerlift benchmarking framework to persist experiments and their results in a relational database.

Description

This module defines the complete database schema for Powerlift's benchmarking system using SQLAlchemy's declarative ORM. It includes five main entity models:

• Experiment -- Represents an overall benchmarking experiment, including the script to execute, pip/shell install requirements, and a trial function. Has relationships to Wheel assets and Trial records.
• Trial -- A single trial replicate tying an experiment to a task and method. Tracks runner assignment, timing, error messages, and measure outcomes. Uses a composite index on experiment_id, runner_id (descending), and id for efficient work assignment queries.
• Task -- Represents a problem tied to a dataset (e.g., regression on Boston data). Stores dataset statistics such as sample count, feature count, class count, and categorical percentages. Contains serialized feature (X) and target (Y) data as large binary columns.
• MeasureOutcome -- Records individual measurement results generated during a trial, with typed values (NUMBER, STR, JSON) and sequence numbering.
• Wheel -- Stores embedded Python wheel binary assets associated with experiments.

Two enums are also defined: TypeEnum (NUMBER, STR, JSON) for measure value types and StatusEnum (READY, RUNNING, COMPLETE, ERROR, SUSPENDED) for trial lifecycle states.

Usage

Use this schema when working with Powerlift's database layer. The models are consumed by the Store class to create, query, and update benchmarking records. They are essential for any component that reads from or writes to the Powerlift database, including executors, runners, and the benchmarking harness itself.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: python/powerlift/powerlift/db/schema.py

Signature

class TypeEnum(enum.Enum):
    NUMBER = 0
    STR = 1
    JSON = 2

class StatusEnum(enum.Enum):
    READY = 0
    RUNNING = 1
    COMPLETE = 2
    ERROR = 3
    SUSPENDED = 4

class Experiment(Base):
    __tablename__ = "experiment"
    id = Column(Integer, primary_key=True, autoincrement=True, nullable=False)
    name = Column(String(NAME_LEN), nullable=False)
    description = Column(String(DESCRIPTION_LEN), nullable=True)
    shell_install = Column(Text, nullable=True)
    pip_install = Column(Text, nullable=True)
    script = Column(Text, nullable=False)
    trial_fn = Column(Text, nullable=False)

class Trial(Base):
    __tablename__ = "trial"
    id = Column(Integer, primary_key=True, autoincrement=True, nullable=False)
    experiment_id = Column(Integer, ForeignKey("experiment.id"), nullable=False)
    runner_id = Column(Integer, nullable=False, server_default=text("-1"))
    task_id = Column(Integer, ForeignKey("task.id"), nullable=False)
    method = Column(String(NAME_LEN), nullable=False)
    meta = Column(Text, nullable=False)
    replicate_num = Column(Integer, nullable=False)

class Task(Base):
    __tablename__ = "task"
    id = Column(Integer, primary_key=True, autoincrement=True, nullable=False)
    name = Column(String(NAME_LEN), nullable=False)
    problem = Column(String(PROBLEM_LEN), nullable=False)
    origin = Column(String(NAME_LEN), nullable=False)
    n_samples = Column(Integer, nullable=False)
    n_features = Column(Integer, nullable=False)
    n_classes = Column(Integer, nullable=False)

class MeasureOutcome(Base):
    __tablename__ = "measure_outcome"
    id = Column(Integer, primary_key=True, autoincrement=True, nullable=False)
    trial_id = Column(Integer, ForeignKey("trial.id"), nullable=False)
    name = Column(String(NAME_LEN), nullable=False)
    type = Column(Integer, nullable=False)
    seq_num = Column(Integer, nullable=False)
    val = Column(Text, nullable=False)

class Wheel(Base):
    __tablename__ = "wheel"
    experiment_id = Column(Integer, ForeignKey("experiment.id"), primary_key=True, nullable=False)
    name = Column(String(NAME_LEN), primary_key=True, nullable=False)
    embedded = Column(LargeBinary, nullable=False)

Import

from powerlift.db.schema import Experiment, Trial, Task, MeasureOutcome, Wheel, TypeEnum, StatusEnum

I/O Contract

Inputs

Name	Type	Required	Description
Base	declarative_base	Yes	SQLAlchemy declarative base shared by all models

Outputs

Name	Type	Description
Experiment	ORM Model	Experiment entity with name, script, install instructions, and relationships to trials and wheels
Trial	ORM Model	Trial replicate entity linking experiment to task with runner assignment and timing
Task	ORM Model	Dataset-problem pairing with statistical metadata and serialized data
MeasureOutcome	ORM Model	Individual measurement record from a trial execution
Wheel	ORM Model	Embedded Python wheel binary asset for an experiment
TypeEnum	Enum	Value type enumeration (NUMBER, STR, JSON)
StatusEnum	Enum	Trial lifecycle state enumeration (READY, RUNNING, COMPLETE, ERROR, SUSPENDED)

Usage Examples

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from powerlift.db.schema import Base, Experiment, Trial, Task

# Create database tables
engine = create_engine("sqlite:///powerlift.db")
Base.metadata.create_all(engine)

# Query experiments and their trials
with Session(engine) as session:
    experiment = session.query(Experiment).filter_by(name="my_benchmark").first()
    for trial in experiment.trials:
        print(f"Trial {trial.id}: method={trial.method}, task={trial.task.name}")

Related Pages

• Implementation:Interpretml_Interpret_Powerlift_Executor -- Abstract base class for executors that create and manage trials
• Implementation:Interpretml_Interpret_Powerlift_RunTrials -- Trial worker entry point that queries and executes trials from the database
• Implementation:Interpretml_Interpret_Powerlift_TaskMeasures -- Functions that compute dataset statistics stored in Task metadata
• Implementation:Interpretml_Interpret_Powerlift_LocalMachine -- Local executor that runs trials using these schema models