bead 0.1.0__py3-none-any.whl

bead/templates/renderers.py

@@ -0,0 +1,177 @@
+"""Template rendering system with plugin support.
+
+This module provides the base template rendering interface and a simple
+default implementation. Language-specific or custom rendering logic should
+be implemented as external plugins.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bead.resources.lexical_item import LexicalItem
+    from bead.resources.template import Slot
+
+
+class TemplateRenderer(ABC):
+    """Base class for template renderers.
+
+    Custom renderers should subclass this and implement the render() method.
+    This allows for language-specific or experiment-specific rendering logic
+    to be implemented as external plugins.
+
+    Examples
+    --------
+    >>> from bead.templates.renderers import TemplateRenderer
+    >>> class CustomRenderer(TemplateRenderer):
+    ...     def render(self, template_string, slot_fillers, template_slots):
+    ...         # Custom rendering logic here
+    ...         return rendered_text
+    """
+
+    @abstractmethod
+    def render(
+        self,
+        template_string: str,
+        slot_fillers: Mapping[str, LexicalItem],
+        template_slots: Mapping[str, Slot],
+    ) -> str:
+        """Render template with slot fillers.
+
+        Parameters
+        ----------
+        template_string : str
+            Template string with {slot_name} placeholders.
+        slot_fillers : Mapping[str, LexicalItem]
+            Mapping from slot names to lexical items that fill them.
+        template_slots : Mapping[str, Slot]
+            Mapping from slot names to slot definitions. Provides access
+            to slot constraints and metadata for context-aware rendering.
+
+        Returns
+        -------
+        str
+            Rendered text with placeholders replaced.
+
+        Examples
+        --------
+        >>> renderer = DefaultRenderer()
+        >>> from bead.resources.lexical_item import LexicalItem
+        >>> from bead.resources.template import Slot
+        >>> fillers = {
+        ...     "subj": LexicalItem(lemma="cat", language_code="eng"),
+        ...     "verb": LexicalItem(lemma="run", form="runs", language_code="eng")
+        ... }
+        >>> slots = {
+        ...     "subj": Slot(name="subj"),
+        ...     "verb": Slot(name="verb")
+        ... }
+        >>> renderer.render("{subj} {verb}", fillers, slots)
+        'cat runs'
+        """
+        ...
+
+
+class DefaultRenderer(TemplateRenderer):
+    """Default renderer using simple slot substitution.
+
+    Uses item.form if available, otherwise item.lemma.
+    This is a language-agnostic implementation suitable for most use cases.
+
+    Examples
+    --------
+    >>> from bead.templates.renderers import DefaultRenderer
+    >>> from bead.resources.lexical_item import LexicalItem
+    >>> from bead.resources.template import Slot
+    >>> renderer = DefaultRenderer()
+    >>>
+    >>> # Example 1: Basic rendering with lemmas
+    >>> fillers = {
+    ...     "det": LexicalItem(lemma="the", language_code="eng"),
+    ...     "noun": LexicalItem(lemma="cat", language_code="eng"),
+    ...     "verb": LexicalItem(lemma="run", language_code="eng")
+    ... }
+    >>> slots = {name: Slot(name=name) for name in fillers.keys()}
+    >>> renderer.render("{det} {noun} {verb}", fillers, slots)
+    'the cat run'
+    >>>
+    >>> # Example 2: Rendering with forms (inflected)
+    >>> fillers_with_forms = {
+    ...     "det": LexicalItem(lemma="the", language_code="eng"),
+    ...     "noun": LexicalItem(lemma="cat", form="cats", language_code="eng"),
+    ...     "verb": LexicalItem(lemma="run", form="runs", language_code="eng")
+    ... }
+    >>> renderer.render("{det} {noun} {verb}", fillers_with_forms, slots)
+    'the cats runs'
+    """
+
+    def render(
+        self,
+        template_string: str,
+        slot_fillers: Mapping[str, LexicalItem],
+        template_slots: Mapping[str, Slot],
+    ) -> str:
+        """Render template with simple slot substitution.
+
+        Uses item.form if available, otherwise item.lemma. This provides
+        a straightforward rendering suitable for most templates without
+        special language-specific handling.
+
+        Parameters
+        ----------
+        template_string : str
+            Template string with {slot_name} placeholders.
+        slot_fillers : Mapping[str, LexicalItem]
+            Mapping from slot names to lexical items.
+        template_slots : Mapping[str, Slot]
+            Mapping from slot names to slot definitions (unused in default
+            implementation, but provided for subclasses).
+
+        Returns
+        -------
+        str
+            Rendered text with placeholders replaced by item forms or lemmas.
+
+        Notes
+        -----
+        This renderer prioritizes item.form over item.lemma to support
+        morphological inflection. If item.form is None, it falls back to
+        item.lemma.
+
+        The template_slots parameter is not used in the default implementation
+        but is available for subclasses that need slot metadata for rendering.
+
+        Examples
+        --------
+        >>> renderer = DefaultRenderer()
+        >>> from bead.resources.lexical_item import LexicalItem
+        >>> from bead.resources.template import Slot
+        >>>
+        >>> # Form takes precedence over lemma
+        >>> fillers = {
+        ...     "verb": LexicalItem(lemma="walk", form="walked", language_code="eng")
+        ... }
+        >>> slots = {"verb": Slot(name="verb")}
+        >>> renderer.render("{verb}", fillers, slots)
+        'walked'
+        >>>
+        >>> # Falls back to lemma when form is None
+        >>> fillers_no_form = {
+        ...     "verb": LexicalItem(lemma="walk", form=None, language_code="eng")
+        ... }
+        >>> renderer.render("{verb}", fillers_no_form, slots)
+        'walk'
+        """
+        result = template_string
+
+        for slot_name, item in slot_fillers.items():
+            placeholder = f"{{{slot_name}}}"
+            if placeholder in result:
+                # Use form if available, otherwise lemma
+                surface = item.form if item.form is not None else item.lemma
+                result = result.replace(placeholder, surface)
+
+        return result

bead/templates/resolver.py

@@ -0,0 +1,178 @@
+"""Constraint resolution for template slot filling.
+
+This module provides the ConstraintResolver class for evaluating constraints
+against lexical items to determine which items satisfy template slot requirements.
+The resolver is now a thin wrapper around DSLEvaluator.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from bead.dsl.evaluator import DSLEvaluator
+from bead.resources.constraints import Constraint
+
+if TYPE_CHECKING:
+    from bead.resources.constraints import ContextValue
+    from bead.resources.lexical_item import LexicalItem
+
+
+class ConstraintResolver:
+    """Simplified resolver that wraps DSLEvaluator.
+
+    The ConstraintResolver evaluates DSL constraint expressions against
+    lexical items and filled slots. It provides two main methods:
+    - evaluate_slot_constraints: for single-slot constraints
+    - evaluate_template_constraints: for multi-slot constraints
+
+    All constraint logic is delegated to the DSL evaluator.
+
+    Examples
+    --------
+    >>> from bead.resources.models import LexicalItem
+    >>> from bead.resources.constraints import Constraint
+    >>> resolver = ConstraintResolver()
+    >>> item = LexicalItem(lemma="walk", pos="VERB")
+    >>> constraints = [
+    ...     Constraint(expression="self.pos == 'VERB'")
+    ... ]
+    >>> resolver.evaluate_slot_constraints(item, constraints)
+    True
+    """
+
+    def __init__(self) -> None:
+        """Initialize resolver with DSL evaluator."""
+        self.dsl_evaluator = DSLEvaluator()
+
+    def evaluate_slot_constraints(
+        self,
+        item: LexicalItem,
+        constraints: list[Constraint],
+        context: dict[str, ContextValue] | None = None,
+    ) -> bool:
+        """Evaluate single-slot constraints.
+
+        Single-slot constraints are evaluated with 'self' referring to
+        the lexical item being checked. The item is available as 'self'
+        in the DSL expression context.
+
+        Parameters
+        ----------
+        item : LexicalItem
+            Lexical item to evaluate constraints against.
+        constraints : list[Constraint]
+            Single-slot constraints from Slot.constraints.
+        context : dict[str, ContextValue] | None
+            Additional context variables (optional).
+
+        Returns
+        -------
+        bool
+            True if all constraints are satisfied, False otherwise.
+
+        Examples
+        --------
+        >>> from bead.resources.models import LexicalItem
+        >>> from bead.resources.constraints import Constraint
+        >>> resolver = ConstraintResolver()
+        >>> item = LexicalItem(lemma="walk", pos="VERB")
+        >>> constraints = [
+        ...     Constraint(
+        ...         expression="self.lemma in motion_verbs",
+        ...         context={"motion_verbs": {"walk", "run", "jump"}}
+        ...     )
+        ... ]
+        >>> resolver.evaluate_slot_constraints(item, constraints)
+        True
+        """
+        for constraint in constraints:
+            # build evaluation context
+            eval_context: dict[str, Any] = {
+                "self": item,
+                **constraint.context,
+            }
+            if context:
+                eval_context.update(context)
+
+            # evaluate constraint
+            result = self.dsl_evaluator.evaluate(constraint.expression, eval_context)
+            if not result:
+                return False
+
+        return True
+
+    def evaluate_template_constraints(
+        self,
+        filled_slots: dict[str, LexicalItem],
+        constraints: list[Constraint],
+        context: dict[str, ContextValue] | None = None,
+    ) -> bool:
+        """Evaluate multi-slot constraints.
+
+        Multi-slot constraints are evaluated with slot names as variables.
+        For example, a constraint like "subject.features.number == verb.features.number"
+        would have access to both the 'subject' and 'verb' slot fillers.
+
+        Parameters
+        ----------
+        filled_slots : dict[str, LexicalItem]
+            Dictionary mapping slot names to their filled items.
+        constraints : list[Constraint]
+            Multi-slot constraints from Template.constraints.
+        context : dict[str, ContextValue] | None
+            Additional context variables (optional).
+
+        Returns
+        -------
+        bool
+            True if all constraints are satisfied, False otherwise.
+
+        Examples
+        --------
+        >>> from bead.resources.models import LexicalItem
+        >>> from bead.resources.constraints import Constraint
+        >>> resolver = ConstraintResolver()
+        >>> subject = LexicalItem(
+        ...     lemma="dog",
+        ...     pos="NOUN",
+        ...     features={"number": "singular"}
+        ... )
+        >>> verb = LexicalItem(
+        ...     lemma="runs",
+        ...     pos="VERB",
+        ...     features={"number": "singular"}
+        ... )
+        >>> filled = {"subject": subject, "verb": verb}
+        >>> constraints = [
+        ...     Constraint(
+        ...         expression="subject.features.number == verb.features.number"
+        ...     )
+        ... ]
+        >>> resolver.evaluate_template_constraints(filled, constraints)
+        True
+        """
+        for constraint in constraints:
+            # build evaluation context with slot fillers
+            eval_context: dict[str, Any] = {
+                **filled_slots,
+                **constraint.context,
+            }
+            if context:
+                eval_context.update(context)
+
+            # evaluate constraint
+            result = self.dsl_evaluator.evaluate(constraint.expression, eval_context)
+            if not result:
+                return False
+
+        return True
+
+    def clear_cache(self) -> None:
+        """Clear DSL evaluator's compiled expression cache.
+
+        Examples
+        --------
+        >>> resolver = ConstraintResolver()
+        >>> resolver.clear_cache()
+        """
+        self.dsl_evaluator.clear_cache()