lionagi 0.7.0__tar.gz → 0.7.1__tar.gz

{lionagi-0.7.0 → lionagi-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.7.0
+Version: 0.7.1
 Summary: An AGentic Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License

lionagi-0.7.1/docs/Makefile

@@ -0,0 +1,23 @@
+SHELL = /bin/sh
+
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html livehtml
+
+help:
+	@echo "Please use 'make <target>' where <target> is one of:"
+	@echo "  html       to build the HTML documentation"
+	@echo "  clean      to remove build artifacts"
+	@echo "  livehtml   to run autobuild for live reloading"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"
+
+# Optional: live reload docs as you edit
+livehtml:
+	sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)/html --port 8000

lionagi-0.7.1/docs/_static/custom.css

@@ -0,0 +1,89 @@
+/* custom.css for your design overrides */
+
+html {
+  font-size: 16px;
+  line-height: 1.6;
+}
+
+/* Constrain wide paragraphs for better readability on large screens */
+@media (min-width: 1200px) {
+  .md-typeset {
+    max-width: 65ch;
+}
+
+/* Improve code block font & background a bit */
+.highlight pre {
+  font-family: "JetBrains Mono", "Source Code Pro", monospace;
+  font-size: 0.9rem;
+  background: #f8f8f8;
+  border-radius: 4px;
+}
+
+/* Example custom coloring for notes/admonitions */
+.admonition {
+  border-left: 4px solid var(--color-brand-primary);
+  margin: 1rem 0;
+  padding: 0.75rem 1rem;
+}
+
+/* Our custom GitHub header link container */
+.my-custom-header {
+  margin: 0.75rem 1rem 0 1rem;
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  border-bottom: 1px solid var(--color-border-muted, #ccc);
+  padding-bottom: 0.5rem;
+}
+
+.my-custom-header .header-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  text-decoration: none;
+  color: var(--color-text-primary, #222);
+  background: var(--color-background-accent, #f5f5f5);
+  padding: 0.4rem 0.75rem;
+  border-radius: 6px;
+  font-weight: 500;
+  transition: background-color 0.2s ease, color 0.2s ease;
+}
+
+.my-custom-header .header-link:hover {
+  background: var(--color-background-accent-hover, #e0e0e0);
+  color: var(--color-text-primary-hover, #111);
+}
+
+/* GitHub icon sizing and transitions */
+.my-custom-header .gh-icon {
+  width: 1.2em;
+  height: 1.2em;
+  flex-shrink: 0;
+  opacity: 0.8;
+  transition: opacity 0.2s ease;
+}
+
+.my-custom-header .header-link:hover .gh-icon {
+  opacity: 1.0;
+}
+
+/* Footer styling */
+.my-custom-footer {
+  margin-top: 2rem;
+  padding-top: 1rem;
+  font-size: 0.9rem;
+  color: var(--color-text-secondary, #777);
+  border-top: 1px solid var(--color-border-muted, #ccc);
+  text-align: center;
+}
+
+.my-custom-footer a {
+  text-decoration: none;
+  color: var(--color-brand-primary, #3070a0);
+  font-weight: 500;
+}
+
+.my-custom-footer a:hover {
+  color: var(--color-brand-content, #3070a0);
+}
+}

{lionagi-0.7.0 → lionagi-0.7.1}/docs/_templates/layout.html

@@ -1,18 +1,16 @@
 {% extends "!layout.html" %}
 
 {% block header %}
-  <!-- Our custom header container -->
   <div class="my-custom-header">
-    <!-- A sleek "View on GitHub" link with an icon -->
     <a class="header-link" 
-       href="https://github.com/lion-agi/lionagi" 
+       href="https://github.com/your-org/your-repo"
        target="_blank" 
        rel="noopener noreferrer"
-       title="View this project on GitHub">
-      <!-- Optional: embed an inline GitHub icon using an SVG -->
-      <svg class="gh-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
-        <path
-          d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 
+       title="GitHub: your-org/your-repo">
+      <!-- Example GitHub icon (inlined) -->
+      <svg class="gh-icon" xmlns="http://www.w3.org/2000/svg" fill="currentColor" 
+           viewBox="0 0 24 24" aria-hidden="true">
+        <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 
              3.438 9.8 8.205 11.387.6.113.82-.258.82-.577 
              0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61 
              -.546-1.387-1.333-1.758-1.333-1.758-1.089-.744.083-.729.083-.729 
@@ -26,9 +24,20 @@
              5.92.43.372.81 1.102.81 2.221 0 1.604-.015 
              2.896-.015 3.286 0 .319.22.694.825.576C20.565 
              22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
-      </svg>
-      <span>View on GitHub</span>
-    </a>
-  </div>
-  {{ super() }}
-{% endblock %}
+            </svg>
+            <span>View on GitHub</span>
+          </a>
+        </div>
+        {{ super() }}
+      {% endblock %}
+      
+      {% block footer %}
+        {{ super() }}
+        <div class="my-custom-footer">
+          <p>© 2025 Haiyang Li — Built with 
+          <a href="https://www.sphinx-doc.org" target="_blank">Sphinx</a> 
+          & 
+          <a href="https://pradyunsg.me/furo/" target="_blank">Furo</a>. 
+          </p>
+        </div>
+      {% endblock %}

lionagi-0.7.1/docs/conf.py

@@ -0,0 +1,52 @@
+import os
+import sys
+
+# Insert your package directory so autodoc can find your modules
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "LionAGI"
+author = "Haiyang Li"
+copyright = "2025"
+release = "0.7"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_title = "LionAGI Documentation"
+
+html_theme_options = {
+    "sidebar_hide_name": True,
+    "navigation_with_keys": True,
+    # Hide the “On This Page” panel:
+    "light_css_variables": {
+        "color-brand-primary": "#3070a0",
+        "color-brand-content": "#3070a0",
+        "font-size--body": "16px",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#5dafff",
+        "color-brand-content": "#5dafff",
+    },
+}
+pygments_style = "friendly"
+pygments_dark_style = "solarized-dark"
+
+html_css_files = [
+    "custom.css",  # loads after theme CSS
+]
+
+# If you want a logo, place 'logo.png' in _static/
+# html_logo = "_static/logo.png"
+
+# Example: Add any additional Sphinx config below
+# napoleon_use_param = True
+# todo_include_todos = True

lionagi-0.7.1/docs/index.rst

@@ -0,0 +1,37 @@
+.. _lionagi-docs-index:
+
+====================================================
+LionAGI — Documentation Home Page
+====================================================
+
+Welcome to LionAGI's documentation! This site covers how to use LionAGI's
+features, including:
+
+- **Branch**: the main conversation manager,
+- **Adapters**: converting data to/from external formats,
+- **Operations**: powerful LLM flows (operate, instruct, parse, etc.),
+- **Action system**: function-calling, advanced multi-step flows, and more.
+
+If you're new, start with the **Tutorials**. If you're looking for deeper 
+API references, check out the **Modules** sections.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table of Contents:
+
+   tutorials/index
+   modules/index
+
+Indices and tables
+==================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Indices & Tables
+
+   genindex
+   modindex
+   search

lionagi-0.7.1/docs/modules/action.rst

@@ -0,0 +1,128 @@
+.. _lionagi-action-system:
+
+================================================
+Action System
+================================================
+.. module:: lionagi.operatives.action
+   :synopsis: Tools, requests, and managers for function-based actions.
+
+Overview
+--------
+The **action** system enables **function calling** within LionAGI:
+
+- **Tools** wrap a Python callable with optional pre/post processors and schema-based validation.
+- **FunctionCalling** is a specialized `Event` that executes these tools.
+- **ActionManager** registers multiple Tools for invocation by requests.
+- **ActionRequestModel** and **ActionResponseModel** define standardized message formats
+  for specifying which function to call, with what arguments, and returning the function's output.
+
+Contents
+--------
+.. contents::
+   :local:
+   :depth: 2
+
+
+FunctionCalling
+---------------
+.. automodule:: lionagi.operatives.action.function_calling
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   The :class:`FunctionCalling` class extends :class:`~lionagi.protocols.generic.event.Event`
+   to manage the entire lifecycle of a **tool** invocation, including optional
+   pre and post processing. It updates :attr:`execution` with status, duration,
+   and any output or error.
+
+
+ActionManager
+-------------
+.. automodule:: lionagi.operatives.action.manager
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   A specialized :class:`~lionagi.protocols._concepts.Manager` that keeps a
+   registry of **tools** (functions). It also provides an `invoke` method for
+   easily executing a registered function, given an :class:`ActionRequest` or
+   its Pydantic model.
+
+
+Request & Response Models
+-------------------------
+.. automodule:: lionagi.operatives.action.request_response_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   Contains pydantic classes:
+   - :class:`ActionRequestModel`: For specifying `function` and `arguments`.
+   - :class:`ActionResponseModel`: For indicating the function output.
+
+
+Tool
+----
+.. automodule:: lionagi.operatives.action.tool
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   Defines :class:`Tool`, which wraps a Python callable and auto-generates a JSON schema
+   describing its parameters. Also includes type aliases like ``FuncTool``.
+
+Utilities
+---------
+.. automodule:: lionagi.operatives.action.utils
+   :members:
+   :undoc-members:
+
+   Internal helpers, including constants for field descriptions and the
+   function `parse_action_request` for parsing a JSON string into a list
+   of requests.
+
+
+Example Usage
+-------------
+A short example of how to use these classes:
+
+.. code-block:: python
+
+   from lionagi.operatives.action.manager import ActionManager
+   from lionagi.operatives.action.request_response_model import ActionRequestModel
+
+   # 1. Create an action manager and register a function
+   def multiply(x, y):
+       return x * y
+
+   manager = ActionManager()
+   manager.register_tool(multiply)
+
+   # 2. Build an ActionRequestModel
+   request_data = {"function": "multiply", "arguments": {"x": 3, "y": 4}}
+   action_request = ActionRequestModel.model_validate(request_data)
+
+   # 3. Invoke
+   result_event = await manager.invoke(action_request)
+   print(result_event.execution.response)  # Should show 12
+
+
+File Locations
+--------------
+- **function_calling.py**: 
+  The :class:`FunctionCalling` event for executing tools.
+
+- **manager.py** (ActionManager): 
+  The main manager for registering and invoking Tools.
+
+- **request_response_model.py**: 
+  Pydantic-based models for requests/responses.
+
+- **tool.py**: 
+  The :class:`Tool` class that wraps a callable function with schema info.
+
+- **utils.py**: 
+  Shared utility constants and a simple parser method for requests.
+
+``Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>``
+``SPDX-License-Identifier: Apache-2.0``

lionagi-0.7.1/docs/modules/adapter.rst

@@ -0,0 +1,120 @@
+.. _lionagi-adapters:
+
+=========================================
+Adapter System
+=========================================
+.. module:: lionagi.protocols.adapters
+   :synopsis: Provides a unified interface for converting data to/from external formats.
+
+Overview
+--------
+This system introduces the concept of an **Adapter** that knows how to
+translate an internal object (like a Pydantic-based Element or a 
+``Collective``) to an external representation (JSON, CSV, Excel, Pandas
+DataFrame, etc.), and vice versa. Adapters are registered in a global
+:class:`AdapterRegistry` under a specific **key** (like ``".csv"`` or
+``"pd_dataframe"``), allowing other code to call ``adapt_from`` or
+``adapt_to`` generically.
+
+Contents
+--------
+.. contents::
+   :local:
+   :depth: 2
+
+
+Adapter and Registry
+--------------------
+.. automodule:: lionagi.protocols.adapters.adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   :class:`Adapter` is a Python protocol specifying two methods:
+   ``from_obj()`` and ``to_obj()``. The :class:`AdapterRegistry` is a
+   container that associates each adapter with a key or extension.
+
+
+JSON Adapters
+-------------
+.. automodule:: lionagi.protocols.adapters.json_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   - **JsonAdapter**: For reading/writing **in-memory** JSON strings.  
+   - **JsonFileAdapter**: For reading/writing JSON files from disk.
+
+
+CSV and Excel Adapters
+----------------------
+.. automodule:: lionagi.protocols.adapters.pandas_.csv_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   Provides **CSVFileAdapter** using pandas.
+
+.. automodule:: lionagi.protocols.adapters.pandas_.excel_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   Provides **ExcelFileAdapter** for `.xlsx` files with pandas.
+
+
+Pandas DataFrame and Series Adapters
+------------------------------------
+.. automodule:: lionagi.protocols.adapters.pandas_.pd_dataframe_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   **PandasDataFrameAdapter** handles converting a list of elements
+   to a single ``pd.DataFrame``, or a DataFrame back into a list of
+   dictionaries.
+
+.. automodule:: lionagi.protocols.adapters.pandas_.pd_series_adapter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   **PandasSeriesAdapter** transforms a single item to/from a
+   single-row ``pd.Series``.
+
+
+Example Usage
+-------------
+Below is a simple snippet using the registry:
+
+.. code-block:: python
+
+   from lionagi.protocols.adapters.adapter import AdapterRegistry
+   from lionagi.protocols.adapters.json_adapter import JsonAdapter
+
+   # Register the adapter
+   AdapterRegistry.register(JsonAdapter)
+
+   # Suppose we have some object with `to_dict()`
+   my_element = SomeElement()
+
+   # Convert to JSON string
+   json_str = AdapterRegistry.adapt_to(my_element, "json")
+
+   # Convert JSON back into a dictionary
+   parsed = AdapterRegistry.adapt_from(type(my_element), json_str, "json")
+
+   # Typically, you'd then call `SomeElement.from_dict(parsed)` if needed.
+
+
+File Locations
+--------------
+- **adapter.py**: The core protocol (Adapter) and :class:`AdapterRegistry`.  
+- **json_adapter.py**: In-memory JSON and JSON-file adapters.  
+- **pandas_/csv_adapter.py**: CSV file adapter.  
+- **pandas_/excel_adapter.py**: Excel file adapter (.xlsx).  
+- **pandas_/pd_dataframe_adapter.py**: DataFrame adapter.  
+- **pandas_/pd_series_adapter.py**: Series adapter.
+
+``Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>``
+``SPDX-License-Identifier: Apache-2.0``

lionagi-0.7.1/docs/modules/branch.rst

@@ -0,0 +1,74 @@
+.. _lionagi-branch-class:
+
+================================================
+Branch: The Orchestrator
+================================================
+.. module:: lionagi.session.branch
+   :synopsis: Provides the Branch class to manage conversation, actions, logs, etc.
+
+Overview
+--------
+A :class:`Branch` represents a single “branch” of conversation in LionAGI.
+It **manages**:
+
+- A :class:`~lionagi.protocols.generic.log.LogManager` for storing logs,
+- A :class:`~lionagi.protocols.generic.log.LogManagerConfig` (if needed),
+- A :class:`~lionagi.protocols.generic.element.Element` as the base object,
+- A :class:`~lionagi.protocols.types.Communicatable` mailbox for cross-branch communication,
+- A :class:`~lionagi.protocols.types.Relational` link,
+- A :class:`~lionagi.protocols.types.SenderRecipient` to identify user or role,
+- A :class:`MessageManager` for messages (system instructions, user instructions, model responses),
+- An :class:`ActionManager` for tools,
+- An :class:`iModelManager` for multiple LLM or model references (like “chat”, “parse”),
+- Utility methods for “chat,” “operate,” “parse,” “act,” etc. (documented in :ref:`lionagi-branch-operations`).
+
+Contents
+--------
+.. contents::
+   :local:
+   :depth: 2
+
+
+Branch
+------
+.. autoclass:: lionagi.session.branch.Branch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   The key attributes include:
+   
+   - **Messages** (via :attr:`msgs`)  
+   - **Logs** (via :attr:`logs`)  
+   - **Tools** (via :attr:`acts`)  
+   - **Models** (via :attr:`mdls`)  
+   - **Mailbox** (for external messaging)
+
+   **Common usage**:
+   1. Instantiate a Branch, optionally providing a system message and some initial tools.
+   2. Use :meth:`chat` or :meth:`communicate` for user queries.
+   3. If you want structured responses or function calls, use :meth:`operate`.
+   4. If you want to parse or validate final text, use :meth:`parse`.
+   5. Tools can be registered anytime via :attr:`acts` or with the arguments 
+      to the constructor.
+
+   Also includes mailbox-based methods like :meth:`send` and :meth:`receive` 
+   for cross-branch or cross-system communication in a multi-agent scenario.
+
+
+Key Differences from a Basic Session
+------------------------------------
+Where a simpler “session” might just store messages + call an LLM, 
+**Branch** expands that concept by:
+
+- Integrating advanced log management with a :class:`LogManager`.
+- Holding a mailbox (like an email or queue system) so that branches 
+  can pass :class:`Package` objects to each other.
+- Tying in a :class:`ActionManager` for immediate function or tool calls.
+- Potentially linking to a “Graph” node or referencing relations 
+  (due to the :class:`Relational` inheritance).
+- Providing **clone** operations if you want to copy the conversation 
+  state to a new branch.
+
+``Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>``
+``SPDX-License-Identifier: Apache-2.0``