lionagi 0.17.11__py3-none-any.whl → 0.18.1__py3-none-any.whl

lionagi/protocols/forms/form.py

@@ -1,86 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any
-
-from pydantic import ConfigDict, Field, model_validator
-from typing_extensions import Self
-
-from .base import BaseForm
-from .flow import FlowDefinition
-
-
-class Form(BaseForm):
-    """
-    A domain form that can handle either a simple 'a,b->c' assignment
-    or a multi-step flow if the assignment string has semicolons, etc.
-    """
-
-    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
-
-    flow_definition: FlowDefinition | None = None
-    # Possibly some extra fields, e.g. "guidance" or "task"
-    guidance: str | None = Field(default=None)
-    task: str | None = Field(default=None)
-
-    @model_validator(mode="before")
-    def parse_assignment_into_flow(cls, values):
-        """
-        If the 'assignment' has semicolons, assume multiple steps, parse into FlowDefinition.
-        If it's a single step or no semicolons, we remain in 'simple' mode.
-        """
-        assignment_str = values.get("assignment")
-        if assignment_str and ";" in assignment_str:
-            flow = FlowDefinition()
-            flow.parse_flow_string(assignment_str)
-            values["flow_definition"] = flow
-        return values
-
-    @model_validator(mode="after")
-    def compute_output_fields(self) -> Self:
-        """
-        If in simple mode, we parse something like 'a,b->c' and set output_fields=[c].
-        If in multi-step mode, we set output_fields to the final produced fields of the flow.
-        """
-        if self.flow_definition:
-            # multi-step
-            produced = self.flow_definition.get_produced_fields()
-            if not self.output_fields:
-                self.output_fields = list(produced)
-        else:
-            # single-step
-            if self.assignment and "->" in self.assignment:
-                # parse the single arrow
-                ins_outs = self.assignment.split("->", 1)
-                outs_str = ins_outs[1]
-                outs = [x.strip() for x in outs_str.split(",") if x.strip()]
-                if not self.output_fields:
-                    self.output_fields = outs
-        return self
-
-    def fill_fields(self, **kwargs) -> None:
-        """
-        A small helper: fill fields in this form by direct assignment.
-        Usually you'd do 'myform(field=val, field2=val2)', but sometimes you want partial updates.
-        """
-        for k, v in kwargs.items():
-            setattr(self, k, v)
-
-    def to_instructions(self) -> dict[str, Any]:
-        """
-        Return a small dictionary that an LLM can read as an 'instruction context'.
-        """
-        return {
-            "assignment": self.assignment,
-            "flow": (
-                self.flow_definition.model_dump()
-                if self.flow_definition
-                else None
-            ),
-            "guidance": self.guidance,
-            "task": self.task,
-            "required_outputs": self.output_fields,
-        }
-
-
-# File: lionagi/protocols/forms/form.py

lionagi/protocols/forms/report.py

@@ -1,48 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from pydantic import Field
-
-from ..generic.pile import Pile
-from .base import BaseForm
-from .form import Form
-
-
-class Report(BaseForm):
-    """
-    A minimal class that collects multiple completed forms as "sub-tasks."
-    If you have a single FlowDefinition that describes the entire multi-step pipeline,
-    you can track each step as a separate form in here.
-    """
-
-    default_form_cls: type[Form] = Form
-    completed_forms: Pile[Form] = Field(
-        default_factory=lambda: Pile(item_type={Form}),
-        description="A list of forms that have been completed for this report.",
-    )
-    form_assignments: dict[str, str] = Field(
-        default_factory=dict,
-        description="Mapping from form ID -> assignment string",
-    )
-
-    def add_completed_form(
-        self, form: Form, update_report_fields: bool = False
-    ):
-        """
-        Add a completed form. Optionally update the report’s fields from the form's output.
-        """
-        missing = form.check_completeness()
-        if missing:
-            raise ValueError(
-                f"Form {form.id} is incomplete: missing {missing}."
-            )
-        self.completed_forms.append(form)
-        self.form_assignments[form.id] = form.assignment or ""
-        # optionally update the report’s own fields
-        if update_report_fields:
-            for f_ in form.output_fields:
-                val = getattr(form, f_, None)
-                setattr(self, f_, val)
-
-
-# File: lionagi/protocols/forms/report.py

lionagi/protocols/mail/__init__.py

@@ -1,2 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0

lionagi/protocols/mail/exchange.py

@@ -1,220 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-import asyncio
-from typing import Any
-
-from lionagi.protocols.generic.element import IDType
-
-from .._concepts import Communicatable
-from ..generic.element import ID
-from ..generic.pile import Pile
-from .mail import Mail, Package, PackageCategory
-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
-        )
-        self.buffer: dict[IDType, list[Mail]] = {}
-        self.mailboxes: dict[IDType, Mailbox] = {}
-        if sources:
-            self.add_source(sources)
-        self._execute_stop: bool = False
-
-    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."
-            )
-
-        self.sources.include(sources)
-        for source in sources:
-            self.mailboxes[source.id] = source.mailbox
-        self.buffer.update({source.id: [] for source in sources})
-
-    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."
-            )
-
-        self.sources.exclude(sources)
-        for source in sources:
-            self.buffer.pop(source.id)
-            self.mailboxes.pop(source.id)
-
-    @staticmethod
-    def create_mail(
-        sender: ID[Communicatable],
-        recipient: ID[Communicatable],
-        category: PackageCategory | str,
-        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]) -> 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.")
-
-        sender_mailbox: Mailbox = self.sources[sender].mailbox
-
-        while sender_mailbox.pending_outs:
-            mail: Mail = sender_mailbox.pile_.popleft()
-            self.buffer[mail.recipient].append(mail)
-
-    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.")
-
-        recipient_mailbox: Mailbox = self.sources[recipient].mailbox
-
-        while self.buffer[recipient]:
-            mail = self.buffer[recipient].pop(0)
-            if mail.recipient != recipient:
-                raise ValueError(
-                    f"Mail recipient {mail.recipient} does not match recipient {recipient}"
-                )
-            if mail.sender not in self.sources:
-                raise ValueError(f"Mail sender {mail.sender} does not exist.")
-            recipient_mailbox.append_in(mail)
-
-    def collect_all(self) -> None:
-        """
-        Collect mail from every source in this exchange.
-        """
-        for source in self.sources:
-            self.collect(sender=source.id)
-
-    def deliver_all(self) -> None:
-        """
-        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:
-        """
-        Continuously collect and deliver mail in an asynchronous loop.
-
-        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

@@ -1,51 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from pydantic import field_validator
-
-from .._concepts import Sendable
-from ..generic.element import Element
-from ..messages.base import IDType
-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
-    package: Package
-
-    @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

@@ -1,103 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from lionagi.protocols.generic.element import IDType
-
-from ..generic.pile import Pile, Progression
-from .mail import Mail
-
-__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