lionagi 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

lionagi/operatives/action/tool.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `Tool` class, which wraps a Python callable (function/method)
+with optional pre/post-processing and schema auto-generation. Also includes
+type aliases for function references.
+"""
+
 import inspect
 from collections.abc import Callable
 from typing import Any, Self, TypeAlias
@@ -22,10 +28,13 @@ __all__ = (
 
 
 class Tool(Element):
-    """A class for handling function calls with schema validation and processing.
+    """
+    Wraps a callable function with optional:
+      - Preprocessing of arguments,
+      - Postprocessing of results,
+      - Strict or partial argument matching.
 
-    This class wraps callable objects with optional pre and post processing,
-    schema validation, and provides utility methods for function inspection.
+    `tool_schema` is auto-generated from the function signature if not provided.
     """
 
     func_callable: Callable[..., Any] = Field(
@@ -82,28 +91,19 @@ class Tool(Element):
 
     @property
     def function(self) -> str:
-        """Get the name of the function from the schema.
-
-        Returns:
-            str: The name of the function as defined in the schema.
-        """
+        """Return the function name from the auto-generated schema."""
         return self.tool_schema["function"]["name"]
 
     @property
     def required_fields(self) -> set[str]:
-        """Get the required fields from the schema.
-
-        Returns:
-            set[str]: Set of required field names.
-        """
+        """Return the set of required parameter names from the schema."""
         return set(self.tool_schema["function"]["parameters"]["required"])
 
     @property
     def minimum_acceptable_fields(self) -> set[str]:
-        """Get the minimum required fields from function signature.
-
-        Returns:
-            set[str]: Set of minimum required field names.
+        """
+        Return the set of parameters that have no default values,
+        ignoring `*args` or `**kwargs`.
         """
         try:
             a = {
@@ -123,13 +123,15 @@ class Tool(Element):
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]):
-        raise NotImplementedError("Tool.from_dict is not implemented.")
+        """This is not implemented, as Tools are not typically created from arbitrary dicts."""
+        raise NotImplementedError("`Tool.from_dict` is not supported.")
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert Tool instance to dictionary.
+        """
+        Serialize the Tool to a dict, including the `function` name.
 
         Returns:
-            dict[str, Any]: Dictionary representation of the Tool.
+            dict[str, Any]: The dictionary form (excluding callables).
         """
         dict_ = super().to_dict()
         dict_["function"] = self.function
@@ -137,5 +139,33 @@ class Tool(Element):
 
 
 FuncTool: TypeAlias = Tool | Callable[..., Any]
+"""Represents either a `Tool` instance or a raw callable function."""
+
 FuncToolRef: TypeAlias = FuncTool | str
+"""
+A reference to a function-based tool, by either the actual object,
+the raw callable, or the function name as a string.
+"""
+
 ToolRef: TypeAlias = FuncToolRef | list[FuncToolRef] | bool
+"""
+Used for specifying one or more tool references, or a boolean
+indicating 'all' or 'none'.
+"""
+
+
+def func_to_tool(func: Callable[..., Any], **kwargs) -> Tool:
+    """
+    Convenience function that wraps a raw function in a `Tool`.
+
+    Args:
+        func (Callable[..., Any]): The function to wrap.
+        **kwargs: Additional arguments passed to the `Tool` constructor.
+
+    Returns:
+        Tool: A new Tool instance wrapping `func`.
+    """
+    return Tool(func_callable=func, **kwargs)
+
+
+# File: lionagi/operatives/action/tool.py

lionagi/protocols/_concepts.py

@@ -91,4 +91,4 @@ class Ordering(ABC, Generic[E]):
         pass
 
 
-# File: protocols/generic/concepts.py
+# File: lionagi/protocols/_concepts.py

lionagi/protocols/adapters/adapter.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `Adapter` protocol (a formal interface), along with the
+`AdapterRegistry` that maps string/file extensions or object keys to
+specific adapter implementations.
+"""
+
 import logging
 from typing import Any, Protocol, TypeVar, runtime_checkable
 
@@ -18,6 +24,25 @@ __all__ = (
 
 @runtime_checkable
 class Adapter(Protocol):
+    """
+    Describes a two-way converter that knows how to transform an object
+    from an external representation to an internal format, and vice versa.
+
+    Attributes
+    ----------
+    obj_key : str
+        A unique key or extension that identifies what format this
+        adapter supports (e.g. ".csv", "json", "pd_dataframe").
+
+    Methods
+    -------
+    from_obj(subj_cls: type[T], obj: Any, /, many: bool, **kwargs) -> dict|list[dict]
+        Converts a raw external object (file contents, JSON string, etc.)
+        into a dictionary or list of dictionaries.
+    to_obj(subj: T, /, many: bool, **kwargs) -> Any
+        Converts an internal object (e.g., a Pydantic-based model)
+        into the target format (file, JSON, DataFrame, etc.).
+    """
 
     obj_key: str
 

lionagi/protocols/adapters/json_adapter.py

@@ -1,3 +1,9 @@
+"""
+Implements two adapters:
+- `JsonAdapter` for in-memory JSON strings
+- `JsonFileAdapter` for reading/writing JSON files
+"""
+
 import json
 import logging
 from pathlib import Path
@@ -8,6 +14,11 @@ from .adapter import Adapter, T
 
 
 class JsonAdapter(Adapter):
+    """
+    Adapter that converts to/from JSON **strings** in memory.
+    Example usage: taking a Python dictionary and making JSON,
+    or parsing JSON string to a dict.
+    """
 
     obj_key = "json"
 
@@ -22,16 +33,31 @@ class JsonAdapter(Adapter):
         **kwargs,
     ) -> dict | list[dict]:
         """
-        kwargs for json.loads(s, **kwargs)
+        Convert a JSON string into a dict or list of dicts.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            The target class for context (not always used).
+        obj : str
+            The JSON string.
+        many : bool, optional
+            If True, expects a JSON array (returns list[dict]).
+            Otherwise returns a single dict or the first element.
+        **kwargs
+            Extra arguments for json.loads().
+
+        Returns
+        -------
+        dict | list[dict]
+            The loaded JSON data.
         """
         result = json.loads(obj, **kwargs)
         if many:
             return result if isinstance(result, list) else [result]
-        return (
-            result[0]
-            if isinstance(result, list) and len(result) > 0
-            else result
-        )
+        if isinstance(result, list) and len(result) > 0:
+            return result[0]
+        return result
 
     @classmethod
     def to_obj(
@@ -40,18 +66,38 @@ class JsonAdapter(Adapter):
         *,
         many: bool = False,
         **kwargs,
-    ):
+    ) -> str:
         """
-        kwargs for json.dumps(obj, **kwargs)
+        Convert an object (or collection) to a JSON string.
+
+        Parameters
+        ----------
+        subj : T
+            The object to serialize.
+        many : bool, optional
+            If True, convert multiple items to a JSON array.
+        **kwargs
+            Extra arguments for json.dumps().
+
+        Returns
+        -------
+        str
+            The resulting JSON string.
         """
         if many:
             if isinstance(subj, Collective):
-                return json.dumps([i.to_dict() for i in subj], **kwargs)
-            return json.dumps([subj.to_dict()], **kwargs)
+                data = [i.to_dict() for i in subj]
+            else:
+                data = [subj.to_dict()]
+            return json.dumps(data, **kwargs)
         return json.dumps(subj.to_dict(), **kwargs)
 
 
 class JsonFileAdapter(Adapter):
+    """
+    Adapter that reads/writes JSON data to/from a file on disk.
+    The file extension key is ".json".
+    """
 
     obj_key = ".json"
 
@@ -66,17 +112,31 @@ class JsonFileAdapter(Adapter):
         **kwargs,
     ) -> dict | list[dict]:
         """
-        kwargs for json.load(fp, **kwargs)
+        Read a JSON file from disk and return a dict or list of dicts.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            The target class for context.
+        obj : str | Path
+            The JSON file path.
+        many : bool
+            If True, expects a list. Otherwise single dict or first element.
+        **kwargs
+            Extra arguments for json.load().
+
+        Returns
+        -------
+        dict | list[dict]
+            The loaded data from file.
         """
-        with open(obj) as f:
+        with open(obj, encoding="utf-8") as f:
             result = json.load(f, **kwargs)
         if many:
             return result if isinstance(result, list) else [result]
-        return (
-            result[0]
-            if isinstance(result, list) and len(result) > 0
-            else result
-        )
+        if isinstance(result, list) and len(result) > 0:
+            return result[0]
+        return result
 
     @classmethod
     def to_obj(
@@ -86,16 +146,36 @@ class JsonFileAdapter(Adapter):
         *,
         fp: str | Path,
         many: bool = False,
+        mode: str = "w",
         **kwargs,
-    ):
+    ) -> None:
         """
-        kwargs for json.dump(obj, fp, **kwargs)
+        Write a dict (or list) to a JSON file.
+
+        Parameters
+        ----------
+        subj : T
+            The object/collection to serialize.
+        fp : str | Path
+            The file path to write.
+        many : bool
+            If True, write as a JSON array of multiple items.
+        **kwargs
+            Extra arguments for json.dump().
+
+        Returns
+        -------
+        None
         """
-        if many:
-            if isinstance(subj, Collective):
-                json.dump([i.to_dict() for i in subj], fp=fp, **kwargs)
-                return
-            json.dump([subj.to_dict()], fp=fp, **kwargs)
-            return
-        json.dump(subj.to_dict(), fp=fp, **kwargs)
-        logging.info(f"Successfully saved data to {fp}")
+        with open(fp, mode, encoding="utf-8") as f:
+            if many:
+                if isinstance(subj, Collective):
+                    json.dump([i.to_dict() for i in subj], f, **kwargs)
+                else:
+                    json.dump([subj.to_dict()], f, **kwargs)
+            else:
+                json.dump(subj.to_dict(), f, **kwargs)
+        logging.info(f"JSON data saved to {fp}")
+
+
+# File: lionagi/protocols/adapters/json_adapter.py

lionagi/protocols/adapters/pandas_/csv_adapter.py

@@ -9,6 +9,11 @@ from ..adapter import Adapter, T
 
 
 class CSVFileAdapter(Adapter):
+    """
+    Reads/writes CSV files to a list of dicts or vice versa,
+    using `pandas`.
+    """
+
     obj_key = ".csv"
 
     @classmethod
@@ -21,10 +26,31 @@ class CSVFileAdapter(Adapter):
         many: bool = False,
         **kwargs,
     ) -> list[dict]:
-        """kwargs for pd.read_csv"""
+        """
+        Read a CSV file into a list of dictionaries.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            The target class for context (not used).
+        obj : str | Path
+            The CSV file path.
+        many : bool, optional
+            If True, returns list[dict]; if False, returns only
+            the first dict.
+        **kwargs
+            Additional options for `pd.read_csv`.
+
+        Returns
+        -------
+        list[dict]
+            The parsed CSV data as a list of row dictionaries.
+        """
         df: pd.DataFrame = pd.read_csv(obj, **kwargs)
         dicts_ = df.to_dict(orient="records")
-        return dicts_[0] if not many else dicts_
+        if many:
+            return dicts_
+        return dicts_[0] if len(dicts_) > 0 else {}
 
     @classmethod
     def to_obj(
@@ -35,16 +61,34 @@ class CSVFileAdapter(Adapter):
         fp: str | Path,
         many: bool = False,
         **kwargs,
-    ):
-        """kwargs for pd.DataFrame.to_csv"""
-        kwargs["index"] = False
+    ) -> None:
+        """
+        Write an object's data to a CSV file.
+
+        Parameters
+        ----------
+        subj : T
+            The item(s) to convert. If `many=True`, can be a Collective.
+        fp : str | Path
+            File path to write the CSV.
+        many : bool
+            If True, we assume a collection of items, else a single item.
+        **kwargs
+            Extra params for `DataFrame.to_csv`.
+
+        Returns
+        -------
+        None
+        """
+        kwargs["index"] = False  # By default, do not save index
         if many:
             if isinstance(subj, Collective):
                 pd.DataFrame([i.to_dict() for i in subj]).to_csv(fp, **kwargs)
-                logging.info(f"Successfully saved data to {fp}")
-                return
+            else:
+                pd.DataFrame([subj.to_dict()]).to_csv(fp, **kwargs)
+        else:
             pd.DataFrame([subj.to_dict()]).to_csv(fp, **kwargs)
-            logging.info(f"Successfully saved data to {fp}")
-            return
-        pd.DataFrame([subj.to_dict()]).to_csv(fp, **kwargs)
-        logging.info(f"Successfully saved data to {fp}")
+        logging.info(f"CSV data saved to {fp}")
+
+
+# File: lionagi/protocols/adapters/pandas_/csv_adapter.py

lionagi/protocols/adapters/pandas_/excel_adapter.py

@@ -1,3 +1,8 @@
+"""
+Provides an ExcelFileAdapter for reading/writing Excel (.xlsx) files
+via pandas.
+"""
+
 import logging
 from pathlib import Path
 
@@ -9,6 +14,10 @@ from ..adapter import Adapter, T
 
 
 class ExcelFileAdapter(Adapter):
+    """
+    Reads/writes Excel (XLSX) files, using `pandas`.
+    """
+
     obj_key = ".xlsx"
 
     @classmethod
@@ -21,10 +30,29 @@ class ExcelFileAdapter(Adapter):
         many: bool = False,
         **kwargs,
     ) -> list[dict]:
-        """kwargs for pd.read_csv"""
+        """
+        Read an Excel file into a list of dictionaries.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            Target class for context.
+        obj : str | Path
+            The Excel file path.
+        many : bool, optional
+            If True, returns list[dict]. If False, returns single dict or first element.
+        **kwargs
+            Additional options for `pd.read_excel`.
+
+        Returns
+        -------
+        list[dict]
+        """
         df: pd.DataFrame = pd.read_excel(obj, **kwargs)
         dicts_ = df.to_dict(orient="records")
-        return dicts_[0] if not many else dicts_
+        if many:
+            return dicts_
+        return dicts_[0] if len(dicts_) > 0 else {}
 
     @classmethod
     def to_obj(
@@ -35,18 +63,32 @@ class ExcelFileAdapter(Adapter):
         fp: str | Path,
         many: bool = False,
         **kwargs,
-    ):
-        """kwargs for pd.DataFrame.to_csv"""
+    ) -> None:
+        """
+        Write data to an Excel file.
+
+        Parameters
+        ----------
+        subj : T
+            The object(s) to convert to Excel rows.
+        fp : str | Path
+            Path to save the XLSX file.
+        many : bool
+            If True, writes multiple items (e.g., a Collective).
+        **kwargs
+            Extra parameters for `DataFrame.to_excel`.
+        """
         kwargs["index"] = False
         if many:
             if isinstance(subj, Collective):
                 pd.DataFrame([i.to_dict() for i in subj]).to_excel(
                     fp, **kwargs
                 )
-                logging.info(f"Successfully saved data to {fp}")
-                return
+            else:
+                pd.DataFrame([subj.to_dict()]).to_excel(fp, **kwargs)
+        else:
             pd.DataFrame([subj.to_dict()]).to_excel(fp, **kwargs)
-            logging.info(f"Successfully saved data to {fp}")
-            return
-        pd.DataFrame([subj.to_dict()]).to_excel(fp, **kwargs)
-        logging.info(f"Successfully saved data to {fp}")
+        logging.info(f"Excel data saved to {fp}")
+
+
+# File: lionagi/protocols/adapters/pandas_/excel_adapter.py

lionagi/protocols/adapters/pandas_/pd_dataframe_adapter.py

@@ -1,3 +1,8 @@
+"""
+Defines a `PandasDataFrameAdapter` that converts between
+a DataFrame and a list of dictionary-based elements.
+"""
+
 from datetime import datetime
 
 import pandas as pd
@@ -6,6 +11,11 @@ from ..adapter import Adapter, T
 
 
 class PandasDataFrameAdapter(Adapter):
+    """
+    Converts a set of objects to a single `pd.DataFrame`, or
+    a DataFrame to a list of dictionaries. Typically used in memory,
+    not for saving to file.
+    """
 
     obj_key = "pd_dataframe"
     alias = ("pandas_dataframe", "pd.DataFrame", "pd_dataframe")
@@ -14,18 +24,58 @@ class PandasDataFrameAdapter(Adapter):
     def from_obj(
         cls, subj_cls: type[T], obj: pd.DataFrame, /, **kwargs
     ) -> list[dict]:
-        """kwargs for pd.DataFrame.to_dict"""
+        """
+        Convert an existing DataFrame into a list of dicts.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            The internal class to which we might parse.
+        obj : pd.DataFrame
+            The DataFrame to convert.
+        **kwargs
+            Additional args for DataFrame.to_dict (like `orient`).
+
+        Returns
+        -------
+        list[dict]
+            Each row as a dictionary.
+        """
         return obj.to_dict(orient="records", **kwargs)
 
     @classmethod
     def to_obj(cls, subj: list[T], /, **kwargs) -> pd.DataFrame:
-        """kwargs for pd.DataFrame"""
+        """
+        Convert multiple items into a DataFrame, adjusting `created_at` to datetime.
+
+        Parameters
+        ----------
+        subj : list[T]
+            The items to convert. Each item must have `to_dict()`.
+        **kwargs
+            Additional arguments for `pd.DataFrame(...)`.
+
+        Returns
+        -------
+        pd.DataFrame
+            The resulting DataFrame.
+        """
         out_ = []
         for i in subj:
             _dict = i.to_dict()
-            _dict["created_at"] = datetime.fromtimestamp(_dict["created_at"])
+            # Attempt to parse timestamps
+            if "created_at" in _dict:
+                try:
+                    _dict["created_at"] = datetime.fromtimestamp(
+                        _dict["created_at"]
+                    )
+                except Exception:
+                    pass
             out_.append(_dict)
         df = pd.DataFrame(out_, **kwargs)
+        # Convert created_at to datetime if present
         if "created_at" in df.columns:
-            df["created_at"] = pd.to_datetime(df["created_at"])
+            df["created_at"] = pd.to_datetime(
+                df["created_at"], errors="coerce"
+            )
         return df

lionagi/protocols/adapters/pandas_/pd_series_adapter.py

@@ -1,17 +1,57 @@
+"""
+Defines a `PandasSeriesAdapter` that converts a single object
+to/from a `pd.Series`.
+"""
+
 import pandas as pd
 
 from ..adapter import Adapter, T
 
 
 class PandasSeriesAdapter(Adapter):
+    """
+    Converts a single item to a Pandas Series and vice versa.
+    Great for 1-row data or simpler key-value pairs.
+    """
 
     obj_key = "pd_series"
     alias = ("pandas_series", "pd.series", "pd_series")
 
     @classmethod
     def from_obj(cls, subj_cls: type[T], obj: pd.Series, /, **kwargs) -> dict:
+        """
+        Convert a Pandas Series into a dictionary.
+
+        Parameters
+        ----------
+        subj_cls : type[T]
+            Possibly the class we might use to rehydrate the item.
+        obj : pd.Series
+            The series to interpret.
+        **kwargs
+            Additional arguments for `Series.to_dict`.
+
+        Returns
+        -------
+        dict
+            The data from the Series as a dictionary.
+        """
         return obj.to_dict(**kwargs)
 
     @classmethod
     def to_obj(cls, subj: T, /, **kwargs) -> pd.Series:
+        """
+        Convert a single item to a Series.
+
+        Parameters
+        ----------
+        subj : T
+            The item, which must have `to_dict()`.
+        **kwargs
+            Extra args passed to `pd.Series`.
+
+        Returns
+        -------
+        pd.Series
+        """
         return pd.Series(subj.to_dict(), **kwargs)

lionagi/protocols/generic/element.py

@@ -457,4 +457,4 @@ class ID(Generic[E]):
             return False
 
 
-# File: protocols/generic/element.py
+# File: lionagi/protocols/generic/element.py