lionagi 0.18.0__py3-none-any.whl → 0.18.2__py3-none-any.whl

lionagi/protocols/mail/manager.py

@@ -1,218 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-import asyncio
-from collections import deque
-from typing import Any
-
-from lionagi._errors import ItemNotFoundError
-
-from .._concepts import Manager, Observable
-from ..generic.element import ID, IDType
-from ..generic.pile import Pile, to_list_type
-from .exchange import Exchange
-from .mail import Mail, Package, PackageCategory
-
-
-class MailManager(Manager):
-    """
-    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.
-
-        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]] = {}
-        self.execute_stop: bool = False
-
-        if sources:
-            self.add_sources(sources)
-
-    def add_sources(self, sources: ID.Item | ID.ItemSeq, /) -> None:
-        """
-        Register new sources in the MailManager.
-
-        Parameters
-        ----------
-        sources : ID.Item | ID.ItemSeq
-            A single source or multiple sources to be added.
-
-        Raises
-        ------
-        ValueError
-            If adding the sources fails for any reason.
-        """
-        try:
-            sources = to_list_type(sources)
-            self.sources.include(sources)
-            for item in sources:
-                self.mails[item.id] = {}
-        except Exception as e:
-            raise ValueError("Failed to add source.") from e
-
-    @staticmethod
-    def create_mail(
-        sender: ID.Ref,
-        recipient: ID.Ref,
-        category: PackageCategory | str,
-        package: Any,
-        request_source: Any = None,
-    ) -> Mail:
-        """
-        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
-        )
-        return Mail(sender=sender, recipient=recipient, package=pack)
-
-    def delete_source(self, source_id: IDType) -> None:
-        """
-        Remove a source from the manager, discarding any associated mail.
-
-        Parameters
-        ----------
-        source_id : IDType
-            The ID of the source to be removed.
-
-        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.")
-        self.sources.pop(source_id)
-        self.mails.pop(source_id)
-
-    def collect(self, sender: IDType) -> None:
-        """
-        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 = (
-            self.sources[sender]
-            if isinstance(self.sources[sender], Exchange)
-            else self.sources[sender].mailbox
-        )
-        while mailbox.pending_outs.size() > 0:
-            mail_id = mailbox.pending_outs.popleft()
-            mail: Mail = mailbox.pile_.pop(mail_id)
-            if mail.recipient not in self.sources:
-                rec_ = mail.recipient
-                raise ItemNotFoundError(
-                    f"Recipient source {rec_} does not exist"
-                )
-            if mail.sender not in self.mails[mail.recipient]:
-                self.mails[mail.recipient].update({mail.sender: deque()})
-            self.mails[mail.recipient][mail.sender].append(mail)
-
-    def send(self, recipient: IDType) -> None:
-        """
-        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."
-            )
-        if not self.mails[recipient]:
-            return
-        for key in list(self.mails[recipient].keys()):
-            pending_mails = self.mails[recipient].pop(key)
-            mailbox: Exchange = (
-                self.sources[recipient]
-                if isinstance(self.sources[recipient], Exchange)
-                else self.sources[recipient].mailbox
-            )
-            while pending_mails:
-                mail = pending_mails.popleft()
-                mailbox.include(mail, direction="in")
-
-    def collect_all(self) -> None:
-        """
-        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 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:
-        """
-        Continuously collect and send mail in an asynchronous loop.
-
-        Parameters
-        ----------
-        refresh_time : int, optional
-            Delay (in seconds) between each collect/send cycle.
-        """
-        while not self.execute_stop:
-            self.collect_all()
-            self.send_all()
-            await asyncio.sleep(refresh_time)
-
-
-# File: lion_core/communication/manager.py

lionagi/protocols/mail/package.py

@@ -1,101 +0,0 @@
-# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
-# SPDX-License-Identifier: Apache-2.0
-
-from enum import Enum
-from typing import Any
-
-from lionagi.ln import now_utc
-from lionagi.protocols.generic.element import ID, IDType
-
-from .._concepts import Communicatable, Observable
-
-
-class PackageCategory(str, Enum):
-    """
-    Enumeration of common package categories in LionAGI:
-
-    - MESSAGE: General message content
-    - TOOL: A tool or action to be invoked
-    - IMODEL: Some internal model reference
-    - NODE: A node in a graph
-    - NODE_LIST: A list of nodes
-    - NODE_ID: A node ID
-    - START: A 'start' signal
-    - END: An 'end' signal
-    - CONDITION: A condition or gating logic
-    - SIGNAL: A more generic signal or marker
-    """
-
-    MESSAGE = "message"
-    TOOL = "tool"
-    IMODEL = "imodel"
-    NODE = "node"
-    NODE_LIST = "node_list"
-    NODE_ID = "node_id"
-    START = "start"
-    END = "end"
-    CONDITION = "condition"
-    SIGNAL = "signal"
-
-
-def validate_category(value: Any) -> PackageCategory:
-    """
-    Validate and convert the input to a valid PackageCategory.
-
-    Parameters
-    ----------
-    value : Any
-        The input to interpret as a `PackageCategory`.
-
-    Returns
-    -------
-    PackageCategory
-        The validated category.
-
-    Raises
-    ------
-    ValueError
-        If the value cannot be converted into a valid package category.
-    """
-    if isinstance(value, PackageCategory):
-        return value
-    try:
-        return PackageCategory(str(value))
-    except ValueError as e:
-        raise ValueError("Invalid value for category.") from e
-
-
-class Package(Observable):
-    """
-    A self-contained package that can be attached to `Mail` items.
-    Includes a unique ID, creation timestamp, category, payload item,
-    and an optional request source for context.
-
-    Attributes
-    ----------
-    category : PackageCategory
-        The classification or type of package.
-    item : Any
-        The main payload or data of this package.
-    request_source : ID[Communicatable] | None
-        An optional reference indicating the origin or context
-        for this package.
-    """
-
-    __slots__ = ("id", "created_at", "category", "item", "request_source")
-
-    def __init__(
-        self,
-        category: PackageCategory,
-        item: Any,
-        request_source: ID[Communicatable] = None,
-    ):
-        super().__init__()
-        self.id = IDType.create()
-        self.created_at = now_utc().timestamp()
-        self.category = validate_category(category)
-        self.item = item
-        self.request_source = request_source
-
-
-# File: lionagi/protocols/mail/package.py

lionagi/protocols/operatives/__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/operatives/operative.py

@@ -1,362 +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 BaseModel
-from pydantic.fields import FieldInfo
-
-from lionagi.ln import extract_json
-from lionagi.ln.fuzzy._fuzzy_match import fuzzy_match_keys
-from lionagi.models import FieldModel, ModelParams, OperableModel
-from lionagi.utils import UNDEFINED
-
-
-class Operative:
-    """Class representing an operative that handles request and response models for operations.
-
-    This implementation uses OperableModel internally for better performance while
-    maintaining backward compatibility with the existing API.
-    """
-
-    def __init__(
-        self,
-        name: str | None = None,
-        request_type: type[BaseModel] | None = None,
-        response_type: type[BaseModel] | None = None,
-        response_model: BaseModel | None = None,
-        response_str_dict: dict | str | None = None,
-        auto_retry_parse: bool = True,
-        max_retries: int = 3,
-        parse_kwargs: dict | None = None,
-        request_params: (
-            ModelParams | None
-        ) = None,  # Deprecated, for backward compatibility
-        **_kwargs,  # Ignored for backward compatibility
-    ):
-        """Initialize the Operative.
-
-        Args:
-            name: Name of the operative
-            request_type: Pydantic model type for requests
-            response_type: Pydantic model type for responses
-            response_model: Current response model instance
-            response_str_dict: Raw response string/dict
-            auto_retry_parse: Whether to auto-retry parsing
-            max_retries: Maximum parse retries
-            parse_kwargs: Additional parse arguments
-            request_params: Deprecated - use direct field addition
-            response_params: Deprecated - use direct field addition
-        """
-        self.name = name
-        self.request_type = request_type
-        self.response_type = response_type
-        self.response_model = response_model
-        self.response_str_dict = response_str_dict
-        self.auto_retry_parse = auto_retry_parse
-        self.max_retries = max_retries
-        self.parse_kwargs = parse_kwargs or {}
-        self._should_retry = None
-
-        # Internal OperableModel instances
-        self._request_operable = OperableModel()
-        self._response_operable = OperableModel()
-
-        # Handle deprecated ModelParams for backward compatibility
-        if request_params:
-            self._init_from_model_params(request_params)
-
-        # Set default name if not provided
-        if not self.name:
-            self.name = (
-                self.request_type.__name__
-                if self.request_type
-                else "Operative"
-            )
-
-    def _init_from_model_params(self, params: ModelParams):
-        """Initialize from ModelParams for backward compatibility."""
-        # Add field models to the request operable
-        if params.field_models:
-            # Coerce to list if single FieldModel instance
-            field_models_list = (
-                [params.field_models]
-                if isinstance(params.field_models, FieldModel)
-                else params.field_models
-            )
-            for field_model in field_models_list:
-                self._request_operable.add_field(
-                    field_model.name,
-                    field_model=field_model,
-                    annotation=field_model.base_type,
-                )
-
-        # Add parameter fields (skip if already added from field_models)
-        if params.parameter_fields:
-            for name, field_info in params.parameter_fields.items():
-                if (
-                    name not in (params.exclude_fields or [])
-                    and name not in self._request_operable.all_fields
-                ):
-                    self._request_operable.add_field(
-                        name, field_obj=field_info
-                    )
-
-        # Generate request_type if not provided
-        if not self.request_type:
-            exclude_fields = params.exclude_fields or []
-            use_fields = set(self._request_operable.all_fields.keys()) - set(
-                exclude_fields
-            )
-
-            # Determine model name - prefer explicit name, then base_type name, then default
-            model_name = "RequestModel"
-            if not params._is_sentinel(params.name):
-                model_name = params.name
-            elif not params._is_sentinel(params.base_type):
-                model_name = params.base_type.__name__
-
-            self.request_type = self._request_operable.new_model(
-                name=model_name,
-                use_fields=use_fields,
-                base_type=params.base_type,
-                frozen=params.frozen,
-                config_dict=params.config_dict,
-                doc=params.doc,
-            )
-
-        # Update name if not set - prefer explicit name, then base_type name
-        if not self.name:
-            if not params._is_sentinel(params.name):
-                self.name = params.name
-            elif not params._is_sentinel(params.base_type):
-                self.name = params.base_type.__name__
-
-    def model_dump(self) -> dict[str, Any]:
-        """Convert to dictionary for backward compatibility.
-
-        Note: This returns a Python dict, not JSON-serializable data.
-        For JSON serialization, convert types appropriately.
-        """
-        return {
-            "name": self.name,
-            "request_type": self.request_type,  # Python class object
-            "response_type": self.response_type,  # Python class object
-            "response_model": self.response_model,
-            "response_str_dict": self.response_str_dict,
-            "auto_retry_parse": self.auto_retry_parse,
-            "max_retries": self.max_retries,
-            "parse_kwargs": self.parse_kwargs,
-        }
-
-    def to_dict(self) -> dict[str, Any]:
-        """Alias for model_dump() - more appropriate name for non-Pydantic class."""
-        return self.model_dump()
-
-    def raise_validate_pydantic(self, text: str) -> None:
-        """Validates and updates the response model using strict matching.
-
-        Args:
-            text (str): The text to validate and parse into the response model.
-
-        Raises:
-            Exception: If the validation fails.
-        """
-        d_ = extract_json(text, fuzzy_parse=True)
-        if isinstance(d_, list | tuple) and len(d_) == 1:
-            d_ = d_[0]
-        try:
-            d_ = fuzzy_match_keys(
-                d_, self.request_type.model_fields, handle_unmatched="raise"
-            )
-            d_ = {k: v for k, v in d_.items() if v != UNDEFINED}
-            self.response_model = self.request_type.model_validate(d_)
-            self._should_retry = False
-        except Exception:
-            self.response_str_dict = d_
-            self._should_retry = True
-
-    def force_validate_pydantic(self, text: str):
-        """Forcibly validates and updates the response model, allowing unmatched fields.
-
-        Args:
-            text (str): The text to validate and parse into the response model.
-        """
-        d_ = text
-        try:
-            d_ = extract_json(text, fuzzy_parse=True)
-            if isinstance(d_, list | tuple) and len(d_) == 1:
-                d_ = d_[0]
-            d_ = fuzzy_match_keys(
-                d_, self.request_type.model_fields, handle_unmatched="force"
-            )
-            d_ = {k: v for k, v in d_.items() if v != UNDEFINED}
-            self.response_model = self.request_type.model_validate(d_)
-            self._should_retry = False
-        except Exception:
-            self.response_str_dict = d_
-            self.response_model = None
-            self._should_retry = True
-
-    def update_response_model(
-        self, text: str | None = None, data: dict | None = None
-    ) -> BaseModel | dict | str | None:
-        """Updates the response model based on the provided text or data.
-
-        Args:
-            text (str, optional): The text to parse and validate.
-            data (dict, optional): The data to update the response model with.
-
-        Returns:
-            BaseModel | dict | str | None: The updated response model or raw data.
-
-        Raises:
-            ValueError: If neither text nor data is provided.
-        """
-        if text is None and data is None:
-            raise ValueError("Either text or data must be provided.")
-
-        if text:
-            self.response_str_dict = text
-            try:
-                self.raise_validate_pydantic(text)
-            except Exception:
-                self.force_validate_pydantic(text)
-
-        if data and self.response_type:
-            d_ = self.response_model.model_dump()
-            d_.update(data)
-            self.response_model = self.response_type.model_validate(d_)
-
-        if not self.response_model and isinstance(
-            self.response_str_dict, list
-        ):
-            try:
-                self.response_model = [
-                    self.request_type.model_validate(d_)
-                    for d_ in self.response_str_dict
-                ]
-            except Exception:
-                pass
-
-        return self.response_model or self.response_str_dict
-
-    def create_response_type(
-        self,
-        response_params: ModelParams | None = None,
-        field_models: list[FieldModel] | None = None,
-        parameter_fields: dict[str, FieldInfo] | None = None,
-        exclude_fields: list[str] | None = None,
-        field_descriptions: dict[str, str] | None = None,
-        inherit_base: bool = True,
-        config_dict: dict | None = None,
-        doc: str | None = None,
-        frozen: bool = False,
-        validators: dict | None = None,
-    ) -> None:
-        """Creates a new response type based on the provided parameters.
-
-        Args:
-            response_params (ModelParams, optional): Parameters for the new response model.
-            field_models (list[FieldModel], optional): List of field models.
-            parameter_fields (dict[str, FieldInfo], optional): Dictionary of parameter fields.
-            exclude_fields (list, optional): List of fields to exclude.
-            field_descriptions (dict, optional): Dictionary of field descriptions.
-            inherit_base (bool, optional): Whether to inherit the base model.
-            config_dict (dict | None, optional): Configuration dictionary.
-            doc (str | None, optional): Documentation string.
-            frozen (bool, optional): Whether the model is frozen.
-            validators (dict, optional): Dictionary of validators.
-        """
-        # Process response_params if provided (for backward compatibility)
-        if response_params:
-            # Extract values from ModelParams
-            field_models = field_models or response_params.field_models
-            parameter_fields = (
-                parameter_fields or response_params.parameter_fields
-            )
-            exclude_fields = exclude_fields or response_params.exclude_fields
-            field_descriptions = (
-                field_descriptions or response_params.field_descriptions
-            )
-            inherit_base = (
-                response_params.inherit_base if inherit_base else False
-            )
-            config_dict = config_dict or response_params.config_dict
-            doc = doc or response_params.doc
-            frozen = frozen or response_params.frozen
-
-        # Clear response operable and rebuild
-        self._response_operable = OperableModel()
-
-        # Copy fields from request operable if inherit_base
-        if inherit_base and self._request_operable:
-            for (
-                field_name,
-                field_model,
-            ) in self._request_operable.extra_field_models.items():
-                self._response_operable.add_field(
-                    field_name, field_model=field_model
-                )
-
-        # Add field models (skip if already exists from inheritance)
-        if field_models:
-            # Coerce to list if single FieldModel instance
-            field_models_list = (
-                [field_models]
-                if isinstance(field_models, FieldModel)
-                else field_models
-            )
-            for field_model in field_models_list:
-                if field_model.name not in self._response_operable.all_fields:
-                    self._response_operable.add_field(
-                        field_model.name,
-                        field_model=field_model,
-                        annotation=field_model.base_type,
-                    )
-
-        # Add parameter fields (skip if already added)
-        if parameter_fields:
-            for name, field_info in parameter_fields.items():
-                if (
-                    name not in (exclude_fields or [])
-                    and name not in self._response_operable.all_fields
-                ):
-                    self._response_operable.add_field(
-                        name, field_obj=field_info
-                    )
-
-        # Add validators if provided
-        if validators:
-            for field_name, validator in validators.items():
-                if field_name in self._response_operable.all_fields:
-                    field_model = (
-                        self._response_operable.extra_field_models.get(
-                            field_name
-                        )
-                    )
-                    if field_model:
-                        field_model.validator = validator
-
-        # Generate response type
-        exclude_fields = exclude_fields or []
-        use_fields = set(self._response_operable.all_fields.keys()) - set(
-            exclude_fields
-        )
-
-        # Determine base type - use request_type if inheriting and no specific base provided
-        base_type = None
-        if response_params and response_params.base_type:
-            base_type = response_params.base_type
-        elif inherit_base and self.request_type:
-            base_type = self.request_type
-
-        self.response_type = self._response_operable.new_model(
-            name=(response_params.name if response_params else None)
-            or "ResponseModel",
-            use_fields=use_fields,
-            base_type=base_type,
-            frozen=frozen,
-            config_dict=config_dict,
-            doc=doc,
-        )