lionagi 0.18.1__py3-none-any.whl → 0.18.2__py3-none-any.whl

lionagi/__init__.py

@@ -5,94 +5,137 @@ import logging
 from typing import TYPE_CHECKING
 
 from . import ln as ln
+from .ln.types import DataClass, Operable, Params, Spec, Undefined, Unset
 from .version import __version__
 
 if TYPE_CHECKING:
     from pydantic import BaseModel, Field
 
     from . import _types as types
+    from .models.field_model import FieldModel
+    from .models.operable_model import OperableModel
     from .operations.builder import OperationGraphBuilder as Builder
     from .operations.node import Operation
     from .protocols.action.manager import load_mcp_tools
+    from .protocols.types import (
+        Edge,
+        Element,
+        Event,
+        Graph,
+        Node,
+        Pile,
+        Progression,
+    )
+    from .service.broadcaster import Broadcaster
+    from .service.hooks import HookedEvent, HookRegistry
     from .service.imodel import iModel
     from .session.session import Branch, Session
 
-
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
 
-# Module-level lazy loading cache
 _lazy_imports = {}
 
 
+def _get_obj(name: str, module: str):
+    global _lazy_imports
+    from lionagi.ln import import_module
+
+    obj_ = import_module("lionagi", module_name=module, import_name=name)
+
+    _lazy_imports[name] = obj_
+    return obj_
+
+
 def __getattr__(name: str):
-    """Lazy loading for expensive imports."""
+    global _lazy_imports
     if name in _lazy_imports:
         return _lazy_imports[name]
 
-    # Lazy load core components
-    if name == "Session":
-        from .session.session import Session
-
-        _lazy_imports[name] = Session
-        return Session
-    elif name == "Branch":
-        from .session.session import Branch
-
-        _lazy_imports[name] = Branch
-        return Branch
-    # Lazy load Pydantic components
-    elif name == "BaseModel":
-        from pydantic import BaseModel
-
-        _lazy_imports[name] = BaseModel
-        return BaseModel
-    elif name == "Field":
-        from pydantic import Field
-
-        _lazy_imports[name] = Field
-        return Field
-    # Lazy load operations
-    elif name == "Operation":
-        from .operations.node import Operation
-
-        _lazy_imports[name] = Operation
-        return Operation
-    elif name == "iModel":
-        from .service.imodel import iModel
-
-        _lazy_imports[name] = iModel
-        return iModel
-    elif name == "types":
-        from . import _types as types
-
-        _lazy_imports["types"] = types
-        return types
-    elif name == "Builder":
-        from .operations.builder import OperationGraphBuilder as Builder
-
-        _lazy_imports["Builder"] = Builder
-        return Builder
-    elif name == "load_mcp_tools":
-        from .protocols.action.manager import load_mcp_tools
-
-        _lazy_imports["load_mcp_tools"] = load_mcp_tools
-        return load_mcp_tools
-
+    match name:
+        case "Session":
+            return _get_obj("Session", "session.session")
+        case "Branch":
+            return _get_obj("Branch", "session.branch")
+        case "iModel":
+            return _get_obj("iModel", "service.imodel")
+        case "Builder":
+            return _get_obj("OperationGraphBuilder", "operations.builder")
+        case "Operation":
+            return _get_obj("Operation", "operations.node")
+        case "load_mcp_tools":
+            return _get_obj("load_mcp_tools", "protocols.action.manager")
+        case "FieldModel":
+            return _get_obj("FieldModel", "models.field_model")
+        case "OperableModel":
+            return _get_obj("OperableModel", "models.operable_model")
+        case "Element":
+            return _get_obj("Element", "protocols.generic.element")
+        case "Pile":
+            return _get_obj("Pile", "protocols.generic.pile")
+        case "Progression":
+            return _get_obj("Progression", "protocols.generic.progression")
+        case "Node":
+            return _get_obj("Node", "protocols.graph.node")
+        case "Edge":
+            return _get_obj("Edge", "protocols.graph.edge")
+        case "Graph":
+            return _get_obj("Graph", "protocols.graph.graph")
+        case "Event":
+            return _get_obj("Event", "protocols.generic.event")
+        case "HookRegistry":
+            return _get_obj("HookRegistry", "service.hooks.hook_registry")
+        case "HookedEvent":
+            return _get_obj("HookedEvent", "service.hooks.hooked_event")
+        case "Broadcaster":
+            return _get_obj("Broadcaster", "service.broadcaster")
+        case "BaseModel":
+            from pydantic import BaseModel
+
+            _lazy_imports["BaseModel"] = BaseModel
+            return BaseModel
+        case "Field":
+            from pydantic import Field
+
+            _lazy_imports["Field"] = Field
+            return Field
+        case "types":
+            from . import _types as types
+
+            _lazy_imports["types"] = types
+            return types
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
 
 __all__ = (
-    "Session",
-    "Branch",
-    "iModel",
-    "types",
     "__version__",
     "BaseModel",
-    "Field",
-    "logger",
+    "Branch",
+    "Broadcaster",
     "Builder",
+    "DataClass",
+    "Edge",
+    "Element",
+    "Event",
+    "Field",
+    "FieldModel",
+    "Graph",
+    "HookRegistry",
+    "HookedEvent",
+    "Node",
+    "Operable",
+    "OperableModel",
     "Operation",
-    "load_mcp_tools",
+    "Params",
+    "Pile",
+    "Progression",
+    "Session",
+    "Spec",
+    "Undefined",
+    "Unset",
+    "iModel",
     "ln",
+    "load_mcp_tools",
+    "logger",
+    "types",
 )

lionagi/adapters/spec_adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Spec adapters for converting Spec objects to framework-specific field definitions."""
+
+from ._protocol import SpecAdapter
+from .pydantic_field import PydanticSpecAdapter
+
+__all__ = (
+    "SpecAdapter",
+    "PydanticSpecAdapter",
+)

lionagi/adapters/spec_adapters/_protocol.py

@@ -0,0 +1,236 @@
+"""Abstract base class for Spec adapters.
+
+Adapters convert framework-agnostic Spec objects to framework-specific
+field and model definitions (Pydantic, msgspec, attrs, dataclasses).
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from lionagi.ln.types import Operable, Spec
+
+__all__ = ("SpecAdapter",)
+
+
+class SpecAdapter(ABC):
+    """Base adapter for converting Spec to framework-specific formats.
+
+    Abstract Methods (must implement):
+        - create_field: Spec → framework field
+        - create_model: Operable → framework model class
+        - validate_model: dict → validated model instance
+        - dump_model: model instance → dict
+
+    Concrete Methods (shared):
+        - parse_json: Extract JSON from text
+        - fuzzy_match_fields: Match dict keys to model fields
+        - validate_response: Full validation pipeline
+        - update_model: Update model instance (uses dump_model + validate_model)
+    """
+
+    # ---- Abstract Methods ----
+
+    @classmethod
+    @abstractmethod
+    def create_field(cls, spec: "Spec") -> Any:
+        """Convert Spec to framework-specific field definition.
+
+        Args:
+            spec: Spec object
+
+        Returns:
+            Framework-specific field (FieldInfo, Attribute, Field, etc.)
+        """
+        ...
+
+    @classmethod
+    @abstractmethod
+    def create_model(
+        cls,
+        operable: "Operable",
+        model_name: str,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+        **kwargs: Any,
+    ) -> type:
+        """Generate model class from Operable.
+
+        Args:
+            operable: Operable containing specs
+            model_name: Name for generated model
+            include: Only include these field names
+            exclude: Exclude these field names
+            **kwargs: Framework-specific options
+
+        Returns:
+            Generated model class
+        """
+        ...
+
+    @classmethod
+    @abstractmethod
+    def validate_model(cls, model_cls: type, data: dict) -> Any:
+        """Validate dict data into model instance.
+
+        Framework-agnostic validation hook. Each adapter implements
+        the appropriate validation mechanism:
+            - Pydantic: model_cls.model_validate(data)
+            - msgspec: msgspec.convert(data, type=model_cls)
+            - attrs: model_cls(**data)
+            - dataclasses: model_cls(**data)
+
+        Args:
+            model_cls: Model class
+            data: Dictionary data to validate
+
+        Returns:
+            Validated model instance
+        """
+        ...
+
+    @classmethod
+    @abstractmethod
+    def dump_model(cls, instance: Any) -> dict:
+        """Dump model instance to dictionary.
+
+        Framework-agnostic serialization hook. Each adapter implements
+        the appropriate serialization mechanism:
+            - Pydantic: instance.model_dump()
+            - msgspec: msgspec.to_builtins(instance)
+            - attrs: attr.asdict(instance)
+            - dataclasses: dataclasses.asdict(instance)
+
+        Args:
+            instance: Model instance
+
+        Returns:
+            Dictionary representation
+        """
+        ...
+
+    @classmethod
+    def create_validator(cls, spec: "Spec") -> Any:
+        """Generate framework-specific validators from Spec metadata.
+
+        Args:
+            spec: Spec with validator metadata
+
+        Returns:
+            Framework-specific validator, or None if not supported
+        """
+        return None
+
+    # ---- Concrete Methods (Shared) ----
+
+    @classmethod
+    def parse_json(cls, text: str, fuzzy: bool = True) -> dict | list | Any:
+        """Extract and parse JSON from text.
+
+        Args:
+            text: Raw text potentially containing JSON
+            fuzzy: Use fuzzy parsing (markdown extraction)
+
+        Returns:
+            Parsed JSON object
+        """
+        from lionagi.ln import extract_json
+
+        data = extract_json(text, fuzzy_parse=fuzzy)
+
+        # Unwrap single-item lists/tuples
+        if isinstance(data, (list, tuple)) and len(data) == 1:
+            data = data[0]
+
+        return data
+
+    @classmethod
+    @abstractmethod
+    def fuzzy_match_fields(
+        cls, data: dict, model_cls: type, strict: bool = False
+    ) -> dict:
+        """Match data keys to model fields with fuzzy matching.
+
+        Framework-specific method - each adapter must implement based on how
+        their framework exposes field definitions.
+
+        Args:
+            data: Raw data dictionary
+            model_cls: Target model class
+            strict: If True, raise on unmatched; if False, force coercion
+
+        Returns:
+            Dictionary with keys matched to model fields
+        """
+        ...
+
+    @classmethod
+    def validate_response(
+        cls,
+        text: str,
+        model_cls: type,
+        strict: bool = False,
+        fuzzy_parse: bool = True,
+    ) -> Any | None:
+        """Validate and parse response text into model instance.
+
+        Pipeline: parse_json → fuzzy_match_fields → validate_model
+
+        Args:
+            text: Raw response text
+            model_cls: Target model class
+            strict: If True, raise on errors; if False, return None
+            fuzzy_parse: Use fuzzy JSON parsing
+
+        Returns:
+            Validated model instance, or None if validation fails (strict=False)
+        """
+        try:
+            # Step 1: Parse JSON
+            data = cls.parse_json(text, fuzzy=fuzzy_parse)
+
+            # Step 2: Fuzzy match fields
+            matched_data = cls.fuzzy_match_fields(
+                data, model_cls, strict=strict
+            )
+
+            # Step 3: Validate with framework-specific method
+            instance = cls.validate_model(model_cls, matched_data)
+
+            return instance
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            # Catch validation-related exceptions only
+            # ValueError: JSON/parsing errors, validation failures
+            # TypeError: Type mismatches during validation
+            # KeyError: Missing required fields
+            # AttributeError: Field access errors
+            if strict:
+                raise
+            return None
+
+    @classmethod
+    def update_model(
+        cls,
+        instance: Any,
+        updates: dict,
+        model_cls: type | None = None,
+    ) -> Any:
+        """Update existing model instance with new data.
+
+        Args:
+            instance: Existing model instance
+            updates: Dictionary of updates
+            model_cls: Optional model class (defaults to instance's class)
+
+        Returns:
+            New validated model instance with updates applied
+        """
+        model_cls = model_cls or type(instance)
+
+        # Merge existing data with updates
+        current_data = cls.dump_model(instance)
+        current_data.update(updates)
+
+        # Validate merged data
+        return cls.validate_model(model_cls, current_data)

lionagi/adapters/spec_adapters/pydantic_field.py

@@ -0,0 +1,158 @@
+"""Pydantic adapter for Spec system."""
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+from lionagi.ln.types import Unset, is_sentinel
+
+from ._protocol import SpecAdapter
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+    from pydantic.fields import FieldInfo
+
+    from lionagi.ln.types import Operable, Spec
+
+
+@functools.lru_cache(maxsize=1)
+def _get_pydantic_field_params() -> set[str]:
+    """Get valid Pydantic Field parameters (cached, thread-safe)."""
+    import inspect
+
+    from pydantic import Field as PydanticField
+
+    params = set(inspect.signature(PydanticField).parameters.keys())
+    params.discard("kwargs")
+    return params
+
+
+class PydanticSpecAdapter(SpecAdapter):
+    """Pydantic implementation of SpecAdapter."""
+
+    @classmethod
+    def create_field(cls, spec: "Spec") -> "FieldInfo":
+        """Create a Pydantic FieldInfo object from Spec."""
+        from pydantic import Field as PydanticField
+
+        # Get valid Pydantic Field parameters (cached)
+        pydantic_field_params = _get_pydantic_field_params()
+
+        # Extract metadata for FieldInfo
+        field_kwargs = {}
+
+        if not is_sentinel(spec.metadata, none_as_sentinel=True):
+            for meta in spec.metadata:
+                if meta.key == "default":
+                    # Handle callable defaults as default_factory
+                    if callable(meta.value):
+                        field_kwargs["default_factory"] = meta.value
+                    else:
+                        field_kwargs["default"] = meta.value
+                elif meta.key == "validator":
+                    # Validators are handled separately in create_model
+                    continue
+                elif meta.key in pydantic_field_params:
+                    # Pass through standard Pydantic field attributes
+                    field_kwargs[meta.key] = meta.value
+                elif meta.key in {"nullable", "listable"}:
+                    # These are FieldTemplate markers, don't pass to FieldInfo
+                    pass
+                else:
+                    # Filter out unserializable objects from json_schema_extra
+                    if isinstance(meta.value, type):
+                        # Skip type objects - can't be serialized
+                        continue
+
+                    # Any other metadata goes in json_schema_extra
+                    if "json_schema_extra" not in field_kwargs:
+                        field_kwargs["json_schema_extra"] = {}
+                    field_kwargs["json_schema_extra"][meta.key] = meta.value
+
+        # Handle nullable case - ensure default is set if not already
+        if (
+            spec.is_nullable
+            and "default" not in field_kwargs
+            and "default_factory" not in field_kwargs
+        ):
+            field_kwargs["default"] = None
+
+        field_info = PydanticField(**field_kwargs)
+        field_info.annotation = spec.annotation
+
+        return field_info
+
+    @classmethod
+    def create_validator(cls, spec: "Spec") -> dict | None:
+        """Create Pydantic field_validator from Spec metadata."""
+        if (v := spec.get("validator")) is Unset:
+            return None
+
+        from pydantic import field_validator
+
+        field_name = spec.name or "field"
+        return {f"{field_name}_validator": field_validator(field_name)(v)}
+
+    @classmethod
+    def create_model(
+        cls,
+        op: "Operable",
+        model_name: str,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+        base_type: type["BaseModel"] | None = None,
+        doc: str | None = None,
+    ) -> type["BaseModel"]:
+        """Generate Pydantic BaseModel from Operable."""
+        from lionagi.models.model_params import ModelParams
+
+        use_specs = op.get_specs(include=include, exclude=exclude)
+        use_fields = {i.name: cls.create_field(i) for i in use_specs if i.name}
+
+        model_cls = ModelParams(
+            name=model_name,
+            parameter_fields=use_fields,
+            base_type=base_type,
+            inherit_base=True,
+            doc=doc,
+        ).create_new_model()
+
+        model_cls.model_rebuild()
+        return model_cls
+
+    @classmethod
+    def fuzzy_match_fields(
+        cls, data: dict, model_cls: type["BaseModel"], strict: bool = False
+    ) -> dict:
+        """Match data keys to Pydantic model fields with fuzzy matching.
+
+        Args:
+            data: Raw data dictionary
+            model_cls: Pydantic model class
+            strict: If True, raise on unmatched; if False, force coercion
+
+        Returns:
+            Dictionary with keys matched to model fields
+        """
+        from lionagi.ln import fuzzy_match_keys
+        from lionagi.ln.types import Undefined
+
+        handle_mode = "raise" if strict else "force"
+
+        matched = fuzzy_match_keys(
+            data, model_cls.model_fields, handle_unmatched=handle_mode
+        )
+
+        # Filter out undefined values
+        return {k: v for k, v in matched.items() if v != Undefined}
+
+    @classmethod
+    def validate_model(
+        cls, model_cls: type["BaseModel"], data: dict
+    ) -> "BaseModel":
+        """Validate dict data into Pydantic model instance."""
+        return model_cls.model_validate(data)
+
+    @classmethod
+    def dump_model(cls, instance: "BaseModel") -> dict:
+        """Dump Pydantic model instance to dictionary."""
+        return instance.model_dump()

lionagi/ln/_async_call.py

@@ -15,7 +15,7 @@ from .concurrency import (
     is_coro_func,
     move_on_after,
 )
-from .types import Params, T, Unset, not_sentinel
+from .types import ModelConfig, Params, T, Unset, not_sentinel
 
 _INITIALIZED = False
 _MODEL_LIKE = None
@@ -262,7 +262,7 @@ async def bcall(
 @dataclass(slots=True, init=False, frozen=True)
 class AlcallParams(Params):
     # ClassVar attributes
-    _none_as_sentinel: ClassVar[bool] = True
+    _config: ClassVar[ModelConfig] = ModelConfig(none_as_sentinel=True)
     _func: ClassVar[Any] = alcall
 
     # input processing

lionagi/ln/fuzzy/_fuzzy_match.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import Any, ClassVar, Literal
 
-from ..types import KeysLike, Params, Unset
+from ..types import KeysLike, ModelConfig, Params, Unset
 from ._string_similarity import (
     SIMILARITY_ALGO_MAP,
     SIMILARITY_TYPE,
@@ -152,7 +152,7 @@ def fuzzy_match_keys(
 
 @dataclass(slots=True, init=False, frozen=True)
 class FuzzyMatchKeysParams(Params):
-    _none_as_sentinel: ClassVar[bool] = False
+    _config: ClassVar[ModelConfig] = ModelConfig(none_as_sentinel=False)
     _func: ClassVar[Any] = fuzzy_match_keys
 
     similarity_algo: SIMILARITY_TYPE | SimilarityFunc = "jaro_winkler"

lionagi/ln/types/__init__.py

@@ -0,0 +1,51 @@
+from ._sentinel import (
+    MaybeSentinel,
+    MaybeUndefined,
+    MaybeUnset,
+    SingletonType,
+    T,
+    Undefined,
+    UndefinedType,
+    Unset,
+    UnsetType,
+    is_sentinel,
+    not_sentinel,
+)
+from .base import (
+    DataClass,
+    Enum,
+    KeysDict,
+    KeysLike,
+    Meta,
+    ModelConfig,
+    Params,
+)
+from .operable import Operable
+from .spec import CommonMeta, Spec
+
+__all__ = (
+    # Sentinel types
+    "Undefined",
+    "Unset",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "MaybeSentinel",
+    "SingletonType",
+    "UndefinedType",
+    "UnsetType",
+    "is_sentinel",
+    "not_sentinel",
+    # Base classes
+    "ModelConfig",
+    "Enum",
+    "Params",
+    "DataClass",
+    "Meta",
+    "KeysDict",
+    "KeysLike",
+    "T",
+    # Spec system
+    "Spec",
+    "CommonMeta",
+    "Operable",
+)