lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/__init__.py

@@ -0,0 +1,84 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "1.0.0-alpha3"  # pragma: no cover
+
+from . import ln as ln
+from .base import (
+    Broadcaster,
+    Edge,
+    EdgeCondition,
+    Element,
+    Event,
+    EventBus,
+    EventStatus,
+    Execution,
+    Flow,
+    Graph,
+    Node,
+    Pile,
+    Progression,
+)
+from .errors import LionherdError
+from .libs import (
+    concurrency as concurrency,
+    schema_handlers as schema_handlers,
+    string_handlers as string_handlers,
+)
+from .types import (
+    CommonMeta,
+    DataClass,
+    Enum,
+    MaybeSentinel,
+    MaybeUndefined,
+    MaybeUnset,
+    Meta,
+    ModelConfig,
+    Operable,
+    Params,
+    Spec,
+    Undefined,
+    UndefinedType,
+    Unset,
+    UnsetType,
+    is_sentinel,
+    not_sentinel,
+)
+
+__all__ = (
+    "Broadcaster",
+    "CommonMeta",
+    "DataClass",
+    "Edge",
+    "EdgeCondition",
+    "Element",
+    "Enum",
+    "Event",
+    "EventBus",
+    "EventStatus",
+    "Execution",
+    "Flow",
+    "Graph",
+    "LionherdError",
+    "MaybeSentinel",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "Meta",
+    "ModelConfig",
+    "Node",
+    "Operable",
+    "Params",
+    "Pile",
+    "Progression",
+    "Spec",
+    "Undefined",
+    "UndefinedType",
+    "Unset",
+    "UnsetType",
+    "concurrency",
+    "is_sentinel",
+    "ln",
+    "not_sentinel",
+    "schema_handlers",
+    "string_handlers",
+)

lionherd_core/base/__init__.py

@@ -0,0 +1,30 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from .broadcaster import Broadcaster
+from .element import Element
+from .event import Event, EventStatus, Execution
+from .eventbus import EventBus, Handler
+from .flow import Flow
+from .graph import Edge, EdgeCondition, Graph
+from .node import NODE_REGISTRY, Node
+from .pile import Pile
+from .progression import Progression
+
+__all__ = [
+    "NODE_REGISTRY",
+    "Broadcaster",
+    "Edge",
+    "EdgeCondition",
+    "Element",
+    "Event",
+    "EventBus",
+    "EventStatus",
+    "Execution",
+    "Flow",
+    "Graph",
+    "Handler",
+    "Node",
+    "Pile",
+    "Progression",
+]

lionherd_core/base/_utils.py

@@ -0,0 +1,295 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import contextlib
+import datetime as dt
+import types
+from collections.abc import Callable
+from enum import Enum
+from functools import wraps
+from typing import Any, Union, get_args, get_origin
+from uuid import UUID
+
+from ..protocols import Observable, Serializable
+
+__all__ = (
+    "async_synchronized",
+    "coerce_created_at",
+    "extract_types",
+    "get_element_serializer_config",
+    "get_json_serializable",
+    "load_type_from_string",
+    "synchronized",
+    "to_uuid",
+)
+
+
+def synchronized(func: Callable) -> Callable:
+    """Decorator for thread-safe method execution.
+
+    Executes method within self._lock context. The class must have a _lock
+    attribute (typically threading.RLock()).
+
+    Example:
+        @synchronized
+        def append(self, item):
+            self.items.append(item)
+    """
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        with self._lock:
+            return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+def async_synchronized(func: Callable) -> Callable:
+    """Decorator for async-safe method execution.
+
+    Executes async method within self._async_lock context. The class must have a
+    _async_lock attribute (typically asyncio.Lock()).
+
+    Example:
+        @async_synchronized
+        async def append_async(self, item):
+            self.items.append(item)
+    """
+
+    @wraps(func)
+    async def wrapper(self, *args, **kwargs):
+        async with self._async_lock:
+            return await func(self, *args, **kwargs)
+
+    return wrapper
+
+
+_TYPE_CACHE: dict[str, type] = {}
+
+
+def load_type_from_string(type_str: str) -> type:
+    """Load type from fully qualified module path string.
+
+    Args:
+        type_str: Fully qualified type path (e.g., 'lionherd.base.Node')
+
+    Returns:
+        Type class
+
+    Raises:
+        ValueError: If type string is invalid or type cannot be loaded
+
+    Example:
+        >>> load_type_from_string("lionherd.base.Node")
+        <class 'lionherd.base.node.Node'>
+    """
+    # Check cache first
+    if type_str in _TYPE_CACHE:
+        return _TYPE_CACHE[type_str]
+
+    if not isinstance(type_str, str):
+        raise ValueError(f"Expected string, got {type(type_str)}")
+
+    if "." not in type_str:
+        raise ValueError(f"Invalid type path (no module): {type_str}")
+
+    try:
+        module_path, class_name = type_str.rsplit(".", 1)
+
+        # Import module using importlib for correct behavior
+        import importlib
+
+        module = importlib.import_module(module_path)
+        if module is None:
+            raise ImportError(f"Module '{module_path}' not found")
+
+        type_class = getattr(module, class_name)
+
+        # Validate it's actually a type
+        if not isinstance(type_class, type):
+            raise ValueError(f"'{type_str}' is not a type")
+
+        # Cache result
+        _TYPE_CACHE[type_str] = type_class
+
+        return type_class
+
+    except (ValueError, ImportError, AttributeError) as e:
+        raise ValueError(f"Failed to load type '{type_str}': {e}") from e
+
+
+def extract_types(item_type: Any) -> set[type]:
+    """Extract types from union types or convert single types to set.
+
+    Handles Python 3.10+ pipe syntax (int | str), typing.Union, lists, and sets.
+
+    Args:
+        item_type: Single type, list of types, set of types, or Union type
+
+    Returns:
+        Set of extracted types
+
+    Examples:
+        extract_types(int) -> {int}
+        extract_types([int, str]) -> {int, str}
+        extract_types(int | str) -> {int, str}
+        extract_types(Union[int, str]) -> {int, str}
+    """
+
+    # Helper to check if type is a union
+    def is_union(t):
+        origin = get_origin(t)
+        # Python 3.10+ pipe syntax (Element | Node) creates types.UnionType
+        # typing.Union creates Union origin
+        return origin is Union or isinstance(t, types.UnionType)
+
+    extracted: set[type] = set()
+
+    # Already a set
+    if isinstance(item_type, set):
+        # Check if any items in set are unions and extract them
+        for t in item_type:
+            if is_union(t):
+                extracted.update(get_args(t))
+            else:
+                extracted.add(t)
+        return extracted
+
+    # List of types
+    if isinstance(item_type, list):
+        for t in item_type:
+            if is_union(t):
+                extracted.update(get_args(t))
+            else:
+                extracted.add(t)
+        return extracted
+
+    # Union type (int | str or Union[int, str])
+    if is_union(item_type):
+        return set(get_args(item_type))
+
+    # Single type
+    return {item_type}
+
+
+def to_uuid(value: Any) -> UUID:
+    """Convert various ID representations to UUID.
+
+    Args:
+        value: UUID, UUID string, or Observable object with id property
+
+    Returns:
+        UUID instance
+
+    Raises:
+        ValueError: If value cannot be converted to UUID or Observable.id is callable
+
+    Examples:
+        >>> to_uuid(UUID("12345678-1234-5678-1234-567812345678"))
+        UUID('12345678-1234-5678-1234-567812345678')
+        >>> to_uuid("12345678-1234-5678-1234-567812345678")
+        UUID('12345678-1234-5678-1234-567812345678')
+    """
+    if isinstance(value, Observable):
+        id_value = value.id
+        if callable(id_value):
+            raise ValueError(
+                f"Observable.id must be a property, not a method. Got callable: {type(value).__name__}.id()"
+            )
+        return id_value
+    if isinstance(value, UUID):
+        return value
+    if isinstance(value, str):
+        return UUID(value)
+    raise ValueError("Cannot get ID from item.")
+
+
+def coerce_created_at(v) -> dt.datetime:
+    """Coerce datetime, timestamp, or ISO string to UTC-aware datetime.
+
+    Args:
+        v: datetime, float timestamp, or ISO 8601 string
+
+    Returns:
+        UTC-aware datetime
+
+    Raises:
+        ValueError: If cannot coerce to datetime
+    """
+    # datetime object
+    if isinstance(v, dt.datetime):
+        if v.tzinfo is None:
+            return v.replace(tzinfo=dt.UTC)
+        return v
+
+    # Float timestamp (seconds since epoch)
+    if isinstance(v, (int, float)):
+        return dt.datetime.fromtimestamp(v, tz=dt.UTC)
+
+    if isinstance(v, str):
+        # Try parsing as float timestamp
+        with contextlib.suppress(ValueError):
+            timestamp = float(v)
+            return dt.datetime.fromtimestamp(timestamp, tz=dt.UTC)
+        # Try parsing as ISO format
+        with contextlib.suppress(ValueError):
+            return dt.datetime.fromisoformat(v)
+
+        raise ValueError(f"String '{v}' is neither a valid timestamp nor ISO format datetime")
+
+    raise ValueError(
+        f"created_at must be datetime, timestamp (int/float), or string, got {type(v).__name__}"
+    )
+
+
+_SIMPLE_TYPE = (str, bytes, bytearray, int, float, type(None), Enum)
+
+
+def get_json_serializable(data) -> dict[str, Any] | Any:
+    """Serialize to dict."""
+    from ..ln import json_dumpb, to_dict
+    from ..types._sentinel import Unset
+
+    if data is Unset:
+        return Unset
+
+    if isinstance(data, _SIMPLE_TYPE):
+        return data
+
+    with contextlib.suppress(Exception):
+        # Check if response is JSON serializable
+        json_dumpb(data)
+        return data
+
+    with contextlib.suppress(Exception):
+        # Attempt to force convert to dict recursively
+        d_ = to_dict(
+            data,
+            recursive=True,
+            recursive_python_only=False,
+            use_enum_values=True,
+        )
+        json_dumpb(d_)
+        return d_
+
+    return Unset
+
+
+def get_element_serializer_config() -> tuple[list, dict]:
+    """Get serializer config for Element.to_json().
+
+    Returns:
+        Tuple of (order, additional) for get_orjson_default():
+        - order: [Serializable, BaseModel]
+        - additional: {type: serializer_func}
+    """
+    from pydantic import BaseModel
+
+    order = [Serializable, BaseModel]
+
+    additional = {
+        Serializable: lambda o: o.to_dict(),
+        BaseModel: lambda o: o.model_dump(mode="json"),
+    }
+
+    return order, additional

lionherd_core/base/broadcaster.py

@@ -0,0 +1,128 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import logging
+import weakref
+from collections.abc import Awaitable, Callable
+from typing import Any, ClassVar
+
+from ..libs.concurrency import is_coro_func
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Broadcaster"]
+
+
+class Broadcaster:
+    """Singleton pub/sub for O(1) memory event broadcasting.
+
+    Memory Management:
+        Uses weakref for automatic subscriber cleanup when callback objects are
+        garbage collected. Prevents memory leaks in long-running services with
+        dynamic agent/tenant lifecycles.
+    """
+
+    _instance: ClassVar[Broadcaster | None] = None
+    _subscribers: ClassVar[
+        list[weakref.ref[Callable[[Any], None] | Callable[[Any], Awaitable[None]]]]
+    ] = []
+    _event_type: ClassVar[type]
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def subscribe(cls, callback: Callable[[Any], None] | Callable[[Any], Awaitable[None]]) -> None:
+        """Add subscriber callback.
+
+        Callbacks stored as weak references for automatic cleanup when callback
+        objects are garbage collected. Prevents cross-tenant/session leaks.
+
+        Supports both regular callables and bound methods via WeakMethod.
+        """
+        # Check if callback already subscribed (compare actual callbacks, not weakrefs)
+        for weak_ref in cls._subscribers:
+            if weak_ref() is callback:
+                return  # Already subscribed
+
+        # Store as weakref for automatic cleanup
+        # Use WeakMethod for bound methods, weakref for regular callables
+        if hasattr(callback, "__self__"):
+            weak_callback = weakref.WeakMethod(callback)
+        else:
+            weak_callback = weakref.ref(callback)
+        cls._subscribers.append(weak_callback)
+
+    @classmethod
+    def unsubscribe(
+        cls, callback: Callable[[Any], None] | Callable[[Any], Awaitable[None]]
+    ) -> None:
+        """Remove subscriber callback."""
+        # Find and remove weakref that points to this callback
+        for weak_ref in list(cls._subscribers):
+            if weak_ref() is callback:
+                cls._subscribers.remove(weak_ref)
+                return
+
+    @classmethod
+    def _cleanup_dead_refs(cls) -> list[Callable[[Any], None] | Callable[[Any], Awaitable[None]]]:
+        """Remove garbage-collected callbacks and return list of live callbacks.
+
+        Lazily cleans up dead weakrefs during normal operations (broadcast/get_subscriber_count).
+        Updates ClassVar subscription list in-place to preserve identity.
+
+        Note: Uses in-place slice assignment (cls._subscribers[:] = alive_refs) rather than
+        reassignment to maintain ClassVar identity across subclasses.
+
+        Returns:
+            List of live callback callables (weakrefs resolved).
+        """
+        callbacks = []
+        alive_refs = []
+
+        for weak_ref in cls._subscribers:
+            callback = weak_ref()
+            if callback is not None:
+                callbacks.append(callback)
+                alive_refs.append(weak_ref)
+
+        # In-place update to maintain ClassVar identity
+        cls._subscribers[:] = alive_refs
+
+        return callbacks
+
+    @classmethod
+    async def broadcast(cls, event: Any) -> None:
+        """Broadcast event to all subscribers.
+
+        Dead weakrefs are lazily cleaned up during broadcast.
+        """
+        if not isinstance(event, cls._event_type):
+            raise ValueError(f"Event must be of type {cls._event_type.__name__}")
+
+        callbacks = cls._cleanup_dead_refs()
+
+        # Broadcast to live callbacks
+        for callback in callbacks:
+            try:
+                if is_coro_func(callback):
+                    result = callback(event)
+                    if result is not None:  # Coroutine functions return awaitable
+                        await result
+                else:
+                    callback(event)
+            except Exception as e:
+                logger.error(f"Error in subscriber callback: {e}", exc_info=True)
+
+    @classmethod
+    def get_subscriber_count(cls) -> int:
+        """Get live subscriber count (excludes garbage-collected callbacks).
+
+        Note: This method mutates state by cleaning up dead weakrefs as a side effect.
+        """
+        callbacks = cls._cleanup_dead_refs()
+        return len(callbacks)