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

lionagi/service/imodel.py

@@ -5,6 +5,8 @@
 import os
 import warnings
 
+from pydantic import BaseModel
+
 from .endpoints.base import APICalling, EndPoint
 from .endpoints.match_endpoint import match_endpoint
 from .endpoints.rate_limited_processor import RateLimitedAPIExecutor
@@ -266,6 +268,15 @@ class iModel:
         """
         return self.kwargs.get("model", "")
 
+    @property
+    def request_options(self) -> type[BaseModel] | None:
+        """type[BaseModel] | None: The request options model for the endpoint.
+
+        Returns:
+            The request options model if available; otherwise, None.
+        """
+        return self.endpoint.request_options
+
     def to_dict(self):
         kwargs = self.kwargs
         if "kwargs" in self.kwargs:

lionagi/service/providers/exa_/search.py

@@ -1,10 +1,8 @@
-from typing import TYPE_CHECKING, Literal
+from typing import Literal
 
 from lionagi.service.endpoints.base import EndPoint
 
-if TYPE_CHECKING:
-    from .models import ExaSearchRequest
-
+from .models import ExaSearchRequest
 
 CATEGORY_OPTIONS = Literal[
     "article",
@@ -21,6 +19,7 @@ CATEGORY_OPTIONS = Literal[
 ]
 
 SEARCH_CONFIG = {
+    "name": "search_exa",
     "provider": "exa",
     "base_url": "https://api.exa.ai",
     "endpoint": "search",
@@ -47,6 +46,7 @@ SEARCH_CONFIG = {
         "type",  # keyword, neural, auto
         "useAutoPrompt",
     },
+    "request_options": ExaSearchRequest,
 }
 
 

lionagi/service/providers/perplexity_/chat_completions.py

@@ -4,7 +4,10 @@
 
 from lionagi.service.endpoints.chat_completion import ChatCompletionEndPoint
 
+from .models import PerplexityChatCompletionRequest
+
 CHAT_COMPLETION_CONFIG = {
+    "name": "search_perplexity",
     "provider": "perplexity",
     "base_url": "https://api.perplexity.ai",
     "endpoint": "chat/completions",
@@ -31,6 +34,7 @@ CHAT_COMPLETION_CONFIG = {
         "frequency_penalty",
     },
     "allowed_roles": ["user", "assistant"],
+    "request_options": PerplexityChatCompletionRequest,
 }
 
 

lionagi/service/providers/perplexity_/models.py

@@ -0,0 +1,144 @@
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class PerplexityRole(str, Enum):
+    """Roles allowed in Perplexity's messages."""
+
+    system = "system"
+    user = "user"
+    assistant = "assistant"
+
+
+class PerplexityMessage(BaseModel):
+    """
+    A single message in the conversation.
+    `role` can be 'system', 'user', or 'assistant'.
+    `content` is the text for that conversation turn.
+    """
+
+    role: PerplexityRole = Field(
+        ...,
+        description="The role of the speaker. Must be system, user, or assistant.",
+    )
+    content: str = Field(..., description="The text content of this message.")
+
+
+class PerplexityChatCompletionRequest(BaseModel):
+    """
+    Represents the request body for Perplexity's Chat Completions endpoint.
+    Endpoint: POST https://api.perplexity.ai/chat/completions
+    """
+
+    model: str = Field(
+        ...,
+        description="The model name, e.g. 'llama-3.1-sonar-small-128k-online'.",
+    )
+    messages: list[PerplexityMessage] = Field(
+        ..., description="A list of messages forming the conversation so far."
+    )
+
+    # Optional parameters
+    frequency_penalty: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Multiplicative penalty > 0. Values > 1.0 penalize repeated tokens more strongly. "
+            "Value=1.0 means no penalty. Incompatible with presence_penalty."
+        ),
+    )
+    presence_penalty: float | None = Field(
+        default=None,
+        ge=-2.0,
+        le=2.0,
+        description=(
+            "Penalizes tokens that have appeared so far (range -2 to 2). "
+            "Positive values encourage talking about new topics. Incompatible with frequency_penalty."
+        ),
+    )
+    max_tokens: int | None = Field(
+        default=None,
+        description=(
+            "Maximum number of completion tokens. If omitted, model generates tokens until it "
+            "hits stop or context limit."
+        ),
+    )
+    return_images: bool | None = Field(
+        default=None,
+        description="If True, attempt to return images (closed beta feature).",
+    )
+    return_related_questions: bool | None = Field(
+        default=None,
+        description="If True, attempt to return related questions (closed beta feature).",
+    )
+    search_domain_filter: list[Any] | None = Field(
+        default=None,
+        description=(
+            "List of domains to limit or exclude in the online search. Example: ['example.com', '-twitter.com']. "
+            "Supports up to 3 entries. (Closed beta feature.)"
+        ),
+    )
+    search_recency_filter: str | None = Field(
+        default=None,
+        description=(
+            "Returns search results within a specified time interval: 'month', 'week', 'day', or 'hour'."
+        ),
+    )
+    stream: bool | None = Field(
+        default=None,
+        description=(
+            "If True, response is returned incrementally via Server-Sent Events (SSE)."
+        ),
+    )
+    temperature: float | None = Field(
+        default=None,
+        ge=0.0,
+        lt=2.0,
+        description=(
+            "Controls randomness of sampling, range [0, 2). Higher => more random. "
+            "Defaults to 0.2."
+        ),
+    )
+    top_k: int | None = Field(
+        default=None,
+        ge=0,
+        le=2048,
+        description=(
+            "Top-K filtering. 0 disables top-k filtering. If set, only the top K tokens are considered. "
+            "We recommend altering either top_k or top_p, but not both."
+        ),
+    )
+    top_p: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Nucleus sampling threshold. We recommend altering either top_k or top_p, but not both."
+        ),
+    )
+
+    @model_validator(mode="before")
+    def validate_penalties(cls, values):
+        """
+        Disallow using both frequency_penalty != 1.0 and presence_penalty != 0.0 at once,
+        since the docs say they're incompatible.
+        """
+        freq_pen = values.get("frequency_penalty", 1.0)
+        pres_pen = values.get("presence_penalty", 0.0)
+
+        # The doc states frequency_penalty is incompatible with presence_penalty.
+        # We'll enforce that if presence_penalty != 0, frequency_penalty must be 1.0
+        # or vice versa. Adjust logic as needed.
+        if pres_pen != 0.0 and freq_pen != 1.0:
+            raise ValueError(
+                "presence_penalty is incompatible with frequency_penalty. "
+                "Please use only one: either presence_penalty=0 with freq_pen !=1, "
+                "or presence_penalty!=0 with freq_pen=1."
+            )
+        return values
+
+    def to_dict(self) -> dict:
+        """Return a dict suitable for JSON serialization and sending to Perplexity API."""
+        return self.model_dump(exclude_none=True)

lionagi/session/branch.py

@@ -45,8 +45,10 @@ from lionagi.protocols.types import (
     SenderRecipient,
     System,
 )
+from lionagi.service.endpoints.base import EndPoint
 from lionagi.service.types import iModel, iModelManager
 from lionagi.settings import Settings
+from lionagi.tools.base import LionTool
 from lionagi.utils import UNDEFINED, alcall, bcall, copy
 
 if TYPE_CHECKING:
@@ -204,7 +206,9 @@ class Branch(Element, Communicatable, Relational):
         )
 
         # --- ActionManager ---
-        self._action_manager = ActionManager(tools)
+        self._action_manager = ActionManager()
+        if tools:
+            self.register_tools(tools)
 
         # --- LogManager ---
         if log_config:
@@ -345,6 +349,29 @@ class Branch(Element, Communicatable, Relational):
 
         return branch_clone
 
+    def _register_tool(self, tools: FuncTool | LionTool, update: bool = False):
+        if isinstance(tools, type) and issubclass(tools, LionTool):
+            tools = tools()
+        if isinstance(tools, LionTool):
+            tools = tools.to_tool()
+        self._action_manager.register_tool(tools, update=update)
+
+    def register_tools(
+        self, tools: FuncTool | list[FuncTool] | LionTool, update: bool = False
+    ):
+        """
+        Registers one or more tools in the ActionManager.
+
+        Args:
+            tools (FuncTool | list[FuncTool] | LionTool):
+                A single tool or a list of tools to register.
+            update (bool, optional):
+                If `True`, updates existing tools with the same name.
+        """
+        tools = [tools] if not isinstance(tools, list) else tools
+        for tool in tools:
+            self._register_tool(tool, update=update)
+
     # -------------------------------------------------------------------------
     # Conversion / Serialization
     # -------------------------------------------------------------------------
@@ -532,6 +559,59 @@ class Branch(Element, Communicatable, Relational):
         for key in self.mailbox.pending_ins:
             self.receive(key)
 
+    def connect(
+        self,
+        provider: str = None,
+        base_url: str = None,
+        endpoint: str | EndPoint = "chat",
+        endpoint_params: list[str] | None = None,
+        api_key: str = None,
+        queue_capacity: int = 100,
+        capacity_refresh_time: float = 60,
+        interval: float | None = None,
+        limit_requests: int = None,
+        limit_tokens: int = None,
+        invoke_with_endpoint: bool = False,
+        imodel: iModel = None,
+        name: str = None,
+        request_options: type[BaseModel] = None,
+        description: str = None,
+        update: bool = False,
+    ):
+        if not imodel:
+            imodel = iModel(
+                provider=provider,
+                base_url=base_url,
+                endpoint=endpoint,
+                endpoint_params=endpoint_params,
+                api_key=api_key,
+                queue_capacity=queue_capacity,
+                capacity_refresh_time=capacity_refresh_time,
+                interval=interval,
+                limit_requests=limit_requests,
+                limit_tokens=limit_tokens,
+                invoke_with_endpoint=invoke_with_endpoint,
+            )
+
+        if not update and name in self.tools:
+            raise ValueError(f"Tool with name '{name}' already exists.")
+
+        async def _connect(**kwargs):
+            """connect to an api endpoint"""
+            api_call = await imodel.invoke(**kwargs)
+            self._log_manager.log(Log.create(api_call))
+            return api_call.response
+
+        _connect.__name__ = name or imodel.endpoint.name
+        if description:
+            _connect.__doc__ = description
+
+        tool = Tool(
+            func_callable=_connect,
+            request_options=request_options or imodel.request_options,
+        )
+        self._action_manager.register_tools(tool, update=update)
+
     # -------------------------------------------------------------------------
     # Dictionary Conversion
     # -------------------------------------------------------------------------
@@ -824,6 +904,11 @@ class Branch(Element, Communicatable, Relational):
         actions: bool = False,
         reason: bool = False,
         action_kwargs: dict = None,
+        action_strategy: Literal[
+            "sequential", "concurrent", "batch"
+        ] = "concurrent",
+        action_batch_size: int = None,
+        verbose_action: bool = False,
         field_models: list[FieldModel] = None,
         exclude_fields: list | dict | None = None,
         request_params: ModelParams = None,
@@ -898,6 +983,12 @@ class Branch(Element, Communicatable, Relational):
                 If `True`, signals that the LLM should provide chain-of-thought or reasoning (where applicable).
             action_kwargs (dict | None, optional):
                 Additional parameters for the `branch.act()` call if tools are invoked.
+            action_strategy (Literal["sequential","concurrent","batch"], optional):
+                The strategy for invoking tools (default: "concurrent").
+            action_batch_size (int, optional):
+                The batch size for concurrent tool invocation if `action_strategy="batch"`.
+            verbose_action (bool, optional):
+                If `True`, logs detailed information about tool invocation.
             field_models (list[FieldModel] | None, optional):
                 Field-level definitions or overrides for the model schema.
             exclude_fields (list|dict|None, optional):
@@ -955,6 +1046,9 @@ class Branch(Element, Communicatable, Relational):
             actions=actions,
             reason=reason,
             action_kwargs=action_kwargs,
+            action_strategy=action_strategy,
+            action_batch_size=action_batch_size,
+            verbose_action=verbose_action,
             field_models=field_models,
             exclude_fields=exclude_fields,
             request_params=request_params,
@@ -1082,6 +1176,7 @@ class Branch(Element, Communicatable, Relational):
         self,
         action_request: ActionRequest | BaseModel | dict,
         suppress_errors: bool = False,
+        verbose_action: bool = False,
     ) -> ActionResponse:
         """
         Internal method to invoke a tool (action) asynchronously.
@@ -1097,13 +1192,19 @@ class Branch(Element, Communicatable, Relational):
         """
         from lionagi.operations._act.act import _act
 
-        return await _act(self, action_request, suppress_errors)
+        return await _act(
+            branch=self,
+            action_request=action_request,
+            suppress_errors=suppress_errors,
+            verbose_action=verbose_action,
+        )
 
     async def act(
         self,
         action_request: list | ActionRequest | BaseModel | dict,
         *,
         strategy: Literal["concurrent", "sequential", "batch"] = "concurrent",
+        verbose_action: bool = False,
         batch_size: int = None,
         suppress_errors: bool = True,
         sanitize_input: bool = False,
@@ -1129,6 +1230,10 @@ class Branch(Element, Communicatable, Relational):
             action_request (list|ActionRequest|BaseModel|dict):
                 A single or list of action requests, each requiring
                 `function` and `arguments`.
+            strategy (Literal["concurrent","sequential","batch"]):
+                The execution strategy to use.
+            verbose_action (bool):
+                If True, log detailed information about the action.
             suppress_errors (bool):
                 If True, log errors instead of raising exceptions.
             sanitize_input (bool):
@@ -1175,6 +1280,7 @@ class Branch(Element, Communicatable, Relational):
             case "concurrent":
                 return await self._concurrent_act(
                     action_request,
+                    verbose_action=verbose_action,
                     suppress_errors=suppress_errors,
                     sanitize_input=sanitize_input,
                     unique_input=unique_input,
@@ -1195,11 +1301,13 @@ class Branch(Element, Communicatable, Relational):
             case "sequential":
                 return await self._sequential_act(
                     action_request,
+                    verbose_action=verbose_action,
                     suppress_errors=suppress_errors,
                 )
             case "batch":
                 return await self._batch_act(
                     action_request,
+                    verbose_action=verbose_action,
                     batch_size=batch_size or 1,
                     max_concurrent=max_concurrent,
                     suppress_errors=suppress_errors,
@@ -1230,6 +1338,7 @@ class Branch(Element, Communicatable, Relational):
         self,
         action_request: ActionRequest | BaseModel | dict,
         suppress_errors: bool = True,
+        verbose_action: bool = False,
     ) -> list:
         action_request = (
             action_request
@@ -1239,7 +1348,11 @@ class Branch(Element, Communicatable, Relational):
         results = []
         for req in action_request:
             results.append(
-                await self._act(req, suppress_errors=suppress_errors)
+                await self._act(
+                    req,
+                    verbose_action=verbose_action,
+                    suppress_errors=suppress_errors,
+                )
             )
         return results
 
@@ -1480,6 +1593,10 @@ class Branch(Element, Communicatable, Relational):
         self,
         instruct: Instruct | dict[str, Any],
         interpret: bool = False,
+        interpret_domain: str | None = None,
+        interpret_style: str | None = None,
+        interpret_sample: str | None = None,
+        interpret_kwargs: dict | None = None,
         tools: Any = None,
         tool_schemas: Any = None,
         response_format: type[BaseModel] = None,
@@ -1488,6 +1605,7 @@ class Branch(Element, Communicatable, Relational):
         response_kwargs: dict | None = None,
         return_analysis: bool = False,
         analysis_model: iModel | None = None,
+        verbose: bool = False,
         **kwargs,
     ):
         """
@@ -1506,6 +1624,14 @@ class Branch(Element, Communicatable, Relational):
             interpret (bool, optional):
                 If `True`, first interprets (`branch.interpret`) the instructions to refine them
                 before proceeding. Defaults to `False`.
+            interpret_domain (str | None, optional):
+                Optional domain hint for the interpretation step.
+            interpret_style (str | None, optional):
+                Optional style hint for the interpretation step.
+            interpret_sample (str | None, optional):
+                Optional sample hint for the interpretation step.
+            interpret_kwargs (dict | None, optional):
+                Additional arguments for the interpretation step.
             tools (Any, optional):
                 Tools to be made available for the ReAct process. If omitted or `None`,
                 and if no `tool_schemas` are provided, it defaults to `True` (all tools).
@@ -1554,6 +1680,10 @@ class Branch(Element, Communicatable, Relational):
             self,
             instruct,
             interpret=interpret,
+            interpret_domain=interpret_domain,
+            interpret_style=interpret_style,
+            interpret_sample=interpret_sample,
+            interpret_kwargs=interpret_kwargs,
             tools=tools,
             tool_schemas=tool_schemas,
             response_format=response_format,
@@ -1562,6 +1692,8 @@ class Branch(Element, Communicatable, Relational):
             response_kwargs=response_kwargs,
             return_analysis=return_analysis,
             analysis_model=analysis_model,
+            verbose_action=verbose,
+            verbose_analysis=verbose,
             **kwargs,
         )
 

lionagi/tools/base.py

@@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+
+from lionagi.operatives.action.tool import Tool
+
+
+class LionTool(ABC):
+    is_lion_system_tool: bool = True
+    system_tool_name: str
+
+    @abstractmethod
+    def to_tool(self) -> Tool:
+        pass