Skip to content

sweetbean.stimulus_spec.spec

Pydantic stimulus specifications for layered SweetBean trial rendering.

AssetStimulusSpec

Bases: _BaseStimulusSpec

Rendered visual asset stimulus (image/gif/other browser image asset).

Source code in sweetbean/stimulus_spec/spec.py
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class AssetStimulusSpec(_BaseStimulusSpec):
    """Rendered visual asset stimulus (image/gif/other browser image asset)."""

    kind: Literal["asset"] = "asset"
    asset_ref: str = Field(
        description=(
            "Asset URL/path, or a timeline placeholder like `{{asset_path_col}}` "
            "resolved from the current CSV row."
        )
    )
    object_fit: Literal["contain", "cover", "fill", "none", "scale-down"] | None = Field(
        default=None,
        description=(
            "Optional CSS object-fit. If omitted, defaults to contain."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )

BanditArmSpec

Bases: _SpecBaseModel

One arm rendered in a bandit stimulus.

Source code in sweetbean/stimulus_spec/spec.py
189
190
191
192
193
194
195
196
197
198
199
200
201
202
class BanditArmSpec(_SpecBaseModel):
    """One arm rendered in a bandit stimulus."""

    color: str = Field(
        description="CSS color for the arm border/accent.",
    )
    label: str | None = Field(
        default=None,
        description="Optional arm label shown under the bandit tile.",
    )
    value_text: str | None = Field(
        default=None,
        description="Optional value text shown inside the tile.",
    )

BanditStimulusSpec

Bases: _BaseStimulusSpec

Rendered static multi-armed bandit display.

Source code in sweetbean/stimulus_spec/spec.py
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
class BanditStimulusSpec(_BaseStimulusSpec):
    """Rendered static multi-armed bandit display."""

    kind: Literal["bandit"] = "bandit"
    bandits: tuple[BanditArmSpec, ...] = Field(
        default_factory=tuple,
        min_length=1,
        description="Bandit arms shown as clickable-style tiles in a grid.",
    )
    title: str | None = Field(
        default=None,
        description="Optional heading text shown above the bandit grid.",
    )
    grid_columns: int | None = Field(
        default=None,
        ge=1,
        description=(
            "Optional explicit number of columns in the grid. "
            "If omitted, renderer picks a near-square layout."
        ),
    )

RectangleSpec

Bases: _SpecBaseModel

Normalized rectangular placement in viewport coordinates.

Source code in sweetbean/stimulus_spec/spec.py
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class RectangleSpec(_SpecBaseModel):
    """Normalized rectangular placement in viewport coordinates."""

    x: float = Field(
        default=0.5,
        ge=0.0,
        le=1.0,
        description="Horizontal center position in normalized viewport coordinates.",
    )
    y: float = Field(
        default=0.5,
        ge=0.0,
        le=1.0,
        description="Vertical center position in normalized viewport coordinates.",
    )
    width: float = Field(
        default=1.0,
        gt=0.0,
        le=1.0,
        description="Normalized width relative to viewport width.",
    )
    height: float = Field(
        default=1.0,
        gt=0.0,
        le=1.0,
        description="Normalized height relative to viewport height.",
    )

SymbolStimulusSpec

Bases: _BaseStimulusSpec

Rendered geometric symbol stimulus.

Source code in sweetbean/stimulus_spec/spec.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class SymbolStimulusSpec(_BaseStimulusSpec):
    """Rendered geometric symbol stimulus."""

    kind: Literal["symbol"] = "symbol"
    shape: Literal["circle", "ring", "rectangle", "triangle", "cross"] = Field(
        description="Symbol geometry to render.",
    )
    color: str = Field(
        default="#111111",
        description="Primary CSS color used for symbol fill/stroke.",
        json_schema_extra=_PROMPT_SILENT,
    )
    size_px: int | None = Field(
        default=None,
        ge=1,
        description=(
            "Optional symbol size in pixels. If omitted, defaults to 160."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )
    stroke_color: str | None = Field(
        default=None,
        description=(
            "Optional outline color for symbol variants that support stroke."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )
    stroke_width_px: int | None = Field(
        default=None,
        ge=0,
        description=(
            "Optional outline width in pixels. If omitted, renderer picks a "
            "shape-specific default when needed."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )
    rotation_deg: float | None = Field(
        default=None,
        description=(
            "Optional clockwise symbol rotation in degrees. If omitted, defaults to 0."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )

TextStimulusSpec

Bases: _BaseStimulusSpec

Rendered text stimulus.

Source code in sweetbean/stimulus_spec/spec.py
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
class TextStimulusSpec(_BaseStimulusSpec):
    """Rendered text stimulus."""

    kind: Literal["text"] = "text"
    text: str = Field(description="Text content to render.")
    color: str = Field(
        default="white",
        description="CSS text color. Default: white.",
        json_schema_extra=_PROMPT_SILENT,
    )
    font_size_px: int | None = Field(
        default=None,
        ge=1,
        description=(
            "Optional font size in pixels. If omitted, defaults to 32."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )
    font_family: str | None = Field(
        default=None,
        description=(
            "Optional CSS font-family. If omitted, defaults to sans-serif."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )
    align: Literal["left", "center", "right"] | None = Field(
        default=None,
        description=(
            "Optional text alignment inside the placement rectangle. "
            "If omitted, defaults to center."
        ),
        json_schema_extra=_PROMPT_SILENT,
    )

TrialSpec

Bases: _SpecBaseModel

One rendered trial containing layered stimuli and response handlers.

Source code in sweetbean/stimulus_spec/spec.py
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
class TrialSpec(_SpecBaseModel):
    """One rendered trial containing layered stimuli and response handlers."""

    stimuli: tuple[StimulusSpecUnion, ...] = Field(
        default_factory=tuple,
        min_length=1,
        description="Layered visual stimuli rendered in one trial frame.",
    )
    responses: tuple[ResponseSpecUnion, ...] = Field(
        default_factory=tuple,
        description="Response handlers active for this trial frame.",
    )
    trial_duration_ms: int | None = Field(
        default=None,
        ge=1,
        description="Optional hard cap for total trial duration.",
        json_schema_extra=_PROMPT_SILENT,
    )
    background_color: str = Field(
        default="black",
        description="CSS background color for the trial frame. Default: black.",
        json_schema_extra=_PROMPT_SILENT,
    )

    @model_validator(mode="after")
    def _validate_unique_ids_and_stimulus_defaults(self) -> "TrialSpec":
        ids = [s.id for s in self.stimuli if s.id]
        if len(ids) != len(set(ids)):
            raise ValueError("Stimulus ids must be unique when provided.")

        resolved: list[StimulusSpecUnion] = []
        for i, s in enumerate(self.stimuli):
            updates: dict[str, object] = {}
            if s.z_index is None:
                updates["z_index"] = i
            if s.rect is None:
                updates["rect"] = RectangleSpec()
            if s.opacity is None:
                updates["opacity"] = 1.0
            if isinstance(s, TextStimulusSpec):
                if s.font_size_px is None:
                    updates["font_size_px"] = 32
                if s.font_family is None:
                    updates["font_family"] = "sans-serif"
                if s.align is None:
                    updates["align"] = "center"
            if isinstance(s, SymbolStimulusSpec):
                if s.size_px is None:
                    updates["size_px"] = 160
                if s.rotation_deg is None:
                    updates["rotation_deg"] = 0.0
            if isinstance(s, AssetStimulusSpec):
                if s.object_fit is None:
                    updates["object_fit"] = "contain"
            if updates:
                s = s.model_copy(update=updates)
            resolved.append(s)

        return self.model_copy(update={"stimuli": tuple(resolved)})