lionagi 0.6.1__py3-none-any.whl → 0.7.1__py3-none-any.whl

lionagi/protocols/generic/pile.py

@@ -994,8 +994,8 @@ class Pile(Element, Collective[E], Generic[E]):
         path_or_buf,
         *,
         use_pd: bool = False,
+        many: bool = False,
         mode="w",
-        verbose=False,
         **kwargs,
     ):
         """Export collection to JSON file.
@@ -1007,15 +1007,9 @@ class Pile(Element, Collective[E], Generic[E]):
             verbose: Print confirmation message.
             **kwargs: Additional arguments for json.dump() or DataFrame.to_json().
         """
-
         if use_pd:
             return self.to_df().to_json(mode=mode, **kwargs)
-        dict_ = self.to_dict()
-        with open(path_or_buf, mode) as f:
-            json.dump(dict_, f, **kwargs)
-
-        if verbose:
-            print(f"Saved Pile to {path_or_buf}")
+        return self.adapt_to(".json", fp=path_or_buf, mode=mode, many=many)
 
 
 def pile(
@@ -1076,3 +1070,6 @@ def to_list_type(value: Any, /) -> list[Any]:
     if isinstance(value, list | tuple | set | deque | Generator):
         return list(value)
     return [value]
+
+
+# File: lionagi/protocols/generic/pile.py

lionagi/protocols/graph/edge.py

@@ -163,4 +163,4 @@ class Edge(Element):
             cond.source = source
 
 
-# File: protocols/graph/edge.py
+# File: lionagi/protocols/graph/edge.py

lionagi/protocols/graph/graph.py

@@ -204,13 +204,14 @@ class Graph(Element, Relational):
     def to_networkx(self, **kwargs) -> Any:
         """Convert the graph to a NetworkX graph object."""
         try:
-            import networkx as nx  # type: ignore
+            from networkx import DiGraph  # type: ignore
+
         except ImportError:
-            raise ImportError(
-                "NetworkX is not installed. Please install it with `pip install networkx`."
-            )
+            from lionagi.libs.package.imports import check_import
 
-        g = nx.DiGraph(**kwargs)
+            DiGraph = check_import("networkx", import_name="DiGraph")
+
+        g = DiGraph(**kwargs)
         for node in self.internal_nodes:
             node_info = node.to_dict()
             node_info.pop("id")
@@ -238,9 +239,13 @@ class Graph(Element, Relational):
             import matplotlib.pyplot as plt  # type: ignore
             import networkx as nx  # type: ignore
         except ImportError:
-            raise ImportError(
-                "Failed to import Matplotlib. Please install the package with `pip install matplotlib`"
-            )
+            from lionagi.libs.package.imports import check_import
+
+            check_import("matplotlib")
+            check_import("networkx")
+
+            import matplotlib.pyplot as plt  # type: ignore
+            import networkx as nx  # type: ignore
 
         g = self.to_networkx(**kwargs)
         pos = nx.spring_layout(g)
@@ -288,3 +293,6 @@ class Graph(Element, Relational):
 
     def __contains__(self, item: object) -> bool:
         return item in self.internal_nodes or item in self.internal_edges
+
+
+# File: lionagi/protocols/graph/graph.py

lionagi/protocols/graph/node.py

@@ -122,4 +122,4 @@ class Node(Element, Relational):
         return cls._get_adapter_registry().list_adapters()
 
 
-# File: protocols/graph/node.py
+# File: lionagi/protocols/graph/node.py

lionagi/protocols/mail/exchange.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Provides the `Exchange` class, which orchestrates mail flows among
+sources that implement `Communicatable`. It collects pending outgoing
+mail from each source and delivers them to the appropriate recipients.
+"""
+
 import asyncio
 from typing import Any
 
@@ -15,8 +21,34 @@ from .mailbox import Mailbox
 
 
 class Exchange:
+    """
+    Manages mail exchange operations among a set of sources that are
+    `Communicatable`. Each source has an associated `Mailbox` to store
+    inbound and outbound mail.
+
+    Attributes
+    ----------
+    sources : Pile[Communicatable]
+        The communicatable sources participating in the exchange.
+    buffer : dict[IDType, list[Mail]]
+        A temporary holding area for mail messages before they reach
+        their recipient's mailbox.
+    mailboxes : dict[IDType, Mailbox]
+        Maps each source's ID to its Mailbox.
+    _execute_stop : bool
+        A flag indicating whether to stop the asynchronous execution loop.
+    """
 
     def __init__(self, sources: ID[Communicatable].ItemSeq = None):
+        """
+        Initialize an `Exchange` instance.
+
+        Parameters
+        ----------
+        sources : ID[Communicatable].ItemSeq, optional
+            One or more communicatable sources to manage. If provided,
+            they are immediately added.
+        """
         self.sources: Pile[Communicatable] = Pile(
             item_type={Communicatable}, strict_type=False
         )
@@ -26,7 +58,20 @@ class Exchange:
             self.add_source(sources)
         self._execute_stop: bool = False
 
-    def add_source(self, sources: ID[Communicatable].ItemSeq):
+    def add_source(self, sources: ID[Communicatable].ItemSeq) -> None:
+        """
+        Register new communicatable sources for mail exchange.
+
+        Parameters
+        ----------
+        sources : ID[Communicatable].ItemSeq
+            The source(s) to be added.
+
+        Raises
+        ------
+        ValueError
+            If the given sources already exist in this exchange.
+        """
         if sources in self.sources:
             raise ValueError(
                 f"Source {sources} already exists in the mail manager."
@@ -37,8 +82,21 @@ class Exchange:
             self.mailboxes[source.id] = source.mailbox
         self.buffer.update({source.id: [] for source in sources})
 
-    def delete_source(self, sources: ID[Communicatable].ItemSeq):
-        """this will remove the source from the mail manager and all assosiated pending mails"""
+    def delete_source(self, sources: ID[Communicatable].ItemSeq) -> None:
+        """
+        Remove specified sources from the exchange, clearing any pending
+        mail associated with them.
+
+        Parameters
+        ----------
+        sources : ID[Communicatable].ItemSeq
+            The source(s) to remove.
+
+        Raises
+        ------
+        ValueError
+            If the given sources do not exist in this exchange.
+        """
         if not sources in self.sources:
             raise ValueError(
                 f"Source {sources} does not exist in the mail manager."
@@ -57,13 +115,47 @@ class Exchange:
         item: Any,
         request_source: Any = None,
     ) -> Mail:
+        """
+        Helper method to create a new Mail instance.
+
+        Parameters
+        ----------
+        sender : ID[Communicatable]
+            The ID (or Communicatable) identifying the mail sender.
+        recipient : ID[Communicatable]
+            The ID (or Communicatable) identifying the mail recipient.
+        category : PackageCategory | str
+            A classification for the package contents.
+        item : Any
+            The actual item/data to be sent.
+        request_source : Any, optional
+            Additional context about the request origin, if any.
+
+        Returns
+        -------
+        Mail
+            A newly created Mail object ready for sending.
+        """
         package = Package(
             category=category, item=item, request_source=request_source
         )
         return Mail(sender=sender, recipient=recipient, package=package)
 
-    def collect(self, sender: ID[Communicatable]):
-        """collect all mails from a particular sender"""
+    def collect(self, sender: ID[Communicatable]) -> None:
+        """
+        Collect all outbound mail from a specific sender, moving it
+        to the exchange buffer.
+
+        Parameters
+        ----------
+        sender : ID[Communicatable]
+            The ID of the source from which mail is collected.
+
+        Raises
+        ------
+        ValueError
+            If the sender is not part of this exchange.
+        """
         if sender not in self.sources:
             raise ValueError(f"Sender source {sender} does not exist.")
 
@@ -73,7 +165,21 @@ class Exchange:
             mail: Mail = sender_mailbox.pile_.popleft()
             self.buffer[mail.recipient].append(mail)
 
-    def deliver(self, recipient: ID[Communicatable]):
+    def deliver(self, recipient: ID[Communicatable]) -> None:
+        """
+        Deliver all mail in the buffer addressed to a specific recipient.
+
+        Parameters
+        ----------
+        recipient : ID[Communicatable]
+            The ID of the source to receive mail.
+
+        Raises
+        ------
+        ValueError
+            If the recipient is not part of this exchange or if mail
+            references an unknown sender.
+        """
         if recipient not in self.sources:
             raise ValueError(f"Recipient source {recipient} does not exist.")
 
@@ -90,27 +196,32 @@ class Exchange:
             recipient_mailbox.append_in(mail)
 
     def collect_all(self) -> None:
-        """Collect mail from all sources."""
+        """
+        Collect mail from every source in this exchange.
+        """
         for source in self.sources:
             self.collect(sender=source.id)
 
     def deliver_all(self) -> None:
-        """Send mail to all recipients."""
+        """
+        Deliver mail to every source in this exchange.
+        """
         for source in self.sources:
             self.deliver(recipient=source.id)
 
     async def execute(self, refresh_time: int = 1) -> None:
         """
-        Execute mail collection and sending process asynchronously.
-
-        This method runs in a loop, collecting and sending mail at
-            regular intervals.
+        Continuously collect and deliver mail in an asynchronous loop.
 
-        Args:
-            refresh_time (int, optional): The time to wait between
-                each cycle in seconds. Defaults to 1.
+        Parameters
+        ----------
+        refresh_time : int, optional
+            Number of seconds to wait between each cycle. Defaults to 1.
         """
         while not self._execute_stop:
             self.collect_all()
             self.deliver_all()
             await asyncio.sleep(refresh_time)
+
+
+# File: lionagi/protocols/mail/exchange.py

lionagi/protocols/mail/mail.py

@@ -2,6 +2,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `Mail` class, which is a `Sendable` element representing
+a single piece of mail, carrying a `Package` between a sender
+and recipient.
+"""
+
 from pydantic import field_validator
 
 from .._concepts import Sendable
@@ -11,6 +17,20 @@ from .package import Package, PackageCategory
 
 
 class Mail(Element, Sendable):
+    """
+    A single mail message that can be sent between communicatable entities.
+    It includes a sender, recipient, and a package that describes the
+    mail's content.
+
+    Attributes
+    ----------
+    sender : IDType
+        The ID representing the mail sender.
+    recipient : IDType
+        The ID representing the mail recipient.
+    package : Package
+        The package (category + payload) contained in this mail.
+    """
 
     sender: IDType
     recipient: IDType
@@ -18,8 +38,21 @@ class Mail(Element, Sendable):
 
     @field_validator("sender", "recipient")
     def _validate_sender_recipient(cls, value):
+        """
+        Validate that the sender and recipient fields are correct IDTypes.
+        """
         return IDType.validate(value)
 
     @property
     def category(self) -> PackageCategory:
+        """
+        Shortcut for retrieving the category from the underlying package.
+
+        Returns
+        -------
+        PackageCategory
+        """
         return self.package.category
+
+
+# File: lionagi/protocols/mail/mail.py

lionagi/protocols/mail/mailbox.py

@@ -2,6 +2,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Implements a simple mailbox system for each Communicatable entity.
+Holds inbound and outbound mail, stored internally in a `Pile`.
+"""
+
 from lionagi.protocols.generic.element import IDType
 
 from ..generic.pile import Pile, Progression
@@ -11,37 +16,94 @@ __all__ = ("Mailbox",)
 
 
 class Mailbox:
+    """
+    A mailbox that accumulates inbound and outbound mail for a single
+    communicatable source.
+
+    Attributes
+    ----------
+    pile_ : Pile[Mail]
+        A concurrency-safe collection storing all mail items.
+    pending_ins : dict[IDType, Progression]
+        Maps each sender's ID to a progression of inbound mail.
+    pending_outs : Progression
+        A progression of mail items waiting to be sent (outbound).
+    """
 
     def __init__(self):
+        """
+        Initialize an empty Mailbox with separate tracks for inbound
+        and outbound mail.
+        """
         self.pile_ = Pile(item_type=Mail, strict_type=True)
         self.pending_ins: dict[IDType, Progression] = {}
         self.pending_outs = Progression()
 
     def __contains__(self, item: Mail) -> bool:
+        """
+        Check if a mail item is currently in this mailbox.
+        """
         return item in self.pile_
 
     @property
     def senders(self) -> list[str]:
+        """
+        List of sender IDs that have inbound mail in this mailbox.
+
+        Returns
+        -------
+        list[str]
+        """
         return list(self.pending_ins.keys())
 
     def append_in(self, item: Mail, /):
+        """
+        Add a mail item to the inbound queue for the item's sender.
+
+        Parameters
+        ----------
+        item : Mail
+        """
         if item.sender not in self.pending_ins:
             self.pending_ins[item.sender] = Progression()
         self.pending_ins[item.sender].include(item)
         self.pile_.include(item)
 
     def append_out(self, item: Mail, /):
+        """
+        Add a mail item to the outbound (pending_outs) queue.
+
+        Parameters
+        ----------
+        item : Mail
+        """
         self.pending_outs.include(item)
         self.pile_.include(item)
 
     def exclude(self, item: Mail, /):
+        """
+        Remove a mail item from all internal references (inbound, outbound, and pile).
+
+        Parameters
+        ----------
+        item : Mail
+        """
         self.pile_.exclude(item)
         self.pending_outs.exclude(item)
         for v in self.pending_ins.values():
             v.exclude(item)
 
     def __bool__(self) -> bool:
+        """
+        Indicates if the mailbox contains any mail.
+        """
         return bool(self.pile_)
 
     def __len__(self) -> int:
+        """
+        Number of mail items in this mailbox.
+        """
         return len(self.pile_)
+
+
+# File: lionagi/protocols/mail/mailbox.py

lionagi/protocols/mail/manager.py

@@ -2,6 +2,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Defines the `MailManager` class, which coordinates mail operations
+across multiple sources in a more abstract or high-level manner.
+"""
+
 import asyncio
 from collections import deque
 from typing import Any
@@ -17,19 +22,29 @@ from .mail import Mail, Package, PackageCategory
 
 class MailManager(Manager):
     """
-    Manages mail operations for multiple sources in the Lion framework.
-
-    This class handles the collection, distribution, and management of mail
-    between different sources within the system.
+    A manager for mail operations across various observable sources
+    within LionAGI. Unlike `Exchange`, this class can manage the state
+    of multiple sources in a more general or higher-level context,
+    storing mail queues in a dictionary rather than individual buffers.
+
+    Attributes
+    ----------
+    sources : Pile[Observable]
+        A concurrency-safe collection of known sources.
+    mails : dict[str, dict[str, deque]]
+        A nested mapping of recipient -> sender -> queue of mail.
+    execute_stop : bool
+        Controls the asynchronous execution loop; set to True to exit.
     """
 
     def __init__(self, sources: ID.Item | ID.ItemSeq = None) -> None:
         """
         Initialize a MailManager instance.
 
-        Args:
-            sources (List[Any], optional): Initial list of mail sources to
-                manage.
+        Parameters
+        ----------
+        sources : ID.Item | ID.ItemSeq, optional
+            Initial source(s) to manage. Each source must be an Observable.
         """
         self.sources: Pile[Observable] = Pile()
         self.mails: dict[str, dict[str, deque]] = {}
@@ -40,14 +55,17 @@ class MailManager(Manager):
 
     def add_sources(self, sources: ID.Item | ID.ItemSeq, /) -> None:
         """
-        Add new sources to the MailManager.
+        Register new sources in the MailManager.
 
-        Args:
-            sources (Any): The sources to add. Can be a single source or
-                a list of sources.
+        Parameters
+        ----------
+        sources : ID.Item | ID.ItemSeq
+            A single source or multiple sources to be added.
 
-        Raises:
-            LionValueError: If adding the source(s) fails.
+        Raises
+        ------
+        ValueError
+            If adding the sources fails for any reason.
         """
         try:
             sources = to_list_type(sources)
@@ -66,17 +84,25 @@ class MailManager(Manager):
         request_source: Any = None,
     ) -> Mail:
         """
-        Create a new Mail object.
-
-        Args:
-            sender (str): The ID of the sender.
-            recipient (str): The ID of the recipient.
-            category (str): The category of the mail.
-            package (Any): The content of the package.
-            request_source (Any, optional): The source of the request.
-
-        Returns:
-            Mail: A new Mail object.
+        Factory method to generate a Mail object.
+
+        Parameters
+        ----------
+        sender : ID.Ref
+            Reference (ID or object) for the sender.
+        recipient : ID.Ref
+            Reference (ID or object) for the recipient.
+        category : PackageCategory | str
+            The category of this package.
+        package : Any
+            The payload or content in the mail.
+        request_source : Any, optional
+            Additional context about the request source.
+
+        Returns
+        -------
+        Mail
+            A new mail object with specified sender, recipient, and package.
         """
         pack = Package(
             category=category, package=package, request_source=request_source
@@ -85,13 +111,17 @@ class MailManager(Manager):
 
     def delete_source(self, source_id: IDType) -> None:
         """
-        Delete a source from the MailManager.
+        Remove a source from the manager, discarding any associated mail.
 
-        Args:
-            source_id (str): The ID of the source to delete.
+        Parameters
+        ----------
+        source_id : IDType
+            The ID of the source to be removed.
 
-        Raises:
-            LionValueError: If the source does not exist.
+        Raises
+        ------
+        ItemNotFoundError
+            If the given source ID is not present.
         """
         if source_id not in self.sources:
             raise ItemNotFoundError(f"Source {source_id} does not exist.")
@@ -99,7 +129,19 @@ class MailManager(Manager):
         self.mails.pop(source_id)
 
     def collect(self, sender: IDType) -> None:
-        """Collect mail from a specific sender."""
+        """
+        Collect outbound mail from a single source.
+
+        Parameters
+        ----------
+        sender : IDType
+            The ID of the sender whose outbound mail is retrieved.
+
+        Raises
+        ------
+        ItemNotFoundError
+            If the sender is not recognized.
+        """
         if sender not in self.sources:
             raise ItemNotFoundError(f"Sender source {sender} does not exist.")
         mailbox: Exchange = (
@@ -120,7 +162,19 @@ class MailManager(Manager):
             self.mails[mail.recipient][mail.sender].append(mail)
 
     def send(self, recipient: IDType) -> None:
-        """Send mail to a specific recipient."""
+        """
+        Send any pending mail to a specified recipient.
+
+        Parameters
+        ----------
+        recipient : IDType
+            The ID of the recipient to which mail should be delivered.
+
+        Raises
+        ------
+        ItemNotFoundError
+            If the recipient ID is not recognized.
+        """
         if recipient not in self.sources:
             raise ItemNotFoundError(
                 f"Recipient source {recipient} does not exist."
@@ -139,25 +193,27 @@ class MailManager(Manager):
                 mailbox.include(mail, direction="in")
 
     def collect_all(self) -> None:
-        """Collect mail from all sources."""
+        """
+        Collect outbound mail from all known sources.
+        """
         for source in self.sources:
             self.collect(sender=source.id)
 
     def send_all(self) -> None:
-        """Send mail to all recipients."""
+        """
+        Send mail to all known recipients who have pending items.
+        """
         for source in self.sources:
             self.send(recipient=source.id)
 
     async def execute(self, refresh_time: int = 1) -> None:
         """
-        Execute mail collection and sending process asynchronously.
-
-        This method runs in a loop, collecting and sending mail at
-            regular intervals.
+        Continuously collect and send mail in an asynchronous loop.
 
-        Args:
-            refresh_time (int, optional): The time to wait between
-                each cycle in seconds. Defaults to 1.
+        Parameters
+        ----------
+        refresh_time : int, optional
+            Delay (in seconds) between each collect/send cycle.
         """
         while not self.execute_stop:
             self.collect_all()
@@ -165,4 +221,4 @@ class MailManager(Manager):
             await asyncio.sleep(refresh_time)
 
 
-# File: lion_core/communication/mail_manager.py
+# File: lion_core/communication/manager.py