Data Schemas

All data crossing the engine boundary is described by self-contained pydantic models in scoring/schemas/__init__.py. They have no external schema dependencies. This page documents the event/session input and the scoring output at a conceptual level; the autogenerated field tables are in the API Reference.

Events: the atomic unit

A GameEvent is one timestamped action:

GameEvent(
    timestamp=123.4,                       # ms, monotonic (performance.now())
    type="pump",                           # "pump" | "collect" | "explode"
    payload=EventPayload(color="purple"),  # at minimum, the balloon color
)

• timestamp must be non-negative (validated).

• type is a free string at the model level; the BART validators restrict it to pump / collect / explode.

• EventPayload is permissive (model_config = {"extra": "allow"}) so you can attach extra fields, but the engine reads color (or the alias balloon_color) and balloon_id.

How balloons are delimited

There is no explicit “balloon start” event. A balloon is the maximal run of pump events ending at the next collect or explode. Each event should carry the color of the balloon it belongs to.

Sessions

A GameSession wraps the full ordered log for submission:

GameSession(
    session_id="uuid-string",
    game_type="BART_RISK",                 # GameType enum
    candidate_id="participant-123",
    events=[...],                          # min 1, must be chronological
)

The model enforces chronological ordering at construction time: an out-of-order timestamp raises a ValueError (surfaces as HTTP 422 in a typical FastAPI backend).

Event validation

scoring.schemas.game_events.validate_bart_events() is a lightweight structural check, separate from the richer scoring.bart.validate_bart_session(). It enforces that:

• every event type is one of pump / collect / explode, and

• no balloon terminates (collect/explode) with zero pumps.

from scoring.schemas.game_events import validate_bart_events

validate_bart_events(events)   # raises ValueError on malformed input

Output models

Model	Role
BARTMetrics	The complete scoring output (see Metrics Reference).
ColorMetrics	Per-color breakdown nested inside BARTMetrics.color_metrics.
NormalizedScore	A raw metric expressed as a z-score / percentile against population norms (optional; you supply the norms).
AssessmentResponse	A full response envelope: raw metrics + normalized scores + trait labels.

NormalizedScore and AssessmentResponse are provided for integrators who maintain population norms; the core engine produces only BARTMetrics and does not require them.