bead 0.1.0__py3-none-any.whl

bead/config/config.py

@@ -0,0 +1,192 @@
+"""Main configuration model for the bead package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from bead.config.active_learning import ActiveLearningConfig
+from bead.config.deployment import DeploymentConfig
+from bead.config.item import ItemConfig
+from bead.config.list import ListConfig
+from bead.config.logging import LoggingConfig
+from bead.config.paths import PathsConfig
+from bead.config.resources import ResourceConfig
+from bead.config.template import TemplateConfig
+
+
+class BeadConfig(BaseModel):
+    """Main configuration for the bead package.
+
+    Reflects the actual bead/ module structure:
+    - active_learning: Active learning (models, trainers, loop, selection)
+    - data_collection: Human data collection (JATOS, Prolific)
+    - deployment: Experiment deployment (jsPsych, JATOS)
+    - evaluation: Model evaluation and metrics
+    - items: Item generation and management
+    - lists: List construction and balancing
+    - resources: Linguistic resources (VerbNet, PropBank, UniMorph)
+    - templates: Template management
+
+    Parameters
+    ----------
+    profile : str
+        Configuration profile name.
+    paths : PathsConfig
+        Paths configuration.
+    resources : ResourceConfig
+        Resources configuration.
+    templates : TemplateConfig
+        Templates configuration.
+    items : ItemConfig
+        Items configuration.
+    lists : ListConfig
+        Lists configuration.
+    deployment : DeploymentConfig
+        Deployment configuration.
+    active_learning : ActiveLearningConfig
+        Active learning configuration (models, trainers, loop, selection).
+    logging : LoggingConfig
+        Logging configuration.
+
+    Examples
+    --------
+    >>> config = BeadConfig()
+    >>> config.profile
+    'default'
+    >>> config.paths.data_dir
+    PosixPath('data')
+    >>> config.active_learning.forced_choice_model.model_name
+    'bert-base-uncased'
+    >>> config.active_learning.trainer.trainer_type
+    'huggingface'
+    >>> config.active_learning.loop.max_iterations
+    10
+    """
+
+    profile: str = Field(default="default", description="Configuration profile name")
+    paths: PathsConfig = Field(
+        default_factory=PathsConfig, description="Paths configuration"
+    )
+    resources: ResourceConfig = Field(
+        default_factory=ResourceConfig, description="Resources configuration"
+    )
+    templates: TemplateConfig = Field(
+        default_factory=TemplateConfig, description="Templates configuration"
+    )
+    items: ItemConfig = Field(
+        default_factory=ItemConfig, description="Items configuration"
+    )
+    lists: ListConfig = Field(
+        default_factory=ListConfig, description="Lists configuration"
+    )
+    deployment: DeploymentConfig = Field(
+        default_factory=DeploymentConfig, description="Deployment configuration"
+    )
+    active_learning: ActiveLearningConfig = Field(
+        default_factory=ActiveLearningConfig,
+        description="Active learning configuration",
+    )
+    logging: LoggingConfig = Field(
+        default_factory=LoggingConfig, description="Logging configuration"
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert configuration to dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Configuration as a dictionary.
+
+        Examples
+        --------
+        >>> config = BeadConfig()
+        >>> d = config.to_dict()
+        >>> d["profile"]
+        'default'
+        """
+        return self.model_dump()
+
+    def to_yaml(self) -> str:
+        """Convert configuration to YAML string.
+
+        Returns
+        -------
+        str
+            Configuration as YAML string.
+
+        Examples
+        --------
+        >>> config = BeadConfig()
+        >>> yaml_str = config.to_yaml()
+        >>> 'profile: default' in yaml_str
+        True
+        """
+        from bead.config.serialization import to_yaml  # noqa: PLC0415
+
+        return to_yaml(self, include_defaults=False)
+
+    def validate_paths(self) -> list[str]:
+        """Validate all path fields exist.
+
+        Returns
+        -------
+        list[str]
+            List of validation errors. Empty if all paths are valid.
+
+        Examples
+        --------
+        >>> config = BeadConfig()
+        >>> errors = config.validate_paths()
+        >>> len(errors)
+        0
+        """
+        errors: list[str] = []
+
+        # check paths config
+        if not self.paths.data_dir.exists() and self.paths.data_dir.is_absolute():
+            errors.append(f"data_dir does not exist: {self.paths.data_dir}")
+        if not self.paths.output_dir.exists() and self.paths.output_dir.is_absolute():
+            errors.append(f"output_dir does not exist: {self.paths.output_dir}")
+        if not self.paths.cache_dir.exists() and self.paths.cache_dir.is_absolute():
+            errors.append(f"cache_dir does not exist: {self.paths.cache_dir}")
+        if self.paths.temp_dir is not None and not self.paths.temp_dir.exists():
+            errors.append(f"temp_dir does not exist: {self.paths.temp_dir}")
+
+        # check resource paths
+        if (
+            self.resources.lexicon_path is not None
+            and not self.resources.lexicon_path.exists()
+        ):
+            errors.append(f"lexicon_path does not exist: {self.resources.lexicon_path}")
+        if (
+            self.resources.templates_path is not None
+            and not self.resources.templates_path.exists()
+        ):
+            errors.append(
+                f"templates_path does not exist: {self.resources.templates_path}"
+            )
+        if (
+            self.resources.constraints_path is not None
+            and not self.resources.constraints_path.exists()
+        ):
+            errors.append(
+                f"constraints_path does not exist: {self.resources.constraints_path}"
+            )
+
+        # check training logging dir
+        if (
+            not self.active_learning.trainer.logging_dir.exists()
+            and self.active_learning.trainer.logging_dir.is_absolute()
+        ):
+            log_dir = self.active_learning.trainer.logging_dir
+            errors.append(f"logging_dir does not exist: {log_dir}")
+
+        # check logging file
+        if self.logging.file is not None and not self.logging.file.parent.exists():
+            parent_dir = self.logging.file.parent
+            errors.append(f"logging file parent directory does not exist: {parent_dir}")
+
+        return errors

bead/config/defaults.py

@@ -0,0 +1,118 @@
+"""Default configurations for the bead package.
+
+This module provides default configuration instances and helper functions
+for retrieving default configurations.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from bead.config.active_learning import ActiveLearningConfig
+from bead.config.config import BeadConfig
+from bead.config.deployment import DeploymentConfig
+from bead.config.item import ItemConfig
+from bead.config.list import ListConfig
+from bead.config.logging import LoggingConfig
+from bead.config.paths import PathsConfig
+from bead.config.resources import ResourceConfig
+from bead.config.template import TemplateConfig
+
+DEFAULT_CONFIG = BeadConfig(
+    profile="default",
+    paths=PathsConfig(),
+    resources=ResourceConfig(),
+    templates=TemplateConfig(),
+    items=ItemConfig(),
+    lists=ListConfig(),
+    deployment=DeploymentConfig(),
+    active_learning=ActiveLearningConfig(),
+    logging=LoggingConfig(),
+)
+"""Default configuration instance.
+
+This configuration uses all default values from each config model.
+It's the base configuration used when no config file is provided.
+
+Examples
+--------
+>>> from bead.config.defaults import DEFAULT_CONFIG
+>>> DEFAULT_CONFIG.profile
+'default'
+>>> DEFAULT_CONFIG.paths.data_dir
+PosixPath('data')
+"""
+
+
+def get_default_config() -> BeadConfig:
+    """Get a copy of the default configuration.
+
+    Returns
+    -------
+    BeadConfig
+        A deep copy of the default configuration.
+
+    Examples
+    --------
+    >>> from bead.config.defaults import get_default_config
+    >>> config = get_default_config()
+    >>> config.profile
+    'default'
+    >>> config.templates.batch_size
+    1000
+
+    Notes
+    -----
+    Returns a deep copy to ensure modifications don't affect the original
+    DEFAULT_CONFIG instance.
+    """
+    return DEFAULT_CONFIG.model_copy(deep=True)
+
+
+def get_default_for_model[T: BaseModel](model_type: type[T]) -> T:
+    """Get default instance of any config model.
+
+    Parameters
+    ----------
+    model_type : type[BaseModel]
+        The configuration model type to instantiate.
+
+    Returns
+    -------
+    T
+        Default instance of the specified model type.
+
+    Examples
+    --------
+    >>> from bead.config.defaults import get_default_for_model
+    >>> from bead.config.paths import PathsConfig
+    >>> paths = get_default_for_model(PathsConfig)
+    >>> paths.data_dir
+    PosixPath('data')
+
+    Raises
+    ------
+    TypeError
+        If model_type is not a valid Pydantic model class.
+
+    Notes
+    -----
+    This function provides runtime validation to ensure the input is a valid
+    Pydantic model class, even though the type system constrains it.
+    """
+    # runtime validation for cases where type checking is bypassed
+    try:
+        if not isinstance(model_type, type):  # type: ignore[reportUnnecessaryIsInstance]
+            msg = f"model_type must be a Pydantic BaseModel class, got {model_type}"
+            raise TypeError(msg)
+        if not issubclass(model_type, BaseModel):  # type: ignore[reportUnnecessaryIsInstance]
+            msg = f"model_type must be a Pydantic BaseModel class, got {model_type}"
+            raise TypeError(msg)
+    except TypeError as e:
+        # re-raise TypeError with our custom message
+        if "must be a Pydantic BaseModel class" in str(e):
+            raise
+        msg = f"model_type must be a Pydantic BaseModel class, got {model_type}"
+        raise TypeError(msg) from e
+
+    return model_type()

bead/config/deployment.py

@@ -0,0 +1,217 @@
+"""Deployment configuration models for the bead package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from bead.deployment.distribution import (
+    DistributionStrategyType,
+    ListDistributionStrategy,
+)
+
+
+class SlopitKeystrokeConfig(BaseModel):
+    """Configuration for slopit keystroke capture.
+
+    Attributes
+    ----------
+    enabled
+        Whether to capture keystroke events.
+    capture_key_up
+        Whether to capture keyup events in addition to keydown.
+    include_modifiers
+        Whether to record modifier key states.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(default=True, description="Capture keystroke events")
+    capture_key_up: bool = Field(default=True, description="Capture keyup events")
+    include_modifiers: bool = Field(default=True, description="Record modifier states")
+
+
+class SlopitFocusConfig(BaseModel):
+    """Configuration for slopit focus/blur capture.
+
+    Attributes
+    ----------
+    enabled
+        Whether to capture focus events.
+    use_visibility_api
+        Whether to use the Page Visibility API.
+    use_blur_focus
+        Whether to track blur and focus events.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(default=True, description="Capture focus events")
+    use_visibility_api: bool = Field(
+        default=True, description="Use Page Visibility API"
+    )
+    use_blur_focus: bool = Field(default=True, description="Track blur/focus events")
+
+
+class SlopitPasteConfig(BaseModel):
+    """Configuration for slopit paste event capture.
+
+    Attributes
+    ----------
+    enabled
+        Whether to capture paste events.
+    prevent
+        Whether to block paste actions.
+    capture_preview
+        Whether to capture preview of pasted text.
+    preview_length
+        Number of characters to include in preview.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(default=True, description="Capture paste events")
+    prevent: bool = Field(default=False, description="Block paste actions")
+    capture_preview: bool = Field(default=True, description="Capture text preview")
+    preview_length: int = Field(
+        default=100, ge=0, description="Preview character limit"
+    )
+
+
+class SlopitIntegrationConfig(BaseModel):
+    """Configuration for slopit behavioral capture integration.
+
+    Slopit captures behavioral signals during experiment trials,
+    including keystroke dynamics, focus patterns, and paste events.
+    These signals can be used to detect AI-assisted responses.
+
+    Attributes
+    ----------
+    enabled
+        Whether to enable slopit behavioral capture. Disabled by default.
+    keystroke
+        Keystroke capture configuration.
+    focus
+        Focus/blur capture configuration.
+    paste
+        Paste event capture configuration.
+    target_selectors
+        CSS selectors for capture targets by task type.
+
+    Examples
+    --------
+    >>> config = SlopitIntegrationConfig(enabled=True)
+    >>> config.keystroke.enabled
+    True
+
+    >>> config = SlopitIntegrationConfig(
+    ...     enabled=True,
+    ...     paste=SlopitPasteConfig(prevent=True),
+    ... )
+    >>> config.paste.prevent
+    True
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable slopit behavioral capture (opt-in)",
+    )
+    keystroke: SlopitKeystrokeConfig = Field(
+        default_factory=SlopitKeystrokeConfig,
+        description="Keystroke capture settings",
+    )
+    focus: SlopitFocusConfig = Field(
+        default_factory=SlopitFocusConfig,
+        description="Focus/blur capture settings",
+    )
+    paste: SlopitPasteConfig = Field(
+        default_factory=SlopitPasteConfig,
+        description="Paste event capture settings",
+    )
+    target_selectors: dict[str, str] = Field(
+        default_factory=lambda: {
+            "likert_rating": ".bead-rating-button",
+            "slider_rating": ".bead-slider",
+            "forced_choice": ".bead-choice-button",
+            "cloze": ".bead-cloze-field",
+        },
+        description="CSS selectors for capture targets by task type",
+    )
+
+    @model_validator(mode="after")
+    def validate_slopit_bundle_exists(self) -> SlopitIntegrationConfig:
+        """Validate that slopit bundle exists when enabled.
+
+        Raises
+        ------
+        ValueError
+            If slopit is enabled but the compiled bundle is not found.
+        """
+        if self.enabled:
+            bundle_path = (
+                Path(__file__).parent.parent
+                / "deployment"
+                / "jspsych"
+                / "dist"
+                / "slopit-bundle.js"
+            )
+            if not bundle_path.exists():
+                msg = (
+                    f"Slopit bundle not found at {bundle_path}. "
+                    "Run 'pnpm build' in bead/deployment/jspsych to compile TypeScript."
+                )
+                raise ValueError(msg)
+        return self
+
+
+class DeploymentConfig(BaseModel):
+    """Configuration for experiment deployment.
+
+    Parameters
+    ----------
+    platform : str
+        Deployment platform.
+    jspsych_version : str
+        jsPsych version to use.
+    apply_material_design : bool
+        Whether to use Material Design.
+    include_demographics : bool
+        Whether to include demographics survey.
+    include_attention_checks : bool
+        Whether to include attention checks.
+    jatos_export : bool
+        Whether to export to JATOS.
+    distribution_strategy : ListDistributionStrategy
+        List distribution strategy for batch experiments.
+        Defaults to balanced assignment.
+
+    Examples
+    --------
+    >>> config = DeploymentConfig()
+    >>> config.platform
+    'jspsych'
+    >>> config.jspsych_version
+    '7.3.0'
+    >>> config.distribution_strategy.strategy_type
+    <DistributionStrategyType.BALANCED: 'balanced'>
+    """
+
+    platform: str = Field(default="jspsych", description="Deployment platform")
+    jspsych_version: str = Field(default="7.3.0", description="jsPsych version")
+    apply_material_design: bool = Field(default=True, description="Use Material Design")
+    include_demographics: bool = Field(
+        default=True, description="Include demographics survey"
+    )
+    include_attention_checks: bool = Field(
+        default=True, description="Include attention checks"
+    )
+    jatos_export: bool = Field(default=False, description="Export to JATOS")
+    distribution_strategy: ListDistributionStrategy = Field(
+        default_factory=lambda: ListDistributionStrategy(
+            strategy_type=DistributionStrategyType.BALANCED
+        ),
+        description="List distribution strategy for batch experiments",
+    )

bead/config/env.py

@@ -0,0 +1,147 @@
+"""Environment variable support for configuration.
+
+This module provides functionality for loading configuration values from
+environment variables, with support for nested configuration paths and
+automatic type parsing.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+
+def parse_env_value(value: str) -> Any:
+    """Parse environment variable value to appropriate Python type.
+
+    Handles: bool, int, float, Path, list (comma-separated), string
+
+    Parameters
+    ----------
+    value : str
+        Raw environment variable value.
+
+    Returns
+    -------
+    Any
+        Parsed value with appropriate type.
+
+    Examples
+    --------
+    >>> parse_env_value("true")
+    True
+    >>> parse_env_value("42")
+    42
+    >>> parse_env_value("/path/to/file")
+    PosixPath('/path/to/file')
+    >>> parse_env_value("a,b,c")
+    ['a', 'b', 'c']
+    """
+    # handle boolean values
+    if value.lower() in ("true", "1", "yes", "on"):
+        return True
+    if value.lower() in ("false", "0", "no", "off"):
+        return False
+
+    # handle numeric values; try int first
+    try:
+        return int(value)
+    except ValueError:
+        pass
+
+    # try float
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    # handle path-like strings
+    if value.startswith(("/", "./", "~/", "../")):
+        return Path(value).expanduser()
+
+    # handle comma-separated lists
+    if "," in value:
+        return [item.strip() for item in value.split(",")]
+
+    # default to string
+    return value
+
+
+def env_to_nested_dict(env_vars: dict[str, str], prefix: str) -> dict[str, Any]:
+    """Convert flat environment variables to nested dictionary.
+
+    Parameters
+    ----------
+    env_vars : dict[str, str]
+        Environment variables to convert.
+    prefix : str
+        Prefix to strip from variable names.
+
+    Returns
+    -------
+    dict[str, Any]
+        Nested configuration dictionary.
+
+    Examples
+    --------
+    >>> env_vars = {"BEAD_LOGGING__LEVEL": "DEBUG"}
+    >>> env_to_nested_dict(env_vars, "BEAD_")
+    {'logging': {'level': 'DEBUG'}}
+    """
+    result: dict[str, Any] = {}
+
+    for key, value in env_vars.items():
+        if not key.startswith(prefix):
+            continue
+
+        # remove prefix
+        key_without_prefix = key[len(prefix) :]
+
+        # split on double underscore for nesting
+        parts = key_without_prefix.split("__")
+
+        # convert to lowercase for config keys
+        parts = [part.lower() for part in parts]
+
+        # parse the value
+        parsed_value = parse_env_value(value)
+
+        # navigate/create nested structure
+        current = result
+        for part in parts[:-1]:
+            if part not in current:
+                current[part] = {}
+            current = current[part]
+
+        # set the final value
+        current[parts[-1]] = parsed_value
+
+    return result
+
+
+def load_from_env(prefix: str = "BEAD_") -> dict[str, Any]:
+    """Load configuration values from environment variables.
+
+    Converts environment variables with the given prefix to a nested
+    configuration dictionary.
+
+    Parameters
+    ----------
+    prefix : str
+        Environment variable prefix to filter on.
+
+    Returns
+    -------
+    dict[str, Any]
+        Nested configuration dictionary from environment.
+
+    Examples
+    --------
+    >>> # With env var: BEAD_LOGGING__LEVEL=DEBUG
+    >>> load_from_env()
+    {'logging': {'level': 'DEBUG'}}
+    """
+    # get all environment variables with the prefix
+    env_vars = {k: v for k, v in os.environ.items() if k.startswith(prefix)}
+
+    # convert to nested dict
+    return env_to_nested_dict(env_vars, prefix)