lionagi 0.8.1__tar.gz → 0.8.3__tar.gz

{lionagi-0.8.1 → lionagi-0.8.3}/PKG-INFO

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

{lionagi-0.8.1 → lionagi-0.8.3}/docs/modules/models.rst

@@ -18,7 +18,7 @@ Below is an overview of the major components in this subsystem.
 ----------------------------
 1. FieldModel (``field_model.py``)
 ----------------------------
-.. module:: lionagi.operatives.model.field_model
+.. module:: lionagi.operatives.models.field_model
    :synopsis: Structured definition of Pydantic fields.
 
 .. class:: FieldModel
@@ -35,7 +35,7 @@ A configurable **field definition** that captures:
 
 **Usage**::
 
-   from lionagi.operatives.model.field_model import FieldModel
+   from lionagi.operatives.models.field_model import FieldModel
 
    field = FieldModel(
        name="age",
@@ -50,7 +50,7 @@ A configurable **field definition** that captures:
 ----------------------------
 2. ModelParams (``model_params.py``)
 ----------------------------
-.. module:: lionagi.operatives.model.model_params
+.. module:: lionagi.operatives.models.model_params
    :synopsis: Dynamically create new Pydantic models.
 
 .. class:: ModelParams
@@ -72,8 +72,8 @@ Finally, call :meth:`create_new_model()` to get a brand-new Pydantic class
 **Example**::
 
    from pydantic import BaseModel
-   from lionagi.operatives.model.model_params import ModelParams
-   from lionagi.operatives.model.field_model import FieldModel
+   from lionagi.operatives.models.model_params import ModelParams
+   from lionagi.operatives.models.field_model import FieldModel
 
    params = ModelParams(
        name="DynamicUser",
@@ -92,7 +92,7 @@ Finally, call :meth:`create_new_model()` to get a brand-new Pydantic class
 ---------------------------
 3. OperableModel (``operable_model.py``)
 ---------------------------
-.. module:: lionagi.operatives.model.operable_model
+.. module:: lionagi.operatives.models.operable_model
    :synopsis: Extends Pydantic for dynamic field management.
 
 .. class:: OperableModel
@@ -112,7 +112,7 @@ structure remains valid with Pydantic's type checks and serialization logic.
 
 **Example**::
 
-   from lionagi.operatives.model.operable_model import OperableModel
+   from lionagi.operatives.models.operable_model import OperableModel
 
    class User(OperableModel):
        name: str = "default_name"
@@ -128,7 +128,7 @@ structure remains valid with Pydantic's type checks and serialization logic.
 --------------------------
 4. Note (``note.py``)
 --------------------------
-.. module:: lionagi.operatives.model.note
+.. module:: lionagi.operatives.models.note
    :synopsis: A flexible container for nested data.
 
 .. class:: Note
@@ -146,7 +146,7 @@ manually in your code.
 
 **Example**::
 
-   from lionagi.operatives.model.note import Note
+   from lionagi.operatives.models.note import Note
 
    note = Note(user={"name": "John", "settings": {"theme": "dark"}})
    name = note.get(["user", "name"])  # "John"
@@ -172,7 +172,7 @@ to **forbid** extra fields by default and use enum values. Provides a
 -------------------------
 6. HashableModel (``hashable_model.py``)
 -------------------------
-.. module:: lionagi.operatives.model.hashable_model
+.. module:: lionagi.utils
    :synopsis: Adds hashing to Pydantic models.
 
 .. class:: HashableModel
@@ -187,7 +187,7 @@ they are not inherently hashable.
 
 **Example**::
 
-   from lionagi.operatives.model.hashable_model import HashableModel
+   from lionagi.utils import HashableModel
 
    class MyConfig(HashableModel):
        alpha: float

{lionagi-0.8.1 → lionagi-0.8.3}/lionagi/operations/ReAct/ReAct.py

@@ -11,6 +11,8 @@ from lionagi.operatives.types import Instruct
 from lionagi.service.imodel import iModel
 from lionagi.utils import copy
 
+from .utils import ReActAnalysis
+
 if TYPE_CHECKING:
     from lionagi.session.branch import Branch
 
@@ -60,11 +62,9 @@ async def ReAct(
     kwargs_for_operate["actions"] = True
     kwargs_for_operate["reason"] = True
 
-    # We'll pass the refined instruct_dict plus the user's other kwargs
-    from .utils import ReActAnalysis
-
     # Step 1: Generate initial ReAct analysis
     analysis: ReActAnalysis = await branch.operate(
+        instruct=instruct_dict,
         response_format=ReActAnalysis,
         tools=tools,
         tool_schemas=tool_schemas,
@@ -83,7 +83,7 @@ async def ReAct(
     while (
         extension_allowed
         and analysis.extension_needed
-        and (extensions if extensions else 1) > 0
+        and (extensions if max_extensions else 0) > 0
     ):
         new_instruction = None
         if extensions == max_extensions:
@@ -95,17 +95,13 @@ async def ReAct(
                 extensions=extensions
             )
 
-        # Each expansion uses a fresh copy of instruct_dict + forcibly "reason" + "actions"
-        expanded_kwargs = copy(instruct_dict)
-        expanded_kwargs["instruction"] = new_instruction
-        expanded_kwargs["reason"] = True
-        expanded_kwargs["actions"] = True
-
         analysis = await branch.operate(
+            instruction=new_instruction,
             response_format=ReActAnalysis,
             tools=tools,
             tool_schemas=tool_schemas,
-            **expanded_kwargs,
+            reason=True,
+            actions=True,
         )
         analyses.append(analysis)
 

{lionagi-0.8.1 → lionagi-0.8.3}/lionagi/operations/ReAct/utils.py

@@ -10,19 +10,19 @@ from pydantic import BaseModel, Field
 class ReActAnalysis(BaseModel):
 
     FIRST_EXT_PROMPT: ClassVar[str] = (
-        "You are provided with another round to perform reason action to provide an accurate final answer. you have max another {extensions} rounds, set extension_needed to False if you are done and ready to provide final answer."
+        "You are provided with additional rounds to perform reason action to provide an accurate final answer. you have max another {extensions} rounds. Pleasen continue."
     )
 
     CONTINUE_EXT_PROMPT: ClassVar[str] = (
-        "You are provided with another round, you have max another {extensions} rounds"
+        "You are provided with another round, you have max another {extensions} rounds. Please continue."
     )
 
     ANSWER_PROMPT: ClassVar[str] = (
-        "given above reason and actions, please provide final answer to the original user request {instruction}"
+        "given above reason and actions, please provide final answer to the original user request:\n\n {instruction}"
     )
 
     analysis: str
     extension_needed: bool = Field(
         False,
-        description="Set to True if more steps are needed to provide an accurate answer. If True, additional rounds are allowed.",
+        description="Set to True if more steps are needed to provide an accurate answer. If True, additional rounds are allowed. Typically should be set to true if more actions should be taken or planned to be taken. If false, will proceed to provide final answer next.",
     )

{lionagi-0.8.1 → lionagi-0.8.3}/lionagi/operatives/action/function_calling.py

@@ -5,7 +5,7 @@
 import asyncio
 from typing import Any
 
-from pydantic import Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 from typing_extensions import Self
 
 from lionagi.protocols.generic.event import Event, EventStatus
@@ -27,12 +27,22 @@ class FunctionCalling(Event):
         exclude=True,
     )
 
-    arguments: dict[str, Any] = Field(
+    arguments: dict[str, Any] | BaseModel = Field(
         ..., description="Dictionary of arguments to pass to the function"
     )
 
+    @field_validator("arguments", mode="before")
+    def _validate_argument(cls, value):
+        if isinstance(value, BaseModel):
+            return value.model_dump(exclude_unset=True)
+        return value
+
     @model_validator(mode="after")
     def _validate_strict_tool(self) -> Self:
+        if self.func_tool.request_options:
+            args: BaseModel = self.func_tool.request_options(**self.arguments)
+            self.arguments = args.model_dump(exclude_unset=True)
+
         if self.func_tool.strict_func_call is True:
             if (
                 not set(self.arguments.keys())

{lionagi-0.8.1 → lionagi-0.8.3}/lionagi/operatives/action/tool.py

@@ -12,6 +12,7 @@ import inspect
 from collections.abc import Callable
 from typing import Any, TypeAlias
 
+from openai import BaseModel
 from pydantic import Field, field_validator, model_validator
 from typing_extensions import Self
 
@@ -49,6 +50,11 @@ class Tool(Element):
         description="Schema describing the function's parameters and structure",
     )
 
+    request_options: type | None = Field(
+        default=None,
+        description="Optional Pydantic model for validating the function's input",
+    )
+
     preprocessor: Callable[[Any], Any] | None = Field(
         default=None,
         description="Optional function for preprocessing inputs before execution",
@@ -88,6 +94,11 @@ class Tool(Element):
     def _validate_tool_schema(self) -> Self:
         if self.tool_schema is None:
             self.tool_schema = function_to_schema(self.func_callable)
+        if self.request_options is not None:
+            schema_ = self.request_options.model_json_schema()
+            schema_.pop("title", None)
+            self.tool_schema["function"]["parameters"] = schema_
+
         return self
 
     @property

{lionagi-0.8.1 → lionagi-0.8.3}/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-0.8.1 → lionagi-0.8.3}/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-0.8.1 → lionagi-0.8.3}/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)