lionagi 0.6.1__py3-none-any.whl → 0.7.1__py3-none-any.whl

lionagi/operations/select/select.py

@@ -2,56 +2,37 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-
 from enum import Enum
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from lionagi.operatives.types import Instruct
-from lionagi.session.branch import Branch
-
-from .prompt import PROMPT
-from .utils import parse_selection, parse_to_representation
 
+from .utils import SelectionModel
 
-class SelectionModel(BaseModel):
-    """Model representing the selection output."""
-
-    selected: list[Any] = Field(default_factory=list)
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
 
 
 async def select(
+    branch: "Branch",
     instruct: Instruct | dict[str, Any],
     choices: list[str] | type[Enum] | dict[str, Any],
     max_num_selections: int = 1,
-    branch: Branch | None = None,
     branch_kwargs: dict[str, Any] | None = None,
     return_branch: bool = False,
     verbose: bool = False,
     **kwargs: Any,
-) -> SelectionModel | tuple[SelectionModel, Branch]:
-    """Perform a selection operation from given choices.
-
-    Args:
-        instruct: Instruction model or dictionary.
-        choices: Options to select from.
-        max_num_selections: Maximum selections allowed.
-        branch: Existing branch or None to create a new one.
-        branch_kwargs: Additional arguments for branch creation.
-        return_branch: If True, return the branch with the selection.
-        verbose: Whether to enable verbose output.
-        **kwargs: Additional keyword arguments.
-
-    Returns:
-        A SelectionModel instance, optionally with the branch.
-    """
+) -> SelectionModel | tuple[SelectionModel, "Branch"]:
     if verbose:
         print(f"Starting selection with up to {max_num_selections} choices.")
 
+    from .utils import SelectionModel, parse_selection, parse_to_representation
+
     branch = branch or Branch(**(branch_kwargs or {}))
     selections, contents = parse_to_representation(choices)
-    prompt = PROMPT.format(
+    prompt = SelectionModel.PROMPT.format(
         max_num_selections=max_num_selections, choices=selections
     )
 
@@ -73,7 +54,7 @@ async def select(
     instruct["context"] = context
 
     response_model: SelectionModel = await branch.operate(
-        operative_model=SelectionModel,
+        response_format=SelectionModel,
         **kwargs,
         **instruct,
     )

lionagi/operations/select/utils.py

@@ -4,14 +4,25 @@
 
 import inspect
 from enum import Enum
-from typing import Any
+from typing import Any, ClassVar
 
-from pydantic import BaseModel, JsonValue
+from pydantic import BaseModel, Field, JsonValue
 
 from lionagi.libs.validate.string_similarity import string_similarity
 from lionagi.utils import is_same_dtype
 
 
+# TODO: Make select a field to be added into a model, much like reason and action
+class SelectionModel(BaseModel):
+    """Model representing the selection output."""
+
+    PROMPT: ClassVar[str] = (
+        "Please select up to {max_num_selections} items from the following list {choices}. Provide the selection(s) into appropriate field in format required, and no comments from you"
+    )
+
+    selected: list[Any] = Field(default_factory=list)
+
+
 def parse_to_representation(
     choices: Enum | dict | list | tuple | set,
 ) -> tuple[list[str], JsonValue]:

lionagi/operations/translate/translate.py

@@ -0,0 +1,47 @@
+from typing import TYPE_CHECKING, Literal
+
+from lionagi.service.imodel import iModel
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def translate(
+    branch: "Branch",
+    text: str,
+    technique: Literal["SynthLang"] = "SynthLang",
+    technique_kwargs: dict = None,
+    compress: bool = False,
+    chat_model: iModel = None,
+    compress_model: iModel = None,
+    compression_ratio: float = 0.2,
+    compress_kwargs=None,
+    verbose: bool = True,
+    new_branch: bool = True,
+    **kwargs,
+):
+    if technique == "SynthLang":
+        from lionagi.libs.token_transform.synthlang import (
+            translate_to_synthlang,
+        )
+
+        if not technique_kwargs:
+            technique_kwargs = {}
+        if not technique_kwargs.get("template_name"):
+            technique_kwargs["template_name"] = "symbolic_systems"
+
+        technique_kwargs = {**technique_kwargs, **kwargs}
+
+        return await translate_to_synthlang(
+            text=text,
+            compress=compress,
+            chat_model=chat_model or branch.chat_model,
+            compress_model=compress_model,
+            compression_ratio=compression_ratio,
+            compress_kwargs=compress_kwargs,
+            verbose=verbose,
+            branch=branch if not new_branch else None,
+            **technique_kwargs,
+        )
+
+    raise ValueError(f"Technique {technique} is not supported.")

lionagi/operations/types.py

@@ -3,11 +3,27 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from .brainstorm.brainstorm import brainstorm
+from .chat.chat import chat
+from .communicate.communicate import communicate
+from .instruct.instruct import instruct
+from .interpret.interpret import interpret
+from .operate.operate import operate
+from .parse.parse import parse
 from .plan.plan import plan
+from .ReAct.ReAct import ReAct
 from .select.select import select
+from .translate.translate import translate
 
 __all__ = (
     "brainstorm",
     "plan",
     "select",
+    "chat",
+    "communicate",
+    "instruct",
+    "interpret",
+    "operate",
+    "parse",
+    "ReAct",
+    "translate",
 )

lionagi/operatives/action/manager.py

@@ -2,11 +2,16 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `ActionManager` class, a specialized Manager that registers
+`Tool` objects (or callables) for function invocation. It can match
+incoming requests (ActionRequest) to a registered tool, then run it.
+"""
+
 from typing import Any
 
 from lionagi.protocols._concepts import Manager
-from lionagi.protocols.generic.event import EventStatus, Execution
-from lionagi.protocols.generic.log import Log
+from lionagi.protocols.generic.event import Execution
 from lionagi.protocols.messages.action_request import ActionRequest
 from lionagi.utils import to_list
 
@@ -18,9 +23,22 @@ __all__ = ("ActionManager",)
 
 
 class ActionManager(Manager):
+    """
+    A manager that registers function-based tools and invokes them
+    when triggered by an ActionRequest. Tools can be registered
+    individually or in bulk, and each tool must have a unique name.
+    """
 
     def __init__(self, *args: FuncTool, **kwargs) -> None:
+        """
+        Create an ActionManager, optionally registering initial tools.
 
+        Args:
+            *args (FuncTool):
+                A variable number of tools or callables.
+            **kwargs:
+                Additional named arguments that are also considered tools.
+        """
         super().__init__()
         self.registry: dict[str, Tool] = {}
 
@@ -28,24 +46,19 @@ class ActionManager(Manager):
         if args:
             tools.extend(to_list(args, dropna=True, flatten=True))
         if kwargs:
-            tools.extend(
-                to_list(kwargs, dropna=True, flatten=True, use_values=True)
-            )
+            tools.extend(to_list(kwargs.values(), dropna=True, flatten=True))
+
         self.register_tools(tools, update=True)
 
     def __contains__(self, tool: FuncToolRef) -> bool:
-        """Check if a tool is registered in the registry.
-
-        Supports checking by:
-        - Tool object
-        - Tool name (string)
-        - Callable function
-
-        Args:
-            tool: The tool to check for registration.
+        """
+        Check if a tool is registered, by either:
+        - The Tool object itself,
+        - A string name for the function,
+        - Or the callable's __name__.
 
         Returns:
-            bool: True if tool is registered, False otherwise.
+            bool: True if found, else False.
         """
         if isinstance(tool, Tool):
             return tool.function in self.registry
@@ -55,24 +68,21 @@ class ActionManager(Manager):
             return tool.__name__ in self.registry
         return False
 
-    def register_tool(
-        self,
-        tool: FuncTool,
-        update: bool = False,
-    ) -> None:
-        """Register a single tool in the registry.
-
-        If the tool is a callable function, it is automatically converted
-        to a Tool object. Existing tools can be updated if update=True.
+    def register_tool(self, tool: FuncTool, update: bool = False) -> None:
+        """
+        Register a single tool/callable in the manager.
 
         Args:
-            tool: The tool to register (Tool object or callable).
-            update: If True, update existing tool; if False, raise error.
+            tool (FuncTool):
+                A `Tool` object or a raw callable function.
+            update (bool):
+                If True, allow replacing an existing tool with the same name.
 
         Raises:
             ValueError: If tool already registered and update=False.
-            TypeError: If tool is not a Tool object or callable.
+            TypeError: If `tool` is not a Tool or callable.
         """
+        # Check if tool already exists
         if not update and tool in self:
             name = None
             if isinstance(tool, Tool):
@@ -81,93 +91,93 @@ class ActionManager(Manager):
                 name = tool.__name__
             raise ValueError(f"Tool {name} is already registered.")
 
+        # Convert raw callable to a Tool if needed
         if callable(tool):
             tool = Tool(func_callable=tool)
         if not isinstance(tool, Tool):
-            raise TypeError("Please register a Tool object or callable.")
-
+            raise TypeError(
+                "Must provide a `Tool` object or a callable function."
+            )
         self.registry[tool.function] = tool
 
     def register_tools(
-        self,
-        tools: list[FuncTool] | FuncTool,
-        update: bool = False,
+        self, tools: list[FuncTool] | FuncTool, update: bool = False
     ) -> None:
-        """Register multiple tools in the registry.
-
-        Handles both single tools and lists of tools. Each tool can be
-        either a Tool object or a callable function.
+        """
+        Register multiple tools at once.
 
         Args:
-            tools: Single tool or list of tools to register.
-            update: If True, update existing tools; if False, raise error.
+            tools (list[FuncTool] | FuncTool):
+                A single or list of tools/callables.
+            update (bool):
+                If True, allow updating existing tools.
 
         Raises:
-            ValueError: If any tool is already registered.
-            TypeError: If any tool is not a Tool object or callable.
+            ValueError: If a duplicate tool is found and update=False.
+            TypeError: If any item is not a Tool or callable.
         """
         tools_list = tools if isinstance(tools, list) else [tools]
-        [
-            self.register_tool(tool, update=update)
-            for tool in to_list(tools_list, dropna=True, flatten=True)
-        ]
+        for t in tools_list:
+            self.register_tool(t, update=update)
 
     def match_tool(
-        self, action_request: ActionRequest | ActionRequestModel
+        self, action_request: ActionRequest | ActionRequestModel | dict
     ) -> FunctionCalling:
-        if not isinstance(action_request, ActionRequest | ActionRequestModel):
+        """
+        Convert an ActionRequest (or dict with "function"/"arguments")
+        into a `FunctionCalling` instance by finding the matching tool.
+
+        Raises:
+            TypeError: If `action_request` is an unsupported type.
+            ValueError: If no matching tool is found in the registry.
+
+        Returns:
+            FunctionCalling: The event object that can be invoked.
+        """
+        if not isinstance(
+            action_request, ActionRequest | ActionRequestModel | dict
+        ):
             raise TypeError(f"Unsupported type {type(action_request)}")
 
-        tool = self.registry.get(action_request.function, None)
+        func, args = None, None
+        if isinstance(action_request, dict):
+            func = action_request["function"]
+            args = action_request["arguments"]
+        else:
+            func = action_request.function
+            args = action_request.arguments
+
+        tool = self.registry.get(func, None)
         if not isinstance(tool, Tool):
-            raise ValueError(
-                f"Function {action_request.function} is not registered."
-            )
-        return FunctionCalling(
-            func_tool=tool, arguments=action_request.arguments
-        )
+            raise ValueError(f"Function {func} is not registered.")
+
+        return FunctionCalling(func_tool=tool, arguments=args)
 
     async def invoke(
-        self, func_call: ActionRequestModel | ActionRequest
-    ) -> FunctionCalling | Execution | None:
-        """Invoke a tool based on the provided function call.
+        self,
+        func_call: ActionRequestModel | ActionRequest,
+    ) -> FunctionCalling:
+        """
+        High-level API to parse and run a function call.
 
-        1. Matches function call to registered tool
-        2. Creates FunctionCalling instance
-        3. Invokes function with arguments
-        4. Logs execution details
-        5. Returns result
+        Steps:
+          1) Convert `func_call` to FunctionCalling via `match_tool`.
+          2) `invoke()` the resulting object.
+          3) Return the `FunctionCalling`, which includes `execution`.
 
         Args:
-            func_call: Function call specification in supported format.
-            log_manager: Optional logger for execution tracking.
+            func_call: The action request model or ActionRequest object.
 
         Returns:
-            Result of tool invocation after processing pipeline.
-
-        Raises:
-            ValueError: If function not registered or call format invalid.
-        """
-        try:
-            function_calling = self.match_tool(func_call)
-        except ValueError as e:
-            return Log(
-                content={
-                    "event_type": "function_call",
-                    "status": EventStatus.FAILED,
-                    "error": str(e),
-                }
-            )
+            `FunctionCalling` event after it completes execution.
+        """
+        function_calling = self.match_tool(func_call)
         await function_calling.invoke()
         return function_calling
 
     @property
     def schema_list(self) -> list[dict[str, Any]]:
-        """List all tool schemas currently registered.
-
-        Returns:
-            List of OpenAI function schemas for all registered tools.
-        """
+        """Return the list of JSON schemas for all registered tools."""
         return [tool.tool_schema for tool in self.registry.values()]
 
     def get_tool_schema(
@@ -176,20 +186,25 @@ class ActionManager(Manager):
         auto_register: bool = True,
         update: bool = False,
     ) -> dict:
-        """Retrieve the schema for specific tools or all tools.
+        """
+        Retrieve schemas for a subset of tools or for all.
 
         Args:
-            tools: Specification of which tools to retrieve schemas for.
-                If True, return all tools. If False, return empty dict.
-                Can also be a specific tool or list of tools.
-            **kwargs: Additional keyword arguments to include in output.
+            tools (ToolRef):
+                - If True, return schema for all tools.
+                - If False, return an empty dict.
+                - If specific tool(s), returns only those schemas.
+            auto_register (bool):
+                If a tool (callable) is not yet in the registry, register if True.
+            update (bool):
+                If True, allow updating existing tools.
 
         Returns:
-            Dictionary containing tool schemas and additional kwargs.
+            dict: e.g., {"tools": [list of schemas]}
 
         Raises:
-            ValueError: If a specified tool is not registered.
-            TypeError: If an unsupported tool type is provided.
+            ValueError: If requested tool is not found and auto_register=False.
+            TypeError: If tool specification is invalid.
         """
         if isinstance(tools, list | tuple) and len(tools) == 1:
             tools = tools[0]
@@ -208,10 +223,15 @@ class ActionManager(Manager):
         tool: Any,
         auto_register: bool = True,
         update: bool = False,
-    ) -> dict[str, Any] | list[dict[str, Any]]:
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """
+        Internal helper to handle retrieval or registration of a single or
+        multiple tools, returning their schema(s).
+        """
         if isinstance(tool, dict):
-            return tool
+            return tool  # Already a schema
         if callable(tool):
+            # Possibly unregistered function
             name = tool.__name__
             if name not in self.registry:
                 if auto_register:
@@ -234,3 +254,5 @@ class ActionManager(Manager):
 
 
 __all__ = ["ActionManager"]
+
+# File: lionagi/operatives/action/manager.py

lionagi/operatives/action/request_response_model.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines Pydantic models for action requests and responses. They typically map
+to conversation messages describing which function is called, with what arguments,
+and any returned output.
+"""
+
 from typing import Any
 
 from pydantic import Field, field_validator
@@ -28,6 +34,10 @@ __all__ = (
 
 
 class ActionRequestModel(HashableModel):
+    """
+    Captures a single action request, typically from a user or system message.
+    Includes the name of the function and the arguments to be passed.
+    """
 
     function: str | None = Field(
         None,
@@ -43,6 +53,12 @@ class ActionRequestModel(HashableModel):
 
     @field_validator("arguments", mode="before")
     def validate_arguments(cls, value: Any) -> dict[str, Any]:
+        """
+        Coerce arguments into a dictionary if possible, recursively.
+
+        Raises:
+            ValueError if the data can't be coerced.
+        """
         return to_dict(
             value,
             fuzzy_parse=True,
@@ -52,10 +68,19 @@ class ActionRequestModel(HashableModel):
 
     @field_validator("function", mode="before")
     def validate_function(cls, value: str) -> str:
+        """
+        Ensure the function name is a valid non-empty string (if provided).
+        """
         return validate_nullable_string_field(cls, value, "function", False)
 
     @classmethod
     def create(cls, content: str):
+        """
+        Attempt to parse a string (usually from a conversation or JSON) into
+        one or more ActionRequestModel instances.
+
+        If no valid structure is found, returns an empty list.
+        """
         try:
             content = parse_action_request(content)
             if content:
@@ -75,6 +100,10 @@ ACTION_REQUESTS_FIELD = FieldModel(
 
 
 class ActionResponseModel(HashableModel):
+    """
+    Encapsulates a function's output after being called. Typically
+    references the original function name, arguments, and the result.
+    """
 
     function: str = Field(default_factory=str, title="Function")
     arguments: dict[str, Any] = Field(default_factory=dict)
@@ -88,3 +117,5 @@ ACTION_RESPONSES_FIELD = FieldModel(
     title="Actions",
     description="**do not fill**",
 )
+
+# File: lionagi/operatives/action/request_response_model.py