lionagi 0.7.2__tar.gz → 0.7.4__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.7.2
-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.4/cookbooks/ch01_get_started.md

@@ -0,0 +1,373 @@
+# LionAGI Cookbook
+
+## Chapter 1: Building Your First AI Assistant
+
+LionAGI helps you build AI-powered applications quickly and reliably. In this chapter, you'll create a **research assistant** that:
+
+- Researches topics thoroughly  
+- Saves findings to files  
+- Handles conversations naturally  
+- Manages errors gracefully  
+
+---
+
+### Prerequisites
+- Python 3.10 or higher  
+- Basic Python knowledge  
+- OpenAI API key  
+
+---
+
+## 1. Setup
+
+### 1.1 Installation
+
+```bash
+# Create a virtual environment
+python -m venv env
+source env/bin/activate  # On Windows: env\Scripts\activate
+
+# Install LionAGI and dotenv
+pip install lionagi
+```
+### 1.2 API Setup
+
+```python
+import os
+from dotenv import load_dotenv
+
+# Load API key from .env file
+# Create a .env file containing:
+# OPENAI_API_KEY=your-key
+load_dotenv()
+
+# Alternatively, set directly (not recommended for production):
+os.environ["OPENAI_API_KEY"] = "your-api-key"
+```
+
+## 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
+
+# 1. Configure the AI model
+ai_model = iModel(
+    provider="openai",
+    model="gpt-4o-mini",  # Example model identifier
+    temperature=0.7,      # Balances accuracy & creativity
+    invoke_with_endpoint=False,
+)
+
+# 2. Create the 'Researcher' assistant branch
+assistant = Branch(
+    name="Researcher",
+    system="""You are a research assistant.
+    Provide clear, accurate information.
+    Support claims with concise evidence.""",
+    chat_model=ai_model,
+)
+
+# 3. Define the topic and questions
+topic = "AI Safety"
+questions = [
+    "What are the main concerns?",
+    "What solutions exist?",
+    "What are future challenges?",
+]
+
+# 4. Conduct the research
+context = f"Research topic: {topic}"
+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.
+
+3. Building an Advanced Assistant
+
+## 3. Building an Advanced Assistant
+
+Now let’s expand on the basic approach. The Advanced Assistant adds:
+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
+
+
+class ResearchAssistant:
+    """Advanced research assistant with persistence."""
+
+    def __init__(
+        self,
+        name: str = "Researcher",
+        model: str = "gpt-4o-mini",
+        save_dir: str = "research",
+    ):
+        # 1. Configure the AI model
+        ai_model = iModel(provider="openai", model=model, temperature=0.7)
+
+        # 2. Create the assistant branch
+        self.assistant = Branch(
+            name=name,
+            system="""You are a research assistant.
+            Provide clear, accurate information.
+            Support claims with evidence.
+            Ask for clarification if needed.""",
+            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.
+        Each file is expected to be named after the topic, e.g. "ai_safety.json".
+        """
+        for file in self.save_dir.glob("*.json"):
+            with open(file) as f:
+                research = json.load(f)
+                self.topics[research["topic"]] = research
+
+    async def research_topic(
+        self, topic: str, questions: list[str]
+    ) -> dict[str, str]:
+        """
+        Researches a topic thoroughly by asking multiple questions.
+        Returns a dictionary of {question -> answer}.
+        """
+        try:
+            answers = {}
+            for question in questions:
+                response = await self.assistant.chat(
+                    f"Regarding {topic}: {question}"
+                )
+                answers[question] = response
+
+            # Save research to a JSON file
+            research = {
+                "topic": topic,
+                "date": datetime.now().isoformat(),
+                "questions": questions,
+                "answers": answers,
+            }
+
+            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."
+                )
+            elif "Rate limit" in str(e):
+                raise ValueError(
+                    "Rate limit exceeded. Please try again later."
+                )
+            else:
+                raise e
+
+    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:
+        """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"
+    )
+
+    # 2. Define topics and questions
+    topics = {
+        "AI Safety": [
+            "What are the main concerns?",
+            "What solutions exist?",
+            "What are future challenges?",
+        ],
+        "Machine Learning": [
+            "What are key concepts?",
+            "What are best practices?",
+            "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}"))
+
+            display(Markdown(f"\nSummary:\n{summary}"))
+
+        except Exception as e:
+            print(f"Error researching {topic}: {str(e)}")
+            continue
+
+    # 4. Show all researched 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 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
+
+A minimal snippet for reference:
+```python
+from lionagi import Branch, iModel
+
+# Configure model
+ai_model = iModel(
+    provider="openai",
+    model="gpt-3.5-turbo",
+    temperature=0.7
+)
+
+# Create an assistant
+assistant = Branch(
+    name="Assistant",
+    system="You are a helpful assistant.",
+    chat_model=ai_model
+)
+
+# Safe chat
+try:
+    response = await assistant.chat("Hello!")
+    print(response)
+except Exception as e:
+    print(f"Error: {str(e)}")
+```
+
+## 6. Next Steps
+
+You have now learned:
+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.
+
+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.