bead 0.1.0__py3-none-any.whl

bead/config/profiles.py

@@ -0,0 +1,320 @@
+"""Configuration profiles for the bead package.
+
+This module provides pre-configured profiles for different environments
+(development, production, testing) with optimized settings for each use case.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from tempfile import gettempdir
+
+from bead.config.active_learning import (
+    ActiveLearningConfig,
+    ForcedChoiceModelConfig,
+    TrainerConfig,
+)
+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.model import ModelConfig
+from bead.config.paths import PathsConfig
+from bead.config.resources import ResourceConfig
+from bead.config.template import TemplateConfig
+
+# development profile: verbose logging, small batches, relative paths
+DEV_CONFIG = BeadConfig(
+    profile="dev",
+    paths=PathsConfig(
+        data_dir=Path("data"),
+        output_dir=Path("output"),
+        cache_dir=Path(".cache"),
+        temp_dir=Path(gettempdir()) / "bead_dev",
+        create_dirs=True,
+    ),
+    resources=ResourceConfig(
+        cache_external=False,  # disable caching for development
+    ),
+    templates=TemplateConfig(
+        filling_strategy="exhaustive",
+        batch_size=100,  # small batch size for quick iteration
+        stream_mode=False,
+    ),
+    items=ItemConfig(
+        model=ModelConfig(
+            provider="huggingface",
+            model_name="gpt2",
+            batch_size=4,  # small batch for development
+            device="cpu",
+        ),
+        parallel_processing=False,  # simpler debugging without parallelism
+    ),
+    lists=ListConfig(
+        num_lists=1,
+    ),
+    deployment=DeploymentConfig(),
+    active_learning=ActiveLearningConfig(
+        forced_choice_model=ForcedChoiceModelConfig(
+            num_epochs=1,  # quick training for testing
+            batch_size=8,
+            learning_rate=2e-5,
+        ),
+        trainer=TrainerConfig(epochs=1),
+    ),
+    logging=LoggingConfig(
+        level="DEBUG",  # verbose logging for development
+        console=True,
+    ),
+)
+"""Development configuration profile.
+
+Optimized for:
+- Quick iteration and debugging
+- Verbose logging (DEBUG level)
+- Small batch sizes for fast feedback
+- No caching for fresh data
+- Simple single-threaded processing
+- Temporary directories for easy cleanup
+
+Examples
+--------
+>>> from bead.config.profiles import DEV_CONFIG
+>>> DEV_CONFIG.logging.level
+'DEBUG'
+>>> DEV_CONFIG.templates.batch_size
+100
+"""
+
+# production profile: optimized settings, large batches, absolute paths
+PROD_CONFIG = BeadConfig(
+    profile="prod",
+    paths=PathsConfig(
+        data_dir=Path("/var/bead/data").absolute(),
+        output_dir=Path("/var/bead/output").absolute(),
+        cache_dir=Path("/var/bead/cache").absolute(),
+        temp_dir=Path("/var/bead/temp").absolute(),
+        create_dirs=True,
+    ),
+    resources=ResourceConfig(
+        cache_external=True,  # enable caching for performance
+    ),
+    templates=TemplateConfig(
+        filling_strategy="exhaustive",
+        batch_size=10000,  # large batches for efficiency
+        stream_mode=True,  # handle large templates efficiently
+    ),
+    items=ItemConfig(
+        model=ModelConfig(
+            provider="huggingface",
+            model_name="gpt2",
+            batch_size=32,  # large batch for production
+            device="cuda",  # use GPU if available
+        ),
+        parallel_processing=True,  # enable parallelism
+        num_workers=8,  # multiple workers
+    ),
+    lists=ListConfig(
+        num_lists=1,
+    ),
+    deployment=DeploymentConfig(
+        apply_material_design=True,
+        include_demographics=True,
+        include_attention_checks=True,
+    ),
+    active_learning=ActiveLearningConfig(
+        forced_choice_model=ForcedChoiceModelConfig(
+            num_epochs=10,  # full training
+            batch_size=32,
+            learning_rate=2e-5,
+        ),
+        trainer=TrainerConfig(epochs=10, use_wandb=True),
+    ),
+    logging=LoggingConfig(
+        level="WARNING",  # minimal logging for production
+        console=False,  # log to file only
+        file=Path("/var/log/bead/app.log"),
+    ),
+)
+"""Production configuration profile.
+
+Optimized for:
+- Maximum performance and throughput
+- Large batch sizes for efficiency
+- GPU acceleration (when available)
+- Parallel processing
+- External caching enabled
+- Minimal logging (WARNING level)
+- Absolute paths to production directories
+- Metrics tracking with W&B
+
+Examples
+--------
+>>> from bead.config.profiles import PROD_CONFIG
+>>> PROD_CONFIG.logging.level
+'WARNING'
+>>> PROD_CONFIG.templates.batch_size
+10000
+>>> PROD_CONFIG.items.parallel_processing
+True
+"""
+
+# test profile: minimal logging, tiny batches, temp directories
+TEST_CONFIG = BeadConfig(
+    profile="test",
+    paths=PathsConfig(
+        data_dir=Path(gettempdir()) / "bead_test" / "data",
+        output_dir=Path(gettempdir()) / "bead_test" / "output",
+        cache_dir=Path(gettempdir()) / "bead_test" / "cache",
+        temp_dir=Path(gettempdir()) / "bead_test" / "temp",
+        create_dirs=True,
+    ),
+    resources=ResourceConfig(
+        cache_external=False,  # no caching for tests
+    ),
+    templates=TemplateConfig(
+        filling_strategy="exhaustive",
+        batch_size=10,  # tiny batches for fast tests
+        max_combinations=100,  # limit for tests
+        random_seed=42,  # reproducible tests
+    ),
+    items=ItemConfig(
+        model=ModelConfig(
+            provider="huggingface",
+            model_name="gpt2",
+            batch_size=1,  # minimal batch for tests
+            device="cpu",  # CPU only for tests
+        ),
+        parallel_processing=False,  # simpler test execution
+        num_workers=1,
+    ),
+    lists=ListConfig(
+        num_lists=1,
+        random_seed=42,  # reproducible tests
+    ),
+    deployment=DeploymentConfig(
+        apply_material_design=False,  # minimal for tests
+        include_demographics=False,
+        include_attention_checks=False,
+    ),
+    active_learning=ActiveLearningConfig(
+        forced_choice_model=ForcedChoiceModelConfig(
+            num_epochs=1,  # minimal training
+            batch_size=2,
+            learning_rate=2e-5,
+        ),
+        trainer=TrainerConfig(epochs=1, use_wandb=False),
+    ),
+    logging=LoggingConfig(
+        level="CRITICAL",  # minimal logging for tests
+        console=False,  # quiet tests
+    ),
+)
+"""Test configuration profile.
+
+Optimized for:
+- Fast test execution
+- Reproducibility (fixed random seeds)
+- Minimal resource usage
+- Tiny batch sizes
+- Temporary directories for isolation
+- Minimal logging (CRITICAL level)
+- No external dependencies
+- CPU-only execution
+
+Examples
+--------
+>>> from bead.config.profiles import TEST_CONFIG
+>>> TEST_CONFIG.logging.level
+'CRITICAL'
+>>> TEST_CONFIG.templates.batch_size
+10
+>>> TEST_CONFIG.templates.random_seed
+42
+"""
+
+# profile registry
+PROFILES: dict[str, BeadConfig] = {
+    "default": BeadConfig(),  # default from models
+    "dev": DEV_CONFIG,
+    "prod": PROD_CONFIG,
+    "test": TEST_CONFIG,
+}
+"""Registry of all available configuration profiles.
+
+Maps profile names to their corresponding BeadConfig instances.
+
+Examples
+--------
+>>> from bead.config.profiles import PROFILES
+>>> list(PROFILES.keys())
+['default', 'dev', 'prod', 'test']
+>>> PROFILES["dev"].logging.level
+'DEBUG'
+"""
+
+
+def get_profile(name: str) -> BeadConfig:
+    """Get configuration profile by name.
+
+    Parameters
+    ----------
+    name : str
+        Profile name. Must be one of: 'default', 'dev', 'prod', 'test'.
+
+    Returns
+    -------
+    BeadConfig
+        Configuration for the specified profile.
+
+    Raises
+    ------
+    ValueError
+        If profile name is not found in the registry.
+
+    Examples
+    --------
+    >>> from bead.config.profiles import get_profile
+    >>> config = get_profile("dev")
+    >>> config.profile
+    'dev'
+    >>> config.logging.level
+    'DEBUG'
+
+    >>> try:
+    ...     get_profile("invalid")
+    ... except ValueError as e:
+    ...     print(str(e))
+    Profile 'invalid' not found. Available profiles: default, dev, prod, test
+    """
+    if name not in PROFILES:
+        available = ", ".join(sorted(PROFILES.keys()))
+        msg = f"Profile {name!r} not found. Available profiles: {available}"
+        raise ValueError(msg)
+
+    return PROFILES[name].model_copy(deep=True)
+
+
+def list_profiles() -> list[str]:
+    """Return list of available profile names.
+
+    Returns
+    -------
+    list[str]
+        List of available profile names, sorted alphabetically.
+
+    Examples
+    --------
+    >>> from bead.config.profiles import list_profiles
+    >>> profiles = list_profiles()
+    >>> "default" in profiles
+    True
+    >>> "dev" in profiles
+    True
+    >>> "prod" in profiles
+    True
+    >>> "test" in profiles
+    True
+    """
+    return sorted(PROFILES.keys())

bead/config/resources.py

@@ -0,0 +1,47 @@
+"""Resource configuration models for the bead package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class ResourceConfig(BaseModel):
+    """Configuration for external resources.
+
+    Parameters
+    ----------
+    lexicon_path : Path | None
+        Path to lexicon file.
+    templates_path : Path | None
+        Path to templates file.
+    constraints_path : Path | None
+        Path to constraints file.
+    external_adapters : list[str]
+        List of external adapters to enable.
+    cache_external : bool
+        Whether to cache external resource lookups.
+
+    Examples
+    --------
+    >>> config = ResourceConfig()
+    >>> config.cache_external
+    True
+    >>> config.external_adapters
+    []
+    """
+
+    lexicon_path: Path | None = Field(default=None, description="Path to lexicon file")
+    templates_path: Path | None = Field(
+        default=None, description="Path to templates file"
+    )
+    constraints_path: Path | None = Field(
+        default=None, description="Path to constraints file"
+    )
+    external_adapters: list[str] = Field(
+        default_factory=list, description="External adapters to enable"
+    )
+    cache_external: bool = Field(
+        default=True, description="Cache external resource lookups"
+    )

bead/config/serialization.py

@@ -0,0 +1,210 @@
+"""Configuration serialization to YAML format.
+
+This module provides functionality for serializing BeadConfig objects to YAML format,
+including conversion to dictionaries and saving to files.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from bead.config.config import BeadConfig
+from bead.config.defaults import get_default_config
+
+
+def config_to_dict(
+    config: BeadConfig, include_defaults: bool = False
+) -> dict[str, Any]:
+    """Convert BeadConfig to dictionary for YAML serialization.
+
+    Parameters
+    ----------
+    config : BeadConfig
+        Configuration to convert.
+    include_defaults : bool
+        Whether to include default values.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary representation suitable for YAML.
+
+    Examples
+    --------
+    >>> from bead.config import get_default_config
+    >>> config = get_default_config()
+    >>> config_dict = config_to_dict(config)
+    >>> 'profile' in config_dict
+    True
+    """
+    # get dictionary with all values, excluding unset fields
+    config_dict: dict[str, Any] = config.model_dump(
+        mode="json", exclude_unset=not include_defaults
+    )
+
+    if not include_defaults:
+        # get default config to compare against
+        default_config = get_default_config()
+        default_dict: dict[str, Any] = default_config.model_dump(mode="json")
+        # remove values that match defaults
+        config_dict = _remove_defaults(config_dict, default_dict)  # type: ignore[arg-type]
+
+    # convert Path objects to strings
+    config_dict = _convert_paths_to_strings(config_dict)  # type: ignore[arg-type]
+
+    return config_dict
+
+
+def _remove_defaults(
+    config_dict: dict[str, Any], default_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Remove values that match defaults from config dictionary.
+
+    Parameters
+    ----------
+    config_dict : dict[str, Any]
+        Configuration dictionary.
+    default_dict : dict[str, Any]
+        Default configuration dictionary.
+
+    Returns
+    -------
+    dict[str, Any]
+        Configuration dictionary with defaults removed.
+    """
+    result: dict[str, Any] = {}
+    for key, value in config_dict.items():
+        if key not in default_dict:
+            # keep values not in defaults
+            result[key] = value
+        elif isinstance(value, dict) and isinstance(default_dict[key], dict):
+            # recursively remove defaults from nested dicts
+            nested_result = _remove_defaults(value, default_dict[key])  # type: ignore[arg-type]
+            if nested_result:  # only include if not empty after removing defaults
+                result[key] = nested_result
+        elif value != default_dict[key]:
+            # keep values that differ from defaults
+            result[key] = value
+    return result
+
+
+def _convert_paths_to_strings(data: dict[str, Any]) -> dict[str, Any]:
+    """Convert Path objects to strings in dictionary.
+
+    Parameters
+    ----------
+    data : dict[str, Any]
+        Dictionary potentially containing Path objects.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary with Path objects converted to strings.
+    """
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        if isinstance(value, dict):
+            result[key] = _convert_paths_to_strings(value)  # type: ignore[arg-type]
+        elif isinstance(value, Path):
+            result[key] = str(value)
+        elif isinstance(value, list):
+            converted_list: list[Any] = [
+                str(item) if isinstance(item, Path) else item
+                for item in value  # type: ignore[misc]
+            ]
+            result[key] = converted_list
+        else:
+            result[key] = value
+    return result
+
+
+def to_yaml(config: BeadConfig, include_defaults: bool = False) -> str:
+    """Serialize configuration to YAML string.
+
+    Parameters
+    ----------
+    config : BeadConfig
+        Configuration to serialize.
+    include_defaults : bool
+        If True, include all fields even if they have default values.
+        If False, only include non-default values.
+
+    Returns
+    -------
+    str
+        YAML representation of configuration.
+
+    Examples
+    --------
+    >>> from bead.config import get_default_config
+    >>> config = get_default_config()
+    >>> yaml_str = to_yaml(config)
+    >>> 'profile: default' in yaml_str
+    True
+    """
+    config_dict = config_to_dict(config, include_defaults=include_defaults)
+
+    # configure YAML dumper for clean output
+    return yaml.dump(
+        config_dict,
+        default_flow_style=False,
+        sort_keys=True,
+        allow_unicode=True,
+        indent=2,
+    )
+
+
+def save_yaml(
+    config: BeadConfig,
+    path: Path | str,
+    include_defaults: bool = False,
+    create_dirs: bool = True,
+) -> None:
+    """Save configuration to YAML file.
+
+    Parameters
+    ----------
+    config : BeadConfig
+        Configuration to save.
+    path : Path | str
+        Path where YAML file should be saved.
+    include_defaults : bool
+        If True, include all fields even if they have default values.
+    create_dirs : bool
+        If True, create parent directories if they don't exist.
+
+    Raises
+    ------
+    IOError
+        If file cannot be written.
+    FileNotFoundError
+        If create_dirs is False and parent directory doesn't exist.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> from bead.config import get_default_config
+    >>> config = get_default_config()
+    >>> save_yaml(config, Path("config.yaml"))
+    """
+    path = Path(path) if isinstance(path, str) else path
+
+    # ensure parent directory exists
+    if create_dirs:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    elif not path.parent.exists():
+        raise FileNotFoundError(
+            f"Parent directory does not exist: {path.parent}. "
+            f"Set create_dirs=True to create it automatically."
+        )
+
+    # get YAML string
+    yaml_str = to_yaml(config, include_defaults=include_defaults)
+
+    # write to file
+    try:
+        with open(path, "w") as f:
+            f.write(yaml_str)
+    except OSError as e:
+        raise OSError(f"Failed to write YAML file {path}: {e}") from e