lionagi 0.7.3__tar.gz → 0.7.4__tar.gz

{lionagi-0.7.3 → lionagi-0.7.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.7.3
-Summary: An AGentic Intelligence Operating System.
+Version: 0.7.4
+Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License
                                    Version 2.0, January 2004

lionagi-0.7.3/cookbooks/ch1_get_started.md → lionagi-0.7.4/cookbooks/ch01_get_started.md

@@ -30,7 +30,7 @@ source env/bin/activate  # On Windows: env\Scripts\activate
 # Install LionAGI and dotenv
 pip install lionagi
 ```
-1.2 API Setup
+### 1.2 API Setup
 
 ```python
 import os
@@ -45,9 +45,21 @@ load_dotenv()
 os.environ["OPENAI_API_KEY"] = "your-api-key"
 ```
 
-2. Building a Basic Assistant
+## 2. Building a Basic Assistant
 
 The Basic Assistant shows how to query GPT-based models with LionAGI. We’ll ask a few questions about AI Safety as an example.
+```python
+from timeit import default_timer as timer
+
+start = timer()
+
+import lionagi
+
+print(f"Imported lionagi in {timer()-start:.3f} seconds")
+print(f"lionagi version: {lionagi.__version__}")
+```
+if this code runs without errors, you have successfully installed LionAGI.
+
 ```python
 from lionagi import Branch, iModel
 from IPython.display import display, Markdown
@@ -84,48 +96,50 @@ responses = []
 for question in questions:
     # Prompt the assistant with context and question
     response = await assistant.chat(f"{context}\nQuestion: {question}")
-    
+
     # Display the response in a Jupyter Notebook (if using IPython)
     display(Markdown(response))
-    
+
     # Store the response
     responses.append({"question": question, "answer": response})
 ```
-Explanation
-	1.	iModel configures how we interact with OpenAI. We specify the model name and temperature.
-	2.	Branch sets up a conversational context (the system prompt).
-	3.	assistant.chat() sends queries (prompts) to GPT.
-	4.	We collect results in responses, which you can later print or save.
+
+
+Explanation:
+1.	iModel configures how we interact with OpenAI. We specify the model name and temperature.
+2.	Branch sets up a conversational context (the system prompt).
+3.	assistant.chat() sends queries (prompts) to GPT.
+4.	We collect results in responses, which you can later print or save.
 
 3. Building an Advanced Assistant
 
+## 3. Building an Advanced Assistant
+
 Now let’s expand on the basic approach. The Advanced Assistant adds:
-	•	Persistent storage for research (JSON files)
-	•	Error handling (API key issues, rate limits)
-	•	Summaries of research topics
-	•	Retrieval of previously saved topics
+1.	Persistent storage for research (JSON files)
+2.	Error handling (API key issues, rate limits)
+3.	Summaries of research topics
+4.	Retrieval of previously saved topics
+
 ```python
 from lionagi import Branch, iModel
 from datetime import datetime
 from pathlib import Path
 import json
-from IPython.display import display, Markdown
+
 
 class ResearchAssistant:
     """Advanced research assistant with persistence."""
+
     def __init__(
         self,
         name: str = "Researcher",
-        model: str = "gpt-4o",
-        save_dir: str = "research"
+        model: str = "gpt-4o-mini",
+        save_dir: str = "research",
     ):
         # 1. Configure the AI model
-        ai_model = iModel(
-            provider="openai",
-            model=model,
-            temperature=0.7
-        )
-        
+        ai_model = iModel(provider="openai", model=model, temperature=0.7)
+
         # 2. Create the assistant branch
         self.assistant = Branch(
             name=name,
@@ -133,17 +147,17 @@ class ResearchAssistant:
             Provide clear, accurate information.
             Support claims with evidence.
             Ask for clarification if needed.""",
-            chat_model=ai_model
+            chat_model=ai_model,
         )
-        
+
         # 3. Setup storage
         self.save_dir = Path(save_dir)
         self.save_dir.mkdir(exist_ok=True)
-        
+
         # 4. Track research in memory
         self.topics: dict[str, dict] = {}
         self._load_history()
-    
+
     def _load_history(self):
         """
         Loads previous research from JSON files in the save_dir.
@@ -153,11 +167,9 @@ class ResearchAssistant:
             with open(file) as f:
                 research = json.load(f)
                 self.topics[research["topic"]] = research
-    
+
     async def research_topic(
-        self,
-        topic: str,
-        questions: list[str]
+        self, topic: str, questions: list[str]
     ) -> dict[str, str]:
         """
         Researches a topic thoroughly by asking multiple questions.
@@ -170,148 +182,154 @@ class ResearchAssistant:
                     f"Regarding {topic}: {question}"
                 )
                 answers[question] = response
-            
+
             # Save research to a JSON file
             research = {
                 "topic": topic,
                 "date": datetime.now().isoformat(),
                 "questions": questions,
-                "answers": answers
+                "answers": answers,
             }
-            
-            file_path = self.save_dir / f"{topic.lower().replace(' ', '_')}.json"
+
+            file_path = (
+                self.save_dir / f"{topic.lower().replace(' ', '_')}.json"
+            )
             with open(file_path, "w") as f:
                 json.dump(research, f, indent=2)
-            
+
             # Update in-memory tracking
             self.topics[topic] = research
-            
+
             return answers
-        
+
         except Exception as e:
             # Handle common errors
             if "API key" in str(e):
-                raise ValueError("Invalid API key. Please check your configuration.")
+                raise ValueError(
+                    "Invalid API key. Please check your configuration."
+                )
             elif "Rate limit" in str(e):
-                raise ValueError("Rate limit exceeded. Please try again later.")
+                raise ValueError(
+                    "Rate limit exceeded. Please try again later."
+                )
             else:
                 raise e
-    
-    async def get_summary(
-        self,
-        topic: str,
-        style: str = "technical"
-    ) -> str:
+
+    async def get_summary(self, topic: str, style: str = "technical") -> str:
         """
         Generates a summary of the answers for a researched topic in a specific style.
         Returns the summary string, or an error if the topic was not found.
         """
         if topic not in self.topics:
             return f"No research found for: {topic}"
-        
+
         research = self.topics[topic]
         questions = research["questions"]
         answers = research["answers"]
-        
+
         prompt = f"""
         Summarize research on {topic}.
         Style: {style}
         Questions covered: {', '.join(questions)}
         Key findings: {json.dumps(answers, indent=2)}
         """
-        
+
         try:
             return await self.assistant.chat(prompt)
         except Exception as e:
             return f"Error generating summary: {str(e)}"
-    
+
     def get_topics(self) -> list[str]:
         """Returns a list of all topics researched so far."""
         return list(self.topics.keys())
-    
-    def get_research(
-        self,
-        topic: str
-    ) -> dict | None:
+
+    def get_research(self, topic: str) -> dict | None:
         """Returns the full research details for a given topic, or None if not found."""
         return self.topics.get(topic)
 ```
+
 Usage Example
+:
 ```python
+from IPython.display import display, Markdown
+
 async def research_project():
     """Demonstrates how to use the advanced ResearchAssistant."""
-    
+
     # 1. Create an instance of ResearchAssistant
     assistant = ResearchAssistant(
-        name="AI Researcher",
-        model="gpt-4o",
-        save_dir="ai_research"
+        name="AI Researcher", model="gpt-4o", save_dir="ai_research"
     )
-    
+
     # 2. Define topics and questions
     topics = {
         "AI Safety": [
             "What are the main concerns?",
             "What solutions exist?",
-            "What are future challenges?"
+            "What are future challenges?",
         ],
         "Machine Learning": [
             "What are key concepts?",
             "What are best practices?",
-            "What are common pitfalls?"
-        ]
+            "What are common pitfalls?",
+        ],
     }
-    
+
     # 3. Research each topic
     for topic, questions in topics.items():
         print(f"\nResearching: {topic}")
-        
+
         try:
             # Gather answers
             answers = await assistant.research_topic(topic, questions)
-            
+
             # Generate and print a summary
             summary = await assistant.get_summary(topic, style="technical")
-            
+
             print("\nFindings:")
             for q, a in answers.items():
                 display(Markdown(f"**Q**: {q}"))
                 display(Markdown(f"**A**: {a}"))
-            
-            print(f"\nSummary:\n{summary}")
-        
+
+            display(Markdown(f"\nSummary:\n{summary}"))
+
         except Exception as e:
             print(f"Error researching {topic}: {str(e)}")
             continue
-    
+
     # 4. Show all researched topics
-    print("\nAll Topics:", assistant.get_topics())
+    display(Markdown(f"\nAll Topics:{assistant.get_topics()}"))
 
 # If you’re running in an environment that supports async,
 # you can execute:
 # await research_project()
+# else you can use:
+# asyncio.run(research_project())
+```
+```python
+# Example call (in an async environment, such as Jupyter Notebook):
+await research_project()
 ```
-
 Explanation
-	1.	ResearchAssistant Class: Encapsulates functions to query GPT, track and load previous research, and generate summaries.
-	2.	_load_history(): Loads prior research from JSON files in the save_dir.
-	3.	research_topic(): Prompts GPT with each question, saves answers to a local JSON file, and updates an internal topics dictionary.
-	4.	get_summary(): Builds a customized summary prompt and returns GPT’s response.
-	5.	Error Handling: Uses Python exceptions to catch and respond to common issues (invalid key, rate limits).
-
-4. Best Practices
-	1.	Assistant Design
-	•	Provide a clear system message (role, instructions, style).
-	•	Configure model parameters (model, temperature) carefully.
-	•	Gracefully handle common errors (API key problems, rate limits).
-	2.	Code Structure
-	•	Use type hints for clarity (e.g., -> dict[str, str]).
-	•	Keep code modular and documented.
-	•	Follow PEP 8 style guidelines.
-	3.	User Experience
-	•	Persist research results so users can revisit them.
-	•	Offer summaries or highlights.
-	•	Provide progress/error notifications to guide the user.
+1.	ResearchAssistant Class: Encapsulates functions to query GPT, track and load previous research, and generate summaries.
+2.	_load_history(): Loads prior research from JSON files in save_dir.
+3.	research_topic(): Prompts GPT with each question, saves answers to a local JSON file, and updates an internal topics dictionary.
+4.	get_summary(): Builds a customized summary prompt and returns GPT’s response.
+5.	Error Handling: Uses Python exceptions to catch and respond to common issues (invalid key, rate limits).
+
+## 4. Best Practices
+1.	Assistant Design
+- Provide a clear system message (role, instructions, style).
+- Configure model parameters (model, temperature) carefully.
+- Gracefully handle common errors (API key problems, rate limits).
+2.	Code Structure
+- Use type hints for clarity (e.g., -> dict[str, str]).
+- Keep code modular and documented.
+- Follow PEP 8 style guidelines.
+3.	User Experience
+- Persist research results so users can revisit them.
+- Offer summaries or highlights.
+- Provide progress/error notifications to guide the user.
 
 5. Quick Reference
 
@@ -341,13 +359,15 @@ except Exception as e:
     print(f"Error: {str(e)}")
 ```
 
-6. Next Steps
+## 6. Next Steps
 
 You have now learned:
-	•	How to create a Basic AI Assistant
-	•	How to research topics, save results, and manage errors
-	•	How to retrieve and summarize past research
+1.	How to create a Basic AI Assistant
+2.	How to research topics, save results, and manage errors
+3.	How to retrieve and summarize past research
+
+In Chapter 2, we’ll explore LionAGI’s core concepts and dive deeper into its architecture.
 
-In Chapter 2, we’ll explore LionAGI’s core concepts and dive deeper into its architecture. You’ll learn how to handle more complex conversation flows, manipulate prompts dynamically, and use advanced features like multiple branches or streaming responses.
+You’ll learn how to handle more complex conversation flows, manipulate prompts dynamically, and use advanced features like multiple branches or streaming responses.
 
 Happy coding and researching!

lionagi-0.7.4/cookbooks/ch02_concepts.md

@@ -0,0 +1,223 @@
+# LionAGI Cookbook
+
+## Chapter 2: Building a Customer Service Bot
+
+In [Chapter 1](ch1_get_started.md), we built a **research assistant** primarily using the `branch.chat()` method. 
+
+That approach was **single-turn**: each call to `chat()` did **not** add messages to the conversation history. Now, we’ll explore **LionAGI’s** architecture and focus on **multi-turn** usage with `branch.communicate()`, which **does** store messages for continuous dialogue.
+
+---
+
+## 1. Architecture & Design Philosophy
+
+LionAGI is deliberately **modular**. When building a “Customer Service” bot, these key pieces unite:
+
+1. **Branch**  
+   - Coordinates a single conversation.  
+   - Maintains messages, tools, logs, and references to an **iModel**.  
+   - We’ll use `communicate()` for multi-turn conversation memory.
+
+2. **iModel**  
+   - Represents a configured LLM endpoint (like GPT-4o, sonnet-3.5, etc.).  
+   - Manages concurrency, token usage, and request settings.
+
+3. **Action System** (Optional)  
+   - Tools exposed to the LLM for real backend operations (e.g., resetting a password, issuing refunds).  
+   - The LLM can “function-call” them if it decides it needs those capabilities.
+
+4. **Messages & Conversation**  
+   - `branch.communicate()` automatically **stores** user messages + assistant replies in order, supporting multi-turn memory.  
+   - `branch.chat()`, by contrast, is typically a single-turn approach (no automatic message storage).
+
+5. **Logs & Session** (Advanced)  
+   - You can attach a `LogManager` or use a `Session` to handle multiple conversation branches and cross-branch communication.  
+   - For now, we’ll stick to a single Branch for a single conversation flow.
+
+### High-Level Flow for Customer Service
+1. **User** asks a question or describes a problem.  
+2. **Branch** uses an **iModel** to generate a reply, storing both the user inquiry and the assistant response in the conversation.  
+3. If a function call is needed (e.g., “reset_password”), the Branch’s tool system handles it.  
+4. The conversation continues seamlessly: new user messages have context from previous messages because we used `communicate()`.
+
+---
+
+## 2. Example: Building a Basic Customer Service Branch
+
+Here’s a **LionAGI** approach for multi-turn conversation. Let’s define a simple Tool, an iModel, and a Branch that uses `communicate()`.
+
+
+### 2.1 Configuring an iModel
+
+```python
+from lionagi import iModel
+
+customer_service_model = iModel(
+    provider="openai",
+    model="gpt-4o-mini",
+    temperature=0.7,
+    # concurrency/rate-limits can be set if needed
+)
+```
+
+### 2.2 Creating the Branch
+
+```python
+from lionagi import Branch
+
+service_branch = Branch(
+    name="CustomerService",
+    system="""You are a polite customer service agent.
+    - Greet the user.
+    - Provide helpful info or next steps.
+    - Escalate if the issue is out of scope.""",
+    chat_model=customer_service_model,
+)
+```
+
+Key Points
+- The system string sets the overall tone and instructions (like a system prompt).
+- chat_model is our chosen LLM interface.
+- tools includes our password reset functionality.
+
+### 2.3 Handling Multi-turn Inquiries with communicate()
+
+```python
+async def handle_inquiry(user_id: str, user_message: str) -> str:
+    """
+    Takes the user's message and returns an AI response, 
+    preserving conversation history for follow-up questions.
+    """
+    # Provide context if needed (e.g., user_id)
+    response = await service_branch.communicate(
+        instruction=user_message,
+        context={"user_id": user_id}
+    )
+    return response
+```
+Why communicate()?
+- It automatically adds the user message and the assistant’s reply to the Branch’s conversation log.
+- Follow-up calls to communicate() within the same Branch will see the entire conversation so far.
+- This is different from branch.chat(), which does not store messages for future turns.
+
+Demo of Multi-Turn Exchange
+```python
+import asyncio
+
+async def customer_service_demo():
+    # 1) First inquiry
+    resp1 = await handle_inquiry("User123", "Hi, I forgot my password.")
+    print("Assistant says:", resp1)
+
+    # 2) Follow-up inquiry (the user is still locked out)
+    resp2 = await handle_inquiry("User123", "I'm still locked out. Help!")
+    print("Assistant says:", resp2)
+
+    # 3) Another question, context is still remembered
+    resp3 = await handle_inquiry("User123", "Thanks! How do I change my billing address next?")
+    print("Assistant says:", resp3)
+
+# asyncio.run(customer_service_demo())
+```
+Here, each call to handle_inquiry() uses communicate(), building a conversation that retains context across multiple user messages.
+
+## 3. Managing Conversation State & Logs
+
+### 3.1 Automatic Logging
+
+LionAGI automatically log conversation events via a LogManager. You can configure log manager by passing a config at branch creation:
+
+```python
+from lionagi import types
+
+log_config = types.LogManagerConfig(
+    persist_dir="./logs",
+    capacity=10,        # logs are dumped after 10 events (api_call, function_call)
+    extension=".json",
+    auto_save_on_exit=True,
+)
+service_branch = Branch(
+    name="CustomerService",
+    system="""You are a polite customer service agent.
+    - Greet the user.
+    - Provide helpful info or next steps.
+    - Escalate if the issue is out of scope.""",
+    chat_model=customer_service_model,
+    tools=[reset_password],  # directly pass in the function
+    log_config=log_config,
+)
+```
+You can also check the logs as a DataFrame:
+
+```python
+df = service_branch.logs.to_df()
+print(df.head())
+```
+3.2 Viewing Stored Conversation
+
+Because we’re using communicate(), the conversation grows with each user message:
+```python
+# this will produce a formatted dataframe of messages in the conversation
+df = service_branch.to_df()
+
+# whereas below will convert all messages data in the conversation into dataframe
+df1 = service_branch.messages.to_df()
+```
+You’ll see System, User, and Assistant roles in chronological order.
+
+## 4. Best Practices
+
+1.	Use communicate() for Multi-turn
+    - If you need a persistent conversation across multiple messages, communicate() automatically appends user & assistant messages.
+    - chat() is simpler but stateless (no built-in memory), ideal for single-turn Q&A or ephemeral prompts.
+2.	Leverage Tools
+    - Real customer service might need secure “Check Account,” “Issue Refund,” or “Reset Password.”
+    - Wrap each as a Tool or put them in an ActionManager. The LLM can function-call them as needed.
+3.	Log Management
+    - Set capacity-based dumping or manual triggers to avoid large memory usage.
+    - For compliance or analytics, consider storing logs externally (e.g., in a database).
+4.	Escalation Strategy
+    - If the LLM says “I can’t handle this” or calls “escalate_ticket,” you can hand off to a manager branch or a real agent.
+    - Use a Session if you want multiple Branches or multi-agent flows.
+5.	Conversation Summaries
+    - For longer sessions, you might occasionally summarize prior messages (to keep context concise) or parse them for user satisfaction.
+
+## 5. Quick Reference
+
+Below is a minimal usage pattern focusing on multi-turn communicate(), different from Chapter 1’s single-turn chat():
+```python
+from lionagi import Branch, iModel
+
+# 1) Model configuration
+cs_model = iModel(
+    provider="openai",
+    model="gpt-4o",
+    temperature=0.7
+)
+
+# 2) Branch creation
+cs_branch = Branch(
+    name="CustomerSupport",
+    system="You are a friendly agent with memory of previous messages.",
+    chat_model=cs_model
+)
+
+# 3) Multi-turn conversation
+async def quick_demo():
+    # First user message
+    first_resp = await cs_branch.communicate("Hi, I need help with my account")
+    print("Assistant:", first_resp)
+
+    # Follow-up user message
+    second_resp = await cs_branch.communicate("I'm also locked out of billing.")
+    print("Assistant:", second_resp)
+```
+Notice how each communicate() call references the same Branch, so user context accumulates.
+
+## 6. Summary & Next Steps
+
+In this chapter, you’ve seen:
+- How communicate() differs from chat(): communicate() keeps conversation state for subsequent turns.
+- Integrating Tools for real backend actions in a multi-turn scenario.
+- Logging conversation history for compliance or analytics.
+
+Coming Up: Chapter 3 explores advanced function calling and tool integration—including custom schemas, concurrency handling, and more. This opens the door to sophisticated customer service workflows, from verifying user details to secure refunds or escalations.

lionagi-0.7.4/lionagi/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from . import _types as types
+from .operations import types as op
+from .operatives import types as ops_types  # deprecated
+from .service.imodel import iModel
+from .session.session import Branch, Session
+from .version import __version__
+
+LiteiModel = iModel
+
+__all__ = (
+    "Session",
+    "Branch",
+    "iModel",
+    "LiteiModel",
+    "types",
+    "ops_types",
+    "op",
+    "__version__",
+)

lionagi-0.7.4/lionagi/_types.py

@@ -0,0 +1,2 @@
+from .operatives.types import *
+from .protocols.types import *

{lionagi-0.7.3 → lionagi-0.7.4}/lionagi/session/branch.py

@@ -611,6 +611,24 @@ class Branch(Element, Communicatable, Relational):
         # Remove placeholders (UNDEFINED) so we don't incorrectly assign them
         return cls(**{k: v for k, v in params.items() if v is not UNDEFINED})
 
+    def dump_logs(self, clear: bool = True, persist_path=None):
+        """
+        Dumps the log to a file or clears it.
+
+        Args:
+            clear (bool, optional):
+                If `True`, clears the log after dumping.
+            persist_path (str, optional):
+                The file path to save the log to.
+        """
+        self._log_manager.dump(clear=clear, persist_path=persist_path)
+
+    async def adump_logs(self, clear: bool = True, persist_path=None):
+        """
+        Asynchronously dumps the log to a file or clears it.
+        """
+        await self._log_manager.adump(clear=clear, persist_path=persist_path)
+
     # -------------------------------------------------------------------------
     # Asynchronous Operations (chat, parse, operate, etc.)
     # -------------------------------------------------------------------------

lionagi-0.7.4/lionagi/version.py

@@ -0,0 +1 @@
+__version__ = "0.7.4"

{lionagi-0.7.3 → lionagi-0.7.4}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "lionagi"
-version = "0.7.3"
-description = "An AGentic Intelligence Operating System."
+version = "0.7.4"
+description = "An Intelligence Operating System."
 authors = [
     { name = "HaiyangLi", email = "quantocean.li@gmail.com" },
 ]
@@ -42,6 +42,8 @@ dev = [
     "sphinx-autobuild>=2024.10.3",
     "sphinx>=8.1.3",
     "furo>=2024.8.6",
+    "ipython>=8.31.0",
+    "ipykernel>=6.29.5",
 ]
 
 [tool.black]