lionagi 0.17.9__py3-none-any.whl → 0.17.11__py3-none-any.whl

lionagi/models/model_params.py

@@ -1,335 +1,336 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
+"""ModelParams implementation using Params base class with aggressive caching.
+
+This module provides ModelParams, a configuration class for dynamically creating
+Pydantic models with explicit behavior and aggressive caching for performance.
+"""
+
+from __future__ import annotations
+
 import inspect
+import os
+import threading
+from collections import OrderedDict
 from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field as dc_field
+from typing import Any, ClassVar
 
-from pydantic import (
-    BaseModel,
-    Field,
-    PrivateAttr,
-    create_model,
-    field_validator,
-    model_validator,
-)
+from pydantic import BaseModel, create_model
 from pydantic.fields import FieldInfo
-from typing_extensions import Self
-
-from lionagi.libs.validate.common_field_validators import (
-    validate_boolean_field,
-    validate_list_dict_str_keys,
-    validate_model_to_type,
-    validate_nullable_string_field,
-    validate_same_dtype_flat_list,
-    validate_str_str_dict,
-)
+
+from lionagi.ln.types import Params
 from lionagi.utils import copy
 
 from .field_model import FieldModel
-from .schema_model import SchemaModel
 
 __all__ = ("ModelParams",)
 
-
-class ModelParams(SchemaModel):
-    """Configuration class for dynamically creating new Pydantic models.
-
-    This class provides a flexible way to create Pydantic models with customizable
-    fields, validators, and configurations. It supports inheritance from base
-    models, field exclusion, and custom validation rules.
-
-    Args:
-        name: Name for the generated model class.
-        parameter_fields: Field definitions for the model.
-        base_type: Base model class to inherit from.
-        field_models: List of field model definitions.
-        exclude_fields: Fields to exclude from the final model.
-        field_descriptions: Custom descriptions for fields.
-        inherit_base: Whether to inherit from base_type.
-        config_dict: Pydantic model configuration.
-        doc: Docstring for the generated model.
-        frozen: Whether the model should be immutable.
+# Global cache configuration
+_MODEL_CACHE_SIZE = int(os.environ.get("LIONAGI_MODEL_CACHE_SIZE", "1000"))
+_model_cache: OrderedDict[int, type[BaseModel]] = OrderedDict()
+_model_cache_lock = threading.RLock()
+
+
+@dataclass(slots=True, frozen=True, init=False)
+class ModelParams(Params):
+    """Configuration for dynamically creating Pydantic models.
+
+    This class provides a way to configure and create Pydantic models dynamically
+    with explicit behavior (no silent conversions) and aggressive caching for
+    performance optimization.
+
+    Key features:
+    - All unspecified fields are explicitly Unset (not None or empty)
+    - No silent type conversions - fails fast on incorrect types
+    - Aggressive caching of created models with LRU eviction
+    - Thread-safe model creation and caching
+    - Not directly instantiable - requires keyword arguments
+
+    Attributes:
+        name: Name for the generated model class
+        parameter_fields: Field definitions for the model
+        base_type: Base model class to inherit from
+        field_models: List of FieldModel definitions
+        exclude_fields: Fields to exclude from the final model
+        field_descriptions: Custom descriptions for fields
+        inherit_base: Whether to inherit from base_type
+        config_dict: Pydantic model configuration
+        doc: Docstring for the generated model
+        frozen: Whether the model should be immutable
+
+    Environment Variables:
+        LIONAGI_MODEL_CACHE_SIZE: Maximum number of cached models (default: 1000)
 
     Examples:
         >>> params = ModelParams(
         ...     name="UserModel",
+        ...     frozen=True,
         ...     field_models=[
-        ...         FieldModel(name="username", annotation=str),
-        ...         FieldModel(name="age", annotation=int, default=0)
+        ...         FieldModel(str, name="username"),
+        ...         FieldModel(int, name="age", default=0)
         ...     ],
         ...     doc="A user model with basic attributes."
         ... )
         >>> UserModel = params.create_new_model()
-    """
-
-    name: str | None = Field(
-        default=None, description="Name for the generated model class"
-    )
-
-    parameter_fields: dict[str, FieldInfo] = Field(
-        default_factory=dict, description="Field definitions for the model"
-    )
-
-    base_type: type[BaseModel] = Field(
-        default=BaseModel, description="Base model class to inherit from"
-    )
-
-    field_models: list[FieldModel] = Field(
-        default_factory=list, description="List of field model definitions"
-    )
-
-    exclude_fields: list = Field(
-        default_factory=list,
-        description="Fields to exclude from the final model",
-    )
-
-    field_descriptions: dict = Field(
-        default_factory=dict, description="Custom descriptions for fields"
-    )
-
-    inherit_base: bool = Field(
-        default=True, description="Whether to inherit from base_type"
-    )
 
-    config_dict: dict | None = Field(
-        default=None, description="Pydantic model configuration"
-    )
+        >>> # All unspecified fields are Unset
+        >>> params2 = ModelParams(name="SimpleModel")
+        >>> assert params2.doc is Unset
+        >>> assert params2.frozen is Unset
+    """
 
-    doc: str | None = Field(
-        default=None, description="Docstring for the generated model"
+    # Class configuration - let Params handle Unset population
+    _prefill_unset: ClassVar[bool] = True
+    _none_as_sentinel: ClassVar[bool] = True
+
+    # Public fields (all start as Unset when not provided)
+    name: str | None
+    parameter_fields: dict[str, FieldInfo]
+    base_type: type[BaseModel]
+    field_models: list[FieldModel]
+    exclude_fields: list[str]
+    field_descriptions: dict[str, str]
+    inherit_base: bool
+    config_dict: dict[str, Any] | None
+    doc: str | None
+    frozen: bool
+
+    # Private computed state
+    _final_fields: dict[str, FieldInfo] = dc_field(
+        default_factory=dict, init=False
     )
-
-    frozen: bool = Field(
-        default=False, description="Whether the model should be immutable"
+    _validators: dict[str, Callable] = dc_field(
+        default_factory=dict, init=False
     )
-    _validators: dict[str, Callable] | None = PrivateAttr(default=None)
-    _use_keys: set[str] = PrivateAttr(default_factory=set)
 
-    @property
-    def use_fields(self) -> dict[str, tuple[type, FieldInfo]]:
-        """Get field definitions to use in new model.
+    def _validate(self) -> None:
+        """Validate types and setup model configuration.
 
-        Filters and combines fields from parameter_fields and field_models based on
-        the _use_keys set, preparing them for use in model creation.
-
-        Returns:
-            A dictionary mapping field names to tuples of (type, FieldInfo),
-            containing only the fields that should be included in the new model.
-        """
-        params = {
-            k: v
-            for k, v in self.parameter_fields.items()
-            if k in self._use_keys
-        }
-        # Add field_models with proper type annotations
-        for f in self.field_models:
-            if f.name in self._use_keys:
-                params[f.name] = f.field_info
-                # Set the annotation from the FieldModel's base_type
-                params[f.name].annotation = f.base_type
-
-        return {k: (v.annotation, v) for k, v in params.items()}
-
-    @field_validator("parameter_fields", mode="before")
-    def _validate_parameters(cls, value) -> dict[str, FieldInfo]:
-        """Validate parameter field definitions.
-
-        Args:
-            value: Value to validate.
-
-        Returns:
-            dict[str, FieldInfo]: Validated parameter fields.
-
-        Raises:
-            ValueError: If parameter fields are invalid.
-        """
-        if value in [None, {}, []]:
-            return {}
-        if not isinstance(value, dict):
-            raise ValueError("Fields must be a dictionary.")
-        for k, v in value.items():
-            if not isinstance(k, str):
-                raise ValueError("Field names must be strings.")
-            if not isinstance(v, FieldInfo):
-                raise ValueError("Field values must be FieldInfo objects.")
-        return copy(value)
-
-    @field_validator("base_type", mode="before")
-    def _validate_base(cls, value) -> type[BaseModel]:
-        """Validate base model type.
-
-        Args:
-            value: Value to validate.
-
-        Returns:
-            type[BaseModel]: Validated base model type.
+        This method performs minimal domain-specific validation, then processes
+        and merges field definitions from various sources.
 
         Raises:
-            ValueError: If base type is invalid.
+            ValueError: If base_type is not a BaseModel subclass
         """
-        return validate_model_to_type(cls, value)
-
-    @field_validator("exclude_fields", mode="before")
-    def _validate_fields(cls, value) -> list[str]:
-        """Validate excluded fields list.
+        # Let parent handle basic Unset population
+        Params._validate(self)
+
+        # Minimal domain validation - only check what matters
+        if not self._is_sentinel(self.base_type):
+            if not (
+                inspect.isclass(self.base_type)
+                and issubclass(self.base_type, BaseModel)
+            ):
+                raise ValueError(
+                    f"base_type must be BaseModel subclass, got {self.base_type}"
+                )
 
-        Args:
-            value: Value to validate.
+        # Process and merge all field sources
+        self._process_fields()
 
-        Returns:
-            list[str]: Validated list of field names to exclude.
+    def _process_fields(self) -> None:
+        """Merge all field sources into final configuration.
 
-        Raises:
-            ValueError: If field names are invalid.
+        This method processes and combines fields from parameter_fields, base_type,
+        and field_models, handling exclusions and descriptions.
         """
-        return validate_list_dict_str_keys(cls, value)
-
-    @field_validator("field_descriptions", mode="before")
-    def _validate_field_descriptions(cls, value) -> dict[str, str]:
-        """Validate field descriptions dictionary.
-
-        Args:
-            value: Value to validate.
+        fields = {}
+        validators = {}
 
-        Returns:
-            dict[str, str]: Validated field descriptions.
+        # Start with explicit parameter_fields
+        if not self._is_sentinel(self.parameter_fields):
+            # Handle empty values - treat them as no fields
+            if not self.parameter_fields:
+                pass  # Empty dict/list/None - no fields to add
+            elif isinstance(self.parameter_fields, dict):
+                # Validate parameter_fields contain FieldInfo instances
+                for name, field_info in self.parameter_fields.items():
+                    if not isinstance(field_info, FieldInfo):
+                        raise ValueError(
+                            f"parameter_fields must contain FieldInfo instances, got {type(field_info)} for field '{name}'"
+                        )
+                fields.update(copy(self.parameter_fields))
+            else:
+                raise ValueError(
+                    f"parameter_fields must be a dictionary, got {type(self.parameter_fields)}"
+                )
+
+        # Add base_type fields (respecting exclusions)
+        if not self._is_sentinel(self.base_type):
+            base_fields = copy(self.base_type.model_fields)
+            if not self._is_sentinel(self.exclude_fields):
+                base_fields = {
+                    k: v
+                    for k, v in base_fields.items()
+                    if k not in self.exclude_fields
+                }
+            fields.update(base_fields)
+
+        # Process field_models
+        if not self._is_sentinel(self.field_models):
+            # Coerce to list if single FieldModel instance
+            field_models_list = (
+                [self.field_models]
+                if isinstance(self.field_models, FieldModel)
+                else self.field_models
+            )
+
+            for fm in field_models_list:
+                if not isinstance(fm, FieldModel):
+                    raise ValueError(
+                        f"field_models must contain FieldModel instances, got {type(fm)}"
+                    )
 
-        Raises:
-            ValueError: If descriptions are invalid.
-        """
-        return validate_str_str_dict(cls, value)
+            # Apply descriptions first
+            field_models = field_models_list
+            if not self._is_sentinel(self.field_descriptions):
+                field_models = [
+                    (
+                        fm.with_description(self.field_descriptions[fm.name])
+                        if fm.name in self.field_descriptions
+                        else fm
+                    )
+                    for fm in field_models
+                ]
 
-    @field_validator("inherit_base", mode="before")
-    def _validate_inherit_base(cls, value) -> bool:
-        """Validate inherit_base flag.
+            # Extract fields and validators using public interface
+            for fm in field_models:
+                fields[fm.name] = fm.create_field()
+                fields[fm.name].annotation = fm.annotation
 
-        Args:
-            value: Value to validate.
+                # Use the public field_validator property
+                if fm.field_validator:
+                    validators.update(fm.field_validator)
 
-        Returns:
-            bool: Validated inherit_base value.
-        """
-        return validate_boolean_field(cls, value, default=True)
+        # Store computed state
+        object.__setattr__(self, "_final_fields", fields)
+        object.__setattr__(self, "_validators", validators)
 
-    @field_validator("name", mode="before")
-    def _validate_name(cls, value) -> str | None:
-        """Validate model name.
+    @property
+    def use_fields(self) -> dict[str, tuple[type, FieldInfo]]:
+        """Get field definitions to use in new model.
 
-        Args:
-            value: Value to validate.
+        Filters and prepares fields based on processed configuration.
 
         Returns:
-            str | None: Validated model name.
-
-        Raises:
-            ValueError: If name is invalid.
+            Dictionary mapping field names to (type, FieldInfo) tuples
         """
-        return validate_nullable_string_field(cls, value, field_name="Name")
-
-    @field_validator("field_models", mode="before")
-    def _validate_field_models(cls, value) -> list[FieldModel]:
-        """Validate field model definitions.
+        if not hasattr(self, "_final_fields"):
+            return {}
 
-        Args:
-            value: Value to validate.
+        return {k: (v.annotation, v) for k, v in self._final_fields.items()}
 
-        Returns:
-            list[FieldModel]: Validated field models.
+    @property
+    def _use_keys(self) -> set[str]:
+        """Get field keys for backward compatibility.
 
-        Raises:
-            ValueError: If field models are invalid.
+        Returns the set of field names that will be used in the generated model.
+        This is derived from _final_fields for consistency.
         """
+        if not hasattr(self, "_final_fields"):
+            return set()
+        return set(self._final_fields.keys())
 
-        return validate_same_dtype_flat_list(cls, value, FieldModel)
+    def _get_cache_key(self) -> int:
+        """Create a hashable cache key from object state.
 
-    @model_validator(mode="after")
-    def validate_param_model(self) -> Self:
-        """Validate complete model configuration.
-
-        Performs comprehensive validation and setup of the model parameters:
-        1. Updates parameter fields from base type if present
-        2. Merges field models into parameter fields
-        3. Manages field inclusion/exclusion via _use_keys
-        4. Sets up validators from field models
-        5. Applies field descriptions
-        6. Handles model name resolution
-
-        Returns:
-            The validated model instance with all configurations applied.
+        Converts unhashable types to hashable representations for caching.
         """
-        if self.base_type is not None:
-            self.parameter_fields.update(copy(self.base_type.model_fields))
-
-        self.parameter_fields.update(
-            {f.name: f.field_info for f in self.field_models}
-        )
-
-        use_keys = list(self.parameter_fields.keys())
-        use_keys.extend(list(self._use_keys))
-
-        if self.exclude_fields:
-            use_keys = [i for i in use_keys if i not in self.exclude_fields]
-
-        self._use_keys = set(use_keys)
-
-        validators = {}
-
-        for i in self.field_models:
-            if i.field_validator is not None:
-                validators.update(i.field_validator)
-        self._validators = validators
-
-        if self.field_descriptions:
-            # Update field_models with descriptions (create new instances since they're immutable)
-            updated_field_models = []
-            for i in self.field_models:
-                if i.name in self.field_descriptions:
-                    # Create new FieldModel with updated description
-                    updated_field_model = i.with_description(
-                        self.field_descriptions[i.name]
-                    )
-                    updated_field_models.append(updated_field_model)
-                else:
-                    updated_field_models.append(i)
-            self.field_models = updated_field_models
-
-        if not isinstance(self.name, str):
-            if hasattr(self.base_type, "class_name"):
-                if callable(self.base_type.class_name):
-                    self.name = self.base_type.class_name()
-                else:
-                    self.name = self.base_type.class_name
-            elif inspect.isclass(self.base_type):
-                self.name = self.base_type.__name__
-
-        return self
+        state = self.to_dict()
+
+        def make_hashable(obj):
+            if isinstance(obj, dict):
+                return tuple(
+                    sorted((k, make_hashable(v)) for k, v in obj.items())
+                )
+            elif isinstance(obj, list):
+                return tuple(make_hashable(x) for x in obj)
+            elif isinstance(obj, set):
+                return tuple(sorted(make_hashable(x) for x in obj))
+            else:
+                return obj
+
+        hashable_state = make_hashable(state)
+        return hash(hashable_state)
 
     def create_new_model(self) -> type[BaseModel]:
         """Create new Pydantic model with specified configuration.
 
         This method generates a new Pydantic model class based on the configured
-        parameters, including fields, validators, and inheritance settings.
+        parameters. Results are cached for performance when the same configuration
+        is used multiple times.
 
         Returns:
-            type[BaseModel]: Newly created Pydantic model class.
+            Newly created or cached Pydantic model class
         """
-        base_type = self.base_type if self.inherit_base else None
-
-        if base_type and self.exclude_fields:
-            if any(
-                i in self.exclude_fields for i in self.base_type.model_fields
+        # Create stable cache key from hashable representation
+        cache_key = self._get_cache_key()
+
+        # Check cache first
+        with _model_cache_lock:
+            if cache_key in _model_cache:
+                _model_cache.move_to_end(cache_key)
+                return _model_cache[cache_key]
+
+        # Determine model name
+        model_name = self.name
+        if self._is_sentinel(model_name) and not self._is_sentinel(
+            self.base_type
+        ):
+            if hasattr(self.base_type, "class_name"):
+                model_name = self.base_type.class_name
+                if callable(model_name):
+                    model_name = model_name()
+            else:
+                model_name = self.base_type.__name__
+
+        if self._is_sentinel(model_name):
+            model_name = "GeneratedModel"
+
+        # Determine base class
+        base_type = None
+        if (
+            not self._is_sentinel(self.inherit_base)
+            and self.inherit_base
+            and not self._is_sentinel(self.base_type)
+        ):
+            # Don't inherit if we're excluding base fields
+            if self._is_sentinel(self.exclude_fields) or not any(
+                f in self.exclude_fields for f in self.base_type.model_fields
             ):
-                base_type = None
+                base_type = self.base_type
 
-        a: type[BaseModel] = create_model(
-            self.name or "StepModel",
-            __config__=self.config_dict,
-            __doc__=self.doc,
+        # Create the model
+        model = create_model(
+            model_name,
             __base__=base_type,
-            __validators__=self._validators,
+            __config__=(
+                self.config_dict
+                if not self._is_sentinel(self.config_dict)
+                else None
+            ),
+            __doc__=self.doc if not self._is_sentinel(self.doc) else None,
+            __validators__=self._validators if self._validators else None,
             **self.use_fields,
         )
-        if self.frozen:
-            a.model_config["frozen"] = True
-        return a
+
+        # Apply frozen configuration
+        if not self._is_sentinel(self.frozen) and self.frozen:
+            model.model_config["frozen"] = True
+
+        # Cache the result
+        with _model_cache_lock:
+            _model_cache[cache_key] = model
+
+            # LRU eviction
+            while len(_model_cache) > _MODEL_CACHE_SIZE:
+                try:
+                    _model_cache.popitem(last=False)  # Remove oldest
+                except KeyError:
+                    # Handle race condition
+                    break
+
+        return model

lionagi/models/operable_model.py

@@ -1,5 +1,4 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
 from typing import Any, TypeVar
@@ -115,13 +114,13 @@ class OperableModel(HashableModel):
         if isinstance(value, dict):
             for k, v in value.items():
                 if isinstance(v, FieldModel):
-                    out[k] = v.field_info
+                    out[k] = v.create_field()
                 elif isinstance(v, FieldInfo):
                     out[k] = v
             return out
 
         elif isinstance(value, list) and is_same_dtype(value, FieldModel):
-            return {v.name: v.field_info for v in value}
+            return {v.name: v.create_field() for v in value}
 
         raise ValueError("Invalid extra_fields value")
 
@@ -139,7 +138,7 @@ class OperableModel(HashableModel):
         if isinstance(self.extra_fields, dict):
             for k, v in self.extra_fields.items():
                 if isinstance(v, FieldModel):
-                    extra_fields[k] = v.field_info
+                    extra_fields[k] = v.create_field()
                     extra_field_models[k] = v
                 elif isinstance(v, FieldInfo):
                     extra_fields[k] = v
@@ -149,7 +148,7 @@ class OperableModel(HashableModel):
             for v in self.extra_fields:
                 # list[FieldModel]
                 if isinstance(v, FieldModel):
-                    extra_fields[v.name] = v.field_info
+                    extra_fields[v.name] = v.create_field()
                     extra_field_models[v.name] = v
 
                 # Handle list[tuple[str, FieldInfo | FieldModel]]
@@ -158,11 +157,11 @@ class OperableModel(HashableModel):
                         if isinstance(v[1], FieldInfo):
                             extra_fields[v[0]] = v[1]
                         if isinstance(v[1], FieldModel):
-                            extra_fields[v[1].name] = v[1].field_info
+                            extra_fields[v[1].name] = v[1].create_field()
                             extra_field_models[v[1].name] = v[1]
 
-        self.extra_fields = extra_fields
-        self.extra_field_models = extra_field_models
+        object.__setattr__(self, "extra_fields", extra_fields)
+        object.__setattr__(self, "extra_field_models", extra_field_models)
         return self
 
     @override
@@ -349,7 +348,7 @@ class OperableModel(HashableModel):
                 raise ValueError(
                     "Invalid field_model, should be a FieldModel object"
                 )
-            self.extra_fields[field_name] = field_model.field_info
+            self.extra_fields[field_name] = field_model.create_field()
             self.extra_field_models[field_name] = field_model
 
         # Handle kwargs