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

lionagi/__init__.py

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import logging
+
 from pydantic import BaseModel, Field
 
 from . import _types as types
@@ -13,6 +15,9 @@ from .version import __version__
 
 LiteiModel = iModel
 
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
 __all__ = (
     "Session",
     "Branch",
@@ -24,4 +29,5 @@ __all__ = (
     "__version__",
     "BaseModel",
     "Field",
+    "logger",
 )

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
 
@@ -19,14 +21,19 @@ async def ReAct(
     branch: "Branch",
     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] | BaseModel = None,
-    extension_allowed: bool = False,
-    max_extensions: int | None = None,
+    extension_allowed: bool = True,
+    max_extensions: int | None = 3,
     response_kwargs: dict | None = None,
     return_analysis: bool = False,
     analysis_model: iModel | None = None,
+    verbose_analysis: bool = False,
     **kwargs,
 ):
     # If no tools or tool schemas are provided, default to "all tools"
@@ -41,8 +48,14 @@ async def ReAct(
                 instruct.to_dict()
                 if isinstance(instruct, Instruct)
                 else instruct
-            )
+            ),
+            domain=interpret_domain,
+            style=interpret_style,
+            sample_writing=interpret_sample,
+            **(interpret_kwargs or {}),
         )
+        if verbose_analysis:
+            print(f"Interpreted instruction: {instruction_str}")
 
     # Convert Instruct to dict if necessary
     instruct_dict = (
@@ -50,21 +63,22 @@ async def ReAct(
         if isinstance(instruct, Instruct)
         else dict(instruct)
     )
-    # Overwrite the "instruction" field with the interpreted string (if any)
-    instruct_dict["instruction"] = instruction_str or instruct_dict.get(
-        "instruction"
-    )
+
+    # Overwrite "instruction" with the interpreted prompt (if any) plus a note about expansions
+    max_ext_info = f"\nIf needed, you can do up to {max_extensions or 0 if extension_allowed else 0} expansions."
+    instruct_dict["instruction"] = (
+        instruction_str
+        or (instruct_dict.get("instruction") or "")  # in case it's missing
+    ) + max_ext_info
 
     # Prepare a copy of user-provided kwargs for the first operate call
     kwargs_for_operate = copy(kwargs)
     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,
@@ -73,17 +87,27 @@ async def ReAct(
     )
     analyses = [analysis]
 
+    # If verbose, show round #1 analysis
+    if verbose_analysis:
+        print(
+            f"ReAct Round #1 Analysis:\n {analysis.model_dump_json(indent=2)}",
+        )
+
     # Validate and clamp max_extensions if needed
-    if max_extensions and max_extensions > 5:
-        logging.warning("max_extensions should not exceed 5; defaulting to 5.")
-        max_extensions = 5
+    if max_extensions and max_extensions > 100:
+        logging.warning(
+            "max_extensions should not exceed 100; defaulting to 100."
+        )
+        max_extensions = 100
 
     # Step 2: Possibly loop through expansions if extension_needed
     extensions = max_extensions
+    round_count = 1
+
     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,20 +119,28 @@ 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
+        operate_kwargs = copy(kwargs)
+        operate_kwargs["actions"] = True
+        operate_kwargs["reason"] = True
+        operate_kwargs["response_format"] = ReActAnalysis
+        operate_kwargs["action_strategy"] = analysis.action_strategy
+        if analysis.action_batch_size:
+            operate_kwargs["action_batch_size"] = analysis.action_batch_size
 
         analysis = await branch.operate(
-            response_format=ReActAnalysis,
+            instruction=new_instruction,
             tools=tools,
             tool_schemas=tool_schemas,
-            **expanded_kwargs,
+            **operate_kwargs,
         )
         analyses.append(analysis)
+        round_count += 1
 
+        # If verbose, show round analysis
+        if verbose_analysis:
+            print(
+                f"ReAct Round #{round_count} Analysis:\n {analysis.model_dump_json(indent=2)}",
+            )
         if extensions:
             extensions -= 1
 

lionagi/operations/ReAct/utils.py

@@ -2,27 +2,91 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from typing import ClassVar
+from typing import ClassVar, Literal
 
 from pydantic import BaseModel, Field
 
 
+class PlannedAction(BaseModel):
+    """
+    Short descriptor for an upcoming action/tool invocation the LLM wants to perform.
+    The model can hold multiple actions in a single round if needed.
+    """
+
+    action_type: str = Field(
+        ...,
+        description="The name or type of tool/action to invoke (e.g., 'search_exa', 'reader_tool').",
+    )
+    description: str = Field(
+        ...,
+        description="A short explanation of why or what is intended to achieve with this action.",
+    )
+
+
 class ReActAnalysis(BaseModel):
+    """
+    Captures the ReAct chain-of-thought output each round:
+    1) The LLM's 'analysis' (reasoning),
+    2) A list of planned actions to perform before finalizing,
+    3) Indication whether more expansions/rounds are needed,
+    4) Additional tuning knobs: how to handle validation, how to execute actions, etc.
+    """
 
+    # Standard ReAct strings for controlling expansions:
     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 can perform multiple reason-action steps for accuracy. "
+        "If you are not ready to finalize, set extension_needed to True. "
+        "You have up to {extensions} expansions. Please continue."
     )
-
     CONTINUE_EXT_PROMPT: ClassVar[str] = (
-        "You are provided with another round, you have max another {extensions} rounds"
+        "Another round is available. You may do multiple actions if needed. "
+        "You have up to {extensions} expansions. Please continue."
     )
-
     ANSWER_PROMPT: ClassVar[str] = (
-        "given above reason and actions, please provide final answer to the original user request {instruction}"
+        "Given your reasoning and actions, please now provide the final answer "
+        "to the user's request:\n\n{instruction}"
+    )
+
+    analysis: str = Field(
+        ...,
+        description="Free-form reasoning or chain-of-thought summary. Must be consistent with the plan.",
+    )
+
+    planned_actions: list[PlannedAction] = Field(
+        default_factory=list,
+        description=(
+            "One or more short descriptors of the tool calls or operations "
+            "the LLM wants to perform this round. For example, read the doc, "
+            "then run a search."
+        ),
     )
 
-    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 True if more expansions are needed. If False, final answer is next.",
+    )
+
+    milestone: str | None = Field(
+        None,
+        description=(
+            "A sub-goal or mini-checkpoint to reach before finalizing. "
+            "E.g. 'Validate results from search_exa, then summarize outcomes.'"
+        ),
+    )
+
+    action_strategy: Literal["sequential", "concurrent", "batch"] = Field(
+        "concurrent",
+        description=(
+            "Specifies how to invoke the planned actions:\n"
+            "'sequential' => Each action is run in order, \n"
+            "'concurrent' => All actions run in parallel, \n"
+            "'batch' => Divide actions into async batches of N (if reasonable)."
+        ),
+    )
+
+    action_batch_size: int | None = Field(
+        None,
+        description=(
+            "provide if and only if action_strategy is 'batch', this specifies the number of actions to run in parallel per batch."
+        ),
     )

lionagi/operations/_act/act.py

@@ -18,6 +18,7 @@ async def _act(
     branch: "Branch",
     action_request: BaseModel | dict,
     suppress_errors: bool = False,
+    verbose_action: bool = False,
 ) -> "ActionResponseModel":
 
     _request = {}
@@ -35,6 +36,11 @@ async def _act(
 
     try:
         func_call = await branch._action_manager.invoke(_request)
+        if verbose_action:
+            print(
+                f"Action {_request['function']} invoked, status: {func_call.status}."
+            )
+
     except Exception as e:
         content = {
             "error": str(e),
@@ -43,6 +49,8 @@ async def _act(
             "branch": str(branch.id),
         }
         branch._log_manager.log(Log(content=content))
+        if verbose_action:
+            print(f"Action {_request['function']} failed, error: {str(e)}.")
         if suppress_errors:
             logging.error(
                 f"Error invoking action '{_request['function']}': {e}"

lionagi/operations/interpret/interpret.py

@@ -16,15 +16,46 @@ async def interpret(
     sample_writing: str | None = None,
     **kwargs,
 ) -> str:
-    instruction = (
-        "Rewrite the following user input into a clear, structured prompt or "
-        "query for an LLM, ensuring any implicit details are made explicit. "
-        "Return only the improved user prompt."
-    )
+    instruction = """
+You are given a user's raw instruction or question. Your task is to rewrite it into a clearer, more structured prompt for an LLM or system, making any implicit or missing details explicit. 
+
+Follow these guidelines:
+
+1. **Dissect the user's request**:
+   - If the user references a local file, note it clearly (e.g., "paper_file_path": "…").
+   - If the user might need external references or up-to-date data, mention that possibility.
+   - If the user's question is ambiguous, propose clarifications.
+   
+2. **Be explicit about the user's final objective**:
+   - For example, if the user wants a comparison with other works, add that as a bullet point or sub-question.
+   - If the user wants a summary plus code snippet, highlight that in your structured prompt.
+
+3. **Do NOT produce final system actions**:
+   - You're not calling any tools directly here; only rewriting the user query to reflect potential next steps.
+   - If the user's request might require searching or doc reading, note it as an *option*, e.g. "Potential tool usage: {search, partial doc read}."
+
+4. **Return only the improved user prompt**:
+   - The final output should be a single text block or short JSON specifying the clarified user request.
+   - Keep it concise yet thorough.
+
+For instance, if the user's original text is:
+"Please read my local PDF on RL and compare it to the newest research methods from exa or perplexity."
+
+A re-written version might be:
+"**Task**: 
+- Summarize the local PDF (paper_file_path: 'myRLpaper.pdf'). 
+- Compare its approach with recent reinforcement learning research found via exa/perplexity searches.
+**Potential Tool Usage**: 
+- Doc reading (reader_tool)
+- External search (search_exa, search_perplexity)
+**Output**: 
+- A structured summary + comparative analysis."
+
+Now, apply this rewriting to the input below. Return only the re-written prompt.
+        """
     guidance = (
         f"Domain hint: {domain or 'general'}. "
         f"Desired style: {style or 'concise'}. "
-        "You can add or clarify context if needed."
     )
     if sample_writing:
         guidance += f" Sample writing: {sample_writing}"
@@ -32,11 +63,11 @@ async def interpret(
     context = [f"User input: {text}"]
 
     # Default temperature if none provided
-    kwargs["temperature"] = kwargs.get("temperature", 0.1)
     kwargs["guidance"] = guidance + "\n" + kwargs.get("guidance", "")
+    kwargs["instruction"] = instruction + "\n" + kwargs.get("instruction", "")
+    kwargs["temperature"] = kwargs.get("temperature", 0.1)
 
     refined_prompt = await branch.chat(
-        instruction=instruction,
         context=context,
         **kwargs,
     )

lionagi/operations/operate/operate.py

@@ -50,6 +50,8 @@ async def operate(
     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,
@@ -189,9 +191,13 @@ async def operate(
             if instruct.action_strategy
             else action_kwargs.get("strategy", "concurrent")
         )
+        if action_batch_size:
+            action_kwargs["batch_size"] = action_batch_size
 
         action_response_models = await branch.act(
-            response_model.action_requests, **action_kwargs
+            response_model.action_requests,
+            verbose_action=verbose_action,
+            **action_kwargs,
         )
         # Possibly refine the operative with the tool outputs
         operative = Step.respond_operative(

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/operatives/action/tool.py

@@ -49,6 +49,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 +93,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/operatives/forms/flow.py

@@ -1,5 +1,4 @@
 # forms/flow.py
-from typing import List
 
 from pydantic import BaseModel, ConfigDict, Field
 

lionagi/operatives/forms/form.py

@@ -1,6 +1,6 @@
 # forms/form.py
 
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import ConfigDict, Field, model_validator
 from typing_extensions import Self

lionagi/protocols/messages/instruction.py

@@ -81,68 +81,121 @@ def format_text_item(item: Any) -> str:
 
 def format_text_content(content: dict) -> str:
     """
-    Convert a dictionary with keys like 'guidance', 'instruction', 'context', etc.
-    into a readable text block.
+    Convert a content dictionary into a minimal textual summary for LLM consumption.
 
-    Args:
-        content (dict): The content dictionary.
-
-    Returns:
-        str: A textual summary.
+    Emphasizes brevity and clarity:
+      - Skips empty or None fields.
+      - Bullet-points for lists.
+      - Key-value pairs for dicts.
+      - Minimal headings for known fields (guidance, instruction, etc.).
     """
-    if "plain_content" in content and isinstance(
-        content["plain_content"], str
-    ):
-        return content["plain_content"]
 
-    msg = "\n---\n # Task\n"
+    if isinstance(content.get("plain_content"), str):
+        return content["plain_content"]
 
-    for k in [
+    lines = []
+    # We only want minimal headings for certain known fields:
+    known_field_order = [
         "guidance",
         "instruction",
         "context",
         "tool_schemas",
         "respond_schema_info",
         "request_response_format",
-    ]:
-        if k in content:
-            v = content[k]
-
-            if k == "tool_schemas":
-                if "tools" in v:
-                    v = v["tools"]
-
-                if isinstance(v, list):
-                    z = []
-                    for idx, z_ in enumerate(v):
-                        if isinstance(z_, dict) and "function" in z_:
-                            z.append({f"Tool {idx+1}": z_["function"]})
-                    v = z
-
-            if k == "request_response_format":
-                k = "response format"
-
-            if v not in [None, [], {}, UNDEFINED]:
-                if isinstance(v, list):
-                    msg += f"## - **{k}**\n"
-                    for i in v:
-                        if (
-                            len(format_text_item(v).replace("\n", "").strip())
-                            > 0
-                        ):
-                            msg += format_text_item(i).strip()
-                    msg += "\n"
-                else:
-                    if len(format_text_item(v).replace("\n", "").strip()) > 0:
-                        msg += (
-                            f"## - **{k}**\n{format_text_item(v).strip()}\n\n"
-                        )
-
-    if not msg.endswith("\n\n"):
-        msg += "\n\n---\n"
+    ]
+
+    # Render known fields in that order
+    for field in known_field_order:
+        if field in content:
+            val = content[field]
+            if _is_not_empty(val):
+                if field == "request_response_format":
+                    field = "response format"
+                elif field == "respond_schema_info":
+                    field = "response schema info"
+                lines.append(f"\n## {field.upper()}:\n")
+                rendered = _render_value(val)
+                # Indent or bullet the rendered result if multiline
+                # We'll keep it minimal: each line is prefixed with "  ".
+                lines.extend(
+                    f"  {line}"
+                    for line in rendered.split("\n")
+                    if line.strip()
+                )
+
+    # Join all lines into a single string
+    return "\n".join(lines).strip()
+
+
+def _render_value(val) -> str:
+    """
+    Render an arbitrary value (scalar, list, dict) in minimal form:
+    - Lists become bullet points.
+    - Dicts become key-value lines.
+    - Strings returned directly.
+    """
+    if isinstance(val, dict):
+        return _render_dict(val)
+    elif isinstance(val, list):
+        return _render_list(val)
     else:
-        msg += "---\n"
-    return msg
+        return str(val).strip()
+
+
+def _render_dict(dct: dict) -> str:
+    """
+    Minimal bullet list for dictionary items:
+      key: rendered subvalue
+    """
+    lines = []
+    for k, v in dct.items():
+        if not _is_not_empty(v):
+            continue
+        subrendered = _render_value(v)
+        # Indent subrendered if multiline
+        sublines = subrendered.split("\n")
+        if len(sublines) == 1:
+            if sublines[0].startswith("- "):
+                lines.append(f"- {k}: {sublines[0][2:]}")
+            else:
+                lines.append(f"- {k}: {sublines[0]}")
+        else:
+            lines.append(f"- {k}:")
+            for s in sublines:
+                lines.append(f"  {s}")
+    return "\n".join(lines)
+
+
+def _render_list(lst: list) -> str:
+    """
+    Each item in the list gets a bullet. Nested structures are recursed.
+    """
+    lines = []
+    for idx, item in enumerate(lst, 1):
+        sub = _render_value(item)
+        sublines = sub.split("\n")
+        if len(sublines) == 1:
+            if sublines[0].startswith("- "):
+                lines.append(f"- {sublines[0][2:]}")
+            else:
+                lines.append(f"- {sublines[0]}")
+        else:
+            lines.append("-")
+            lines.extend(f"  {s}" for s in sublines)
+    return "\n".join(lines)
+
+
+def _is_not_empty(x) -> bool:
+    """
+    Returns True if x is neither None, nor empty string/list/dict.
+    """
+    if x is None:
+        return False
+    if isinstance(x, (list, dict)) and not x:
+        return False
+    if isinstance(x, str) and not x.strip():
+        return False
+    return True
 
 
 def format_image_content(

lionagi/service/endpoints/base.py

@@ -61,6 +61,7 @@ class EndpointConfig(BaseModel):
         use_enum_values=True,
     )
 
+    name: str | None = None
     provider: str | None = None
     base_url: str | None = None
     endpoint: str
@@ -75,6 +76,7 @@ class EndpointConfig(BaseModel):
     requires_tokens: bool = False
     api_version: str | None = None
     allowed_roles: list[str] | None = None
+    request_options: type | None = None
 
 
 class EndPoint(ABC):
@@ -100,6 +102,11 @@ class EndPoint(ABC):
         config.update(kwargs)
         self.config = EndpointConfig(**config)
 
+    @property
+    def name(self) -> str | None:
+        """str | None: The name of the endpoint, if any."""
+        return self.config.name or self.endpoint
+
     @property
     def is_streamable(self) -> bool:
         """bool: Whether this endpoint supports streaming responses."""
@@ -185,6 +192,10 @@ class EndPoint(ABC):
         """bool: Indicates if this endpoint uses role-based messages."""
         return self.allowed_roles is not None
 
+    @property
+    def request_options(self) -> type | None:
+        return self.config.request_options
+
     def create_payload(self, **kwargs) -> dict:
         """Generates a request payload (and headers) for this endpoint.