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

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.2"
+__version__ = "0.8.7"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.8.2
+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.