lionagi 0.8.5__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

@@ -28,11 +28,12 @@ async def ReAct(
     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"
@@ -53,6 +54,8 @@ async def ReAct(
             sample_writing=interpret_sample,
             **(interpret_kwargs or {}),
         )
+        if verbose_analysis:
+            print(f"Interpreted instruction: {instruction_str}")
 
     # Convert Instruct to dict if necessary
     instruct_dict = (
@@ -60,10 +63,13 @@ 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)
@@ -81,13 +87,23 @@ 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
@@ -103,16 +119,28 @@ async def ReAct(
                 extensions=extensions
             )
 
+        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(
             instruction=new_instruction,
-            response_format=ReActAnalysis,
             tools=tools,
             tool_schemas=tool_schemas,
-            reason=True,
-            actions=True,
+            **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 additional rounds to perform reason action to provide an accurate final answer. you have max another {extensions} rounds. Pleasen continue."
+        "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. Please continue."
+        "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:\n\n {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. 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.",
+        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/session/branch.py

@@ -48,6 +48,7 @@ from lionagi.protocols.types import (
 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:
@@ -205,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:
@@ -346,19 +349,28 @@ 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], update: bool = False
+        self, tools: FuncTool | list[FuncTool] | LionTool, update: bool = False
     ):
         """
         Registers one or more tools in the ActionManager.
 
         Args:
-            tools (FuncTool | list[FuncTool]):
+            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.
         """
-        self._action_manager.register_tools(tools, update=update)
+        tools = [tools] if not isinstance(tools, list) else tools
+        for tool in tools:
+            self._register_tool(tool, update=update)
 
     # -------------------------------------------------------------------------
     # Conversion / Serialization
@@ -892,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,
@@ -966,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):
@@ -1023,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,
@@ -1150,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.
@@ -1165,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,
@@ -1197,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):
@@ -1243,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,
@@ -1263,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,
@@ -1298,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
@@ -1307,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
 
@@ -1560,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,
     ):
         """
@@ -1646,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

lionagi/tools/reader.py

@@ -0,0 +1,244 @@
+import tempfile
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+from lionagi.operatives.action.tool import Tool
+from lionagi.utils import to_num
+
+from .base import LionTool
+
+
+class ReaderAction(str, Enum):
+    """
+    This enumeration indicates the *type* of action the LLM wants to perform.
+    - 'open': Convert a file/URL to text and store it internally for partial reads
+    - 'read': Return a partial slice of the already-opened doc
+    """
+
+    open = "open"
+    read = "read"
+
+
+class ReaderRequest(BaseModel):
+    """
+    The request model for the 'ReaderTool'.
+    It indicates:
+      - whether we are 'open'-ing a doc or 'read'-ing from a doc
+      - which file/URL we want to open (if action='open')
+      - which doc_id and offsets we want to read (if action='read')
+    """
+
+    action: ReaderAction = Field(
+        ...,
+        description=(
+            "Action to perform. Must be one of: "
+            "- 'open': Convert a file/URL to text and store it internally for partial reads. "
+            "- 'read': Return a partial slice of the already-opened doc."
+        ),
+    )
+
+    path_or_url: str | None = Field(
+        None,
+        description=(
+            "Local file path or remote URL to open. This field is REQUIRED if action='open'. "
+            "If action='read', leave it None."
+        ),
+    )
+
+    doc_id: str | None = Field(
+        None,
+        description=(
+            "Unique ID referencing a previously opened document. "
+            "This field is REQUIRED if action='read'. If action='open', leave it None."
+        ),
+    )
+
+    start_offset: int | None = Field(
+        None,
+        description=(
+            "Character start offset in the doc for partial reading. "
+            "If omitted or None, defaults to 0. Only used if action='read'."
+        ),
+    )
+
+    end_offset: int | None = Field(
+        None,
+        description=(
+            "Character end offset in the doc for partial reading. "
+            "If omitted or None, we read until the document's end. Only used if action='read'."
+        ),
+    )
+
+    @field_validator("start_offset", "end_offset", mode="before")
+    def _validate_offsets(cls, v):
+        try:
+            return to_num(v, num_type=int)
+        except ValueError:
+            return None
+
+
+class DocumentInfo(BaseModel):
+    """
+    Returned info when we 'open' a doc.
+    doc_id: The unique string to reference this doc in subsequent 'read' calls
+    length: The total character length of the converted text
+    """
+
+    doc_id: str
+    length: int | None = None
+
+
+class PartialChunk(BaseModel):
+    """
+    Represents a partial slice of text from [start_offset..end_offset).
+    """
+
+    start_offset: int | None = None
+    end_offset: int | None = None
+    content: str | None = None
+
+
+class ReaderResponse(BaseModel):
+    """
+    The response from the 'ReaderTool'.
+    - If action='open' succeeded, doc_info is filled (doc_id & length).
+    - If action='read' succeeded, chunk is filled (the partial text).
+    - If failure occurs, success=False & error hold details.
+    """
+
+    success: bool = Field(
+        ...,
+        description=(
+            "Indicates if the requested action was performed successfully."
+        ),
+    )
+    error: str | None = Field(
+        None,
+        description=("Describes any error that occurred, if success=False."),
+    )
+    doc_info: DocumentInfo | None = Field(
+        None,
+        description=(
+            "Populated only if action='open' succeeded, letting the LLM know doc_id & total length."
+        ),
+    )
+    chunk: PartialChunk | None = Field(
+        None,
+        description=(
+            "Populated only if action='read' succeeded, providing the partial slice of text."
+        ),
+    )
+
+
+class ReaderTool(LionTool):
+    """
+    A single tool that the LLM can call with ReaderRequest to either:
+      - open a doc (File/URL) -> returns doc_id, doc length
+      - read partial text from doc -> returns chunk
+    """
+
+    is_lion_system_tool = True
+    system_tool_name = "reader_tool"
+
+    from lionagi.libs.package.imports import check_import
+
+    DocumentConverter = check_import(
+        "docling",
+        module_name="document_converter",
+        import_name="DocumentConverter",
+    )
+
+    def __init__(self):
+        super().__init__()
+        self.converter = ReaderTool.DocumentConverter()
+        self.documents = {}  # doc_id -> (temp_file_path, doc_length)
+        self._tool = None
+
+    def handle_request(self, request: ReaderRequest) -> ReaderResponse:
+        """
+        A function that takes ReaderRequest to either:
+        - open a doc (File/URL) -> returns doc_id, doc length
+        - read partial text from doc -> returns chunk
+        """
+        if isinstance(request, dict):
+            request = ReaderRequest(**request)
+        if request.action == "open":
+            return self._open_doc(request.path_or_url)
+        elif request.action == "read":
+            return self._read_doc(
+                request.doc_id, request.start_offset, request.end_offset
+            )
+        else:
+            return ReaderResponse(success=False, error="Unknown action type")
+
+    def _open_doc(self, source: str) -> ReaderResponse:
+        try:
+            result = self.converter.convert(source)
+            text = result.document.export_to_markdown()
+        except Exception as e:
+            return ReaderResponse(
+                success=False, error=f"Conversion error: {str(e)}"
+            )
+
+        doc_id = f"DOC_{abs(hash(source))}"
+        temp_file = tempfile.NamedTemporaryFile(
+            delete=False, mode="w", encoding="utf-8"
+        )
+        temp_file.write(text)
+        doc_len = len(text)
+        temp_file.close()
+
+        # store info
+        self.documents[doc_id] = (temp_file.name, doc_len)
+
+        return ReaderResponse(
+            success=True, doc_info=DocumentInfo(doc_id=doc_id, length=doc_len)
+        )
+
+    def _read_doc(self, doc_id: str, start: int, end: int) -> ReaderResponse:
+        if doc_id not in self.documents:
+            return ReaderResponse(
+                success=False, error="doc_id not found in memory"
+            )
+
+        path, length = self.documents[doc_id]
+        # clamp offsets
+        s = max(0, start if start is not None else 0)
+        e = min(length, end if end is not None else length)
+
+        try:
+            with open(path, encoding="utf-8") as f:
+                f.seek(s)
+                content = f.read(e - s)
+        except Exception as ex:
+            return ReaderResponse(
+                success=False, error=f"Read error: {str(ex)}"
+            )
+
+        return ReaderResponse(
+            success=True,
+            chunk=PartialChunk(start_offset=s, end_offset=e, content=content),
+        )
+
+    def to_tool(self):
+        if self._tool is None:
+
+            def reader_tool(**kwargs):
+                """
+                A function that takes ReaderRequest to either:
+                - open a doc (File/URL) -> returns doc_id, doc length
+                - read partial text from doc -> returns chunk
+                """
+                return self.handle_request(
+                    ReaderRequest(**kwargs)
+                ).model_dump()
+
+            if self.system_tool_name != "reader_tool":
+                reader_tool.__name__ = self.system_tool_name
+
+            self._tool = Tool(
+                func_callable=reader_tool,
+                request_options=ReaderRequest,
+            )
+        return self._tool

lionagi/tools/types.py

@@ -0,0 +1,3 @@
+from .reader import ReaderTool
+
+__all__ = ("ReaderTool",)

lionagi/version.py

@@ -1 +1 @@
-__version__ = "0.8.5"
+__version__ = "0.8.7"

{lionagi-0.8.5.dist-info → lionagi-0.8.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.8.5
+Version: 0.8.7
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License
@@ -235,310 +235,134 @@ Description-Content-Type: text/markdown
 
 [Documentation](https://lion-agi.github.io/lionagi/) | [Discord](https://discord.gg/aqSJ2v46vu) | [PyPI](https://pypi.org/project/lionagi/) | [Roadmap](https://trello.com/b/3seomsrI/lionagi)
 
-# LION Framework
-### Language InterOperable Network - The Future of Controlled AI Operations
+# LION - Language InterOperable Network
 
-> Harness the power of next-generation AI while maintaining complete control and reliability.
+## An Intelligence Operating System
 
-## Why LION?
+LionAGI is a robust framework for orchestrating multi-step AI operations with precise control. Bring together multiple models, advanced ReAct reasoning, tool integrations, and custom validations in a single coherent pipeline.
 
-The AI revolution is transforming how we work - but with great power comes great responsibility. LION provides the control mechanisms and reliability features needed to safely integrate advanced AI capabilities into enterprise workflows.
-
-LION is designed to be:
-- 🔒 **Controlled**: Built-in safety mechanisms and verification
-- 🎯 **Precise**: Exact control over AI behaviors
-- 🔧 **Flexible**: Build any workflow you need
-- 🚀 **Efficient**: Minimal dependencies, maximum performance
+## Why LionAGI?
 
+- **Structured**: LLM interactions are validated and typed (via Pydantic).
+- **Expandable**: Integrate multiple providers (OpenAI, Anthropic, Perplexity, custom) with minimal friction.
+- **Controlled**: Built-in safety checks, concurrency strategies, and advanced multi-step flows—like ReAct with verbose outputs.
+- **Transparent**: Real-time logging, message introspection, and easy debugging of tool usage.
 
 
 ## Installation
 
-LION maintains minimal dependencies for maximum reliability:
-
-```bash
-uv pip install lionagi
+```
+pip install lionagi
 ```
 
 Dependencies:
-- litellm
-- jinja2
-- pandas
-- pillow
-- python-dotenv
-
+	•	litellm
+	•	jinja2
+	•	pandas
+	•	pillow
+	•	python-dotenv
 
 ## Quick Start
-
 ```python
-from lionagi import iModel, Branch
+from lionagi import Branch, iModel
 
-# Initialize model
-gpt4o = iModel(provider="openai", task="chat", model="gpt-4o")
+# Pick a model
+gpt4o = iModel(provider="openai", model="gpt-4o")
 
+# Create a Branch (conversation context)
 hunter = Branch(
-  system="you are a hilarious dragon hunter who responds in 10 words rhymes",
-  imodel=gpt4o,
+  system="you are a hilarious dragon hunter who responds in 10 words rhymes.",
+  chat_model=gpt4o,
 )
 
-# Chat asynchronously
-print(await hunter.communicate("I am a dragon"))
+# Communicate asynchronously
+response = await hunter.communicate("I am a dragon")
+print(response)
 ```
 
 ```
 You claim to be a dragon, oh what a braggin'!
 ```
+### Structured Responses
 
-## 📦 Features
-
-### 1. Model Agnostic Structured Output
-
-LION provides a unified interface for interacting with any AI model, regardless of the underlying architecture. This allows you to easily switch between models without changing your code.
+Use Pydantic to keep outputs structured:
 
 ```python
 from pydantic import BaseModel
 
 class Joke(BaseModel):
-  joke: str
+    joke: str
 
-sonnet = iModel(
-  provider="anthropic",
-  model="claude-3-5-sonnet-20241022",
-  max_tokens=100,                    # max_tokens is required for anthropic models
+res = await hunter.communicate(
+    "Tell me a short dragon joke",
+    response_format=Joke
 )
-
-response = await hunter.communicate(
-  instruction="I am a dragon",
-  response_format=Joke,           # structured output in given pydantic model
-  clear_messages=True,            # refresh the conversation
-  imodel=sonnet,                  # use sonnet model, which doesn't support structured output
-)
-
 print(type(response))
 print(response.joke)
 ```
-
 ```
 <class '__main__.Joke'>
-Joke(joke='With fiery claws, dragons hide their laughter flaws!')
+With fiery claws, dragons hide their laughter flaws!
 ```
 
+### ReAct and Tools
 
-### 2. Complete Observability
+LionAGI supports advanced multi-step reasoning with ReAct. Tools let the LLM invoke external actions:
 
 ```python
-# using perplexity model
-pplx_small = iModel(
-    provider="perplexity",
-    task="chat/completions",
-    model="llama-3.1-sonar-small-128k-online",
-    max_tokens=1000,
-)
-
-b = await hunter.communicate(
-    instruction="What makes a well-behaved dragon?",
-    clear_messages=True,            # refresh the conversation
-    imodel=pplx_small,              # use perplexity model
+from lionagi.tools.types import ReaderTool
+
+branch = Branch(chat_model=gpt4o, tools=ReaderTool)
+result = await branch.ReAct(
+    instruct={
+      "instruction": "Summarize my PDF and compare with relevant papers.",
+      "context": {"paper_file_path": "/path/to/paper.pdf"},
+    },
+    extension_allowed=True,     # allow multi-round expansions
+    max_extensions=5,
+    verbose=True,      # see step-by-step chain-of-thought
 )
-
-print(b)
-```
-
-```
-A well-behaved dragon is one that's calm and bright,
-No stress or fear, just a peaceful night.
-It's active, not lethargic, with a happy face,
-And behaviors like digging, not a frantic pace.
-It's social, friendly, and never a fright,
-Just a gentle soul, shining with delight
-```
-
-```python
-hunter.msgs.last_response.model_response
-```
-
-```
-{'id': '1be10f4c-0936-4050-ab48-91bd86ab11a5',
- 'model': 'llama-3.1-sonar-small-128k-online',
- 'object': 'chat.completion',
- 'created': 1734369700,
- 'choices': [{'index': 0,
-   'message': {'role': 'assistant',
-    'content': "A well-behaved dragon is one that's calm and bright,\nNo stress or fear, just a peaceful night.\nIt's active, not lethargic, with a happy face,\nAnd behaviors like digging, not a frantic pace.\nIt's social, friendly, and never a fright,\nJust a gentle soul, shining with delight"},
-   'finish_reason': 'stop',
-   'delta': {'role': 'assistant', 'content': ''}}],
- 'usage': {'prompt_tokens': 40, 'completion_tokens': 69, 'total_tokens': 109},
- 'citations': [{'url': 'https://dragonsdiet.com/blogs/dragon-care/15-bearded-dragon-behaviors-and-what-they-could-mean'},
-  {'url': 'https://masterbraeokk.tripod.com/dragons/behavior.html'},
-  {'url': 'https://files.eric.ed.gov/fulltext/ED247607.pdf'},
-  {'url': 'https://www.travelchinaguide.com/intro/social_customs/zodiac/dragon/five-elements.htm'},
-  {'url': 'https://www.travelchinaguide.com/intro/social_customs/zodiac/dragon/'}]}
+print(result)
 ```
 
+The LLM can now open the PDF, read in slices, fetch references, and produce a final structured summary.
 
-### 3. Easy composition of complex workflows
-
+### Observability & Debugging
+- Inspect messages:
 ```python
-# chain of thoughts
-from pydantic import Field
-
-class Reason(BaseModel):
-  reason: str
-  confidence_score: float
-
-class Thought(BaseModel):
-  thought: str
-
-class Analysis(BaseModel):
-  thought: list[Thought] = Field(
-    default_factory=list, 
-    description="concise Chain of thoughts from you, 3 step, each in 8 words"
-  )
-  analysis: str = Field(
-    ...,
-    description="Final analysis of the dragon's psyche in 20 words",
-  )
-  reason: list[Reason] = Field(
-    default_factory=list,
-    description="Concise Reasoning behind the analysis, 3 support, each in 8 words"
-  )
-
-context1 = "I am a dragon, I think therefore I am, I suffer from shiny objects syndrome"
-context2 = "I like food and poetry, I use uv sometimes, it's cool but I am not familiar with pip"
-
-async def analyze(context) -> Analysis:
-  psychologist = Branch(
-    system="you are a renowned dragon psychologist",
-    imodel=gpt4o,
-  )
-  return await psychologist.communicate(
-    instruction="analyze the dragon's psyche using chain of thoughts",
-    guidance="think step by step, reason with logic",
-    context=context,
-    response_format=Analysis,
-  )
-
+df = branch.to_df()
+print(df.tail())
 ```
+- Action logs show each tool call, arguments, and outcomes.
+- Verbose ReAct provides chain-of-thought analysis (helpful for debugging multi-step flows).
 
-```python
-result1 = await analyze(context1)
-
-print("\nThoughts:")
-for i in result1.thought:
-    print(i.thought)
-
-print("\nAnalysis:")    
-print(result1.analysis)
-
-print("\nReasoning:")
-for i in result1.reason:
-    print(i.reason)
-```
-
-```
-
-Thoughts:
-Dragons are attracted to shiny objects naturally.
-This suggests a strong affinity for hoarding.
-Reflects the dragon's inherent desire for possession.
-
-Analysis:
-The dragon demonstrates a compulsive hoarding behavior linked to attraction for shiny objects.
-
-Reasoning:
-Shiny objects trigger instinctual hoarding behavior.
-Possession indicates a symbol of power and security.
-Hoarding is reinforced by evolutionary survival mechanisms.
-```
+### Example: Multi-Model Orchestration
 
 ```python
-result2 = await analyze(context2)
+from lionagi import Branch, iModel
 
-print("\nThoughts:")
-for i in result2.thought:
-    print(i.thought)
-
-print("\nAnalysis:")    
-print(result2.analysis)
+gpt4o = iModel(provider="openai", model="gpt-4o")
+sonnet = iModel(
+  provider="anthropic",
+  model="claude-3-5-sonnet-20241022",
+  max_tokens=1000,                    # max_tokens is required for anthropic models
+)
 
-print("\nReasoning:")
-for i in result2.reason:
-    print(i.reason)
+branch = Branch(chat_model=gpt4o)
+# Switch mid-flow
+analysis = await branch.communicate("Analyze these stats", imodel=sonnet)
 ```
 
-```
-Thoughts:
-Dragon enjoys both food and poetry regularly.
-Dragon uses uv light with frequent interest.
-Dragon is unfamiliar and not comfortable with pip.
-
-Analysis:
-The dragon is curious and exploratory, yet selectively cautious about unfamiliar methodologies.
-
-Reasoning:
-Preference for food and poetry suggests curiosity.
-Frequent uv light use indicates exploratory nature.
-Discomfort with pip usage shows selective caution.
-```
+Seamlessly route to different models in the same workflow.
 
+## Community & Contributing
 
+We welcome issues, ideas, and pull requests:
+- Discord: Join to chat or get help
+- Issues / PRs: GitHub
 
-## 🌟 Example Workflow
-
-Below is an example of what you can build with LION. Note that these are sample implementations - LION provides the building blocks, you create the workflows that fit your needs.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Client
-    participant Orchestrator
-    participant ResearchAgent
-    participant AnalysisAgent
-    participant ValidationAgent
-    participant Tools
-
-    Client->>+Orchestrator: Submit Complex Task
-    Note over Orchestrator: Task Analysis & Planning
-
-    %% Research Phase
-    Orchestrator->>+ResearchAgent: Delegate Research
-    activate ResearchAgent
-    ResearchAgent->>Tools: Access Data Sources
-    Tools-->>ResearchAgent: Raw Data
-    ResearchAgent-->>-Orchestrator: Research Results
-    deactivate ResearchAgent
-
-    %% Analysis Phase
-    Orchestrator->>+AnalysisAgent: Process Data
-    activate AnalysisAgent
-    AnalysisAgent->>Tools: Apply Models
-    Tools-->>AnalysisAgent: Analysis Results
-    AnalysisAgent-->>-Orchestrator: Processed Insights
-    deactivate AnalysisAgent
-
-    %% Validation Phase
-    Orchestrator->>+ValidationAgent: Verify Results
-    activate ValidationAgent
-    ValidationAgent->>Tools: Apply Safety Checks
-    Tools-->>ValidationAgent: Validation Status
-    ValidationAgent-->>-Orchestrator: Verified Results
-    deactivate ValidationAgent
-
-    Orchestrator-->>-Client: Return Validated Output
+### Citation
 ```
-
-
-## 🤝 Contributing
-
-Join our [Discord community](https://discord.gg/aqSJ2v46vu) to:
-- Share ideas
-- Report issues
-- Contribute code
-- Learn from others
-
-## 📚 Citation
-
-```bibtex
 @software{Li_LionAGI_2023,
   author = {Haiyang Li},
   month = {12},
@@ -547,3 +371,6 @@ Join our [Discord community](https://discord.gg/aqSJ2v46vu) to:
   url = {https://github.com/lion-agi/lionagi},
 }
 ```
+
+**🦁 LionAGI**
+> Because real AI orchestration demands more than a single prompt. Try it out and discover the next evolution in structured, multi-model, safe AI.

{lionagi-0.8.5.dist-info → lionagi-0.8.7.dist-info}/RECORD

@@ -1,10 +1,10 @@
-lionagi/__init__.py,sha256=-tKLn-wTj_VK4XQr3CV16ioTNnaUYD2fhUAtJOZZ0vU,574
+lionagi/__init__.py,sha256=TWvUzgX_HgXO6xoShWT3kY8BNaZDOc8JIOu59PFqN2M,672
 lionagi/_class_registry.py,sha256=dutMsw-FQNqVV5gGH-NEIv90uBkSr8fERJ_x3swbb-s,3112
 lionagi/_errors.py,sha256=wNKdnVQvE_CHEstK7htrrj334RA_vbGcIds-3pUiRkc,455
 lionagi/_types.py,sha256=9g7iytvSj3UjZxD-jL06_fxuNfgZyWT3Qnp0XYp1wQU,63
 lionagi/settings.py,sha256=k9zRJXv57TveyfHO3Vr9VGiKrSwlRUUVKt5zf6v9RU4,1627
 lionagi/utils.py,sha256=QbF4E1PG-BaRcEVH3kJIYCJVNq-oRNoTxjda5k8NYW4,73177
-lionagi/version.py,sha256=K0kGrhh1kzVisZcoSkeuJdC06rTwxufV05Vy2hOVGoo,22
+lionagi/version.py,sha256=vTwvdJOZi8jZb9U-Em7-d50qNDNPS2z51IXqRoojeNM,22
 lionagi/libs/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/libs/parse.py,sha256=tpEbmIRGuHhLCJlUlm6fjmqm_Z6XJLAXGNFHNuk422I,1011
 lionagi/libs/file/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
@@ -48,11 +48,11 @@ lionagi/operations/__init__.py,sha256=O7nV0tedpUe7_OlUWmCcduGPFtqtzWZcR_SIOnjLsr
 lionagi/operations/manager.py,sha256=H7UY86PIxvxKdzJY9YVsWyJcqlwLWhVyvm4sYePH_uY,565
 lionagi/operations/types.py,sha256=LIa68xcyKLVafof-DSFwKtSkneuYPFqrtGyClohYI6o,704
 lionagi/operations/utils.py,sha256=Twy6L_UFt9JqJFRYuKKTKVZIXsePidNl5ipcYcCbesI,1220
-lionagi/operations/ReAct/ReAct.py,sha256=pmg50Bz859dfoFW4S-fh5-2FUZKkleCVISMp4d6ye5E,4018
+lionagi/operations/ReAct/ReAct.py,sha256=_PwoP3RgazGsAaDEOWEABATpBujI7e5OQhbc9AyIA1o,5082
 lionagi/operations/ReAct/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/operations/ReAct/utils.py,sha256=yBsbaZm3NNb-LhdjdK3jVmxSYbp0enWzl8d09iv8oSo,1099
+lionagi/operations/ReAct/utils.py,sha256=uWPZC1aJVAPvJweAgr3NdXpYszeagN5OnJIkUdrSvlw,3228
 lionagi/operations/_act/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/operations/_act/act.py,sha256=HBp-sNwNigLDNkuEZqGU_98UCaJXPZsaokkFAXwOMn0,2454
+lionagi/operations/_act/act.py,sha256=FWK8vXiccBZI_sIQcEBw8Cn6slMooZkfmkmxBaYA4kw,2739
 lionagi/operations/brainstorm/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/operations/brainstorm/brainstorm.py,sha256=OwByrh6E-rTU_u6fDNTwWOlkJ4ycYJB9ZF-x-HYOs8I,17222
 lionagi/operations/brainstorm/prompt.py,sha256=f-Eh6pO606dT2TrX9BFv_einRDpYwFi6Gep9Strd1cM,610
@@ -63,9 +63,9 @@ lionagi/operations/communicate/communicate.py,sha256=1PzBpzgATcAdBog0EUxtj5_uJGi
 lionagi/operations/instruct/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/operations/instruct/instruct.py,sha256=CYICzWvmgALtSPIetfF3csx6WDsCuiu4NRRPL56UA2g,795
 lionagi/operations/interpret/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/operations/interpret/interpret.py,sha256=mjTcOCOixc34JNnX0WowSVACtZXz9IBuzjp9VyOus5w,1244
+lionagi/operations/interpret/interpret.py,sha256=Mtg65jletgMZAZ08kNLgjbC_y9C3l2xw67fHpHmBesg,2905
 lionagi/operations/operate/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/operations/operate/operate.py,sha256=kzH7R4J3O-1Ue-PYqIoEdrXHrkYYQVfHa6gSC4Km_sc,7003
+lionagi/operations/operate/operate.py,sha256=eHf1wopNm04hOAg1NMcrn6nz4acofUENi0R4r8FQMMs,7218
 lionagi/operations/parse/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
 lionagi/operations/parse/parse.py,sha256=LpF6LVAvCVoE8n63BkhSxXSHYgSx7CNkN7yXUwaNpQo,3003
 lionagi/operations/plan/__init__.py,sha256=AFkAmOJBTqPlYuqFRRn7rCvIw3CGh9XXH_22cNWbfig,156
@@ -188,9 +188,13 @@ lionagi/service/providers/perplexity_/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZK
 lionagi/service/providers/perplexity_/chat_completions.py,sha256=jhE-KHWRX6yYEeKWLMCKLgK3bQzieSv2viqQWDP8q0Q,1197
 lionagi/service/providers/perplexity_/models.py,sha256=gXH4XGkhZ4aFxvMSDTlHq9Rz1mhu3aTENXAtE-BIr6U,4866
 lionagi/session/__init__.py,sha256=v8vNyJVIVj8_Oz9RJdVe6ZKUQMYTgDh1VQpnr1KdLaw,112
-lionagi/session/branch.py,sha256=JFRX_amOH5puYBIFifvXlk6YztUTi8D2Zy-eck0AFn8,65757
+lionagi/session/branch.py,sha256=EH1JhOe1ZGlCVXpf0znz_xAA3GibNIGFATwLAyxiCK0,67835
 lionagi/session/session.py,sha256=po6C7PnM0iu_ISHUo4PBzzQ61HFOgcsAUfPoO--eLak,8987
-lionagi-0.8.5.dist-info/METADATA,sha256=nTeNxoGDS7shH8qi3iSb03arU23BDaQ2DgB9_UJvTEQ,22819
-lionagi-0.8.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-lionagi-0.8.5.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
-lionagi-0.8.5.dist-info/RECORD,,
+lionagi/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lionagi/tools/base.py,sha256=ffaIcLF_uwEphCkP_wsa3UfkqVenML3HpsnR5kRCTtA,236
+lionagi/tools/reader.py,sha256=jYWgEfyQZ7TR5-cW7ceGhz6b47eWlSS0bAvbCnHh1-I,7504
+lionagi/tools/types.py,sha256=_OWzoTHTcqNwPs3OGrPkpO9m_vHDCxVDL-FN-t6ZD60,58
+lionagi-0.8.7.dist-info/METADATA,sha256=-mm0T59W8n5E3bk73nVaqEsxn6bYCrgEIYNZ389h-Tw,18008
+lionagi-0.8.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lionagi-0.8.7.dist-info/licenses/LICENSE,sha256=VXFWsdoN5AAknBCgFqQNgPWYx7OPp-PFEP961zGdOjc,11288
+lionagi-0.8.7.dist-info/RECORD,,