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

lionagi/core/communication/templates/instruction_message.jinja2

@@ -0,0 +1,61 @@
+{%- set content = [] -%}
+
+{# If plain_content is provided, we use it directly. Otherwise, we build a text block from guidance, instruction, context, etc. #}
+{% if plain_content %}
+{% set content = content + [{"type": "text", "text": plain_content}] %}
+{% else %}
+{# Build a text block from the available sections #}
+{% set text_block = "" %}
+
+{% if guidance %}
+## Guidance
+{{ guidance }}
+
+{% endif %}
+
+{% if instruction %}
+## Instruction
+{{ instruction }}
+
+{% endif %}
+
+{% if context %}
+## Context
+{% for item in context %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+{% if tool_schemas %}
+## Tool Schemas
+{% include "tool_schemas.jinja2" %}
+{% endif %}
+
+{% if request_fields %}
+## Requested Fields
+Please return a JSON object with the following fields:
+```json
+{{ request_fields | tojson(indent=2) }}
+
+{% endif %}
+
+{% if request_response_format %}
+
+Response Format
+
+{{ request_response_format }}
+{% endif %}
+
+{# Append the built sections into text_block #}
+{% set text_block = text_block + self %}
+{% set content = content + [{“type”: “text”, “text”: text_block.strip()}] %}
+{% endif %}
+
+{# If images are present, we append image_url items to content #}
+{% if images %}
+{% for img in images %}
+{% set content = content + [{“type”: “image_url”, “image_url”: {“url”: “data:image/jpeg;base64,” ~ img, “detail”: image_detail}}] %}
+{% endfor %}
+{% endif %}
+
+{{ content | tojson(indent=2) }}

lionagi/core/communication/templates/system_message.jinja2

@@ -0,0 +1,11 @@
+{{ system_message }}
+{% if system_datetime %}
+System datetime: {{ system_datetime }}
+{% endif %}
+
+{% if additional_context %}
+Additional Context:
+{% for c in additional_context %}
+- {{ c }}
+{% endfor %}
+{% endif %}

lionagi/core/communication/templates/tool_schemas.jinja2

@@ -0,0 +1,7 @@
+{% for name, schema in tool_schemas.items() %}
+Tool: {{ name }}
+Schema:
+```json
+{{ schema | tojson(indent=2) }}
+
+{% endfor %}

lionagi/core/communication/types.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .action_request import ActionRequest
+from .action_response import ActionResponse
+from .assistant_response import AssistantResponse
+from .base_mail import BaseMail
+from .instruction import Instruction
+from .message import MESSAGE_FIELDS, MessageRole, RoledMessage
+from .message_manager import MessageManager
+from .system import System
+from .utils import validate_sender_recipient
+
+__all__ = [
+    "ActionRequest",
+    "ActionResponse",
+    "AssistantResponse",
+    "BaseMail",
+    "Instruction",
+    "MESSAGE_FIELDS",
+    "MessageRole",
+    "RoledMessage",
+    "MessageManager",
+    "System",
+    "validate_sender_recipient",
+]

lionagi/core/communication/utils.py

@@ -0,0 +1,254 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.typing import (
+    ID,
+    UNDEFINED,
+    Any,
+    BaseModel,
+    IDError,
+    Literal,
+    LnID,
+    Note,
+)
+from lionagi.integrations.pydantic_ import break_down_pydantic_annotation
+from lionagi.libs.utils import time
+
+DEFAULT_SYSTEM = "You are a helpful AI assistant. Let's think step by step."
+
+
+def format_system_content(
+    system_datetime: bool | str | None,
+    system_message: str,
+) -> Note:
+    """
+    Format system message content with optional datetime information.
+
+    Args:
+        system_datetime: Flag or string for datetime inclusion
+        system_message: The system message content
+
+    Returns:
+        Note: Formatted system content
+    """
+    content = Note(system=str(system_message or DEFAULT_SYSTEM))
+    if system_datetime:
+        if isinstance(system_datetime, str):
+            content["system_datetime"] = system_datetime
+        else:
+            content["system_datetime"] = time(type_="iso", timespec="minutes")
+    return content
+
+
+def prepare_request_response_format(request_fields: dict) -> str:
+    """
+    Prepare a standardized format for request responses.
+
+    Args:
+        request_fields: Dictionary of fields to include in response
+
+    Returns:
+        str: Formatted response template
+    """
+    return (
+        "**MUST RETURN JSON-PARSEABLE RESPONSE ENCLOSED BY JSON CODE BLO"
+        f"CKS.** \n```json\n{request_fields}\n```"
+    ).strip()
+
+
+def format_image_item(idx: str, x: str, /) -> dict[str, Any]:
+    """
+    Create an image_url dictionary for content formatting.
+
+    Args:
+        idx: Base64 encoded image data
+        x: Image detail level
+
+    Returns:
+        dict: Formatted image item
+    """
+    return {
+        "type": "image_url",
+        "image_url": {
+            "url": f"data:image/jpeg;base64,{idx}",
+            "detail": x,
+        },
+    }
+
+
+def format_text_item(item: Any) -> str:
+    """
+    Format a text item or list of items into a string.
+
+    Args:
+        item: Text item(s) to format
+
+    Returns:
+        str: Formatted text
+    """
+    msg = ""
+    item = [item] if not isinstance(item, list) else item
+    for j in item:
+        if isinstance(j, dict):
+            for k, v in j.items():
+                msg += f"- {k}: {v} \n\n"
+        else:
+            msg += f"{j}\n"
+    return msg
+
+
+def format_text_content(content: dict) -> str:
+    """
+    Format dictionary content into a structured text format.
+
+    Args:
+        content: Dictionary containing content sections
+
+    Returns:
+        str: Formatted text content
+    """
+    if "plain_content" in content and isinstance(
+        content["plain_content"], str
+    ):
+        return content["plain_content"]
+
+    msg = "\n---\n # Task\n"
+    for k, v in content.items():
+        if k in [
+            "guidance",
+            "instruction",
+            "context",
+            "request_response_format",
+            "tool_schemas",
+        ]:
+            if k == "request_response_format":
+                k = "response format"
+            msg += f"## **Task {k}**\n{format_text_item(v)}\n\n"
+    msg += "\n\n---\n"
+    return msg
+
+
+def format_image_content(
+    text_content: str,
+    images: list,
+    image_detail: Literal["low", "high", "auto"],
+) -> dict[str, Any]:
+    """
+    Format text content with images for message content.
+
+    Args:
+        text_content: The text content to format
+        images: List of images to include
+        image_detail: Level of detail for images
+
+    Returns:
+        dict: Formatted content with text and images
+    """
+    content = [{"type": "text", "text": text_content}]
+    content.extend(format_image_item(i, image_detail) for i in images)
+    return content
+
+
+def prepare_instruction_content(
+    guidance: str | None = None,
+    instruction: str | None = None,
+    context: str | dict | list | None = None,
+    request_fields: dict | list[str] | None = None,
+    plain_content: str | None = None,
+    request_model: BaseModel = None,
+    images: str | list | None = None,
+    image_detail: Literal["low", "high", "auto"] | None = None,
+    tool_schemas: dict | None = None,
+) -> Note:
+    """
+    Prepare the content for an instruction message.
+
+    Args:
+        guidance: Optional guidance text
+        instruction: Main instruction content
+        context: Additional context information
+        request_fields: Fields to request in response
+        plain_content: Plain text content
+        request_model: Pydantic model for structured requests
+        images: Images to include
+        image_detail: Level of detail for images
+        tool_schemas: Tool schemas to include
+
+    Returns:
+        Note: Prepared instruction content
+
+    Raises:
+        ValueError: If both request_fields and request_model are provided
+    """
+    if request_fields and request_model:
+        raise ValueError(
+            "only one of request_fields or request_model can be provided"
+        )
+
+    out_ = {"context": []}
+    if guidance:
+        out_["guidance"] = guidance
+    if instruction:
+        out_["instruction"] = instruction
+    if context:
+        if isinstance(context, list):
+            out_["context"].extend(context)
+        else:
+            out_["context"].append(context)
+    if images:
+        out_["images"] = images if isinstance(images, list) else [images]
+        out_["image_detail"] = image_detail or "low"
+
+    if tool_schemas:
+        out_["tool_schemas"] = tool_schemas
+
+    if request_model:
+        out_["request_model"] = request_model
+        request_fields = break_down_pydantic_annotation(request_model)
+        out_["context"].append(
+            {"respond_schema_info": request_model.model_json_schema()}
+        )
+
+    if request_fields:
+        _fields = request_fields if isinstance(request_fields, dict) else {}
+        if not isinstance(request_fields, dict):
+            _fields = {i: "..." for i in request_fields}
+        out_["request_fields"] = _fields
+        out_["request_response_format"] = prepare_request_response_format(
+            request_fields=_fields
+        )
+
+    if plain_content:
+        out_["plain_content"] = plain_content
+
+    return Note(
+        **{k: v for k, v in out_.items() if v not in [None, UNDEFINED]},
+    )
+
+
+def validate_sender_recipient(
+    value: Any, /
+) -> LnID | Literal["system", "user", "N/A", "assistant"]:
+    """
+    Validate sender and recipient fields for mail-like communication.
+
+    Args:
+        value: The value to validate
+
+    Returns:
+        Union[LnID, Literal]: Valid sender/recipient value
+
+    Raises:
+        ValueError: If value is not a valid sender or recipient
+    """
+    if value in ["system", "user", "N/A", "assistant"]:
+        return value
+
+    if value is None:
+        return "N/A"
+
+    try:
+        return ID.get_id(value)
+    except IDError as e:
+        raise ValueError("Invalid sender or recipient") from e

lionagi/core/forms/__init__.py

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

lionagi/core/forms/base.py

@@ -0,0 +1,232 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from pydantic import field_validator
+
+from ..generic.types import Component
+from ..typing import UNDEFINED, Any, Field, Literal, PydanticUndefined
+
+
+class BaseForm(Component):
+    """Base form class providing core functionality for form handling.
+
+    This class serves as a foundation for creating custom forms within the
+    lion-core library. It includes methods for managing output fields,
+    handling results, and applying field annotations.
+
+    The BaseForm class focuses on output fields, which are fields that are
+    presented as the result of form processing. Output fields can include all,
+    part, or none of the request fields and can be conditionally modified by
+    the process if the form is not set to be strict.
+
+    Attributes:
+        assignment: The objective of the task, which may define how input
+            fields are processed into output fields.
+        template_name: The name of the form template.
+        output_fields: A list of field names that are outputted and presented
+            by the form.
+        none_as_valid_value: Indicates whether to treat None as a valid value
+            when processing output fields.
+        has_processed: Indicates if the task has been processed.
+
+    Example:
+        >>> form = BaseForm(
+        ...     assignment="input1, input2 -> output",
+        ...     output_fields=["output1", "output2"],
+        ... )
+        >>> result = form.get_results()
+        >>> print(result)
+    """
+
+    assignment: str | None = Field(
+        default=None,
+        description="The objective of the task.",
+        examples=["input1, input2 -> output"],
+    )
+    template_name: str = Field(
+        default="default_form", description="Name of the form template"
+    )
+    output_fields: list[str] = Field(
+        default_factory=list,
+        description="Fields that are outputted and presented by the form.",
+    )
+    none_as_valid_value: bool = Field(
+        default=False,
+        description="Indicate whether to treat None as a valid value.",
+    )
+    has_processed: bool = Field(
+        default=False,
+        description="Indicates if the task has been processed.",
+        exclude=True,
+    )
+
+    def check_is_completed(
+        self,
+        handle_how: Literal["raise", "return_missing"] = "raise",
+    ) -> list[str] | None:
+        """Check if all required fields are completed.
+
+        Args:
+            handle_how: How to handle incomplete fields.
+
+        Returns:
+            List of incomplete fields if handle_how is "return_missing",
+            None otherwise.
+
+        Raises:
+            ValueError: If required fields are incomplete and handle_how
+                is "raise".
+        """
+        non_complete_request = []
+        invalid_values = [UNDEFINED, PydanticUndefined]
+        if not self.none_as_valid_value:
+            invalid_values.append(None)
+
+        for i in self.required_fields:
+            if getattr(self, i) in invalid_values:
+                non_complete_request.append(i)
+
+        if non_complete_request:
+            if handle_how == "raise":
+                raise ValueError(
+                    f"Incomplete request fields: {non_complete_request}"
+                )
+            elif handle_how == "return_missing":
+                return non_complete_request
+        else:
+            self.has_processed = True
+
+    def is_completed(self) -> bool:
+        """Check if the form is completed.
+
+        Returns:
+            True if the form is completed, False otherwise.
+        """
+        try:
+            self.check_is_completed(handle_how="raise")
+            return True
+        except Exception:
+            return False
+
+    @field_validator("output_fields", mode="before")
+    @classmethod
+    def _validate_output(cls, value):
+        """Validate the output_fields attribute.
+
+        Args:
+            value: The value to validate.
+
+        Returns:
+            The validated value.
+
+        Raises:
+            LionValueError: If the value is invalid.
+        """
+        if isinstance(value, str):
+            return [value]
+        if isinstance(value, list) and all(
+            [i for i in value if isinstance(i, str)],
+        ):
+            return value
+        if not value:
+            return []
+        raise ValueError("Invalid output fields.")
+
+    @property
+    def work_fields(self) -> list[str]:
+        """Get the list of fields that are outputted by the form.
+
+        Returns:
+            A list of field names.
+        """
+        return self.output_fields
+
+    @property
+    def work_dict(self) -> dict[str, Any]:
+        """Get a dictionary of all work fields and their values.
+
+        Returns:
+            A dictionary of field names and their values.
+        """
+        return {i: getattr(self, i, UNDEFINED) for i in self.work_fields}
+
+    @property
+    def required_fields(self) -> list[str]:
+        """Get the list of required fields for the form.
+
+        Returns:
+            A list of required field names.
+        """
+        return self.output_fields
+
+    @property
+    def required_dict(self) -> dict[str, Any]:
+        """Get a dictionary of all required fields and their values.
+
+        Returns:
+            A dictionary of required field names and their values.
+        """
+        dict_ = {}
+        for i in self.required_fields:
+            dict_[i] = getattr(self, i, UNDEFINED)
+
+        return dict_
+
+    def get_results(
+        self,
+        suppress: bool = False,
+        valid_only: bool = False,
+    ) -> dict[str, Any]:
+        """Retrieve the results of the form.
+
+        Args:
+            suppress: If True, suppress errors for missing fields.
+            valid_only: If True, return only valid (non-empty) results.
+
+        Returns:
+            A dictionary of field names and their values.
+
+        Raises:
+            ValueError: If a required field is missing and suppress is False.
+        """
+        result = {}
+        out_fields = self.output_fields or getattr(self, "request_fields", [])
+
+        for i in out_fields:
+            if i not in self.all_fields:
+                if not suppress:
+                    raise ValueError(f"Missing field: {i}")
+            else:
+                result[i] = getattr(self, i, UNDEFINED)
+
+        # add a validator for output fields
+
+        if valid_only:
+            invalid_values = [
+                UNDEFINED,
+                PydanticUndefined,
+            ]
+            if not self.none_as_valid_value:
+                invalid_values.append(None)
+
+            res_ = {}
+            for k, v in result.items():
+                if v not in invalid_values:
+                    res_[k] = v
+            result = res_
+
+        return result
+
+    @property
+    def display_dict(self) -> dict[str, Any]:
+        """
+        Get a dictionary of the required fields and their values for display.
+
+        Returns:
+            A dictionary of required field names and their values.
+        """
+        return self.required_dict
+
+
+__all__ = ["BaseForm"]