bead 0.1.0__py3-none-any.whl

bead/data/__init__.py

@@ -0,0 +1,65 @@
+"""Data infrastructure.
+
+Provides core data models, identifiers, timestamps, serialization,
+metadata tracking, repository pattern, and validation utilities.
+"""
+
+from __future__ import annotations
+
+from bead.data.base import BeadBaseModel
+from bead.data.identifiers import extract_timestamp, generate_uuid, is_valid_uuid7
+from bead.data.metadata import (
+    MetadataTracker,
+    ProcessingRecord,
+    ProvenanceRecord,
+)
+from bead.data.range import Range
+from bead.data.repository import Repository
+from bead.data.serialization import (
+    DeserializationError,
+    SerializationError,
+    append_jsonlines,
+    read_jsonlines,
+    stream_jsonlines,
+    write_jsonlines,
+)
+from bead.data.timestamps import format_iso8601, now_iso8601, parse_iso8601
+from bead.data.validation import (
+    ValidationReport,
+    validate_jsonlines_file,
+    validate_provenance_chain,
+    validate_uuid_references,
+)
+
+__all__ = [
+    # Base model
+    "BeadBaseModel",
+    # Identifiers
+    "generate_uuid",
+    "extract_timestamp",
+    "is_valid_uuid7",
+    # Range
+    "Range",
+    # Timestamps
+    "now_iso8601",
+    "parse_iso8601",
+    "format_iso8601",
+    # Serialization
+    "write_jsonlines",
+    "read_jsonlines",
+    "stream_jsonlines",
+    "append_jsonlines",
+    "SerializationError",
+    "DeserializationError",
+    # Metadata
+    "MetadataTracker",
+    "ProvenanceRecord",
+    "ProcessingRecord",
+    # Repository
+    "Repository",
+    # Validation
+    "ValidationReport",
+    "validate_jsonlines_file",
+    "validate_uuid_references",
+    "validate_provenance_chain",
+]

bead/data/base.py

@@ -0,0 +1,87 @@
+"""Base Pydantic model for all bead objects.
+
+This module provides BeadBaseModel, the foundational Pydantic v2 model that all
+bead data models should inherit from. It provides automatic ID generation,
+timestamp tracking, and versioning.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from bead.data.identifiers import generate_uuid
+from bead.data.timestamps import now_iso8601
+
+# Type alias for JSON-serializable values (recursive type)
+type JsonValue = (
+    str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
+)
+
+
+class BeadBaseModel(BaseModel):
+    """Base Pydantic model for all bead objects.
+
+    This model provides foundational fields and configuration that all bead
+    data models inherit. It includes automatic ID generation using UUIDv7,
+    timestamp tracking for creation and modification, versioning, and metadata.
+
+    Attributes
+    ----------
+    id : UUID
+        Unique identifier (UUIDv7) automatically generated on creation
+    created_at : datetime
+        UTC timestamp when object was created
+    modified_at : datetime
+        UTC timestamp when object was last modified
+    version : str
+        Version string for schema versioning (default: "1.0.0")
+    metadata : dict[str, JsonValue]
+        Optional metadata dictionary for arbitrary key-value pairs
+
+    Examples
+    --------
+    >>> class MyModel(BeadBaseModel):
+    ...     name: str
+    ...     value: int
+    >>> obj = MyModel(name="test", value=42)
+    >>> obj.id  # doctest: +SKIP
+    UUID('...')
+    >>> obj.version
+    '1.0.0'
+    >>> obj.update_modified_time()
+    >>> obj.modified_at > obj.created_at
+    True
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",  # Disallow extra fields not defined in model
+        frozen=False,  # Allow modification after creation
+        validate_assignment=True,  # Validate when assigning to fields
+    )
+
+    id: UUID = Field(default_factory=generate_uuid)
+    created_at: datetime = Field(default_factory=now_iso8601)
+    modified_at: datetime = Field(default_factory=now_iso8601)
+    version: str = Field(default="1.0.0")
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+    def update_modified_time(self) -> None:
+        """Update the modified_at timestamp to current UTC time.
+
+        This method should be called whenever the object is modified to
+        maintain accurate modification tracking.
+
+        Examples
+        --------
+        >>> obj = BeadBaseModel()
+        >>> original_time = obj.modified_at
+        >>> import time
+        >>> time.sleep(0.01)  # Small delay to ensure different timestamp
+        >>> obj.update_modified_time()
+        >>> obj.modified_at > original_time
+        True
+        """
+        self.modified_at = now_iso8601()

bead/data/identifiers.py

@@ -0,0 +1,97 @@
+"""UUIDv7 generation and utilities for bead package.
+
+This module provides functions for generating time-ordered UUIDv7 identifiers,
+extracting timestamps from them, and validating UUID versions.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+import uuid_utils
+
+
+def generate_uuid() -> UUID:
+    """Generate a time-ordered UUIDv7.
+
+    UUIDv7 is a time-ordered UUID format that embeds a timestamp in the first
+    48 bits, making UUIDs sortable by creation time. This is useful for
+    maintaining chronological ordering of database records.
+
+    Returns
+    -------
+    UUID
+        A newly generated UUIDv7 with embedded timestamp
+
+    Examples
+    --------
+    >>> uuid1 = generate_uuid()
+    >>> uuid2 = generate_uuid()
+    >>> uuid1 < uuid2  # uuids are time-ordered
+    True
+    """
+    # convert uuid_utils.UUID to standard Python UUID for Pydantic compatibility
+    uuid7 = uuid_utils.uuid7()
+    return UUID(str(uuid7))
+
+
+def extract_timestamp(uuid: UUID) -> int:
+    """Extract timestamp in milliseconds from a UUIDv7.
+
+    The timestamp is stored in the first 48 bits of the UUID and represents
+    milliseconds since Unix epoch (January 1, 1970 00:00:00 UTC).
+
+    Parameters
+    ----------
+    uuid
+        The UUIDv7 to extract timestamp from.
+
+    Returns
+    -------
+    int
+        Timestamp in milliseconds since Unix epoch
+
+    Examples
+    --------
+    >>> import time
+    >>> uuid = generate_uuid()
+    >>> timestamp = extract_timestamp(uuid)
+    >>> current_time = int(time.time() * 1000)
+    >>> abs(timestamp - current_time) < 1000  # within 1 second
+    True
+    """
+    # UUIDv7 stores timestamp in first 48 bits (6 bytes);
+    # UUID.bytes gives us the UUID as 16 bytes;
+    # extract first 6 bytes and convert to milliseconds
+    timestamp_bytes = uuid.bytes[:6]
+    timestamp_ms = int.from_bytes(timestamp_bytes, byteorder="big")
+    return timestamp_ms
+
+
+def is_valid_uuid7(uuid: UUID) -> bool:
+    """Check if a UUID is a valid UUIDv7.
+
+    Validates that the UUID has version 7 by checking the version bits
+    (bits 48-51) which should be 0111 (7).
+
+    Parameters
+    ----------
+    uuid
+        The UUID to validate.
+
+    Returns
+    -------
+    bool
+        True if the UUID is version 7, False otherwise
+
+    Examples
+    --------
+    >>> uuid7 = generate_uuid()
+    >>> is_valid_uuid7(uuid7)
+    True
+    >>> from uuid import uuid4
+    >>> uuid4_val = uuid4()
+    >>> is_valid_uuid7(uuid4_val)
+    False
+    """
+    return uuid.version == 7

bead/data/language_codes.py

@@ -0,0 +1,61 @@
+"""ISO 639 language code validation and utilities."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from langcodes import Language
+from langcodes.tag_parser import LanguageTagError
+from pydantic import AfterValidator, Field
+
+
+def validate_iso639_code(code: str | None) -> str | None:
+    """Validate language code against ISO 639-1 or ISO 639-3.
+
+    Parameters
+    ----------
+    code
+        Language code to validate (e.g., "en", "eng", "ko", "kor").
+
+    Returns
+    -------
+    str | None
+        Normalized language code (converted to ISO 639-3 if valid).
+
+    Raises
+    ------
+    ValueError
+        If code is not a valid ISO 639 language code.
+
+    Examples
+    --------
+    >>> validate_iso639_code("en")
+    'eng'
+    >>> validate_iso639_code("eng")
+    'eng'
+    >>> validate_iso639_code("ko")
+    'kor'
+    >>> validate_iso639_code(None)
+    None
+    >>> validate_iso639_code("invalid")
+    Traceback (most recent call last):
+        ...
+    ValueError: Invalid language code: 'invalid'
+    """
+    if code is None:
+        return None
+
+    try:
+        # parse and normalize to ISO 639-3
+        lang = Language.get(code)
+        return lang.to_alpha3()
+    except (LanguageTagError, LookupError) as e:
+        raise ValueError(f"Invalid language code: {code!r}") from e
+
+
+# type alias for language codes
+LanguageCode = Annotated[
+    str | None,
+    AfterValidator(validate_iso639_code),
+    Field(description="ISO 639-1 or ISO 639-3 language code"),
+]

bead/data/metadata.py

@@ -0,0 +1,270 @@
+"""Metadata tracking models for provenance and processing history.
+
+This module provides models for tracking provenance chains and processing history
+for all bead objects. This enables full traceability of data transformations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import Field
+
+from bead.data.base import BeadBaseModel, JsonValue
+from bead.data.timestamps import now_iso8601
+
+
+def _empty_provenance_list() -> list[ProvenanceRecord]:
+    """Create empty provenance list."""
+    return []
+
+
+def _empty_processing_list() -> list[ProcessingRecord]:
+    """Create empty processing list."""
+    return []
+
+
+class ProvenanceRecord(BeadBaseModel):
+    """Record of a provenance relationship between objects.
+
+    Tracks a single parent-child relationship in the provenance chain, including
+    what the parent was, its type, and the nature of the relationship.
+
+    Attributes
+    ----------
+    parent_id : UUID
+        UUID of the parent object in the provenance chain
+    parent_type : str
+        Type name of the parent object (e.g., "LexicalItem", "Template")
+    relationship : str
+        Type of relationship (e.g., "derived_from", "filled_from", "generated_from")
+    timestamp : datetime
+        When this relationship was established (UTC with timezone)
+
+    Examples
+    --------
+    >>> from uuid import uuid4
+    >>> parent_id = uuid4()
+    >>> record = ProvenanceRecord(
+    ...     parent_id=parent_id,
+    ...     parent_type="Template",
+    ...     relationship="filled_from"
+    ... )
+    >>> record.parent_type
+    'Template'
+    >>> record.timestamp is not None
+    True
+    """
+
+    parent_id: UUID
+    parent_type: str
+    relationship: str
+    timestamp: datetime = Field(default_factory=now_iso8601)
+
+
+class ProcessingRecord(BeadBaseModel):
+    """Record of a processing operation applied to an object.
+
+    Tracks a single operation in the processing history, including the operation
+    name, parameters used, when it was performed, and who/what performed it.
+
+    Attributes
+    ----------
+    operation : str
+        Name of the operation (e.g., "fill_template", "apply_constraint", "filter")
+    parameters : dict[str, JsonValue]
+        Parameters passed to the operation (default: empty dict)
+    timestamp : datetime
+        When the operation was performed (UTC with timezone)
+    operator : str | None
+        Who/what performed the operation (e.g., "TemplateFiller-v1.0", user ID)
+        (default: None)
+
+    Examples
+    --------
+    >>> record = ProcessingRecord(
+    ...     operation="fill_template",
+    ...     parameters={"strategy": "exhaustive", "max_items": 100},
+    ...     operator="TemplateFiller-v1.0"
+    ... )
+    >>> record.operation
+    'fill_template'
+    >>> record.parameters["strategy"]
+    'exhaustive'
+    >>> record.timestamp is not None
+    True
+    """
+
+    operation: str
+    parameters: dict[str, JsonValue] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=now_iso8601)
+    operator: str | None = None
+
+
+class MetadataTracker(BeadBaseModel):
+    """Metadata tracking for provenance and processing history.
+
+    Tracks both provenance (where data came from) and processing history
+    (what operations were applied) for complete data lineage.
+
+    Attributes
+    ----------
+    provenance : list[ProvenanceRecord]
+        Chain of provenance relationships (default: empty list)
+    processing_history : list[ProcessingRecord]
+        History of processing operations (default: empty list)
+    custom_metadata : dict[str, JsonValue]
+        Custom metadata fields (default: empty dict)
+
+    Examples
+    --------
+    >>> from uuid import uuid4
+    >>> tracker = MetadataTracker()
+    >>> parent_id = uuid4()
+    >>> tracker.add_provenance(parent_id, "Template", "filled_from")
+    >>> tracker.add_processing("fill_template", {"strategy": "exhaustive"})
+    >>> len(tracker.provenance)
+    1
+    >>> len(tracker.processing_history)
+    1
+    >>> chain = tracker.get_provenance_chain()
+    >>> len(chain)
+    1
+    """
+
+    provenance: list[ProvenanceRecord] = Field(default_factory=_empty_provenance_list)
+    processing_history: list[ProcessingRecord] = Field(
+        default_factory=_empty_processing_list
+    )
+    custom_metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+    def add_provenance(
+        self, parent_id: UUID, parent_type: str, relationship: str
+    ) -> None:
+        """Add a provenance record to the chain.
+
+        Creates a new provenance record and adds it to the provenance list.
+        The timestamp is automatically set to the current time.
+
+        Parameters
+        ----------
+        parent_id : UUID
+            UUID of the parent object
+        parent_type : str
+            Type name of the parent object (e.g., "Template", "LexicalItem")
+        relationship : str
+            Type of relationship (e.g., "derived_from", "filled_from")
+
+        Examples
+        --------
+        >>> from uuid import uuid4
+        >>> tracker = MetadataTracker()
+        >>> parent_id = uuid4()
+        >>> tracker.add_provenance(parent_id, "Template", "filled_from")
+        >>> len(tracker.provenance)
+        1
+        >>> tracker.provenance[0].parent_type
+        'Template'
+        """
+        record = ProvenanceRecord(
+            parent_id=parent_id, parent_type=parent_type, relationship=relationship
+        )
+        self.provenance.append(record)
+
+    def add_processing(
+        self,
+        operation: str,
+        parameters: dict[str, JsonValue] | None = None,
+        operator: str | None = None,
+    ) -> None:
+        """Add a processing record to the history.
+
+        Creates a new processing record and adds it to the processing history.
+        The timestamp is automatically set to the current time.
+
+        Parameters
+        ----------
+        operation : str
+            Name of the operation performed
+        parameters : dict[str, JsonValue] | None, optional
+            Parameters passed to the operation (default: None, which creates empty dict)
+        operator : str | None, optional
+            Who/what performed the operation (default: None)
+
+        Examples
+        --------
+        >>> tracker = MetadataTracker()
+        >>> tracker.add_processing("fill_template", {"strategy": "exhaustive"})
+        >>> len(tracker.processing_history)
+        1
+        >>> tracker.processing_history[0].operation
+        'fill_template'
+        >>> tracker.add_processing("filter", operator="FilterSystem-v2.0")
+        >>> tracker.processing_history[1].operator
+        'FilterSystem-v2.0'
+        """
+        if parameters is None:
+            parameters = {}
+        record = ProcessingRecord(
+            operation=operation, parameters=parameters, operator=operator
+        )
+        self.processing_history.append(record)
+
+    def get_provenance_chain(self) -> list[UUID]:
+        """Get the full provenance chain as a list of parent UUIDs.
+
+        Returns the parent UUIDs in the order they were added to the provenance list.
+
+        Returns
+        -------
+        list[UUID]
+            List of parent UUIDs in chronological order
+
+        Examples
+        --------
+        >>> from uuid import uuid4
+        >>> tracker = MetadataTracker()
+        >>> parent1 = uuid4()
+        >>> parent2 = uuid4()
+        >>> tracker.add_provenance(parent1, "Template", "filled_from")
+        >>> tracker.add_provenance(parent2, "LexicalItem", "derived_from")
+        >>> chain = tracker.get_provenance_chain()
+        >>> len(chain)
+        2
+        >>> chain[0] == parent1
+        True
+        """
+        return [record.parent_id for record in self.provenance]
+
+    def get_recent_processing(self, n: int = 5) -> list[ProcessingRecord]:
+        """Get the N most recent processing records.
+
+        Returns the most recent processing records, up to N records. If there
+        are fewer than N records, returns all available records.
+
+        Parameters
+        ----------
+        n : int, optional
+            Number of recent records to return (default: 5)
+
+        Returns
+        -------
+        list[ProcessingRecord]
+            List of up to N most recent processing records, newest first
+
+        Examples
+        --------
+        >>> tracker = MetadataTracker()
+        >>> tracker.add_processing("operation1")
+        >>> tracker.add_processing("operation2")
+        >>> tracker.add_processing("operation3")
+        >>> recent = tracker.get_recent_processing(n=2)
+        >>> len(recent)
+        2
+        >>> recent[0].operation
+        'operation3'
+        >>> recent[1].operation
+        'operation2'
+        """
+        return list(reversed(self.processing_history[-n:]))

bead/data/range.py

@@ -0,0 +1,123 @@
+"""Generic numeric range model with validation.
+
+Provides a reusable Range[T] model for representing validated numeric ranges
+with bounds checking, containment testing, and value clamping.
+"""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+T = TypeVar("T", int, float)
+
+
+class Range(BaseModel, Generic[T]):  # noqa: UP046 - Pydantic requires Generic[T]
+    """A validated numeric range with inclusive bounds.
+
+    Provides a generic container for numeric ranges with automatic validation
+    that min < max. Supports containment testing and value clamping.
+
+    Attributes
+    ----------
+    min
+        Minimum value (inclusive).
+    max
+        Maximum value (inclusive).
+
+    Examples
+    --------
+    >>> scale = Range[int](min=1, max=7)
+    >>> scale.contains(4)
+    True
+    >>> scale.contains(0)
+    False
+    >>> scale.clamp(10)
+    7
+
+    >>> probability = Range[float](min=0.0, max=1.0)
+    >>> probability.contains(0.5)
+    True
+    >>> probability.clamp(-0.1)
+    0.0
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+    )
+
+    min: T
+    max: T
+
+    @model_validator(mode="after")
+    def validate_order(self) -> Range[T]:
+        """Validate that min is strictly less than max.
+
+        Returns
+        -------
+        Range[T]
+            The validated range instance.
+
+        Raises
+        ------
+        ValueError
+            If min is greater than or equal to max.
+        """
+        if self.min >= self.max:
+            raise ValueError(f"min ({self.min}) must be less than max ({self.max})")
+        return self
+
+    def contains(self, value: T) -> bool:
+        """Check if a value is within the range (inclusive).
+
+        Parameters
+        ----------
+        value
+            The value to check.
+
+        Returns
+        -------
+        bool
+            True if min <= value <= max, False otherwise.
+
+        Examples
+        --------
+        >>> r = Range[int](min=1, max=5)
+        >>> r.contains(3)
+        True
+        >>> r.contains(1)
+        True
+        >>> r.contains(5)
+        True
+        >>> r.contains(6)
+        False
+        """
+        return self.min <= value <= self.max
+
+    def clamp(self, value: T) -> T:
+        """Clamp a value to the range bounds.
+
+        Parameters
+        ----------
+        value
+            The value to clamp.
+
+        Returns
+        -------
+        T
+            The clamped value (min if value < min, max if value > max,
+            otherwise the original value).
+
+        Examples
+        --------
+        >>> r = Range[int](min=1, max=5)
+        >>> r.clamp(3)
+        3
+        >>> r.clamp(0)
+        1
+        >>> r.clamp(10)
+        5
+        """
+        return max(self.min, min(self.max, value))