lionagi 0.8.1__py3-none-any.whl → 0.8.2__py3-none-any.whl

lionagi/operatives/models/field_model.py

@@ -27,23 +27,23 @@ class FieldModel(SchemaModel):
     configuration options including type validation, default values, documentation,
     and validation rules.
 
-    Attributes:
-        name (str): Required field identifier.
-        annotation (type | Any): Field type annotation, defaults to Any.
-        default (Any): Default value for the field.
-        default_factory (Callable): Function to generate default values.
-        validator (Callable): Optional validation function.
-        validator_kwargs (dict): Parameters for validator configuration.
-        title (str): Human-readable field title.
-        description (str): Detailed field description.
-        examples (list): Example values for documentation.
-        exclude (bool): Whether to exclude from serialization.
-        deprecated (bool): Whether the field is deprecated.
-        frozen (bool): Whether the field is immutable.
-        alias (str): Alternative field name.
-        alias_priority (int): Priority for alias resolution.
-
-    Example:
+    Args:
+        name: Required field identifier.
+        annotation: Field type annotation. Defaults to Any.
+        default: Default value for the field.
+        default_factory: Function to generate default values.
+        validator: Optional validation function.
+        validator_kwargs: Parameters for validator configuration.
+        title: Human-readable field title.
+        description: Detailed field description.
+        examples: Example values for documentation.
+        exclude: Whether to exclude from serialization.
+        deprecated: Whether the field is deprecated.
+        frozen: Whether the field is immutable.
+        alias: Alternative field name.
+        alias_priority: Priority for alias resolution.
+
+    Examples:
         >>> field = FieldModel(
         ...     name="age",
         ...     annotation=int,
@@ -129,7 +129,14 @@ class FieldModel(SchemaModel):
 
     @field_validator("validator_kwargs", mode="before")
     def _validate_validator_kwargs(cls, value):
-        """Validate validator kwargs."""
+        """Validate validator kwargs.
+
+        Args:
+            value: Validator kwargs to validate.
+
+        Returns:
+            Validated kwargs dictionary.
+        """
         return validate_dict_kwargs_params(cls, value)
 
     @field_validator("validator", mode="before")
@@ -140,7 +147,7 @@ class FieldModel(SchemaModel):
             value: Validator function to check.
 
         Returns:
-            Callable | Any: Validated validator function.
+            Validated validator function.
 
         Raises:
             ValueError: If validator is not callable.
@@ -151,8 +158,11 @@ class FieldModel(SchemaModel):
     def field_info(self) -> FieldInfo:
         """Generate Pydantic FieldInfo from current configuration.
 
+        Converts the current field configuration into a Pydantic FieldInfo object,
+        handling annotation defaults and field attributes.
+
         Returns:
-            FieldInfo: Configured field information object.
+            Configured Pydantic FieldInfo object.
         """
         annotation = (
             self.annotation if self.annotation is not UNDEFINED else Any
@@ -165,8 +175,12 @@ class FieldModel(SchemaModel):
     def field_validator(self) -> dict[str, Callable] | None:
         """Create field validator configuration.
 
+        Generates a validator configuration dictionary if a validator function
+        is defined, otherwise returns None.
+
         Returns:
-            dict[str, Callable] | None: Validator configuration if defined.
+            Dictionary mapping validator name to validator function if defined,
+            None otherwise.
         """
         if self.validator is UNDEFINED:
             return None
@@ -181,8 +195,11 @@ class FieldModel(SchemaModel):
     def _validate_defaults(self) -> Self:
         """Ensure default value configuration is valid.
 
+        Validates that default and default_factory are not both set, as this
+        would create ambiguity about which default to use.
+
         Returns:
-            Self: Validated instance.
+            The validated model instance.
 
         Raises:
             ValueError: If both default and default_factory are set.

lionagi/operatives/models/model_params.py

@@ -39,17 +39,28 @@ class ModelParams(SchemaModel):
     fields, validators, and configurations. It supports inheritance from base
     models, field exclusion, and custom validation rules.
 
-    Attributes:
-        name (str | None): Name for the generated model class.
-        parameter_fields (dict[str, FieldInfo]): Field definitions for the model.
-        base_type (type[BaseModel]): Base model class to inherit from.
-        field_models (list[FieldModel]): List of field model definitions.
-        exclude_fields (list): Fields to exclude from the final model.
-        field_descriptions (dict): Custom descriptions for fields.
-        inherit_base (bool): Whether to inherit from base_type.
-        config_dict (dict | None): Pydantic model configuration.
-        doc (str | None): Docstring for the generated model.
-        frozen (bool): Whether the model should be immutable.
+    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.
+
+    Examples:
+        >>> params = ModelParams(
+        ...     name="UserModel",
+        ...     field_models=[
+        ...         FieldModel(name="username", annotation=str),
+        ...         FieldModel(name="age", annotation=int, default=0)
+        ...     ],
+        ...     doc="A user model with basic attributes."
+        ... )
+        >>> UserModel = params.create_new_model()
     """
 
     name: str | None = Field(
@@ -99,9 +110,12 @@ class ModelParams(SchemaModel):
     def use_fields(self) -> dict[str, tuple[type, FieldInfo]]:
         """Get field definitions to use in new model.
 
+        Filters and combines fields from parameter_fields and field_models based on
+        the _use_keys set, preparing them for use in model creation.
+
         Returns:
-            dict[str, tuple[type, FieldInfo]]: Mapping of field names to their
-            type and field info.
+            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
@@ -233,11 +247,16 @@ class ModelParams(SchemaModel):
     def validate_param_model(self) -> Self:
         """Validate complete model configuration.
 
-        This method performs final validation and setup of the model parameters,
-        including updating field definitions, validators, and descriptions.
+        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:
-            Self: The validated instance.
+            The validated model instance with all configurations applied.
         """
         if self.base_type is not None:
             self.parameter_fields.update(copy(self.base_type.model_fields))

lionagi/operatives/models/note.py

@@ -21,34 +21,33 @@ IndiceType: TypeAlias = str | list[str | int]
 class Note(BaseModel):
     """Container for managing nested dictionary data structures.
 
-    Provides:
-    - Deep nested data access
-    - Dictionary-like interface
-    - Flattening capabilities
-    - Update operations
-
-    Example:
-        ```python
-        note = Note(
-            user={
-                "name": "John",
-                "settings": {
-                    "theme": "dark"
-                }
-            }
-        )
-
-        # Access nested data
-        name = note.get(["user", "name"])
-        theme = note["user"]["settings"]["theme"]
-
-        # Update nested structure
-        note.update(["user", "settings"], {"language": "en"})
-        ```
+    A flexible container that provides deep nested data access, dictionary-like
+    interface, flattening capabilities, and update operations for managing
+    complex nested data structures.
+
+    Args:
+        **kwargs: Key-value pairs for initial content.
 
     Attributes:
-        content: Nested dictionary structure
-        model_config: Configuration allowing arbitrary types
+        content: Nested dictionary structure.
+        model_config: Configuration allowing arbitrary types.
+
+    Examples:
+        >>> note = Note(
+        ...     user={
+        ...         "name": "John",
+        ...         "settings": {
+        ...             "theme": "dark"
+        ...         }
+        ...     }
+        ... )
+        >>>
+        >>> # Access nested data
+        >>> name = note.get(["user", "name"])
+        >>> theme = note["user"]["settings"]["theme"]
+        >>>
+        >>> # Update nested structure
+        >>> note.update(["user", "settings"], {"language": "en"})
     """
 
     content: dict[str, Any] = Field(
@@ -65,7 +64,8 @@ class Note(BaseModel):
         """Initialize Note with dictionary data.
 
         Args:
-            **kwargs: Key-value pairs for initial content
+            **kwargs: Key-value pairs that will form the initial nested
+                dictionary structure.
         """
         super().__init__()
         self.content = kwargs
@@ -103,15 +103,22 @@ class Note(BaseModel):
     ) -> Any:
         """Remove and return item from nested structure.
 
+        Removes and returns the value at the specified path in the nested
+        structure. If the path doesn't exist and no default is provided,
+        raises KeyError.
+
         Args:
-            indices: Path to item
-            default: Value to return if not found
+            indices: Path to the item to remove, can be a string for top-level
+                keys or a list for nested access.
+            default: Value to return if the path is not found. If not provided
+                and path is not found, raises KeyError.
 
         Returns:
-            Removed value or default
+            The value that was removed, or the default value if provided and
+            path not found.
 
         Raises:
-            KeyError: If path not found and no default
+            KeyError: If the path is not found and no default value is provided.
         """
         indices = to_list(indices, flatten=True, dropna=True)
         return npop(self.content, indices, default)
@@ -147,15 +154,21 @@ class Note(BaseModel):
     ) -> Any:
         """Get value from nested structure at specified indices.
 
+        Retrieves the value at the specified path in the nested structure.
+        If the path doesn't exist and no default is provided, raises KeyError.
+
         Args:
-            indices: Path to value
-            default: Value to return if not found
+            indices: Path to the value, can be a string for top-level keys
+                or a list for nested access.
+            default: Value to return if the path is not found. If not provided
+                and path is not found, raises KeyError.
 
         Returns:
-            Value at path or default
+            The value at the specified path, or the default value if provided
+            and path not found.
 
         Raises:
-            KeyError: If path not found and no default
+            KeyError: If the path is not found and no default value is provided.
         """
         indices = to_list(indices, flatten=True, dropna=True)
         return nget(self.content, indices, default)
@@ -179,12 +192,18 @@ class Note(BaseModel):
     def values(self, /, flat: bool = False, **kwargs: Any) -> ValuesView:
         """Get values of the Note.
 
+        Returns either a view of top-level values or, if flat=True, a view
+        of all values in the flattened nested structure.
+
         Args:
-            flat: If True, return flattened values
-            kwargs: Additional flattening options
+            flat: If True, returns values from all levels of the nested
+                structure. If False, returns only top-level values.
+            kwargs: Additional options for flattening behavior when flat=True.
+                Common options include coerce_keys and coerce_sequence.
 
         Returns:
-            View of values, optionally flattened
+            A ValuesView object containing either top-level values or all
+            values from the flattened structure if flat=True.
         """
         if flat:
             kwargs["coerce_keys"] = kwargs.get("coerce_keys", False)
@@ -219,12 +238,21 @@ class Note(BaseModel):
     ) -> None:
         """Update nested structure at specified indices.
 
+        Updates the value at the specified path in the nested structure.
+        The behavior depends on the existing value and the update value:
+        - If path doesn't exist: creates it with value (wrapped in list if scalar)
+        - If existing is list: extends with value if list, appends if scalar
+        - If existing is dict: updates with value if dict, raises error if not
+
         Args:
-            indices: Location to update
-            value: New value to set
+            indices: Path to the location to update, can be a string for
+                top-level keys or a list for nested access.
+            value: The new value to set. Must be compatible with existing
+                value type (dict for dict, any value for list).
 
         Raises:
-            ValueError: If trying to update dict with non-dict
+            ValueError: If trying to update a dictionary with a non-dictionary
+                value.
         """
         existing = None
         if not indices:
@@ -269,19 +297,26 @@ class Note(BaseModel):
     def __contains__(self, indices: IndiceType) -> bool:
         """Check if indices exist in content.
 
+        Implements the 'in' operator for checking path existence in the nested
+        structure.
+
         Args:
-            indices: Path to check
+            indices: Path to check, can be a string for top-level keys or a
+                list for nested access.
 
         Returns:
-            True if path exists, False otherwise
+            True if the path exists in the nested structure, False otherwise.
         """
         return self.content.get(indices, UNDEFINED) is not UNDEFINED
 
     def __len__(self) -> int:
         """Get length of content.
 
+        Implements len() function to return the number of top-level keys in
+        the nested structure.
+
         Returns:
-            Number of top-level keys
+            The number of top-level keys in the content dictionary.
         """
         return len(self.content)
 
@@ -305,8 +340,12 @@ class Note(BaseModel):
     def __str__(self) -> str:
         """Get string representation of content.
 
+        Implements str() function to provide a simple string representation
+        of the Note's content. Uses the standard dictionary string format.
+
         Returns:
-            String representation of content dict
+            A string representation of the content dictionary, showing its
+            current state.
         """
         return str(self.content)
 

lionagi/operatives/models/operable_model.py

@@ -4,7 +4,13 @@
 
 from typing import Any, TypeVar
 
-from pydantic import ConfigDict, Field, field_validator, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined
 from typing_extensions import Self, override
@@ -12,6 +18,7 @@ from typing_extensions import Self, override
 from lionagi.utils import UNDEFINED, HashableModel, is_same_dtype
 
 from .field_model import FieldModel
+from .model_params import ModelParams
 
 FieldName = TypeVar("FieldName", bound=str)
 
@@ -22,16 +29,20 @@ __all__ = ("OperableModel",)
 class OperableModel(HashableModel):
     """Base model supporting dynamic field management and operations.
 
-    This class extends Pydantic's model system to allow runtime field
-    modifications, attribute tracking, and nested model serialization.
-    Fields can be added, updated, and removed dynamically while maintaining
-    type safety and validation.
+    A Pydantic model extension that enables runtime field modifications while
+    maintaining type safety and validation. Supports dynamic field addition,
+    updates, and removal, with full serialization capabilities.
+
+    Args:
+        **kwargs: Key-value pairs for initial field values.
 
     Attributes:
-        extra_fields: Dynamically added field definitions.
-        extra_field_models: Associated field models.
+        extra_fields: Dictionary mapping field names to their FieldInfo
+            definitions for dynamically added fields.
+        extra_field_models: Dictionary mapping field names to their FieldModel
+            instances for fields with additional configuration.
 
-    Example:
+    Examples:
         >>> class UserModel(OperableModel):
         ...     name: str = "default"
         ...
@@ -199,6 +210,15 @@ class OperableModel(HashableModel):
             super().__setattr__(field_name, value)
 
     def __delattr__(self, field_name):
+        """Delete an attribute from the model.
+
+        For extra fields, attempts to reset to default value if one exists,
+        otherwise removes the field completely. For regular fields, delegates
+        to parent class deletion behavior.
+
+        Args:
+            field_name: Name of the field to delete.
+        """
         if field_name in self.extra_fields:
             if self.extra_fields[field_name].default not in [
                 UNDEFINED,
@@ -476,3 +496,93 @@ class OperableModel(HashableModel):
             raise AttributeError(
                 f"field {field_name} has no attribute {attr}",
             )
+
+    def new_model(
+        self,
+        name: str | None = None,
+        use_fields: set[str] | None = None,  # default is all_fields
+        base_type: type[BaseModel] | None = None,  # default is BaseModel
+        exclude_fields: list = None,
+        inherit_base: bool = True,
+        config_dict: ConfigDict | dict | None = None,
+        doc: str | None = None,
+        frozen: bool = False,
+        update_forward_refs: bool = True,
+    ) -> type[BaseModel]:
+        """Create a new Pydantic model type from the current model's fields.
+
+        Generates a new model class using the specified fields and configuration.
+        The new model can inherit from a base type and include a subset of fields
+        from the current model.
+
+        Args:
+            name: Name for the new model class. If None, a default name will be
+                generated.
+            use_fields: Set of field names to include in the new model. If None,
+                includes all fields.
+            base_type: Base model class to inherit from. Defaults to BaseModel
+                if None.
+            exclude_fields: List of field names to exclude from the new model.
+            inherit_base: Whether to inherit fields from the base_type.
+                Defaults to True.
+            config_dict: Pydantic model configuration for the new model.
+            doc: Docstring for the new model class.
+            frozen: If True, creates an immutable model where fields cannot be
+                modified after creation. Defaults to False.
+            update_forward_refs: Whether to attempt updating forward references
+                in the new model. Defaults to True.
+
+        Returns:
+            A new Pydantic model class with the specified configuration.
+
+        Raises:
+            ValueError: If use_fields contains invalid field names.
+
+        Examples:
+            >>> model = OperableModel()
+            >>> model.add_field("name", value="test", annotation=str)
+            >>> model.add_field("age", value=25, annotation=int)
+            >>> NewModel = model.new_model(
+            ...     name="UserModel",
+            ...     use_fields={"name", "age"},
+            ...     frozen=True
+            ... )
+            >>> user = NewModel(name="Alice", age=30)
+        """
+
+        use_fields = (
+            set(use_fields) if use_fields else set(self.all_fields.keys())
+        )
+        if not use_fields.issubset(self.all_fields.keys()):
+            raise ValueError("Invalid field names in use_fields")
+
+        field_models = []
+        parameter_fields = {}
+
+        for field_name in use_fields:
+            if field_name in self.extra_field_models:
+                field_models.append(self.extra_field_models[field_name])
+            elif field_name in self.all_fields:
+                parameter_fields[field_name] = self.all_fields[field_name]
+
+        model_params = ModelParams(
+            name=name,
+            parameter_fields=parameter_fields,
+            base_type=base_type,
+            field_models=field_models,
+            exclude_fields=exclude_fields,
+            inherit_base=inherit_base,
+            config_dict=config_dict,
+            doc=doc,
+            frozen=frozen,
+        )
+        model_cls = model_params.create_new_model()
+
+        # Update forward references if requested
+        if update_forward_refs:
+            try:
+                model_cls.model_rebuild()
+            except Exception:
+                pass  # Ignore rebuild errors for forward refs that can't be resolved yet
+
+        return model_cls

lionagi/version.py

@@ -1 +1 @@
-__version__ = "0.8.1"
+__version__ = "0.8.2"

{lionagi-0.8.1.dist-info → lionagi-0.8.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.8.1
+Version: 0.8.2
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License

{lionagi-0.8.1.dist-info → lionagi-0.8.2.dist-info}/RECORD

@@ -4,7 +4,7 @@ lionagi/_errors.py,sha256=wNKdnVQvE_CHEstK7htrrj334RA_vbGcIds-3pUiRkc,455
 lionagi/_types.py,sha256=9g7iytvSj3UjZxD-jL06_fxuNfgZyWT3Qnp0XYp1wQU,63
 lionagi/settings.py,sha256=k9zRJXv57TveyfHO3Vr9VGiKrSwlRUUVKt5zf6v9RU4,1627
 lionagi/utils.py,sha256=QbF4E1PG-BaRcEVH3kJIYCJVNq-oRNoTxjda5k8NYW4,73177
-lionagi/version.py,sha256=Ocl79hbbH8_jdr5dGC90VR1cAvZc05Rc0tkZttUnMjo,22
+lionagi/version.py,sha256=B7GiO0rd49YwtLYjvPg4lmCZEDlMTonslQKdSImaMJk,22
 lionagi/libs/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/libs/parse.py,sha256=tpEbmIRGuHhLCJlUlm6fjmqm_Z6XJLAXGNFHNuk422I,1011
 lionagi/libs/file/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
@@ -100,10 +100,10 @@ lionagi/operatives/instruct/node.py,sha256=0g7g2jsLO8L8VlD-L1mFmjcFTwWy39moWCDtL
 lionagi/operatives/instruct/prompts.py,sha256=RG8rB7Y0J17aTHTb9kTTHxltVjgRAuC4vjM9B1_hTuQ,1747
 lionagi/operatives/instruct/reason.py,sha256=mdCMBO3YSWYncXU_B1bYuZqpkj4pfUMsxsz9vXXAMw4,2341
 lionagi/operatives/models/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/operatives/models/field_model.py,sha256=yfRRBbfQ5llPGIt_QkyLrIrmNwNQ14aUXA-llHeER4M,6083
-lionagi/operatives/models/model_params.py,sha256=UnugiT0GDFzB9igYeCvN6pcq01bqTpZuAHom0yCBSdk,9653
-lionagi/operatives/models/note.py,sha256=KUaMf6j1BzbR_r7RCTYoCDagNbfdkIR6vAVyxj6xlmQ,9524
-lionagi/operatives/models/operable_model.py,sha256=Br9vCo_Z3iqqE8Zdfy_n4fqu7xfIovyzzrhm4y99U1g,15573
+lionagi/operatives/models/field_model.py,sha256=jugM0K3b-iE--OcKU6i2CvpByGfQv--AQfNuSeudBuU,6518
+lionagi/operatives/models/model_params.py,sha256=41CFRuunSPXZEiMAx12zENfRUI9i0YI4rRCcv5pNF0o,10362
+lionagi/operatives/models/note.py,sha256=7OjtoSVxqGlzPnnscKCbi9bMz8WGJh7zQ9o8MEPv3kQ,12202
+lionagi/operatives/models/operable_model.py,sha256=7bF4XYvYhcMYT_mh862K-xr8izkhmPfod-aioWuMDvg,19728
 lionagi/operatives/models/schema_model.py,sha256=-BeCwW_1Rle--w-f7MajbOYH7t_8SPWw0_qK0fpTsRg,666
 lionagi/operatives/strategies/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/operatives/strategies/base.py,sha256=cfZXUZYPypW-hFZJj7HDtTPc-x99XB6dO_S5os1srTk,1820
@@ -189,7 +189,7 @@ lionagi/service/providers/perplexity_/chat_completions.py,sha256=SsDbrtXwQsR4Yu2
 lionagi/session/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/session/branch.py,sha256=JvErd9YUuGdWyLj37rtKOteSqV0ltn9lg0R2G8GO40c,62539
 lionagi/session/session.py,sha256=po6C7PnM0iu_ISHUo4PBzzQ61HFOgcsAUfPoO--eLak,8987
-lionagi-0.8.1.dist-info/METADATA,sha256=CsuHv1XHjLu2hP8gC7WfIquHVrnBWGR1zNsxQdsTHHc,22819
-lionagi-0.8.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-lionagi-0.8.1.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
-lionagi-0.8.1.dist-info/RECORD,,
+lionagi-0.8.2.dist-info/METADATA,sha256=lJ_wNrsDsRFOVYHqCc9GbFWe5bFyusOF7-nZW_cMIL4,22819
+lionagi-0.8.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lionagi-0.8.2.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
+lionagi-0.8.2.dist-info/RECORD,,