lionagi 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

lionagi/core/communication/instruction.py

@@ -0,0 +1,376 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.generic.log import Log
+from lionagi.core.typing import (
+    ID,
+    Any,
+    BaseModel,
+    JsonValue,
+    Literal,
+    override,
+)
+from lionagi.integrations.pydantic_ import break_down_pydantic_annotation
+from lionagi.libs.parse import to_str
+from lionagi.libs.utils import copy
+
+from .message import MessageFlag, MessageRole, RoledMessage
+from .utils import (
+    format_image_content,
+    format_text_content,
+    prepare_instruction_content,
+    prepare_request_response_format,
+)
+
+
+class Instruction(RoledMessage):
+    """
+    Represents an instruction message in the system.
+
+    This class encapsulates various components of an instruction, including
+    the main instruction content, guidance, context, and request fields.
+    It supports both text and image content, and can handle structured
+    request specifications through Pydantic models.
+
+    Attributes:
+        instruction: The main instruction content
+        context: Additional context information
+        guidance: Optional guidance for instruction execution
+        images: Optional list of images
+        request_fields: Fields requested in the response
+        plain_content: Plain text content
+        image_detail: Level of detail for images
+        request_model: Optional Pydantic model for structured requests
+        tool_schemas: Optional tool schemas
+    """
+
+    @override
+    def __init__(
+        self,
+        instruction: JsonValue | MessageFlag,
+        context: JsonValue | MessageFlag = None,
+        guidance: JsonValue | MessageFlag = None,
+        images: list | MessageFlag = None,
+        sender: ID.Ref | MessageFlag = None,
+        recipient: ID.Ref | MessageFlag = None,
+        request_fields: JsonValue | MessageFlag = None,
+        plain_content: JsonValue | MessageFlag = None,
+        image_detail: Literal["low", "high", "auto"] | MessageFlag = None,
+        request_model: BaseModel | type[BaseModel] | MessageFlag = None,
+        tool_schemas: dict | None = None,
+        protected_init_params: dict | None = None,
+    ) -> None:
+        """
+        Initialize an Instruction instance.
+
+        Args:
+            instruction: The main instruction content
+            context: Additional context for the instruction
+            guidance: Guidance information
+            images: List of images
+            sender: The sender of the instruction
+            recipient: The recipient of the instruction
+            request_fields: Fields requested in the response
+            plain_content: Plain text content
+            image_detail: Level of detail for images
+            request_model: A Pydantic model for structured requests
+            tool_schemas: Tool schemas
+            protected_init_params: Protected initialization parameters
+        """
+        message_flags = [
+            instruction,
+            context,
+            guidance,
+            images,
+            sender,
+            recipient,
+            request_fields,
+            plain_content,
+            image_detail,
+            tool_schemas,
+            request_model,
+        ]
+
+        if all(x == MessageFlag.MESSAGE_LOAD for x in message_flags):
+            protected_init_params = protected_init_params or {}
+            super().__init__(**protected_init_params)
+            return
+
+        if all(x == MessageFlag.MESSAGE_CLONE for x in message_flags):
+            super().__init__(role=MessageRole.USER)
+            return
+
+        super().__init__(
+            role=MessageRole.USER,
+            content=prepare_instruction_content(
+                guidance=guidance,
+                instruction=instruction,
+                context=context,
+                images=images,
+                request_fields=request_fields,
+                plain_content=plain_content,
+                image_detail=image_detail,
+                request_model=request_model,
+                tool_schemas=tool_schemas,
+            ),
+            sender=sender or "user",
+            recipient=recipient or "N/A",
+        )
+
+    @property
+    def guidance(self) -> str | None:
+        """Get the guidance content of the instruction."""
+        return self.content.get(["guidance"], None)
+
+    @guidance.setter
+    def guidance(self, guidance: str) -> None:
+        """Set the guidance content of the instruction."""
+        if not isinstance(guidance, str):
+            guidance = to_str(guidance)
+        self.content["guidance"] = guidance
+
+    @property
+    def instruction(self) -> JsonValue | None:
+        """Get the main instruction content."""
+        if "plain_content" in self.content:
+            return self.content["plain_content"]
+        else:
+            return self.content.get(["instruction"], None)
+
+    @instruction.setter
+    def instruction(self, instruction: JsonValue) -> None:
+        """Set the main instruction content."""
+        self.content["instruction"] = instruction
+
+    @property
+    def context(self) -> JsonValue | None:
+        """Get the context of the instruction."""
+        return self.content.get(["context"], None)
+
+    @context.setter
+    def context(self, context: JsonValue) -> None:
+        """Set the context of the instruction."""
+        if not isinstance(context, list):
+            context = [context]
+        self.content["context"] = context
+
+    @property
+    def tool_schemas(self) -> JsonValue | None:
+        """Get the schemas of the tools in the instruction."""
+        return self.content.get(["tool_schemas"], None)
+
+    @tool_schemas.setter
+    def tool_schemas(self, tool_schemas: dict) -> None:
+        """Set the schemas of the tools in the instruction."""
+        self.content["tool_schemas"] = tool_schemas
+
+    @property
+    def plain_content(self) -> str | None:
+        """Get the plain text content of the instruction."""
+        return self.content.get(["plain_content"], None)
+
+    @plain_content.setter
+    def plain_content(self, plain_content: str) -> None:
+        """Set the plain text content of the instruction."""
+        self.content["plain_content"] = plain_content
+
+    @property
+    def image_detail(self) -> Literal["low", "high", "auto"] | None:
+        """Get the image detail level of the instruction."""
+        return self.content.get(["image_detail"], None)
+
+    @image_detail.setter
+    def image_detail(
+        self, image_detail: Literal["low", "high", "auto"]
+    ) -> None:
+        """Set the image detail level of the instruction."""
+        self.content["image_detail"] = image_detail
+
+    @property
+    def images(self) -> list:
+        """Get the images associated with the instruction."""
+        return self.content.get(["images"], [])
+
+    @images.setter
+    def images(self, images: list) -> None:
+        """Set the images associated with the instruction."""
+        if not isinstance(images, list):
+            images = [images]
+        self.content["images"] = images
+
+    @property
+    def request_fields(self) -> dict | None:
+        """Get the requested fields in the instruction."""
+        return self.content.get(["request_fields"], None)
+
+    @request_fields.setter
+    def request_fields(self, request_fields: dict) -> None:
+        """Set the requested fields in the instruction."""
+        self.content["request_fields"] = request_fields
+        self.content["request_response_format"] = (
+            prepare_request_response_format(request_fields)
+        )
+
+    @property
+    def request_model(self) -> type[BaseModel] | None:
+        """Get the request model of the instruction."""
+        return self.content.get(["request_model"], None)
+
+    @request_model.setter
+    def request_model(self, request_model: type[BaseModel]) -> None:
+        """
+        Set the request model of the instruction.
+
+        This also updates request fields and context based on the model.
+        """
+        if isinstance(request_model, BaseModel):
+            self.content["request_model"] = type(request_model)
+        else:
+            self.content["request_model"] = request_model
+
+        self.request_fields = {}
+        self.extend_context(
+            respond_schema_info=request_model.model_json_schema()
+        )
+        self.request_fields = break_down_pydantic_annotation(request_model)
+
+    def extend_images(
+        self,
+        images: list | str,
+        image_detail: Literal["low", "high", "auto"] = None,
+    ) -> None:
+        """
+        Add new images to the instruction.
+
+        Args:
+            images: New images to add
+            image_detail: Optional new image detail level
+        """
+        images = images if isinstance(images, list) else [images]
+        _ima: list = self.content.get(["images"], [])
+        _ima.extend(images)
+        self.images = _ima
+
+        if image_detail:
+            self.image_detail = image_detail
+
+    def extend_context(self, *args, **kwargs) -> None:
+        """
+        Add new context to the instruction.
+
+        Args:
+            *args: Positional arguments to add to context
+            **kwargs: Keyword arguments to add to context
+        """
+        context: list = self.content.get("context", [])
+
+        if args:
+            context.extend(args)
+        if kwargs:
+            kwargs = copy(kwargs)
+            for k, v in kwargs.items():
+                context.append({k: v})
+
+        self.context = context
+
+    def update(
+        self,
+        *args,
+        guidance: JsonValue = None,
+        instruction: JsonValue = None,
+        request_fields: JsonValue = None,
+        plain_content: JsonValue = None,
+        request_model: BaseModel | type[BaseModel] = None,
+        images: str | list = None,
+        image_detail: Literal["low", "high", "auto"] = None,
+        tool_schemas: dict = None,
+        **kwargs,
+    ):
+        """
+        Update multiple aspects of the instruction.
+
+        Args:
+            *args: Positional arguments for context update
+            guidance: New guidance content
+            instruction: New instruction content
+            request_fields: New request fields
+            plain_content: New plain text content
+            request_model: New request model
+            images: New images to add
+            image_detail: New image detail level
+            tool_schemas: New tool schemas
+            **kwargs: Additional keyword arguments for context update
+
+        Raises:
+            ValueError: If both request_model and request_fields are provided
+        """
+        if request_model and request_fields:
+            raise ValueError(
+                "You cannot pass both request_model and request_fields "
+                "to create_instruction"
+            )
+        if guidance:
+            self.guidance = guidance
+
+        if instruction:
+            self.instruction = instruction
+
+        if plain_content:
+            self.plain_content = plain_content
+
+        if request_fields:
+            self.request_fields = request_fields
+
+        if request_model:
+            self.request_model = request_model
+
+        if images:
+            self.images = images
+
+        if image_detail:
+            self.image_detail = image_detail
+
+        if tool_schemas:
+            self.tool_schemas = tool_schemas
+
+        self.extend_context(*args, **kwargs)
+
+    @override
+    def _format_content(self) -> dict[str, Any]:
+        """Format the content of the instruction."""
+        content = self.content.to_dict()
+        text_content = format_text_content(content)
+        if "images" not in content:
+            return {"role": self.role.value, "content": text_content}
+        else:
+            content = format_image_content(
+                text_content=text_content,
+                images=self.images,
+                image_detail=self.image_detail,
+            )
+            return {"role": self.role.value, "content": content}
+
+    @override
+    def to_log(self) -> Log:
+        """
+        Convert the message to a Log object.
+
+        Creates a Log instance containing the message content and additional
+        information as loginfo.
+
+        Returns:
+            Log: A Log object representing the message.
+        """
+        dict_ = self.to_dict()
+        content = dict_.pop("content")
+        content.pop("request_model", None)
+        content.pop("request_fields", None)
+        _log = Log(
+            content=content,
+            loginfo=dict_,
+        )
+        return _log
+
+
+__all__ = ["Instruction"]

lionagi/core/communication/message.py

@@ -0,0 +1,286 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+
+from lionagi.core._class_registry import get_class
+from lionagi.core.generic.types import Component, Log
+from lionagi.core.typing import (
+    Any,
+    Communicatable,
+    Enum,
+    Field,
+    Note,
+    field_serializer,
+    field_validator,
+    override,
+)
+from lionagi.libs.utils import copy
+
+from .base_mail import BaseMail
+
+
+class MessageRole(str, Enum):
+    """
+    Enum for possible roles a message can assume in a conversation.
+
+    These roles define the nature and purpose of messages in the system:
+    - SYSTEM: System-level messages providing context or instructions
+    - USER: Messages from users making requests or providing input
+    - ASSISTANT: Messages from AI assistants providing responses
+    """
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+class MessageFlag(str, Enum):
+    """
+    Enum to signal special message construction modes.
+
+    These flags are used internally to control message instantiation:
+    - MESSAGE_CLONE: Signal to create a clone of an existing message
+    - MESSAGE_LOAD: Signal to load a message from stored data
+    """
+
+    MESSAGE_CLONE = "MESSAGE_CLONE"
+    MESSAGE_LOAD = "MESSAGE_LOAD"
+
+
+class MessageField(str, Enum):
+    """
+    Enum for standard message fields.
+
+    Defines the standard fields that can be present in a message:
+    - TIMESTAMP: Message creation timestamp
+    - LION_CLASS: Class identifier for LION system
+    - ROLE: Message role (system/user/assistant)
+    - CONTENT: Message content
+    - ln_id: Unique message identifier
+    - SENDER: Message sender
+    - RECIPIENT: Message recipient
+    - METADATA: Additional message metadata
+    """
+
+    TIMESTAMP = "timestamp"
+    LION_CLASS = "lion_class"
+    ROLE = "role"
+    CONTENT = "content"
+    ln_id = "ln_id"
+    SENDER = "sender"
+    RECIPIENT = "recipient"
+    METADATA = "metadata"
+
+
+MESSAGE_FIELDS = [i.value for i in MessageField.__members__.values()]
+
+
+class RoledMessage(Component, BaseMail):
+    """
+    A base class representing a message with roles and properties.
+
+    This class combines functionality from Component and BaseMail to create
+    a versatile message object with role-based behavior. It serves as the
+    foundation for all specific message types in the system.
+
+    Attributes:
+        content (Note): The content of the message, stored in a Note object
+        role (MessageRole): The role of the message in the conversation
+            (system, user, or assistant)
+
+    Example:
+        >>> msg = RoledMessage(role=MessageRole.USER, content="Hello")
+        >>> print(msg.role)
+        MessageRole.USER
+    """
+
+    content: Note = Field(
+        default_factory=Note,
+        description="The content of the message.",
+    )
+
+    role: MessageRole | None = Field(
+        default=None,
+        description="The role of the message in the conversation.",
+        examples=["system", "user", "assistant"],
+    )
+
+    @property
+    def image_content(self) -> list[dict[str, Any]] | None:
+        """
+        Return image content if present in the message.
+
+        Returns:
+            Optional[List[Dict[str, Any]]]: A list of image content
+                dictionaries, or None if no images are present.
+        """
+        msg_ = self.chat_msg
+        if isinstance(msg_, dict) and isinstance(msg_["content"], list):
+            return [i for i in msg_["content"] if i["type"] == "image_url"]
+        return None
+
+    @property
+    def chat_msg(self) -> dict[str, Any] | None:
+        """
+        Return message in chat representation format.
+
+        Returns:
+            Optional[Dict[str, Any]]: The message formatted for chat use,
+                or None if formatting fails.
+        """
+        try:
+            return self._format_content()
+        except Exception:
+            return None
+
+    @field_validator("role")
+    def _validate_role(cls, v: Any) -> MessageRole | None:
+
+        if v in [r.value for r in MessageRole]:
+            return MessageRole(v)
+        raise ValueError(f"Invalid message role: {v}")
+
+    def clone(self) -> "RoledMessage":
+        """
+        Creates a copy of the current RoledMessage object.
+
+        Creates a new instance with the same attributes as the current one,
+        but with a new identity. The original message is referenced in the
+        clone's metadata.
+
+        Returns:
+            RoledMessage: A new instance with copied attributes.
+        """
+        cls = self.__class__
+        signature = inspect.signature(cls.__init__)
+        param_num = len(signature.parameters) - 2
+
+        init_args = [MessageFlag.MESSAGE_CLONE] * param_num
+
+        obj = cls(*init_args)
+        obj.role = self.role
+        obj.content = self.content
+        obj.metadata.set("clone_from", self)
+
+        return obj
+
+    @override
+    @classmethod
+    def from_dict(cls, data: dict, /, **kwargs: Any) -> "RoledMessage":
+        """
+        Loads a RoledMessage object from a dictionary.
+
+        Creates a new instance from serialized data, handling both standard
+        fields and any extra fields that might be present.
+
+        Args:
+            data: The dictionary containing the message data
+            **kwargs: Additional keyword arguments to override data
+
+        Returns:
+            RoledMessage: An instance created from the dictionary
+        """
+        data = copy(data)
+        if kwargs:
+            data.update(kwargs)
+        if "lion_class" in data:
+            cls = get_class(data.pop("lion_class"))
+        signature = inspect.signature(cls.__init__)
+        param_num = len(signature.parameters) - 2
+
+        init_args = [MessageFlag.MESSAGE_LOAD] * param_num
+
+        extra_fields = {}
+        for k, v in list(data.items()):
+            if k not in cls.model_fields:
+                extra_fields[k] = data.pop(k)
+
+        obj = cls(*init_args, protected_init_params=data)
+
+        for k, v in extra_fields.items():
+            obj.add_field(name=k, value=v)
+
+        metadata = data.get("metadata", {})
+        last_updated = metadata.get("last_updated", None)
+        if last_updated is not None:
+            obj.metadata.set(["last_updated"], last_updated)
+        return obj
+
+    @override
+    def __str__(self) -> str:
+
+        content_preview = (
+            f"{str(self.content)[:75]}..."
+            if len(str(self.content)) > 75
+            else str(self.content)
+        )
+        return (
+            f"Message(role={self.role}, sender={self.sender}, "
+            f"content='{content_preview}')"
+        )
+
+    def to_log(self) -> Log:
+        """
+        Convert the message to a Log object.
+
+        Creates a Log instance containing the message content and additional
+        information as loginfo.
+
+        Returns:
+            Log: A Log object representing the message.
+        """
+        dict_ = self.to_dict()
+        content = dict_.pop("content")
+        _log = Log(
+            content=content,
+            loginfo=dict_,
+        )
+        return _log
+
+    @field_serializer("content")
+    def _serialize_content(self, value: Note) -> dict[str, Any]:
+
+        output_dict = copy(value.content, deep=True)
+        origin_obj = output_dict.pop("clone_from", None)
+
+        if origin_obj and isinstance(origin_obj, Communicatable):
+            info_dict = {
+                "clone_from_info": {
+                    "original_ln_id": origin_obj.ln_id,
+                    "original_timestamp": origin_obj.timestamp,
+                    "original_sender": origin_obj.sender,
+                    "original_recipient": origin_obj.recipient,
+                }
+            }
+            output_dict.update(info_dict)
+        return output_dict
+
+    @field_serializer("role")
+    def _serialize_role(self, value: MessageRole):
+        """
+        Serialize the role for storage or transmission.
+
+        Args:
+            value: The MessageRole to serialize
+
+        Returns:
+            str: The string value of the role
+        """
+        return value.value
+
+    def _format_content(self) -> dict[str, Any]:
+        """
+        Format the message content for chat representation.
+
+        Handles both text and image content appropriately.
+
+        Returns:
+            dict[str, Any]: The formatted content with role and content fields
+        """
+        if self.content.get("images", None):
+            content = self.content.to_dict()
+        else:
+            content = str(self.content.to_dict())
+        return {"role": self.role.value, "content": content}