bead 0.1.0__py3-none-any.whl

bead/config/item.py

@@ -0,0 +1,45 @@
+"""Item configuration models for the bead package."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from bead.config.model import ModelConfig
+
+
+class ItemConfig(BaseModel):
+    """Configuration for item generation.
+
+    Parameters
+    ----------
+    model : ModelConfig
+        Model configuration.
+    apply_constraints : bool
+        Whether to apply model-based constraints.
+    track_metadata : bool
+        Whether to track item metadata.
+    parallel_processing : bool
+        Whether to use parallel processing.
+    num_workers : int
+        Number of workers for parallel processing.
+
+    Examples
+    --------
+    >>> config = ItemConfig()
+    >>> config.apply_constraints
+    True
+    >>> config.num_workers
+    4
+    """
+
+    model: ModelConfig = Field(
+        default_factory=ModelConfig, description="Model configuration"
+    )
+    apply_constraints: bool = Field(
+        default=True, description="Apply model-based constraints"
+    )
+    track_metadata: bool = Field(default=True, description="Track item metadata")
+    parallel_processing: bool = Field(
+        default=False, description="Use parallel processing"
+    )
+    num_workers: int = Field(default=4, description="Number of workers", gt=0)

bead/config/list.py

@@ -0,0 +1,193 @@
+"""List configuration models for the bead package."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+if TYPE_CHECKING:
+    pass
+
+
+class BatchConstraintConfig(BaseModel):
+    """Configuration for batch-level constraints.
+
+    Batch constraints operate across all lists in a batch to ensure global
+    properties like coverage, balance, and diversity.
+
+    Attributes
+    ----------
+    type : Literal["coverage", "balance", "diversity", "min_occurrence"]
+        Type of batch constraint.
+    property_expression : str
+        Expression to extract property (e.g., "item['template_id']").
+    target_values : list[str | int | float] | None
+        Target values for coverage constraint. Default: None.
+    min_coverage : float
+        Minimum coverage fraction for coverage constraint (0.0-1.0). Default: 1.0.
+    target_distribution : dict[str, float] | None
+        Target distribution for balance constraint (values sum to 1.0). Default: None.
+    tolerance : float
+        Tolerance for balance constraint (0.0-1.0). Default: 0.1.
+    max_lists_per_value : int | None
+        Maximum lists per value for diversity constraint. Default: None.
+    min_occurrences : int | None
+        Minimum occurrences per value for min_occurrence constraint. Default: None.
+    priority : int
+        Constraint priority (higher = more important). Default: 1.
+
+    Examples
+    --------
+    >>> # Coverage constraint
+    >>> config = BatchConstraintConfig(
+    ...     type="coverage",
+    ...     property_expression="item['template_id']",
+    ...     target_values=list(range(26)),
+    ...     min_coverage=1.0
+    ... )
+    >>> # Balance constraint
+    >>> config = BatchConstraintConfig(
+    ...     type="balance",
+    ...     property_expression="item['pair_type']",
+    ...     target_distribution={"same_verb": 0.5, "different_verb": 0.5},
+    ...     tolerance=0.05
+    ... )
+    >>> # Diversity constraint
+    >>> config = BatchConstraintConfig(
+    ...     type="diversity",
+    ...     property_expression="item['verb_lemma']",
+    ...     max_lists_per_value=3
+    ... )
+    >>> # Min occurrence constraint
+    >>> config = BatchConstraintConfig(
+    ...     type="min_occurrence",
+    ...     property_expression="item['quantile']",
+    ...     min_occurrences=50
+    ... )
+    """
+
+    type: Literal["coverage", "balance", "diversity", "min_occurrence"] = Field(
+        ..., description="Type of batch constraint"
+    )
+    property_expression: str = Field(..., description="Expression to extract property")
+    target_values: list[str | int | float] | None = Field(
+        default=None, description="Target values for coverage constraint"
+    )
+    min_coverage: float = Field(
+        default=1.0, ge=0.0, le=1.0, description="Minimum coverage fraction"
+    )
+    target_distribution: dict[str, float] | None = Field(
+        default=None, description="Target distribution for balance constraint"
+    )
+    tolerance: float = Field(
+        default=0.1, ge=0.0, le=1.0, description="Tolerance for balance constraint"
+    )
+    max_lists_per_value: int | None = Field(
+        default=None, ge=1, description="Maximum lists per value for diversity"
+    )
+    min_occurrences: int | None = Field(
+        default=None, ge=1, description="Minimum occurrences for min_occurrence"
+    )
+    priority: int = Field(default=1, ge=1, description="Constraint priority")
+
+    @field_validator("property_expression")
+    @classmethod
+    def validate_property_expression(cls, v: str) -> str:
+        """Validate property expression is non-empty."""
+        if not v or not v.strip():
+            raise ValueError("property_expression must be non-empty")
+        return v.strip()
+
+    @model_validator(mode="after")
+    def validate_constraint_params(self) -> BatchConstraintConfig:
+        """Validate constraint-specific parameters are provided."""
+        if self.type == "coverage":
+            # coverage requires target_values (can be None for auto-detection)
+            pass
+        elif self.type == "balance":
+            if self.target_distribution is None:
+                raise ValueError("target_distribution required for balance constraint")
+        elif self.type == "diversity":
+            if self.max_lists_per_value is None:
+                raise ValueError(
+                    "max_lists_per_value required for diversity constraint"
+                )
+        elif self.type == "min_occurrence":
+            if self.min_occurrences is None:
+                raise ValueError(
+                    "min_occurrences required for min_occurrence constraint"
+                )
+
+        return self
+
+
+class ListConfig(BaseModel):
+    """Configuration for list partitioning.
+
+    Parameters
+    ----------
+    partitioning_strategy : str
+        Strategy name for partitioning.
+    num_lists : int
+        Number of lists to create.
+    items_per_list : int | None
+        Items per list.
+    balance_by : list[str]
+        Fields to balance on.
+    ensure_uniqueness : bool
+        Whether to ensure items are unique across lists.
+    random_seed : int | None
+        Random seed for reproducibility.
+    batch_constraints : list[BatchConstraintConfig] | None
+        Batch-level constraints to apply across all lists.
+
+    Examples
+    --------
+    >>> config = ListConfig()
+    >>> config.partitioning_strategy
+    'balanced'
+    >>> config.num_lists
+    1
+    """
+
+    partitioning_strategy: str = Field(
+        default="balanced", description="Partitioning strategy"
+    )
+    num_lists: int = Field(default=1, description="Number of lists to create", gt=0)
+    items_per_list: int | None = Field(default=None, description="Items per list")
+    balance_by: list[str] = Field(
+        default_factory=list, description="Fields to balance on"
+    )
+    ensure_uniqueness: bool = Field(
+        default=True, description="Ensure items unique across lists"
+    )
+    random_seed: int | None = Field(default=None, description="Random seed")
+    batch_constraints: list[BatchConstraintConfig] | None = Field(
+        default=None, description="Batch-level constraints"
+    )
+
+    @field_validator("items_per_list")
+    @classmethod
+    def validate_items_per_list(cls, v: int | None) -> int | None:
+        """Validate items_per_list is positive.
+
+        Parameters
+        ----------
+        v : int | None
+            Items per list value.
+
+        Returns
+        -------
+        int | None
+            Validated value.
+
+        Raises
+        ------
+        ValueError
+            If value is not positive.
+        """
+        if v is not None and v <= 0:
+            msg = f"items_per_list must be positive, got {v}"
+            raise ValueError(msg)
+        return v

bead/config/loader.py

@@ -0,0 +1,149 @@
+"""Configuration loading from YAML files.
+
+This module provides functionality for loading configurations from YAML files,
+merging configurations from multiple sources, and applying configuration overrides.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from bead.config.config import BeadConfig
+from bead.config.profiles import get_profile
+
+
+def merge_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Deep merge two configuration dictionaries.
+
+    Recursively merges override into base, with override values taking precedence.
+
+    Parameters
+    ----------
+    base : dict[str, Any]
+        Base configuration dictionary.
+    override : dict[str, Any]
+        Override configuration dictionary.
+
+    Returns
+    -------
+    dict[str, Any]
+        Merged configuration dictionary.
+
+    Examples
+    --------
+    >>> base = {"a": 1, "b": {"c": 2}}
+    >>> override = {"b": {"d": 3}}
+    >>> merge_configs(base, override)
+    {'a': 1, 'b': {'c': 2, 'd': 3}}
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = merge_configs(result[key], value)  # type: ignore[arg-type]
+        else:
+            result[key] = value
+    return result
+
+
+def load_yaml_file(path: Path | str) -> dict[str, Any]:
+    """Load YAML file and return as dictionary.
+
+    Parameters
+    ----------
+    path : Path | str
+        Path to YAML file.
+
+    Returns
+    -------
+    dict[str, Any]
+        Parsed YAML content.
+
+    Raises
+    ------
+    FileNotFoundError
+        If file doesn't exist.
+    yaml.YAMLError
+        If YAML is malformed.
+    """
+    path = Path(path) if isinstance(path, str) else path
+
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {path}")
+
+    try:
+        with open(path) as f:
+            content = yaml.safe_load(f)
+            # handle empty files
+            return content if content is not None else {}
+    except yaml.YAMLError as e:
+        raise yaml.YAMLError(f"Failed to parse YAML file {path}: {e}") from e
+
+
+def load_config(
+    config_path: Path | str | None = None,
+    profile: str = "default",
+    **overrides: Any,
+) -> BeadConfig:
+    """Load configuration from YAML file with optional overrides.
+
+    Precedence (lowest to highest):
+    1. Profile defaults
+    2. YAML file values
+    3. Keyword overrides
+
+    Parameters
+    ----------
+    config_path : Path | str | None
+        Path to YAML config file. If None, uses profile defaults.
+    profile : str
+        Profile to use as base (default, dev, prod, test).
+    **overrides : Any
+        Direct overrides for config values.
+
+    Returns
+    -------
+    BeadConfig
+        Loaded and merged configuration.
+
+    Raises
+    ------
+    FileNotFoundError
+        If config_path is specified but doesn't exist.
+    yaml.YAMLError
+        If YAML file is malformed.
+    ValidationError
+        If configuration is invalid.
+
+    Examples
+    --------
+    >>> config = load_config(profile="dev")
+    >>> config.profile
+    'dev'
+    >>> config = load_config(config_path="config.yaml", logging__level="DEBUG")
+    >>> config.logging.level
+    'DEBUG'
+    """
+    # start with profile defaults
+    base_config: dict[str, Any] = get_profile(profile).model_dump()
+
+    # merge with YAML file if provided
+    if config_path is not None:
+        yaml_config = load_yaml_file(config_path)
+        base_config = merge_configs(base_config, yaml_config)
+
+    # convert overrides with __ syntax to nested dicts
+    if overrides:
+        override_dict: dict[str, Any] = {}
+        for key, value in overrides.items():
+            parts = key.split("__")
+            current = override_dict
+            for part in parts[:-1]:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+            current[parts[-1]] = value
+        base_config = merge_configs(base_config, override_dict)
+
+    # construct and validate BeadConfig
+    return BeadConfig(**base_config)

bead/config/logging.py

@@ -0,0 +1,42 @@
+"""Logging configuration models for the bead package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class LoggingConfig(BaseModel):
+    """Configuration for logging.
+
+    Parameters
+    ----------
+    level : str
+        Log level.
+    format : str
+        Log format string.
+    file : Path | None
+        Log file path.
+    console : bool
+        Whether to log to console.
+
+    Examples
+    --------
+    >>> config = LoggingConfig()
+    >>> config.level
+    'INFO'
+    >>> config.console
+    True
+    """
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO", description="Log level"
+    )
+    format: str = Field(
+        default="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        description="Log format",
+    )
+    file: Path | None = Field(default=None, description="Log file path")
+    console: bool = Field(default=True, description="Log to console")

bead/config/model.py

@@ -0,0 +1,49 @@
+"""Model configuration models for the bead package."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ModelConfig(BaseModel):
+    """Configuration for language models.
+
+    Parameters
+    ----------
+    provider : str
+        Model provider name.
+    model_name : str
+        Model identifier.
+    batch_size : int
+        Inference batch size.
+    device : str
+        Device to use for computation.
+    max_length : int
+        Maximum sequence length.
+    temperature : float
+        Sampling temperature.
+    cache_outputs : bool
+        Whether to cache model outputs.
+
+    Examples
+    --------
+    >>> config = ModelConfig()
+    >>> config.provider
+    'huggingface'
+    >>> config.device
+    'cpu'
+    """
+
+    provider: Literal["huggingface", "openai", "anthropic"] = Field(
+        default="huggingface", description="Model provider"
+    )
+    model_name: str = Field(default="gpt2", description="Model identifier")
+    batch_size: int = Field(default=8, description="Inference batch size", gt=0)
+    device: Literal["cpu", "cuda", "mps"] = Field(
+        default="cpu", description="Device to use"
+    )
+    max_length: int = Field(default=512, description="Max sequence length", gt=0)
+    temperature: float = Field(default=1.0, description="Sampling temperature", ge=0)
+    cache_outputs: bool = Field(default=True, description="Cache model outputs")

bead/config/paths.py

@@ -0,0 +1,46 @@
+"""Path configuration models for the bead package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class PathsConfig(BaseModel):
+    """Configuration for file system paths.
+
+    Parameters
+    ----------
+    data_dir : Path
+        Base directory for data files.
+    output_dir : Path
+        Base directory for outputs.
+    cache_dir : Path
+        Cache directory.
+    temp_dir : Path | None
+        Temporary directory. If None, uses system temp.
+    create_dirs : bool
+        Whether to create directories if they don't exist.
+
+    Examples
+    --------
+    >>> config = PathsConfig()
+    >>> config.data_dir
+    PosixPath('data')
+    >>> config = PathsConfig(data_dir=Path("/absolute/path"))
+    >>> config.data_dir
+    PosixPath('/absolute/path')
+    """
+
+    data_dir: Path = Field(
+        default=Path("data"), description="Base directory for data files"
+    )
+    output_dir: Path = Field(
+        default=Path("output"), description="Base directory for outputs"
+    )
+    cache_dir: Path = Field(default=Path(".cache"), description="Cache directory")
+    temp_dir: Path | None = Field(default=None, description="Temporary directory")
+    create_dirs: bool = Field(
+        default=True, description="Create directories if they don't exist"
+    )