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

lionagi/operations/chat/chat.py

@@ -0,0 +1,173 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel
+
+from lionagi.protocols.types import (
+    ActionResponse,
+    AssistantResponse,
+    Instruction,
+    Log,
+    RoledMessage,
+)
+from lionagi.service.imodel import iModel
+from lionagi.utils import copy
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def chat(
+    branch: "Branch",
+    instruction=None,
+    guidance=None,
+    context=None,
+    sender=None,
+    recipient=None,
+    request_fields=None,
+    response_format: type[BaseModel] = None,
+    progression=None,
+    imodel: iModel = None,
+    tool_schemas=None,
+    images: list = None,
+    image_detail: Literal["low", "high", "auto"] = None,
+    plain_content: str = None,
+    return_ins_res_message: bool = False,
+    **kwargs,
+) -> tuple[Instruction, AssistantResponse]:
+    ins: Instruction = branch.msgs.create_instruction(
+        instruction=instruction,
+        guidance=guidance,
+        context=context,
+        sender=sender or branch.user or "user",
+        recipient=recipient or branch.id,
+        response_format=response_format,
+        request_fields=request_fields,
+        images=images,
+        image_detail=image_detail,
+        tool_schemas=tool_schemas,
+        plain_content=plain_content,
+    )
+
+    progression = progression or branch.msgs.progression
+    messages: list[RoledMessage] = [
+        branch.msgs.messages[i] for i in progression
+    ]
+
+    use_ins = None
+    _to_use = []
+    _action_responses: set[ActionResponse] = set()
+
+    for i in messages:
+        if isinstance(i, ActionResponse):
+            _action_responses.add(i)
+        if isinstance(i, AssistantResponse):
+            j = AssistantResponse(
+                role=i.role,
+                content=copy(i.content),
+                sender=i.sender,
+                recipient=i.recipient,
+                template=i.template,
+            )
+            _to_use.append(j)
+        if isinstance(i, Instruction):
+            j = Instruction(
+                role=i.role,
+                content=copy(i.content),
+                sender=i.sender,
+                recipient=i.recipient,
+                template=i.template,
+            )
+            j.tool_schemas = None
+            j.respond_schema_info = None
+            j.request_response_format = None
+
+            if _action_responses:
+                d_ = [k.content for k in _action_responses]
+                for z in d_:
+                    if z not in j.context:
+                        j.context.append(z)
+
+                _to_use.append(j)
+                _action_responses = set()
+            else:
+                _to_use.append(j)
+
+    messages = _to_use
+    if _action_responses:
+        j = ins.model_copy()
+        d_ = [k.content for k in _action_responses]
+        for z in d_:
+            if z not in j.context:
+                j.context.append(z)
+        use_ins = j
+
+    if messages and len(messages) > 1:
+        _msgs = [messages[0]]
+
+        for i in messages[1:]:
+            if isinstance(i, AssistantResponse):
+                if isinstance(_msgs[-1], AssistantResponse):
+                    _msgs[-1].response = (
+                        f"{_msgs[-1].response}\n\n{i.response}"
+                    )
+                else:
+                    _msgs.append(i)
+            else:
+                if isinstance(_msgs[-1], AssistantResponse):
+                    _msgs.append(i)
+        messages = _msgs
+
+    imodel = imodel or branch.chat_model
+    if branch.msgs.system and imodel.sequential_exchange:
+        messages = [msg for msg in messages if msg.role != "system"]
+        first_instruction = None
+
+        if len(messages) == 0:
+            first_instruction = ins.model_copy()
+            first_instruction.guidance = branch.msgs.system.rendered + (
+                first_instruction.guidance or ""
+            )
+            messages.append(first_instruction)
+        elif len(messages) >= 1:
+            first_instruction = messages[0]
+            if not isinstance(first_instruction, Instruction):
+                raise ValueError(
+                    "First message in progression must be an Instruction or System"
+                )
+            first_instruction = first_instruction.model_copy()
+            first_instruction.guidance = branch.msgs.system.rendered + (
+                first_instruction.guidance or ""
+            )
+            messages[0] = first_instruction
+            messages.append(use_ins or ins)
+
+    else:
+        messages.append(use_ins or ins)
+
+    kwargs["messages"] = [i.chat_msg for i in messages]
+    imodel = imodel or branch.chat_model
+
+    api_call = None
+    if kwargs.get("stream", None) is True:
+        api_call = await imodel.stream(**kwargs)
+    else:
+        api_call = await imodel.invoke(**kwargs)
+
+    branch._log_manager.log(Log.create(api_call))
+
+    if return_ins_res_message:
+        # Wrap result in `AssistantResponse` and return
+        return ins, AssistantResponse.create(
+            assistant_response=api_call.response,
+            sender=branch.id,
+            recipient=branch.user,
+        )
+    return AssistantResponse.create(
+        assistant_response=api_call.response,
+        sender=branch.id,
+        recipient=branch.user,
+    ).response

lionagi/operations/communicate/communicate.py

@@ -0,0 +1,167 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+from typing import TYPE_CHECKING
+
+from lionagi.libs.validate.fuzzy_validate_mapping import fuzzy_validate_mapping
+from lionagi.utils import UNDEFINED
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def communicate(
+    branch: "Branch",
+    instruction=None,
+    *,
+    guidance=None,
+    context=None,
+    plain_content=None,
+    sender=None,
+    recipient=None,
+    progression=None,
+    request_model=None,
+    response_format=None,
+    request_fields=None,
+    imodel=None,
+    chat_model=None,
+    parse_model=None,
+    skip_validation=False,
+    images=None,
+    image_detail="auto",
+    num_parse_retries=3,
+    fuzzy_match_kwargs=None,
+    clear_messages=False,
+    operative_model=None,
+    **kwargs,
+):
+    """
+    A simpler orchestration than `operate()`, typically without tool invocation.
+
+    **Flow**:
+        1. Sends an instruction (or conversation) to the chat model.
+        2. Optionally parses the response into a structured model or fields.
+        3. Returns either the raw string, the parsed model, or a dict of fields.
+
+    Args:
+        instruction (Instruction | dict, optional):
+            The user's main query or data.
+        guidance (JsonValue, optional):
+            Additional instructions or context for the LLM.
+        context (JsonValue, optional):
+            Extra data or context.
+        plain_content (str, optional):
+            Plain text content appended to the instruction.
+        sender (SenderRecipient, optional):
+            Sender ID (defaults to `Branch.user`).
+        recipient (SenderRecipient, optional):
+            Recipient ID (defaults to `self.id`).
+        progression (ID.IDSeq, optional):
+            Custom ordering of messages.
+        request_model (type[BaseModel] | BaseModel | None, optional):
+            Model for validating or structuring the LLM's response.
+        response_format (type[BaseModel], optional):
+            Alias for `request_model`. If both are provided, raises ValueError.
+        request_fields (dict|list[str], optional):
+            If you only need certain fields from the LLM's response.
+        imodel (iModel, optional):
+            Deprecated alias for `chat_model`.
+        chat_model (iModel, optional):
+            An alternative to the default chat model.
+        parse_model (iModel, optional):
+            If parsing is needed, you can override the default parse model.
+        skip_validation (bool, optional):
+            If True, returns the raw response string unvalidated.
+        images (list, optional):
+            Any relevant images.
+        image_detail (Literal["low","high","auto"], optional):
+            Image detail level (if used).
+        num_parse_retries (int, optional):
+            Maximum parsing retries (capped at 5).
+        fuzzy_match_kwargs (dict, optional):
+            Additional settings for fuzzy field matching (if used).
+        clear_messages (bool, optional):
+            Whether to clear stored messages before sending.
+        operative_model (type[BaseModel], optional):
+            Deprecated, alias for `response_format`.
+        **kwargs:
+            Additional arguments for the underlying LLM call.
+
+    Returns:
+        Any:
+            - Raw string (if `skip_validation=True`),
+            - A validated Pydantic model,
+            - A dict of the requested fields,
+            - or `None` if parsing fails and `handle_validation='return_none'`.
+    """
+    if operative_model:
+        logging.warning(
+            "operative_model is deprecated. Use response_format instead."
+        )
+    if (
+        (operative_model and response_format)
+        or (operative_model and request_model)
+        or (response_format and request_model)
+    ):
+        raise ValueError(
+            "Cannot specify both operative_model and response_format"
+            "or operative_model and request_model as they are aliases"
+            "for the same parameter."
+        )
+
+    response_format = response_format or operative_model or request_model
+
+    imodel = imodel or chat_model or branch.chat_model
+    parse_model = parse_model or branch.parse_model
+
+    if clear_messages:
+        branch.msgs.clear_messages()
+
+    if num_parse_retries > 5:
+        logging.warning(
+            f"Are you sure you want to retry {num_parse_retries} "
+            "times? lowering retry attempts to 5. Suggestion is under 3"
+        )
+        num_parse_retries = 5
+
+    ins, res = await branch.chat(
+        instruction=instruction,
+        guidance=guidance,
+        context=context,
+        sender=sender,
+        recipient=recipient,
+        response_format=response_format,
+        progression=progression,
+        imodel=imodel,
+        images=images,
+        image_detail=image_detail,
+        plain_content=plain_content,
+        return_ins_res_message=True,
+        **kwargs,
+    )
+    branch.msgs.add_message(instruction=ins)
+    branch.msgs.add_message(assistant_response=res)
+
+    if skip_validation:
+        return res.response
+
+    if response_format is not None:
+        return await branch.parse(
+            text=res.response,
+            request_type=response_format,
+            max_retries=num_parse_retries,
+            **(fuzzy_match_kwargs or {}),
+        )
+
+    if request_fields is not None:
+        _d = fuzzy_validate_mapping(
+            res.response,
+            request_fields,
+            handle_unmatched="force",
+            fill_value=UNDEFINED,
+        )
+        return {k: v for k, v in _d.items() if v != UNDEFINED}
+
+    return res.response

lionagi/operations/instruct/__init__.py

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

lionagi/operations/instruct/instruct.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any
+
+from lionagi.operatives.types import Instruct
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def instruct(
+    branch: "Branch",
+    instruct: Instruct,
+    /,
+    **kwargs,
+) -> Any:
+    config = {
+        **(instruct.to_dict() if isinstance(instruct, Instruct) else instruct),
+        **kwargs,
+    }
+    if any(i in config and config[i] for i in Instruct.reserved_kwargs):
+        if "response_format" in config or "request_model" in config:
+            return await branch.operate(**config)
+        for i in Instruct.reserved_kwargs:
+            config.pop(i, None)
+
+    return await branch.communicate(**config)

lionagi/operations/interpret/__init__.py

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

lionagi/operations/interpret/interpret.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def interpret(
+    branch: "Branch",
+    text: str,
+    domain: str | None = None,
+    style: str | None = None,
+    **kwargs,
+) -> str:
+    instruction = (
+        "Rewrite the following user input into a clear, structured prompt or "
+        "query for an LLM, ensuring any implicit details are made explicit. "
+        "Return only the improved user prompt."
+    )
+    guidance = (
+        f"Domain hint: {domain or 'general'}. "
+        f"Desired style: {style or 'concise'}. "
+        "You can add or clarify context if needed."
+    )
+    context = [f"User input: {text}"]
+
+    # Default temperature if none provided
+    kwargs["temperature"] = kwargs.get("temperature", 0.1)
+
+    refined_prompt = await branch.communicate(
+        instruction=instruction,
+        guidance=guidance,
+        context=context,
+        skip_validation=True,
+        **kwargs,
+    )
+    return str(refined_prompt)

lionagi/operations/operate/__init__.py

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

lionagi/operations/operate/operate.py

@@ -0,0 +1,189 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel, JsonValue
+
+from lionagi.operatives.models.field_model import FieldModel
+from lionagi.operatives.models.model_params import ModelParams
+from lionagi.operatives.types import Instruct, Operative, Step, ToolRef
+from lionagi.protocols.types import Instruction, Progression, SenderRecipient
+from lionagi.service.imodel import iModel
+
+if TYPE_CHECKING:
+    from lionagi.session.branch import Branch
+
+
+async def operate(
+    branch: "Branch",
+    *,
+    instruct: Instruct = None,
+    instruction: Instruction | JsonValue = None,
+    guidance: JsonValue = None,
+    context: JsonValue = None,
+    sender: SenderRecipient = None,
+    recipient: SenderRecipient = None,
+    progression: Progression = None,
+    imodel: iModel = None,  # deprecated, alias of chat_model
+    chat_model: iModel = None,
+    invoke_actions: bool = True,
+    tool_schemas: list[dict] = None,
+    images: list = None,
+    image_detail: Literal["low", "high", "auto"] = None,
+    parse_model: iModel = None,
+    skip_validation: bool = False,
+    tools: ToolRef = None,
+    operative: Operative = None,
+    response_format: type[BaseModel] = None,  # alias of operative.request_type
+    return_operative: bool = False,
+    actions: bool = False,
+    reason: bool = False,
+    action_kwargs: dict = None,
+    field_models: list[FieldModel] = None,
+    exclude_fields: list | dict | None = None,
+    request_params: ModelParams = None,
+    request_param_kwargs: dict = None,
+    response_params: ModelParams = None,
+    response_param_kwargs: dict = None,
+    handle_validation: Literal[
+        "raise", "return_value", "return_none"
+    ] = "return_value",
+    operative_model: type[BaseModel] = None,
+    request_model: type[BaseModel] = None,
+    **kwargs,
+) -> list | BaseModel | None | dict | str:
+    if operative_model:
+        logging.warning(
+            "`operative_model` is deprecated. Use `response_format` instead."
+        )
+    if (
+        (operative_model and response_format)
+        or (operative_model and request_model)
+        or (response_format and request_model)
+    ):
+        raise ValueError(
+            "Cannot specify both `operative_model` and `response_format` (or `request_model`) "
+            "as they are aliases of each other."
+        )
+
+    # Use the final chosen format
+    response_format = response_format or operative_model or request_model
+
+    # Decide which chat model to use
+    chat_model = chat_model or imodel or branch.chat_model
+    parse_model = parse_model or chat_model
+
+    # Convert dict-based instructions to Instruct if needed
+    if isinstance(instruct, dict):
+        instruct = Instruct(**instruct)
+
+    # Or create a new Instruct if not provided
+    instruct = instruct or Instruct(
+        instruction=instruction,
+        guidance=guidance,
+        context=context,
+    )
+
+    # If reason or actions are requested, apply them to instruct
+    if reason:
+        instruct.reason = True
+    if actions:
+        instruct.actions = True
+
+    # 1) Create or update the Operative
+    operative = Step.request_operative(
+        request_params=request_params,
+        reason=instruct.reason,
+        actions=instruct.actions,
+        exclude_fields=exclude_fields,
+        base_type=response_format,
+        field_models=field_models,
+        **(request_param_kwargs or {}),
+    )
+
+    # If the instruction signals actions, ensure tools are provided
+    if instruct.actions:
+        tools = tools or True
+
+    # If we want to auto-invoke tools, fetch or generate the schemas
+    if invoke_actions and tools:
+        tool_schemas = branch.acts.get_tool_schema(tools=tools)
+
+    # 2) Send the instruction to the chat model
+    ins, res = await branch.chat(
+        instruction=instruct.instruction,
+        guidance=instruct.guidance,
+        context=instruct.context,
+        sender=sender,
+        recipient=recipient,
+        response_format=operative.request_type,
+        progression=progression,
+        imodel=chat_model,  # or the override
+        images=images,
+        image_detail=image_detail,
+        tool_schemas=tool_schemas,
+        return_ins_res_message=True,
+        **kwargs,
+    )
+    branch.msgs.add_message(instruction=ins)
+    branch.msgs.add_message(assistant_response=res)
+
+    # 3) Populate the operative with the raw response
+    operative.response_str_dict = res.response
+
+    # 4) Possibly skip validation
+    if skip_validation:
+        return operative if return_operative else operative.response_str_dict
+
+    # 5) Parse or validate the response into the operative’s model
+    response_model = operative.update_response_model(res.response)
+    if not isinstance(response_model, BaseModel):
+        # If the response isn't directly a model, attempt a parse
+        response_model = await branch.parse(
+            text=res.response,
+            request_type=operative.request_type,
+            max_retries=operative.max_retries,
+            handle_validation="return_value",
+        )
+        operative.response_model = operative.update_response_model(
+            text=response_model
+        )
+
+    # If we still fail to parse, handle according to user preference
+    if not isinstance(response_model, BaseModel):
+        match handle_validation:
+            case "return_value":
+                return response_model
+            case "return_none":
+                return None
+            case "raise":
+                raise ValueError(
+                    "Failed to parse the LLM response into the requested format."
+                )
+
+    # 6) If no tool invocation is needed, return result or operative
+    if not invoke_actions:
+        return operative if return_operative else operative.response_model
+
+    # 7) If the model indicates an action is required, call the tools
+    if (
+        getattr(response_model, "action_required", None) is True
+        and getattr(response_model, "action_requests", None) is not None
+    ):
+        action_response_models = await branch.act(
+            response_model.action_requests,
+            **(action_kwargs or {}),
+        )
+        # Possibly refine the operative with the tool outputs
+        operative = Step.respond_operative(
+            response_params=response_params,
+            operative=operative,
+            additional_data={"action_responses": action_response_models},
+            **(response_param_kwargs or {}),
+        )
+
+    # Return final result or the full operative
+    return operative if return_operative else operative.response_model

lionagi/operations/parse/__init__.py

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