bead 0.1.0__py3-none-any.whl

bead/resources/constraint_builders.py

@@ -0,0 +1,329 @@
+"""Abstract base classes for programmatic constraint generation.
+
+This module provides language-agnostic base classes for building constraints
+programmatically. Language-specific implementations should extend these bases.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from bead.resources.constraints import Constraint, ContextValue
+
+
+class ConstraintBuilder(ABC):
+    """Abstract base class for programmatic constraint generation.
+
+    Constraint builders encapsulate logic for generating DSL constraints
+    based on configuration and rules. Subclasses implement specific
+    constraint generation strategies.
+
+    Examples
+    --------
+    >>> class NumberAgreementBuilder(ConstraintBuilder):
+    ...     def build(self, *slot_names: str) -> Constraint:
+    ...         # Generate number agreement constraint
+    ...         pairs = []
+    ...         for i, slot1 in enumerate(slot_names):
+    ...             for slot2 in slot_names[i+1:]:
+    ...                 pairs.append(f"{slot1}.number == {slot2}.number")
+    ...         return Constraint(
+    ...             expression=" and ".join(pairs),
+    ...             description=f"Number agreement: {', '.join(slot_names)}"
+    ...         )
+    """
+
+    @abstractmethod
+    def build(self, *args: Any, **kwargs: Any) -> Constraint:
+        """Build a Constraint object.
+
+        Parameters
+        ----------
+        *args : Any
+            Positional arguments (slot names, properties, etc.).
+        **kwargs : Any
+            Keyword arguments (configuration options).
+
+        Returns
+        -------
+        Constraint
+            Generated constraint.
+        """
+        ...
+
+
+class AgreementConstraintBuilder(ConstraintBuilder):
+    """Builder for feature agreement constraints.
+
+    Generates constraints that enforce feature agreement across slots
+    (e.g., number, gender, case). Supports exact matching or equivalence
+    classes via agreement rules.
+
+    Parameters
+    ----------
+    feature_name : str
+        Name of the feature to enforce agreement on (e.g., "number", "gender").
+    agreement_rules : dict[str, list[str]] | None
+        Optional equivalence classes. Maps canonical value to list of
+        equivalent values. For example:
+        {"singular": ["singular", "sing", "sg"], "plural": ["plural", "pl"]}
+
+    Examples
+    --------
+    Exact number agreement:
+    >>> builder = AgreementConstraintBuilder("number")
+    >>> constraint = builder.build("subject", "verb")
+    >>> expr = "subject.features.get('number') == verb.features.get('number')"
+    >>> expr in constraint.expression
+    True
+
+    Agreement with equivalence rules:
+    >>> rules = {"singular": ["sing", "sg"], "plural": ["pl"]}
+    >>> builder = AgreementConstraintBuilder("number", agreement_rules=rules)
+    >>> constraint = builder.build("det", "noun")
+    >>> "equiv_" in constraint.expression  # Uses equivalence class checks
+    True
+    """
+
+    def __init__(
+        self,
+        feature_name: str,
+        *,
+        agreement_rules: dict[str, list[str]] | None = None,
+    ) -> None:
+        self.feature_name = feature_name
+        self.agreement_rules = agreement_rules
+
+    def build(self, *slot_names: str) -> Constraint:
+        """Build agreement constraint for given slots.
+
+        Parameters
+        ----------
+        *slot_names : str
+            Names of slots to enforce agreement between (≥2 required).
+
+        Returns
+        -------
+        Constraint
+            Agreement constraint.
+
+        Raises
+        ------
+        ValueError
+            If fewer than 2 slot names provided.
+        """
+        if len(slot_names) < 2:
+            raise ValueError("Agreement requires at least 2 slot names")
+
+        if self.agreement_rules:
+            return self._build_with_rules(slot_names)
+        else:
+            return self._build_exact_match(slot_names)
+
+    def _build_exact_match(self, slot_names: tuple[str, ...]) -> Constraint:
+        """Build exact match agreement constraint."""
+        # create pairwise equality checks
+        pairs: list[str] = []
+        for i, slot1 in enumerate(slot_names):
+            for slot2 in slot_names[i + 1 :]:
+                left = f"{slot1}.features.get('{self.feature_name}')"
+                right = f"{slot2}.features.get('{self.feature_name}')"
+                expr = f"{left} == {right}"
+                pairs.append(expr)
+
+        expression: str = " and ".join(pairs)
+        slot_list = ", ".join(slot_names)
+        description = f"{self.feature_name.capitalize()} agreement: {slot_list}"
+
+        return Constraint(expression=expression, description=description)
+
+    def _build_with_rules(self, slot_names: tuple[str, ...]) -> Constraint:
+        """Build agreement constraint with equivalence classes."""
+        # build context with equivalence class sets
+        context: dict[str, Any] = {}
+        for canonical, variants in self.agreement_rules.items():  # type: ignore
+            equiv_set = set(variants)
+            context[f"equiv_{canonical}"] = equiv_set
+
+        # build expression: check if all slots' values are in same equivalence class
+        equiv_checks: list[str] = []
+        for canonical in self.agreement_rules.keys():  # type: ignore
+            # all slots must have values in this equivalence class
+            slot_checks: list[str] = [
+                f"{slot}.features.get('{self.feature_name}') in equiv_{canonical}"
+                for slot in slot_names
+            ]
+            equiv_checks.append(f"({' and '.join(slot_checks)})")
+
+        expression: str = " or ".join(equiv_checks)
+        slot_list = ", ".join(slot_names)
+        feat_name = self.feature_name.capitalize()
+        description = f"{feat_name} agreement with rules: {slot_list}"
+
+        return Constraint(
+            expression=expression, context=context, description=description
+        )
+
+
+class ConditionalConstraintBuilder(ConstraintBuilder):
+    """Builder for IF-THEN (conditional) constraints.
+
+    Generates constraints that enforce requirements when conditions are met.
+    Implements logical implication: IF condition THEN requirement.
+
+    Examples
+    --------
+    >>> builder = ConditionalConstraintBuilder()
+    >>> constraint = builder.build(
+    ...     condition="det.lemma == 'a'",
+    ...     requirement="noun.features.get('number') == 'singular'",
+    ...     description="'a' requires singular noun"
+    ... )
+    >>> "not (" in constraint.expression  # IF-THEN encoded as: not cond or req
+    True
+    """
+
+    def build(
+        self,
+        *,
+        condition: str,
+        requirement: str,
+        description: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> Constraint:
+        """Build conditional constraint.
+
+        Parameters
+        ----------
+        condition : str
+            Condition expression (IF part).
+        requirement : str
+            Requirement expression (THEN part).
+        description : str | None
+            Human-readable description.
+        context : dict[str, Any] | None
+            Context variables for evaluation.
+
+        Returns
+        -------
+        Constraint
+            Conditional constraint.
+
+        Notes
+        -----
+        Logical implication (IF A THEN B) is encoded as: (NOT A) OR B
+        """
+        # encode IF-THEN as: (NOT condition) OR requirement
+        expression = f"not ({condition}) or ({requirement})"
+
+        return Constraint(
+            expression=expression,
+            context=context or {},
+            description=description,
+        )
+
+
+class SetMembershipConstraintBuilder(ConstraintBuilder):
+    """Builder for whitelist/blacklist constraints.
+
+    Generates constraints that restrict slot properties to allowed values
+    (whitelist) or exclude forbidden values (blacklist).
+
+    Parameters
+    ----------
+    slot_name : str
+        Name of slot to constrain.
+    property_path : str
+        Dot-separated path to property (e.g., "lemma", "features.number").
+    allowed_values : set | None
+        Whitelist of allowed values (mutually exclusive with forbidden_values).
+    forbidden_values : set | None
+        Blacklist of forbidden values.
+    description : str | None
+        Custom description.
+
+    Examples
+    --------
+    Whitelist constraint:
+    >>> builder = SetMembershipConstraintBuilder()
+    >>> constraint = builder.build(
+    ...     slot_name="verb",
+    ...     property_path="lemma",
+    ...     allowed_values={"walk", "run", "jump"},
+    ...     description="Motion verbs only"
+    ... )
+    >>> "verb.lemma in allowed_values" in constraint.expression
+    True
+
+    Blacklist constraint:
+    >>> constraint = builder.build(
+    ...     slot_name="verb",
+    ...     property_path="lemma",
+    ...     forbidden_values={"be", "have"},
+    ...     description="Exclude copula and auxiliary"
+    ... )
+    >>> "verb.lemma not in forbidden_values" in constraint.expression
+    True
+    """
+
+    def build(
+        self,
+        *,
+        slot_name: str,
+        property_path: str,
+        allowed_values: set[str] | None = None,
+        forbidden_values: set[str] | None = None,
+        description: str | None = None,
+    ) -> Constraint:
+        """Build set membership constraint.
+
+        Parameters
+        ----------
+        slot_name : str
+            Slot to constrain.
+        property_path : str
+            Property path within slot.
+        allowed_values : set | None
+            Whitelist of allowed values.
+        forbidden_values : set | None
+            Blacklist of forbidden values.
+        description : str | None
+            Constraint description.
+
+        Returns
+        -------
+        Constraint
+            Set membership constraint.
+
+        Raises
+        ------
+        ValueError
+            If neither or both of allowed_values/forbidden_values provided.
+        """
+        # exactly one of allowed_values or forbidden_values must be provided
+        if (allowed_values is None) == (forbidden_values is None):
+            raise ValueError(
+                "Exactly one of 'allowed_values' or 'forbidden_values' must be provided"
+            )
+
+        expression: str
+        context: dict[str, ContextValue]
+
+        if allowed_values is not None:
+            expression = f"{slot_name}.{property_path} in allowed_values"
+            context = {"allowed_values": allowed_values}
+            if description is None:
+                prop_path = f"{slot_name}.{property_path}"
+                description = f"Restrict {prop_path} to allowed values"
+        else:
+            assert forbidden_values is not None
+            expression = f"{slot_name}.{property_path} not in forbidden_values"
+            context = {"forbidden_values": forbidden_values}
+            if description is None:
+                prop_path = f"{slot_name}.{property_path}"
+                description = f"Exclude {prop_path} from forbidden values"
+
+        return Constraint(
+            expression=expression, context=context, description=description
+        )

bead/resources/constraints.py

@@ -0,0 +1,165 @@
+"""Constraint models for lexical item selection.
+
+This module provides a universal constraint model based on DSL expressions.
+Constraints are pure DSL expressions with optional context variables.
+
+Scope is determined by storage location:
+- Slot.constraints → single-slot constraints (self = slot filler)
+- Template.constraints → multi-slot constraints (slot names as variables)
+- TemplateSequence.constraints → cross-template constraints
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import Field
+
+from bead.data.base import BeadBaseModel
+from bead.dsl.ast import ASTNode
+
+# Type aliases for constraint context values
+type ContextValue = str | int | float | bool | list[str] | set[str] | set[UUID]
+type MetadataValue = (
+    str | int | float | bool | list[str | int | float] | dict[str, str | int | float]
+)
+
+
+class Constraint(BeadBaseModel):
+    """Universal constraint expressed via DSL.
+
+    All constraints are DSL expressions evaluated with a context dictionary.
+    The scope of the constraint is determined by where it is stored:
+    - Slot.constraints: single-slot constraints where 'self' refers to the slot filler
+    - Template.constraints: multi-slot constraints where slot names are variables
+    - TemplateSequence.constraints: cross-template constraints
+
+    Attributes
+    ----------
+    expression : str
+        DSL expression to evaluate (must return boolean).
+    context : dict[str, ContextValue]
+        Context variables available during evaluation (e.g., whitelists, constants).
+    description : str | None
+        Optional human-readable description of the constraint.
+    compiled : ASTNode | None
+        Cached compiled AST after first compilation (optimization).
+
+    Examples
+    --------
+    Extensional (whitelist):
+    >>> constraint = Constraint(
+    ...     expression="self.lemma in motion_verbs",
+    ...     context={"motion_verbs": {"walk", "run", "jump"}}
+    ... )
+
+    Intensional (feature-based):
+    >>> constraint = Constraint(
+    ...     expression="self.pos == 'VERB' and self.features.number == 'singular'"
+    ... )
+
+    Binary agreement:
+    >>> constraint = Constraint(
+    ...     expression="subject.features.number == verb.features.number"
+    ... )
+
+    IF-THEN conditional:
+    >>> constraint = Constraint(
+    ...     expression="det.lemma != 'a' or noun.features.number == 'singular'"
+    ... )
+    """
+
+    expression: str
+    context: dict[str, ContextValue] = Field(default_factory=dict)
+    description: str | None = None
+    compiled: ASTNode | None = None
+
+    @classmethod
+    def combine(
+        cls,
+        *constraints: Constraint,
+        logic: str = "and",
+    ) -> Constraint:
+        """Combine multiple constraints with AND or OR logic.
+
+        Merges all context dictionaries from input constraints and combines
+        their expressions using the specified logical operator.
+
+        Parameters
+        ----------
+        *constraints : Constraint
+            Variable number of constraints to combine.
+        logic : str
+            Logical operator to use: "and" or "or" (default: "and").
+
+        Returns
+        -------
+        Constraint
+            New constraint with combined expressions and merged contexts.
+
+        Raises
+        ------
+        ValueError
+            If no constraints provided or invalid logic operator.
+
+        Examples
+        --------
+        >>> c1 = Constraint(
+        ...     expression="self.pos == 'VERB'",
+        ...     description="Must be a verb"
+        ... )
+        >>> c2 = Constraint(
+        ...     expression="self.features.tense == 'present'",
+        ...     description="Must be present tense"
+        ... )
+        >>> combined = Constraint.combine(c1, c2)
+        >>> "and" in combined.expression
+        True
+        >>> combined.description
+        'Must be a verb; Must be present tense'
+
+        With OR logic and contexts:
+        >>> c1 = Constraint(
+        ...     expression="self.lemma in verbs",
+        ...     context={"verbs": {"walk", "run"}},
+        ...     description="Motion verb"
+        ... )
+        >>> c2 = Constraint(
+        ...     expression="self.lemma in actions",
+        ...     context={"actions": {"jump", "hop"}},
+        ...     description="Action verb"
+        ... )
+        >>> combined = Constraint.combine(c1, c2, logic="or")
+        >>> " or " in combined.expression
+        True
+        >>> len(combined.context)
+        2
+        """
+        if not constraints:
+            raise ValueError("Must provide at least one constraint")
+
+        if logic not in ("and", "or"):
+            raise ValueError(f"Invalid logic operator '{logic}'. Must be 'and' or 'or'")
+
+        if len(constraints) == 1:
+            return constraints[0]
+
+        # combine expressions with specified logic operator
+        expressions = [f"({c.expression})" for c in constraints]
+        combined_expression = f" {logic} ".join(expressions)
+
+        # merge contexts
+        combined_context: dict[str, ContextValue] = {}
+        for constraint in constraints:
+            if constraint.context:
+                combined_context.update(constraint.context)
+
+        # combine descriptions
+        descriptions = [c.description for c in constraints if c.description]
+        combined_description = "; ".join(descriptions) if descriptions else None
+
+        return cls(
+            expression=combined_expression,
+            context=combined_context,
+            description=combined_description,
+        )