bead 0.1.0__py3-none-any.whl

bead/participants/models.py

@@ -0,0 +1,276 @@
+"""Participant data models.
+
+This module provides Participant and ParticipantIDMapping models for
+storing participant information with privacy-preserving external ID mapping.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from pydantic import Field, field_validator
+
+from bead.data.base import BeadBaseModel, JsonValue
+from bead.data.timestamps import now_iso8601
+
+if TYPE_CHECKING:
+    from bead.participants.metadata_spec import ParticipantMetadataSpec
+
+
+def _empty_metadata_dict() -> dict[str, JsonValue]:
+    """Return empty metadata dict."""
+    return {}
+
+
+def _empty_session_list() -> list[str]:
+    """Return empty session list."""
+    return []
+
+
+class Participant(BeadBaseModel):
+    """A study participant with demographic and session metadata.
+
+    Inherits UUID, timestamps, version, and metadata from BeadBaseModel.
+    The internal `id` (UUID) is used for all analysis; external IDs
+    (e.g., Prolific IDs) are stored separately for privacy.
+
+    Attributes
+    ----------
+    id : UUID
+        Internal unique identifier (UUIDv7, inherited from BeadBaseModel).
+    created_at : datetime
+        When participant record was created (inherited).
+    modified_at : datetime
+        When participant record was last modified (inherited).
+    participant_metadata : dict[str, JsonValue]
+        Demographic and other participant attributes (e.g., age, education).
+        Keys should match a ParticipantMetadataSpec for validation.
+    study_id : str | None
+        Optional study identifier this participant belongs to.
+    session_ids : list[str]
+        Session identifiers for this participant (for longitudinal studies).
+    consent_timestamp : datetime | None
+        When participant provided consent.
+    notes : str | None
+        Free-text notes about this participant.
+
+    Examples
+    --------
+    >>> participant = Participant(
+    ...     participant_metadata={
+    ...         "age": 25,
+    ...         "education": "bachelors",
+    ...         "native_speaker": True,
+    ...     },
+    ...     study_id="study_001",
+    ... )
+    >>> participant.participant_metadata["age"]
+    25
+    >>> str(participant.id)  # doctest: +SKIP
+    '019...'  # UUIDv7
+    """
+
+    participant_metadata: dict[str, JsonValue] = Field(
+        default_factory=_empty_metadata_dict,
+        description="Participant attributes (demographics, etc.)",
+    )
+    study_id: str | None = Field(default=None, description="Study identifier")
+    session_ids: list[str] = Field(
+        default_factory=_empty_session_list, description="Session identifiers"
+    )
+    consent_timestamp: datetime | None = Field(
+        default=None, description="Consent timestamp"
+    )
+    notes: str | None = Field(default=None, description="Free-text notes")
+
+    def validate_against_spec(
+        self, spec: ParticipantMetadataSpec
+    ) -> tuple[bool, list[str]]:
+        """Validate participant_metadata against a specification.
+
+        Parameters
+        ----------
+        spec : ParticipantMetadataSpec
+            Specification to validate against.
+
+        Returns
+        -------
+        tuple[bool, list[str]]
+            (is_valid, list of error messages)
+
+        Examples
+        --------
+        >>> from bead.participants.metadata_spec import (
+        ...     FieldSpec, ParticipantMetadataSpec
+        ... )
+        >>> spec = ParticipantMetadataSpec(
+        ...     name="test",
+        ...     fields=[FieldSpec(name="age", field_type="int", required=True)]
+        ... )
+        >>> p = Participant(participant_metadata={"age": 25})
+        >>> p.validate_against_spec(spec)
+        (True, [])
+        """
+        # Convert JsonValue dict to the expected type for validation
+        metadata: dict[str, str | int | float | bool | None] = {}
+        for key, value in self.participant_metadata.items():
+            if isinstance(value, str | int | float | bool) or value is None:
+                metadata[key] = value
+            # Skip complex values (lists, dicts) - they won't match FieldSpec types
+        return spec.validate_metadata(metadata)
+
+    def get_attribute(self, key: str, default: JsonValue = None) -> JsonValue:
+        """Get a metadata attribute with optional default.
+
+        Parameters
+        ----------
+        key : str
+            Attribute name.
+        default : JsonValue
+            Default value if attribute not found.
+
+        Returns
+        -------
+        JsonValue
+            Attribute value or default.
+
+        Examples
+        --------
+        >>> p = Participant(participant_metadata={"age": 25})
+        >>> p.get_attribute("age")
+        25
+        >>> p.get_attribute("unknown", default="N/A")
+        'N/A'
+        """
+        return self.participant_metadata.get(key, default)
+
+    def set_attribute(self, key: str, value: JsonValue) -> None:
+        """Set a metadata attribute.
+
+        Parameters
+        ----------
+        key : str
+            Attribute name.
+        value : JsonValue
+            Attribute value.
+
+        Examples
+        --------
+        >>> p = Participant()
+        >>> p.set_attribute("age", 25)
+        >>> p.participant_metadata["age"]
+        25
+        """
+        self.participant_metadata[key] = value
+        self.update_modified_time()
+
+    def add_session(self, session_id: str) -> None:
+        """Add a session ID to this participant.
+
+        Parameters
+        ----------
+        session_id : str
+            Session identifier to add.
+
+        Examples
+        --------
+        >>> p = Participant()
+        >>> p.add_session("session_001")
+        >>> p.session_ids
+        ['session_001']
+        """
+        self.session_ids.append(session_id)
+        self.update_modified_time()
+
+
+class ParticipantIDMapping(BeadBaseModel):
+    """Mapping between external participant IDs and internal UUIDs.
+
+    This model is stored SEPARATELY from participant data for IRB/privacy
+    compliance. The external ID (e.g., Prolific PID) can be deleted while
+    retaining the internal UUID for analysis.
+
+    Attributes
+    ----------
+    id : UUID
+        Unique identifier for this mapping record (inherited).
+    external_id : str
+        External participant identifier (e.g., Prolific PID).
+    external_source : str
+        Source of the external ID (e.g., "prolific", "mturk", "sona").
+    participant_id : UUID
+        Internal participant UUID (references Participant.id).
+    mapping_timestamp : datetime
+        When this mapping was created.
+    is_active : bool
+        Whether this mapping is active (for soft deletion).
+
+    Examples
+    --------
+    >>> from uuid import UUID
+    >>> mapping = ParticipantIDMapping(
+    ...     external_id="PROLIFIC_ABC123",
+    ...     external_source="prolific",
+    ...     participant_id=UUID("01234567-89ab-cdef-0123-456789abcdef"),
+    ... )
+    >>> mapping.external_source
+    'prolific'
+    """
+
+    external_id: str = Field(..., description="External participant ID")
+    external_source: str = Field(..., description="Source of external ID")
+    participant_id: UUID = Field(..., description="Internal participant UUID")
+    mapping_timestamp: datetime = Field(
+        default_factory=now_iso8601, description="When mapping was created"
+    )
+    is_active: bool = Field(default=True, description="Whether mapping is active")
+
+    @field_validator("external_id", "external_source")
+    @classmethod
+    def validate_non_empty(cls, v: str) -> str:
+        """Validate string fields are non-empty.
+
+        Parameters
+        ----------
+        v : str
+            String value to validate.
+
+        Returns
+        -------
+        str
+            Validated string.
+
+        Raises
+        ------
+        ValueError
+            If string is empty or whitespace only.
+        """
+        if not v or not v.strip():
+            raise ValueError("Field cannot be empty")
+        return v.strip()
+
+    def deactivate(self) -> None:
+        """Soft-delete this mapping (for privacy compliance).
+
+        Sets is_active to False without deleting the record. This allows
+        the mapping to be retained for audit purposes while marking it
+        as no longer valid.
+
+        Examples
+        --------
+        >>> from uuid import uuid4
+        >>> mapping = ParticipantIDMapping(
+        ...     external_id="ABC123",
+        ...     external_source="prolific",
+        ...     participant_id=uuid4(),
+        ... )
+        >>> mapping.is_active
+        True
+        >>> mapping.deactivate()
+        >>> mapping.is_active
+        False
+        """
+        self.is_active = False
+        self.update_modified_time()

bead/resources/__init__.py

@@ -0,0 +1,29 @@
+"""Resource models.
+
+Provides data models for lexical items, templates, constraints, and
+template structures.
+"""
+
+from bead.resources.constraints import Constraint
+from bead.resources.lexical_item import LexicalItem, MultiWordExpression, MWEComponent
+from bead.resources.lexicon import Lexicon
+from bead.resources.template import Slot, Template, TemplateSequence, TemplateTree
+from bead.resources.template_collection import TemplateCollection
+
+__all__ = [
+    # Lexical items
+    "LexicalItem",
+    "MWEComponent",
+    "MultiWordExpression",
+    # Lexicon
+    "Lexicon",
+    # Constraints
+    "Constraint",
+    # Templates and structures
+    "Slot",
+    "Template",
+    "TemplateSequence",
+    "TemplateTree",
+    # Template collection
+    "TemplateCollection",
+]

bead/resources/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""External resource adapters for linguistic databases.
+
+Fetches lexical items from VerbNet, PropBank, FrameNet (via glazing), and
+UniMorph morphological paradigms.
+"""
+
+from bead.resources.adapters.base import ResourceAdapter
+from bead.resources.adapters.cache import AdapterCache
+from bead.resources.adapters.glazing import GlazingAdapter
+from bead.resources.adapters.registry import AdapterRegistry
+from bead.resources.adapters.unimorph import UniMorphAdapter
+
+__all__ = [
+    "ResourceAdapter",
+    "AdapterCache",
+    "GlazingAdapter",
+    "UniMorphAdapter",
+    "AdapterRegistry",
+]

bead/resources/adapters/base.py

@@ -0,0 +1,104 @@
+"""Abstract base class for external resource adapters.
+
+This module defines the interface that all resource adapters must implement
+to fetch lexical items from external linguistic databases.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from bead.data.language_codes import LanguageCode
+from bead.resources.lexical_item import LexicalItem
+
+
+class ResourceAdapter(ABC):
+    """Abstract base class for external resource adapters.
+
+    Resource adapters fetch lexical items from external linguistic databases
+    and convert them to the bead LexicalItem format. All adapters must
+    implement language_code filtering to support multi-language workflows.
+
+    Subclasses must implement:
+    - fetch_items(): Retrieve items from the external resource
+    - is_available(): Check if the external resource is accessible
+
+    Examples
+    --------
+    >>> class MyAdapter(ResourceAdapter):
+    ...     def fetch_items(self, query=None, language_code=None, **kwargs):
+    ...         # Fetch from external resource
+    ...         return [LexicalItem(lemma="walk", pos="VERB", language_code="en")]
+    ...     def is_available(self):
+    ...         return True
+    >>> adapter = MyAdapter()
+    >>> items = adapter.fetch_items(query="walk", language_code="en")
+    >>> len(items) > 0
+    True
+    """
+
+    @abstractmethod
+    def fetch_items(
+        self,
+        query: str | None = None,
+        language_code: LanguageCode = None,
+        **kwargs: Any,
+    ) -> list[LexicalItem]:
+        """Fetch lexical items from external resource.
+
+        Parameters
+        ----------
+        query : str | None
+            Query string in adapter-specific format (e.g., lemma, predicate name,
+            class identifier). If None, behavior is adapter-specific (may return
+            all items, raise error, or use default query).
+        language_code : LanguageCode
+            ISO 639-1 (2-letter) or ISO 639-3 (3-letter) language code to filter
+            results. Examples: "en", "eng", "ko", "kor". If None, returns items
+            for all available languages.
+        **kwargs : Any
+            Additional adapter-specific parameters (e.g., pos="VERB",
+            resource="verbnet", include_features=True).
+
+        Returns
+        -------
+        list[LexicalItem]
+            Lexical items fetched from the external resource. Each item should
+            have language_code set if known.
+
+        Raises
+        ------
+        ValueError
+            If query is invalid or required parameters are missing.
+        RuntimeError
+            If the external resource is unavailable or the request fails.
+
+        Examples
+        --------
+        >>> adapter = MyAdapter()
+        >>> items = adapter.fetch_items(query="break", language_code="en")
+        >>> all(item.language_code == "en" for item in items)
+        True
+        """
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the external resource is available.
+
+        This method should verify that the external resource can be accessed,
+        whether via installed packages, accessible data files, or network APIs.
+
+        Returns
+        -------
+        bool
+            True if the resource can be accessed, False otherwise.
+
+        Examples
+        --------
+        >>> adapter = MyAdapter()
+        >>> adapter.is_available()
+        True
+        """
+        ...

bead/resources/adapters/cache.py

@@ -0,0 +1,128 @@
+"""Caching for adapter fetch results.
+
+This module provides an in-memory cache to avoid redundant fetches from
+external resources when the same query is repeated.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from bead.resources.lexical_item import LexicalItem
+
+
+class AdapterCache:
+    """In-memory cache for adapter fetch results.
+
+    The cache stores results keyed by a hash of query parameters. This avoids
+    redundant fetches when the same query is made multiple times.
+
+    Examples
+    --------
+    >>> cache = AdapterCache()
+    >>> items = [LexicalItem(lemma="walk", pos="VERB")]
+    >>> key = cache.make_key("glazing", query="walk", language_code="en")
+    >>> cache.set(key, items)
+    >>> cached = cache.get(key)
+    >>> cached == items
+    True
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, list[LexicalItem]] = {}
+
+    def get(self, key: str) -> list[LexicalItem] | None:
+        """Get cached result.
+
+        Parameters
+        ----------
+        key : str
+            Cache key generated by make_key().
+
+        Returns
+        -------
+        list[LexicalItem] | None
+            Cached items if key exists, None otherwise.
+
+        Examples
+        --------
+        >>> cache = AdapterCache()
+        >>> cache.get("nonexistent")
+        None
+        """
+        return self._cache.get(key)
+
+    def set(self, key: str, items: list[LexicalItem]) -> None:
+        """Cache result.
+
+        Parameters
+        ----------
+        key : str
+            Cache key generated by make_key().
+        items : list[LexicalItem]
+            Items to cache.
+
+        Examples
+        --------
+        >>> cache = AdapterCache()
+        >>> items = [LexicalItem(lemma="walk")]
+        >>> cache.set("key1", items)
+        >>> cache.get("key1") == items
+        True
+        """
+        self._cache[key] = items
+
+    def clear(self) -> None:
+        """Clear entire cache.
+
+        Examples
+        --------
+        >>> cache = AdapterCache()
+        >>> cache.set("key1", [])
+        >>> cache.clear()
+        >>> cache.get("key1")
+        None
+        """
+        self._cache.clear()
+
+    def make_key(
+        self, adapter_name: str, query: str | None = None, **kwargs: Any
+    ) -> str:
+        """Generate cache key from query parameters.
+
+        Create a deterministic hash key from adapter name, query, and
+        additional parameters. Same inputs always produce same key.
+
+        Parameters
+        ----------
+        adapter_name : str
+            Name of the adapter (e.g., "glazing", "unimorph").
+        query : str | None
+            Query string.
+        **kwargs : Any
+            Additional query parameters (e.g., language_code, pos).
+
+        Returns
+        -------
+        str
+            Cache key (hexadecimal hash string).
+
+        Examples
+        --------
+        >>> cache = AdapterCache()
+        >>> key1 = cache.make_key("glazing", query="walk", language_code="en")
+        >>> key2 = cache.make_key("glazing", query="walk", language_code="en")
+        >>> key1 == key2
+        True
+        >>> key3 = cache.make_key("glazing", query="run", language_code="en")
+        >>> key1 != key3
+        True
+        """
+        # create deterministic dict for hashing
+        params = {"adapter": adapter_name, "query": query, **kwargs}
+        # sort keys for deterministic serialization
+        serialized = json.dumps(params, sort_keys=True)
+        # return SHA256 hash
+        return hashlib.sha256(serialized.encode()).hexdigest()