bead 0.1.0__py3-none-any.whl

bead/deployment/jatos/exporter.py

@@ -0,0 +1,210 @@
+"""JATOS exporter for jsPsych experiments.
+
+This module provides the JATOSExporter class for creating JATOS study packages (.jzip)
+from generated jsPsych experiments.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import tempfile
+import uuid
+import zipfile
+from datetime import datetime
+from pathlib import Path
+
+from bead.data.base import BeadBaseModel, JsonValue
+
+
+class JATOSExporter(BeadBaseModel):
+    """Exports jsPsych experiments as JATOS study packages (.jzip).
+
+    A .jzip file is a ZIP archive containing:
+    - study.json: JATOS metadata
+    - experiment/: All experiment files (HTML, JS, CSS, data)
+
+    Attributes
+    ----------
+    study_title : str
+        Title of the JATOS study.
+    study_description : str
+        Description of the study.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> exporter = JATOSExporter("Test Study", "A test study")
+    >>> # exporter.export(Path("experiment"), Path("study.jzip"))
+    """
+
+    study_title: str
+    study_description: str = ""
+
+    def export(
+        self,
+        experiment_dir: Path,
+        output_path: Path,
+        component_title: str = "Main Experiment",
+    ) -> None:
+        """Create JATOS .jzip file.
+
+        Parameters
+        ----------
+        experiment_dir : Path
+            Directory containing experiment files (from JsPsychExperimentGenerator).
+            Expected structure:
+            - index.html
+            - css/experiment.css
+            - js/experiment.js
+            - data/timeline.json
+            - data/config.json
+        output_path : Path
+            Output path for .jzip file.
+        component_title : str
+            Title for the JATOS component.
+
+        Raises
+        ------
+        ValueError
+            If experiment_dir does not exist or is missing required files.
+        FileNotFoundError
+            If required experiment files are not found.
+
+        Examples
+        --------
+        >>> exporter = JATOSExporter("Test Study")
+        >>> exporter.export(Path("exp"), Path("study.jzip"))
+        """
+        if not experiment_dir.exists():
+            raise ValueError(f"Experiment directory does not exist: {experiment_dir}")
+
+        if not experiment_dir.is_dir():
+            raise ValueError(f"Path is not a directory: {experiment_dir}")
+
+        # verify required files exist
+        required_files = ["index.html"]
+        for file in required_files:
+            if not (experiment_dir / file).exists():
+                raise FileNotFoundError(
+                    f"Required file not found: {experiment_dir / file}"
+                )
+
+        # create temporary directory for staging
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+
+            # create study.json
+            study_json = self._create_study_json(component_title)
+            study_json_path = temp_path / "study.json"
+            study_json_path.write_text(json.dumps(study_json, indent=2))
+
+            # copy experiment files to temp/experiment/
+            experiment_target = temp_path / "experiment"
+            shutil.copytree(experiment_dir, experiment_target)
+
+            # create .jzip file
+            with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+                # add study.json
+                zipf.write(study_json_path, "study.json")
+
+                # add all experiment files
+                for file_path in experiment_target.rglob("*"):
+                    if file_path.is_file():
+                        # archive name relative to temp_path
+                        arcname = file_path.relative_to(temp_path)
+                        zipf.write(file_path, arcname)
+
+    def _create_study_json(self, component_title: str) -> dict[str, JsonValue]:
+        """Create JATOS study.json structure.
+
+        Parameters
+        ----------
+        component_title : str
+            Title for the JATOS component.
+
+        Returns
+        -------
+        dict[str, JsonValue]
+            JATOS study metadata dictionary.
+
+        Notes
+        -----
+        The study.json follows JATOS v3 schema format.
+        """
+        # generate UUIDs for study and component
+        study_uuid = str(uuid.uuid4())
+        component_uuid = str(uuid.uuid4())
+
+        # sanitize title for directory name
+        dir_name = self._sanitize_dirname(self.study_title)
+
+        return {
+            "version": "3",
+            "data": {
+                "uuid": study_uuid,
+                "title": self.study_title,
+                "description": self.study_description,
+                "dirName": dir_name,
+                "comments": f"Generated by bead {datetime.now().isoformat()}",
+                "jsonData": None,
+                "componentList": [
+                    {
+                        "uuid": component_uuid,
+                        "title": component_title,
+                        "htmlFilePath": "experiment/index.html",
+                        "reloadable": True,
+                        "active": True,
+                        "comments": "",
+                        "jsonData": None,
+                    }
+                ],
+                "batchList": [],
+                "groupStudy": False,
+                "linearStudy": False,
+                "allowPreview": True,
+            },
+        }
+
+    def _sanitize_dirname(self, title: str) -> str:
+        """Sanitize study title for use as directory name.
+
+        Parameters
+        ----------
+        title : str
+            Study title to sanitize.
+
+        Returns
+        -------
+        str
+            Sanitized directory name.
+
+        Examples
+        --------
+        >>> exporter = JATOSExporter("My Study")
+        >>> exporter._sanitize_dirname("My Study")
+        'my_study'
+        >>> exporter._sanitize_dirname("Study (2024)")
+        'study_2024'
+        """
+        # convert to lowercase
+        dirname = title.lower()
+
+        # replace spaces with underscores
+        dirname = dirname.replace(" ", "_")
+
+        # remove non-alphanumeric characters (except underscores)
+        dirname = re.sub(r"[^a-z0-9_]", "", dirname)
+
+        # remove consecutive underscores
+        dirname = re.sub(r"_+", "_", dirname)
+
+        # remove leading/trailing underscores
+        dirname = dirname.strip("_")
+
+        # ensure it's not empty
+        if not dirname:
+            dirname = "study"
+
+        return dirname

bead/deployment/jspsych/__init__.py

@@ -0,0 +1,9 @@
+"""jsPsych 8.x deployment components.
+
+Generates jsPsych experiments with batch mode support and server-side list
+distribution via JATOS batch sessions.
+"""
+
+from bead.deployment.jspsych.randomizer import generate_randomizer_function
+
+__all__ = ["generate_randomizer_function"]

bead/deployment/jspsych/biome.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "include": ["src/**/*.ts"],
+    "ignore": ["dist", "node_modules"]
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "noNonNullAssertion": "off",
+        "useNodejsImportProtocol": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "warn"
+      },
+      "complexity": {
+        "useLiteralKeys": "off"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  }
+}

bead/deployment/jspsych/config.py

@@ -0,0 +1,411 @@
+"""Configuration models for jsPsych experiment generation.
+
+This module provides Pydantic models for configuring jsPsych experiment
+generation, including experiment types, UI settings, and display options.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from bead.config.deployment import SlopitIntegrationConfig
+from bead.data.range import Range
+from bead.deployment.distribution import ListDistributionStrategy
+
+# Type alias for experiment types
+type ExperimentType = Literal[
+    "likert_rating",
+    "slider_rating",
+    "binary_choice",
+    "forced_choice",
+]
+
+# Type alias for UI themes
+type UITheme = Literal["light", "dark", "auto"]
+
+
+# Factory functions for default lists
+def _empty_demographics_fields() -> list[DemographicsFieldConfig]:
+    """Return empty demographics field list."""
+    return []
+
+
+def _empty_instruction_pages() -> list[InstructionPage]:
+    """Return empty instruction pages list."""
+    return []
+
+
+class DemographicsFieldConfig(BaseModel):
+    """Configuration for a single demographics form field.
+
+    Used to configure fields in a demographics form that appears before
+    the experiment instructions. Supports various input types including
+    text, number, dropdown, radio buttons, and checkboxes.
+
+    Attributes
+    ----------
+    name : str
+        Field name (used as key in collected data).
+    field_type : Literal["text", "number", "dropdown", "radio", "checkbox"]
+        Type of form input.
+    label : str
+        Display label for the field.
+    required : bool
+        Whether this field is required (default: False).
+    options : list[str] | None
+        Options for dropdown/radio fields (default: None).
+    range : Range[int] | Range[float] | None
+        Numeric range constraint for number fields (default: None).
+    placeholder : str | None
+        Placeholder text for text/number inputs (default: None).
+    help_text : str | None
+        Help text displayed below the field (default: None).
+
+    Examples
+    --------
+    >>> age_field = DemographicsFieldConfig(
+    ...     name="age",
+    ...     field_type="number",
+    ...     label="Your Age",
+    ...     required=True,
+    ...     range=Range[int](min=18, max=100),
+    ... )
+    >>> education_field = DemographicsFieldConfig(
+    ...     name="education",
+    ...     field_type="dropdown",
+    ...     label="Highest Education Level",
+    ...     required=True,
+    ...     options=["High School", "Bachelor's", "Master's", "PhD"],
+    ... )
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+    field_type: Literal["text", "number", "dropdown", "radio", "checkbox"]
+    label: str
+    required: bool = False
+    options: list[str] | None = None
+    range: Range[int] | Range[float] | None = None
+    placeholder: str | None = None
+    help_text: str | None = None
+
+
+class DemographicsConfig(BaseModel):
+    """Configuration for participant demographics form.
+
+    Defines a demographics form that appears before experiment instructions.
+    When enabled, participants must complete this form before proceeding.
+
+    Attributes
+    ----------
+    enabled : bool
+        Whether to show the demographics form (default: False).
+    title : str
+        Title displayed at the top of the form (default: "Participant Information").
+    fields : list[DemographicsFieldConfig]
+        List of fields to include in the form.
+    submit_button_text : str
+        Text for the submit button (default: "Continue").
+
+    Examples
+    --------
+    >>> config = DemographicsConfig(
+    ...     enabled=True,
+    ...     title="About You",
+    ...     fields=[
+    ...         DemographicsFieldConfig(
+    ...             name="age",
+    ...             field_type="number",
+    ...             label="Age",
+    ...             required=True,
+    ...         ),
+    ...     ],
+    ... )
+    >>> config.enabled
+    True
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    title: str = "Participant Information"
+    fields: list[DemographicsFieldConfig] = Field(
+        default_factory=_empty_demographics_fields
+    )
+    submit_button_text: str = "Continue"
+
+
+class InstructionPage(BaseModel):
+    """A single instruction page for multi-page instructions.
+
+    Attributes
+    ----------
+    content : str
+        HTML content for this page.
+    title : str | None
+        Optional title for this page (displayed above content).
+
+    Examples
+    --------
+    >>> page = InstructionPage(
+    ...     title="Welcome",
+    ...     content="<p>Thank you for participating in this study.</p>",
+    ... )
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    content: str
+    title: str | None = None
+
+
+class InstructionsConfig(BaseModel):
+    """Configuration for multi-page experiment instructions.
+
+    Allows creating rich, multi-page instructions with navigation controls.
+    Participants can optionally navigate backwards through pages.
+
+    Attributes
+    ----------
+    pages : list[InstructionPage]
+        List of instruction pages to display.
+    show_page_numbers : bool
+        Whether to show page numbers (default: True).
+    allow_backwards : bool
+        Whether to allow navigating to previous pages (default: True).
+    button_label_next : str
+        Label for the next button (default: "Next").
+    button_label_finish : str
+        Label for the final button (default: "Begin Experiment").
+
+    Examples
+    --------
+    >>> config = InstructionsConfig(
+    ...     pages=[
+    ...         InstructionPage(title="Welcome", content="<p>Welcome!</p>"),
+    ...         InstructionPage(title="Task", content="<p>Your task is...</p>"),
+    ...     ],
+    ...     allow_backwards=True,
+    ... )
+    >>> len(config.pages)
+    2
+
+    >>> # Create from plain text (single page)
+    >>> config = InstructionsConfig.from_text("Please rate each sentence.")
+    >>> len(config.pages)
+    1
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    pages: list[InstructionPage] = Field(default_factory=_empty_instruction_pages)
+    show_page_numbers: bool = True
+    allow_backwards: bool = True
+    button_label_next: str = "Next"
+    button_label_finish: str = "Begin Experiment"
+
+    @classmethod
+    def from_text(cls, text: str) -> InstructionsConfig:
+        """Create single-page instructions from plain text.
+
+        Provides backward compatibility with simple string instructions.
+
+        Parameters
+        ----------
+        text : str
+            Plain text or HTML content for a single instruction page.
+
+        Returns
+        -------
+        InstructionsConfig
+            Instructions config with a single page.
+
+        Examples
+        --------
+        >>> config = InstructionsConfig.from_text("Rate each item from 1-7.")
+        >>> config.pages[0].content
+        'Rate each item from 1-7.'
+        """
+        return cls(pages=[InstructionPage(content=text)])
+
+
+class ExperimentConfig(BaseModel):
+    """Configuration for jsPsych experiment generation.
+
+    Defines all configurable aspects of a jsPsych experiment, including experiment
+    type, UI settings, trial presentation options, and list distribution strategy.
+
+    Attributes
+    ----------
+    experiment_type : ExperimentType
+        Type of experiment (likert_rating, slider_rating, binary_choice, forced_choice)
+    title : str
+        Experiment title displayed to participants
+    description : str
+        Brief description of the experiment
+    instructions : str | InstructionsConfig
+        Instructions shown to participants before the experiment. Can be a simple
+        string (single page) or InstructionsConfig for multi-page instructions.
+    demographics : DemographicsConfig | None
+        Optional demographics form shown before instructions (default: None).
+        When provided and enabled, participants must complete this form first.
+    distribution_strategy : ListDistributionStrategy
+        List distribution strategy for batch mode (required, no default).
+        Specifies how participants are assigned to experiment lists using JATOS
+        batch sessions. See bead.deployment.distribution for available strategies.
+    randomize_trial_order : bool
+        Whether to randomize trial order (default: True)
+    show_progress_bar : bool
+        Whether to show a progress bar during the experiment (default: True)
+    ui_theme : UITheme
+        UI theme for the experiment (light, dark, auto; default: light)
+    on_finish_url : str | None
+        URL to redirect to after experiment completion (default: None)
+        If prolific_completion_code is set, this will be auto-generated
+    allow_backwards : bool
+        Whether participants can go back to previous trials (default: False)
+    show_click_target : bool
+        Whether to show click target for accuracy tracking (default: False)
+    minimum_duration_ms : int
+        Minimum trial duration in milliseconds (default: 0)
+    use_jatos : bool
+        Whether to enable JATOS integration (default: True)
+    prolific_completion_code : str | None
+        Prolific completion code for automatic redirect URL generation (default: None)
+        When set, on_finish_url will be auto-generated as:
+        https://app.prolific.co/submissions/complete?cc=<code>
+    slopit : SlopitIntegrationConfig
+        Slopit behavioral capture integration configuration (default: disabled).
+        When enabled, captures keystroke dynamics, focus patterns, and paste events
+        during experiment trials for AI-assisted response detection.
+
+    Examples
+    --------
+    >>> from bead.deployment.distribution import (
+    ...     ListDistributionStrategy,
+    ...     DistributionStrategyType
+    ... )
+    >>> strategy = ListDistributionStrategy(
+    ...     strategy_type=DistributionStrategyType.BALANCED,
+    ...     max_participants=100
+    ... )
+    >>> config = ExperimentConfig(
+    ...     experiment_type="likert_rating",
+    ...     title="Sentence Acceptability Study",
+    ...     description="Rate the acceptability of sentences",
+    ...     instructions="Please rate each sentence on a scale from 1 to 7.",
+    ...     distribution_strategy=strategy
+    ... )
+    >>> config.randomize_trial_order
+    True
+    >>> config.ui_theme
+    'light'
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+    )
+
+    experiment_type: ExperimentType
+    title: str
+    description: str
+    instructions: str | InstructionsConfig
+    distribution_strategy: ListDistributionStrategy
+    demographics: DemographicsConfig | None = Field(
+        default=None,
+        description="Demographics form shown before instructions",
+    )
+    randomize_trial_order: bool = Field(default=True)
+    show_progress_bar: bool = Field(default=True)
+    ui_theme: UITheme = Field(default="light")
+    on_finish_url: str | None = Field(default=None)
+    allow_backwards: bool = Field(default=False)
+    show_click_target: bool = Field(default=False)
+    minimum_duration_ms: int = Field(default=0, ge=0)
+    use_jatos: bool = Field(default=True)
+    prolific_completion_code: str | None = Field(default=None)
+    slopit: SlopitIntegrationConfig = Field(
+        default_factory=SlopitIntegrationConfig,
+        description="Slopit behavioral capture integration (opt-in, disabled)",
+    )
+
+
+class RatingScaleConfig(BaseModel):
+    """Configuration for rating scale trials.
+
+    Attributes
+    ----------
+    scale
+        Numeric range for the rating scale with min and max values.
+        Default is Range(min=1, max=7) for a standard 7-point Likert scale.
+    min_label
+        Label for the minimum value (default: "Not at all").
+    max_label
+        Label for the maximum value (default: "Very much").
+    step
+        Step size between values (default: 1).
+    show_numeric_labels
+        Whether to show numeric labels on the scale (default: True).
+    required
+        Whether a response is required (default: True).
+
+    Examples
+    --------
+    >>> config = RatingScaleConfig()
+    >>> config.scale.min
+    1
+    >>> config.scale.max
+    7
+    >>> config.scale.contains(4)
+    True
+
+    >>> # Custom 5-point scale
+    >>> config = RatingScaleConfig(scale=Range[int](min=1, max=5))
+    >>> config.scale.max
+    5
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+    )
+
+    scale: Range[int] = Field(
+        default_factory=lambda: Range[int](min=1, max=7),
+        description="Numeric range for the rating scale",
+    )
+    min_label: str = Field(default="Not at all")
+    max_label: str = Field(default="Very much")
+    step: int = Field(default=1, ge=1)
+    show_numeric_labels: bool = Field(default=True)
+    required: bool = Field(default=True)
+
+
+class ChoiceConfig(BaseModel):
+    """Configuration for choice trials.
+
+    Attributes
+    ----------
+    button_html : str | None
+        Custom HTML for choice buttons (default: None)
+    required : bool
+        Whether a response is required (default: True)
+    randomize_choice_order : bool
+        Whether to randomize the order of choices (default: False)
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+    )
+
+    button_html: str | None = Field(default=None)
+    required: bool = Field(default=True)
+    randomize_choice_order: bool = Field(default=False)