bead 0.1.0__py3-none-any.whl

bead/resources/loaders.py

@@ -0,0 +1,209 @@
+"""Lexicon loading utilities for various data formats.
+
+This module provides class methods for loading Lexicon objects from
+various data formats (CSV, TSV) with flexible column mapping.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from pandas import DataFrame, Series
+
+from bead.data.language_codes import LanguageCode
+from bead.resources.lexical_item import LexicalItem
+from bead.resources.lexicon import Lexicon
+
+
+def from_csv(
+    path: str | Path,
+    name: str,
+    *,
+    language_code: LanguageCode,
+    column_mapping: dict[str, str] | None = None,
+    feature_columns: list[str] | None = None,
+    pos: str | None = None,
+    description: str | None = None,
+    **csv_kwargs: Any,
+) -> Lexicon:
+    """Load lexicon from CSV file with flexible column mapping.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the CSV file.
+    name : str
+        Name for the lexicon.
+    language_code : LanguageCode
+        ISO 639-3 language code for all items.
+    column_mapping : dict[str, str] | None
+        Mapping from CSV column names to feature names.
+        Example: {"word": "lemma"}
+    feature_columns : list[str] | None
+        CSV column names to include in features dict.
+        Example: ["number", "tense", "countability", "semantic_class"]
+    pos : str | None
+        Part-of-speech tag to assign to all items (e.g., "NOUN", "VERB").
+        Will be added to features dict as "pos".
+    description : str | None
+        Optional description of the lexicon.
+    **csv_kwargs : Any
+        Additional keyword arguments passed to pandas.read_csv().
+
+    Returns
+    -------
+    Lexicon
+        New lexicon loaded from CSV.
+
+    Raises
+    ------
+    ValueError
+        If required "lemma" column/mapping is missing.
+    FileNotFoundError
+        If CSV file does not exist.
+
+    Examples
+    --------
+    >>> lexicon = from_csv(
+    ...     "bleached_nouns.csv",
+    ...     "nouns",
+    ...     language_code="eng",
+    ...     column_mapping={"word": "lemma"},
+    ...     feature_columns=["number", "countability", "semantic_class"],
+    ...     pos="NOUN"
+    ... )  # doctest: +SKIP
+    """
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"CSV file not found: {file_path}")
+
+    # read CSV
+    df: DataFrame = pd.read_csv(file_path, **csv_kwargs)
+
+    # set up column mapping
+    mapping = column_mapping or {}
+    reverse_mapping = {v: k for k, v in mapping.items()}
+
+    # check for required lemma column
+    lemma_col = reverse_mapping.get("lemma", "lemma")
+    columns_list = list(df.columns)
+    if lemma_col not in columns_list:
+        raise ValueError(
+            f"CSV must have a 'lemma' column or provide column_mapping. "
+            f"Available columns: {columns_list}"
+        )
+
+    # create lexicon
+    lexicon = Lexicon(
+        name=name,
+        description=description,
+        language_code=language_code,
+    )
+
+    # process each row
+    row_iter: Iterator[tuple[int | str, Series[Any]]] = df.iterrows()
+    for _, row_data in row_iter:
+        row: Series[Any] = row_data
+
+        # get lemma
+        lemma_col = reverse_mapping.get("lemma", "lemma")
+        lemma = str(row[lemma_col])
+
+        # build features dict
+        features: dict[str, Any] = {}
+
+        # add POS if provided
+        if pos:
+            features["pos"] = pos
+
+        # handle mapped "pos" column
+        pos_col = reverse_mapping.get("pos")
+        if pos_col and pos_col in columns_list and pd.notna(row[pos_col]):
+            features["pos"] = str(row[pos_col])
+
+        # add feature columns
+        if feature_columns:
+            for col in feature_columns:
+                if col in columns_list and pd.notna(row[col]):
+                    # store feature value, converting to string if needed
+                    val = row[col]
+                    if not isinstance(val, str | int | float | bool):
+                        features[col] = str(val)
+                    else:
+                        features[col] = val
+
+        # create and add item
+        item = LexicalItem(
+            lemma=lemma,
+            language_code=language_code,
+            features=features if features else {},
+            source=None,
+        )
+        lexicon.add(item)
+
+    return lexicon
+
+
+def from_tsv(
+    path: str | Path,
+    name: str,
+    *,
+    language_code: LanguageCode,
+    column_mapping: dict[str, str] | None = None,
+    feature_columns: list[str] | None = None,
+    pos: str | None = None,
+    description: str | None = None,
+    **tsv_kwargs: Any,
+) -> Lexicon:
+    r"""Load lexicon from TSV file with flexible column mapping.
+
+    This is a convenience wrapper around from_csv() that sets sep="\t".
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the TSV file.
+    name : str
+        Name for the lexicon.
+    language_code : LanguageCode
+        ISO 639-3 language code for all items.
+    column_mapping : dict[str, str] | None
+        Mapping from TSV column names to feature names.
+    feature_columns : list[str] | None
+        TSV column names to include in features dict.
+    pos : str | None
+        Part-of-speech tag to assign to all items.
+    description : str | None
+        Optional description of the lexicon.
+    **tsv_kwargs : Any
+        Additional keyword arguments passed to pandas.read_csv().
+
+    Returns
+    -------
+    Lexicon
+        New lexicon loaded from TSV.
+
+    Examples
+    --------
+    >>> lexicon = from_tsv(
+    ...     "verbs.tsv",
+    ...     "verbs",
+    ...     language_code="eng",
+    ...     feature_columns=["tense", "aspect"],
+    ...     pos="VERB"
+    ... )  # doctest: +SKIP
+    """
+    return from_csv(
+        path=path,
+        name=name,
+        language_code=language_code,
+        column_mapping=column_mapping,
+        feature_columns=feature_columns,
+        pos=pos,
+        description=description,
+        sep="\t",
+        **tsv_kwargs,
+    )

bead/resources/template.py

@@ -0,0 +1,441 @@
+"""Template and structure models for sentence generation.
+
+This module provides models for sentence templates and their structures.
+Templates contain slots that are filled with lexical items during
+sentence generation.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from pydantic import Field, field_validator, model_validator
+
+from bead.data.base import BeadBaseModel
+from bead.data.language_codes import LanguageCode
+from bead.resources.constraints import Constraint
+
+if TYPE_CHECKING:
+    from bead.items.item_template import MetadataValue
+    from bead.templates.filler import FilledTemplate
+else:
+    # Recursive type for metadata values
+    type MetadataValue = (
+        str | int | float | bool | None | dict[str, MetadataValue] | list[MetadataValue]
+    )
+
+
+def _empty_constraint_list() -> list[Constraint]:
+    """Create an empty constraint list."""
+    return []
+
+
+def _empty_str_list() -> list[str]:
+    """Create an empty string list."""
+    return []
+
+
+class Slot(BeadBaseModel):
+    """A slot in a template that can be filled with a lexical item.
+
+    Attributes
+    ----------
+    name : str
+        Unique name for the slot within the template.
+    description : str | None
+        Human-readable description of the slot's purpose.
+    constraints : list[Constraint]
+        Constraints that determine valid fillers.
+    required : bool
+        Whether the slot must be filled.
+    default_value : str | None
+        Default value if slot is not filled.
+
+    Examples
+    --------
+    >>> from bead.resources.constraints import Constraint
+    >>> slot = Slot(
+    ...     name="subject",
+    ...     description="The subject of the sentence",
+    ...     constraints=[
+    ...         Constraint(expression="self.features.pos == 'NOUN'")
+    ...     ],
+    ...     required=True
+    ... )
+    """
+
+    name: str
+    description: str | None = None
+    constraints: list[Constraint] = Field(default_factory=_empty_constraint_list)
+    required: bool = True
+    default_value: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate that name is a valid Python identifier.
+
+        Parameters
+        ----------
+        v : str
+            The slot name to validate.
+
+        Returns
+        -------
+        str
+            The validated slot name.
+
+        Raises
+        ------
+        ValueError
+            If name is not a valid Python identifier.
+        """
+        if not v or not v.strip():
+            raise ValueError("name must be non-empty")
+        if not v.isidentifier():
+            raise ValueError(f"name '{v}' must be a valid Python identifier")
+        return v
+
+
+class Template(BeadBaseModel):
+    """A sentence template with slots for lexical items.
+
+    Templates define the structure of generated sentences. They contain:
+    - A template string with slot placeholders (e.g., "{subject} {verb} {object}")
+    - Slot definitions with constraints
+    - Optional language code
+    - Optional metadata
+
+    Attributes
+    ----------
+    name : str
+        Unique name for the template.
+    template_string : str
+        Template with {slot_name} placeholders.
+    slots : dict[str, Slot]
+        Slot definitions keyed by slot name.
+    constraints : list[Constraint]
+        Multi-slot constraints (slot names as variables in DSL expressions).
+    description : str | None
+        Human-readable description.
+    language_code : LanguageCode | None
+        ISO 639-1 (2-letter) or ISO 639-3 (3-letter) language code.
+        Examples: "en", "eng", "ko", "kor", "zu", "zul".
+        Required for cross-linguistic classification via TemplateClass.
+    tags : list[str]
+        Tags for categorization.
+    metadata : dict[str, MetadataValue]
+        Additional metadata.
+
+    Examples
+    --------
+    >>> template = Template(
+    ...     name="simple_transitive",
+    ...     template_string="{subject} {verb} {object}.",
+    ...     slots={
+    ...         "subject": Slot(name="subject", required=True),
+    ...         "verb": Slot(name="verb", required=True),
+    ...         "object": Slot(name="object", required=True)
+    ...     },
+    ...     tags=["transitive", "simple"]
+    ... )
+    """
+
+    name: str
+    template_string: str
+    slots: dict[str, Slot] = Field(default_factory=dict)
+    constraints: list[Constraint] = Field(default_factory=_empty_constraint_list)
+    description: str | None = None
+    language_code: LanguageCode | None = None
+    tags: list[str] = Field(default_factory=_empty_str_list)
+    metadata: dict[str, MetadataValue] = Field(default_factory=dict)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate that name is non-empty.
+
+        Parameters
+        ----------
+        v : str
+            The template name to validate.
+
+        Returns
+        -------
+        str
+            The validated template name.
+
+        Raises
+        ------
+        ValueError
+            If name is empty.
+        """
+        if not v or not v.strip():
+            raise ValueError("name must be non-empty")
+        return v
+
+    @field_validator("template_string")
+    @classmethod
+    def validate_template_string(cls, v: str) -> str:
+        """Validate that template_string is non-empty.
+
+        Parameters
+        ----------
+        v : str
+            The template string to validate.
+
+        Returns
+        -------
+        str
+            The validated template string.
+
+        Raises
+        ------
+        ValueError
+            If template_string is empty.
+        """
+        if not v or not v.strip():
+            raise ValueError("template_string must be non-empty")
+        return v
+
+    @model_validator(mode="after")
+    def validate_slots_match_template(self) -> Template:
+        """Validate that template_string and slots are consistent.
+
+        Ensures that:
+        - All slot names in template_string exist in slots dict
+        - All slots in dict are referenced in template_string
+        - Slot names match their keys in the dict
+
+        Returns
+        -------
+        Template
+            The validated template.
+
+        Raises
+        ------
+        ValueError
+            If template_string and slots are inconsistent.
+        """
+        # Extract slot names from template string
+        template_slots = set(re.findall(r"\{(\w+)\}", self.template_string))
+
+        # Get slot names from slots dict
+        dict_slots = set(self.slots.keys())
+
+        # Check that all template slots exist in dict
+        missing_in_dict = template_slots - dict_slots
+        if missing_in_dict:
+            raise ValueError(
+                f"Template references slots not in slots dict: {missing_in_dict}"
+            )
+
+        # Check that all dict slots are referenced in template
+        missing_in_template = dict_slots - template_slots
+        if missing_in_template:
+            raise ValueError(
+                f"Slots dict contains slots not referenced in template: "
+                f"{missing_in_template}"
+            )
+
+        # Check that slot names match their keys
+        for key, slot in self.slots.items():
+            if slot.name != key:
+                raise ValueError(
+                    f"Slot key '{key}' does not match slot name '{slot.name}'"
+                )
+
+        return self
+
+    @property
+    def required_slot_names(self) -> set[str]:
+        """Get names of all required slots.
+
+        Returns
+        -------
+        set[str]
+            Set of slot names where required=True.
+        """
+        return {name for name, slot in self.slots.items() if slot.required}
+
+    def fill_with_values(
+        self, slot_values: dict[str, str], strategy_name: str = "manual"
+    ) -> FilledTemplate:
+        """Create a FilledTemplate by filling slots with string values.
+
+        This is a lightweight alternative to CSPFiller for cases where
+        you already have the values and just need a FilledTemplate object.
+
+        Parameters
+        ----------
+        slot_values : dict[str, str]
+            Mapping of slot names to string values to fill them with.
+        strategy_name : str
+            Name of strategy used (for metadata).
+
+        Returns
+        -------
+        FilledTemplate
+            A filled template with the provided values.
+
+        Examples
+        --------
+        >>> template = Template(
+        ...     name="test",
+        ...     template_string="{subj} {verb}.",
+        ...     slots={"subj": Slot(name="subj"), "verb": Slot(name="verb")}
+        ... )
+        >>> filled = template.fill_with_values({"subj": "cat", "verb": "runs"})
+        >>> filled.rendered_text
+        'cat runs.'
+        """
+        from bead.resources.lexical_item import LexicalItem  # noqa: PLC0415
+        from bead.templates.filler import FilledTemplate  # noqa: PLC0415
+
+        # Create LexicalItem objects for each value
+        slot_fillers = {}
+        for slot_name, value in slot_values.items():
+            if slot_name in self.slots:
+                # Create a minimal LexicalItem with just the lemma
+                slot_fillers[slot_name] = LexicalItem(
+                    lemma=value,
+                    language_code=self.language_code or "eng",
+                    features={"pos": "UNKNOWN"},
+                )
+
+        # Render text by replacing slot placeholders
+        rendered_text = self.template_string
+        for slot_name, value in slot_values.items():
+            rendered_text = rendered_text.replace(f"{{{slot_name}}}", value)
+
+        # Create template_slots mapping (slot_name -> is_required)
+        template_slots = {name: slot.required for name, slot in self.slots.items()}
+
+        return FilledTemplate(
+            template_id=str(self.id),
+            template_name=self.name,
+            slot_fillers=slot_fillers,
+            rendered_text=rendered_text,
+            strategy_name=strategy_name,
+            template_slots=template_slots,
+        )
+
+
+def _empty_template_list() -> list[Template]:
+    """Create an empty template list."""
+    return []
+
+
+class TemplateSequence(BeadBaseModel):
+    """A sequence of templates to be filled together.
+
+    Template sequences allow multiple templates to be filled with
+    related constraints (e.g., relational constraints across templates).
+
+    Attributes
+    ----------
+    name : str
+        Unique name for the sequence.
+    templates : list[Template]
+        Ordered list of templates.
+    constraints : list[Constraint]
+        Cross-template constraints (span multiple templates).
+
+    Examples
+    --------
+    >>> sequence = TemplateSequence(
+    ...     name="question_answer",
+    ...     templates=[question_template, answer_template],
+    ...     constraints=[...]
+    ... )
+    """
+
+    name: str
+    templates: list[Template] = Field(default_factory=_empty_template_list)
+    constraints: list[Constraint] = Field(default_factory=_empty_constraint_list)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate that name is non-empty.
+
+        Parameters
+        ----------
+        v : str
+            The sequence name to validate.
+
+        Returns
+        -------
+        str
+            The validated sequence name.
+
+        Raises
+        ------
+        ValueError
+            If name is empty.
+        """
+        if not v or not v.strip():
+            raise ValueError("name must be non-empty")
+        return v
+
+
+def _empty_tree_list() -> list[TemplateTree]:
+    """Create an empty template tree list."""
+    return []
+
+
+class TemplateTree(BeadBaseModel):
+    """A tree structure of templates.
+
+    Template trees represent hierarchical relationships between
+    templates (e.g., a discourse structure).
+
+    Attributes
+    ----------
+    name : str
+        Unique name for the tree.
+    root : Template
+        Root template.
+    children : list[TemplateTree]
+        Child subtrees.
+
+    Examples
+    --------
+    >>> tree = TemplateTree(
+    ...     name="discourse",
+    ...     root=intro_template,
+    ...     children=[
+    ...         TemplateTree(name="body", root=body_template, children=[]),
+    ...         TemplateTree(name="conclusion", root=conclusion_template, children=[])
+    ...     ]
+    ... )
+    """
+
+    name: str
+    root: Template
+    children: list[TemplateTree] = Field(default_factory=_empty_tree_list)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate that name is non-empty.
+
+        Parameters
+        ----------
+        v : str
+            The tree name to validate.
+
+        Returns
+        -------
+        str
+            The validated tree name.
+
+        Raises
+        ------
+        ValueError
+            If name is empty.
+        """
+        if not v or not v.strip():
+            raise ValueError("name must be non-empty")
+        return v