lionagi 0.13.5__tar.gz → 0.13.6__tar.gz

lionagi-0.13.6/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: |
+          uv sync --group docs
+          uv add --group docs sphinx-autobuild
+
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run sphinx-build -M html "." "_build" --keep-going
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{lionagi-0.13.5 → lionagi-0.13.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.13.5
+Version: 0.13.6
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>, Liangbingyan Luo <llby_luo@outlook.com>
 License:            Apache License
@@ -235,6 +235,7 @@ Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: toml>=0.9.0
 Provides-Extra: all
 Requires-Dist: claude-code-sdk>=0.0.14; extra == 'all'
+Requires-Dist: datamodel-code-generator>=0.31.2; extra == 'all'
 Requires-Dist: docling>=2.15.1; extra == 'all'
 Requires-Dist: fastmcp>=2.10.5; extra == 'all'
 Requires-Dist: ollama>=0.4.0; extra == 'all'
@@ -257,6 +258,8 @@ Provides-Extra: reader
 Requires-Dist: docling>=2.15.1; extra == 'reader'
 Provides-Extra: rich
 Requires-Dist: rich>=13.0.0; extra == 'rich'
+Provides-Extra: schema
+Requires-Dist: datamodel-code-generator>=0.31.2; extra == 'schema'
 Provides-Extra: test
 Requires-Dist: pytest-asyncio>=1.0.0; extra == 'test'
 Requires-Dist: pytest>=8.3.4; extra == 'test'

lionagi-0.13.6/cookbooks/001_branch_converse.ipynb

@@ -0,0 +1,415 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Start a chat with LLM"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `Branch` object is the foundational building block of lionagi, serving as your primary interface for AI model interactions.\n",
+    "\n",
+    "Think of a Branch as a conversation thread that:\n",
+    "- **Manages messages**: Automatically handles system prompts, user inputs, and AI responses in a structured conversation flow\n",
+    "- **Enables multi-turn conversations**: Maintains context across multiple exchanges, allowing for natural back-and-forth dialogue\n",
+    "- **Handles advanced features**: Supports structured outputs, tool usage, and sophisticated context management out of the box\n",
+    "\n",
+    "**Architecture Overview:**\n",
+    "- A `Session` can contain multiple branches, but every session starts with a default `'main'` branch\n",
+    "- Each branch maintains its own conversation history in `branch.messages`\n",
+    "\n",
+    "This design allows you to organize complex AI workflows into logical conversation threads, each with their own context and purpose."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Configuration and Model Selection:**\n",
+    "\n",
+    "lionagi comes with sensible defaults for popular AI providers. You can explore these configurations in `lionagi.integrations.config` to understand available models and their settings.\n",
+    "\n",
+    "The framework supports multiple AI providers through a unified interface, making it easy to switch between different models without changing your core application logic."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 1. Using `chat()` - Stateless Interactions\n",
+    "\n",
+    "The `chat()` method provides **stateless** communication with AI models. Each call is independent, making it perfect for one-off queries or when you want to control conversation history manually.\n",
+    "\n",
+    "**When to use `chat()`:**\n",
+    "- Single-shot questions that don't require conversation context\n",
+    "- When you want to manually manage conversation state\n",
+    "- For parallel processing of independent queries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from lionagi import iModel, Branch\n",
+    "from IPython.display import Markdown"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SYSTEM = \"As a comedian, you are sarcastically funny\"\n",
+    "prompt1 = \"short joke: a blue whale and a big shark meet at the bar and start dancing\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "**comedian1**: A blue whale and a big shark walk into a bar. They start dancing—turns out, even in the ocean, they're just trying to groove away from their terrible dating profiles."
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# create a branch with gpt-4.1-nano model, need an OpenAI API key\n",
+    "comedian1 = Branch(\n",
+    "    chat_model=iModel(model=\"openai/gpt-4.1-nano\"), system=SYSTEM\n",
+    ")\n",
+    "joke1 = await comedian1.chat(prompt1)\n",
+    "\n",
+    "Markdown(f\"**comedian1**: {joke1}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Model Provider Flexibility:**\n",
+    "\n",
+    "lionagi's unified interface allows you to seamlessly switch between different AI providers. Whether you're using OpenAI's latest models, local Ollama instances, or other providers, the API remains consistent.\n",
+    "\n",
+    "This provider-agnostic approach gives you the flexibility to:\n",
+    "- Choose the best model for your specific use case\n",
+    "- Switch providers based on cost, performance, or availability\n",
+    "- Test the same logic across different AI models"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 2. Using `communicate()` - Stateful Conversations\n",
+    "\n",
+    "The `communicate()` method provides **stateful** interactions where each message builds upon the previous conversation history. This is ideal for multi-turn dialogues and complex reasoning tasks.\n",
+    "\n",
+    "**Key Difference from `chat()`:**\n",
+    "- `chat()` is **stateless**: Each call is independent, no memory between calls\n",
+    "- `communicate()` is **stateful**: Automatically maintains conversation history, enabling context-aware responses\n",
+    "\n",
+    "**When to use `communicate()`:**\n",
+    "- Multi-turn conversations where context matters\n",
+    "- Building up complex reasoning over multiple exchanges\n",
+    "- When you want automatic conversation memory management"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "**comedian2**: <think>\n",
+       "Okay, so I have this user query. Let's see what they're asking for. They want me to be a comedian who’s sarcastically funny and come up with a joke based on them. The setup is that a blue whale and a big shark meet at the bar and start dancing. Hmm.\n",
+       "\n",
+       "Alright, I need to think about how a blue whale and a shark can go smoothly or maybe accidentally dance together in a bar. Well, they're both water-based creatures. That could be a funny angle. Maybe the idea of them being on the water side? \n",
+       "\n",
+       "So, starting with that theme, maybe something about not wanting to be too far from shorelines because there’s a lot of activity when they’re out. That ties into their characteristics. Also, considering the bar itself—sharks can be seen drinking, etc.\n",
+       "\n",
+       "Putting it all together, I should avoid sounding too serious and add some humor through their behaviors. Maybe include something playful like swishing arms or bellowing in fits. \n",
+       "\n",
+       "The user also mentioned a short joke, so keeping it concise is key. I need to make sure it's clear and gets the point across without being too wordy.\n",
+       "\n",
+       "Alright, let me try formulating that. Maybe something about not wanting to be too far from shorelines because there’s a lot of activities out. That ties into both the blue whale and shark characteristics. \n",
+       "\n",
+       "Then have them start dancing together at the bar, keeping it humorous yet appropriate, adding some flair to make it light despite being the opposite in many ways.\n",
+       "</think>\n",
+       "\n",
+       "The blue whale and the big shark aren’t exactly on the same boat when they pop into the bar. They’re both waterberms, like moths trapped under a glass. You know what happens next? They’ll start bellowing in fits and swishing arms like they’ve seen too many fish in total."
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Need to install \"lionagi[ollama]\" to use Ollama models\n",
+    "\n",
+    "comedian2 = Branch(\n",
+    "    chat_model=iModel(model=\"ollama/deepseek-r1:1.5b\"), system=SYSTEM\n",
+    ")\n",
+    "joke2 = await comedian2.communicate(prompt1)\n",
+    "\n",
+    "Markdown(f\"**comedian2**: {joke2}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>created_at</th>\n",
+       "      <th>role</th>\n",
+       "      <th>content</th>\n",
+       "      <th>id</th>\n",
+       "      <th>sender</th>\n",
+       "      <th>recipient</th>\n",
+       "      <th>metadata</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>1.753069e+09</td>\n",
+       "      <td>system</td>\n",
+       "      <td>{'system_message': 'As a comedian, you are sar...</td>\n",
+       "      <td>935c1318-3f5a-4172-b4c4-728bb8948880</td>\n",
+       "      <td>system</td>\n",
+       "      <td>6e490b3f-7b51-4657-95b6-6e66362338b3</td>\n",
+       "      <td>{'lion_class': 'lionagi.protocols.messages.sys...</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "     created_at    role                                            content  \\\n",
+       "0  1.753069e+09  system  {'system_message': 'As a comedian, you are sar...   \n",
+       "\n",
+       "                                     id  sender  \\\n",
+       "0  935c1318-3f5a-4172-b4c4-728bb8948880  system   \n",
+       "\n",
+       "                              recipient  \\\n",
+       "0  6e490b3f-7b51-4657-95b6-6e66362338b3   \n",
+       "\n",
+       "                                            metadata  \n",
+       "0  {'lion_class': 'lionagi.protocols.messages.sys...  "
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# One message, only the system\n",
+    "\n",
+    "comedian1.to_df()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>created_at</th>\n",
+       "      <th>role</th>\n",
+       "      <th>content</th>\n",
+       "      <th>id</th>\n",
+       "      <th>sender</th>\n",
+       "      <th>recipient</th>\n",
+       "      <th>metadata</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>1.753069e+09</td>\n",
+       "      <td>system</td>\n",
+       "      <td>{'system_message': 'As a comedian, you are sar...</td>\n",
+       "      <td>6c39df29-c90e-4a74-a404-7678d6f1f9bd</td>\n",
+       "      <td>system</td>\n",
+       "      <td>3c5be94e-00b2-46d7-9f0f-7715e768c7c7</td>\n",
+       "      <td>{'lion_class': 'lionagi.protocols.messages.sys...</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>1.753069e+09</td>\n",
+       "      <td>user</td>\n",
+       "      <td>{'context': [], 'instruction': 'short joke: a ...</td>\n",
+       "      <td>41ca3cce-a47e-4496-88c7-fd31a34eefb7</td>\n",
+       "      <td>user</td>\n",
+       "      <td>3c5be94e-00b2-46d7-9f0f-7715e768c7c7</td>\n",
+       "      <td>{'lion_class': 'lionagi.protocols.messages.ins...</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>1.753069e+09</td>\n",
+       "      <td>assistant</td>\n",
+       "      <td>{'assistant_response': '&lt;think&gt;\n",
+       "Okay, so I hav...</td>\n",
+       "      <td>eac70edd-6338-40eb-8525-a8bd25ee5836</td>\n",
+       "      <td>3c5be94e-00b2-46d7-9f0f-7715e768c7c7</td>\n",
+       "      <td>user</td>\n",
+       "      <td>{'model_response': {'id': 'chatcmpl-198', 'obj...</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "     created_at       role                                            content  \\\n",
+       "0  1.753069e+09     system  {'system_message': 'As a comedian, you are sar...   \n",
+       "1  1.753069e+09       user  {'context': [], 'instruction': 'short joke: a ...   \n",
+       "2  1.753069e+09  assistant  {'assistant_response': '<think>\n",
+       "Okay, so I hav...   \n",
+       "\n",
+       "                                     id                                sender  \\\n",
+       "0  6c39df29-c90e-4a74-a404-7678d6f1f9bd                                system   \n",
+       "1  41ca3cce-a47e-4496-88c7-fd31a34eefb7                                  user   \n",
+       "2  eac70edd-6338-40eb-8525-a8bd25ee5836  3c5be94e-00b2-46d7-9f0f-7715e768c7c7   \n",
+       "\n",
+       "                              recipient  \\\n",
+       "0  3c5be94e-00b2-46d7-9f0f-7715e768c7c7   \n",
+       "1  3c5be94e-00b2-46d7-9f0f-7715e768c7c7   \n",
+       "2                                  user   \n",
+       "\n",
+       "                                            metadata  \n",
+       "0  {'lion_class': 'lionagi.protocols.messages.sys...  \n",
+       "1  {'lion_class': 'lionagi.protocols.messages.ins...  \n",
+       "2  {'model_response': {'id': 'chatcmpl-198', 'obj...  "
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Three messages, system + user + assistant\n",
+    "\n",
+    "comedian2.to_df()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'model_response': {'id': 'chatcmpl-198',\n",
+       "  'object': 'chat.completion',\n",
+       "  'created': 1753069177,\n",
+       "  'model': 'deepseek-r1:1.5b',\n",
+       "  'system_fingerprint': 'fp_ollama',\n",
+       "  'choices': [{'index': 0,\n",
+       "    'message': {'role': 'assistant',\n",
+       "     'content': \"<think>\\nOkay, so I have this user query. Let's see what they're asking for. They want me to be a comedian who’s sarcastically funny and come up with a joke based on them. The setup is that a blue whale and a big shark meet at the bar and start dancing. Hmm.\\n\\nAlright, I need to think about how a blue whale and a shark can go smoothly or maybe accidentally dance together in a bar. Well, they're both water-based creatures. That could be a funny angle. Maybe the idea of them being on the water side? \\n\\nSo, starting with that theme, maybe something about not wanting to be too far from shorelines because there’s a lot of activity when they’re out. That ties into their characteristics. Also, considering the bar itself—sharks can be seen drinking, etc.\\n\\nPutting it all together, I should avoid sounding too serious and add some humor through their behaviors. Maybe include something playful like swishing arms or bellowing in fits. \\n\\nThe user also mentioned a short joke, so keeping it concise is key. I need to make sure it's clear and gets the point across without being too wordy.\\n\\nAlright, let me try formulating that. Maybe something about not wanting to be too far from shorelines because there’s a lot of activities out. That ties into both the blue whale and shark characteristics. \\n\\nThen have them start dancing together at the bar, keeping it humorous yet appropriate, adding some flair to make it light despite being the opposite in many ways.\\n</think>\\n\\nThe blue whale and the big shark aren’t exactly on the same boat when they pop into the bar. They’re both waterberms, like moths trapped under a glass. You know what happens next? They’ll start bellowing in fits and swishing arms like they’ve seen too many fish in total.\"},\n",
+       "    'finish_reason': 'stop'}],\n",
+       "  'usage': {'prompt_tokens': 40,\n",
+       "   'completion_tokens': 379,\n",
+       "   'total_tokens': 419}}}"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Review the entire model response from LLMs\n",
+    "\n",
+    "comedian2.messages[-1].metadata"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "lionagi",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.15"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}