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

lionagi/operations/communicate/communicate.py

@@ -1,18 +1,23 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
-import logging
-from typing import TYPE_CHECKING
+import warnings
+from typing import TYPE_CHECKING, Any, Literal
 
+from pydantic import JsonValue
+
+from lionagi.ln.fuzzy import FuzzyMatchKeysParams
 from lionagi.ln.fuzzy._fuzzy_validate import fuzzy_validate_mapping
-from lionagi.utils import UNDEFINED
+from lionagi.ln.types import Undefined
+
+from ..types import ChatParam, ParseParam
 
 if TYPE_CHECKING:
+    from lionagi.protocols.messages.instruction import Instruction
     from lionagi.session.branch import Branch
 
 
-async def communicate(
+def prepare_communicate_kw(
     branch: "Branch",
     instruction=None,
     *,
@@ -30,7 +35,7 @@ async def communicate(
     parse_model=None,
     skip_validation=False,
     images=None,
-    image_detail="auto",
+    image_detail: Literal["low", "high", "auto"] = "auto",
     num_parse_retries=3,
     fuzzy_match_kwargs=None,
     clear_messages=False,
@@ -38,88 +43,141 @@ async def communicate(
     include_token_usage_to_model: bool = False,
     **kwargs,
 ):
+    # Handle deprecated parameters
     if operative_model:
-        logging.warning(
-            "operative_model is deprecated. Use response_format instead."
+        warnings.warn(
+            "Parameter 'operative_model' is deprecated. Use 'response_format' instead.",
+            DeprecationWarning,
+            stacklevel=2,
         )
+
     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"
+            "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"
+        warnings.warn(
+            f"num_parse_retries={num_parse_retries} is high. Lowering to 5. Suggestion: <3",
+            UserWarning,
+            stacklevel=2,
         )
         num_parse_retries = 5
 
-    ins, res = await branch.chat(
-        instruction=instruction,
+    # Build contexts
+    chat_param = ChatParam(
         guidance=guidance,
         context=context,
-        sender=sender,
-        recipient=recipient,
+        sender=sender or branch.user or "user",
+        recipient=recipient or branch.id,
         response_format=response_format,
         progression=progression,
-        imodel=imodel,
-        images=images,
+        tool_schemas=[],
+        images=images or [],
         image_detail=image_detail,
-        plain_content=plain_content,
-        return_ins_res_message=True,
+        plain_content=plain_content or "",
         include_token_usage_to_model=include_token_usage_to_model,
-        **kwargs,
+        imodel=imodel,
+        imodel_kw=kwargs,
+    )
+
+    parse_param = None
+    if response_format and not skip_validation:
+        from ..parse.parse import get_default_call
+
+        fuzzy_kw = fuzzy_match_kwargs or {}
+        handle_validation = fuzzy_kw.pop("handle_validation", "raise")
+
+        parse_param = ParseParam(
+            response_format=response_format,
+            fuzzy_match_params=(
+                FuzzyMatchKeysParams(**fuzzy_kw)
+                if fuzzy_kw
+                else FuzzyMatchKeysParams()
+            ),
+            handle_validation=handle_validation,
+            alcall_params=get_default_call().with_updates(
+                retry_attempts=num_parse_retries
+            ),
+            imodel=parse_model,
+            imodel_kw={},
+        )
+
+    return {
+        "instruction": instruction or "",
+        "chat_param": chat_param,
+        "parse_param": parse_param,
+        "clear_messages": clear_messages,
+        "skip_validation": skip_validation,
+        "request_fields": request_fields,
+    }
+
+
+async def communicate(
+    branch: "Branch",
+    instruction: "JsonValue | Instruction",
+    chat_param: ChatParam,
+    parse_param: ParseParam | None = None,
+    clear_messages: bool = False,
+    skip_validation: bool = False,
+    request_fields: dict | None = None,
+) -> Any:
+    if clear_messages:
+        branch.msgs.clear_messages()
+
+    from ..chat.chat import chat
+
+    ins, res = await chat(
+        branch, instruction, chat_param, return_ins_res_message=True
     )
+
     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:
-        # Default to raising errors unless explicitly set in fuzzy_match_kwargs
-        parse_kwargs = {
-            "handle_validation": "raise",  # Default to raising errors
-            **(fuzzy_match_kwargs or {}),
-        }
+    # Handle response_format with parse
+    if parse_param and chat_param.response_format:
+        from lionagi.protocols.messages.assistant_response import (
+            AssistantResponse,
+        )
+
+        from ..parse.parse import parse
 
         try:
-            return await branch.parse(
-                text=res.response,
-                request_type=response_format,
-                max_retries=num_parse_retries,
-                **parse_kwargs,
+            out, res2 = await parse(
+                branch, res.response, parse_param, return_res_message=True
             )
+            if res2 and isinstance(res2, AssistantResponse):
+                res.metadata["original_model_response"] = res.model_response
+                # model_response is read-only property - update metadata instead
+                res.metadata["model_response"] = res2.model_response
+            return out
         except ValueError as e:
             # Re-raise with more context
-            logging.error(
-                f"Failed to parse response '{res.response}' into {response_format}: {e}"
-            )
             raise ValueError(
-                f"Failed to parse model response into {response_format.__name__}: {e}"
+                f"Failed to parse model response into {chat_param.response_format}: {e}"
             ) from e
 
+    # Handle request_fields with fuzzy validation
     if request_fields is not None:
         _d = fuzzy_validate_mapping(
             res.response,
             request_fields,
             handle_unmatched="force",
-            fill_value=UNDEFINED,
+            fill_value=Undefined,
         )
-        return {k: v for k, v in _d.items() if v != UNDEFINED}
+        return {k: v for k, v in _d.items() if v != Undefined}
 
     return res.response

lionagi/operations/flow.py

@@ -1,5 +1,4 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
 """
@@ -430,14 +429,14 @@ class DependencyAwareExecutor:
                     if hasattr(branch, "_message_manager") and hasattr(
                         primary_branch, "_message_manager"
                     ):
-                        branch._message_manager.pile.clear()
-                        for msg in primary_branch._message_manager.pile:
+                        branch._message_manager.messages.clear()
+                        for msg in primary_branch._message_manager.messages:
                             if hasattr(msg, "clone"):
-                                branch._message_manager.pile.append(
+                                branch._message_manager.messages.append(
                                     msg.clone()
                                 )
                             else:
-                                branch._message_manager.pile.append(msg)
+                                branch._message_manager.messages.append(msg)
 
                     # Clear the pending flag
                     branch.metadata["pending_context_inheritance"] = False

lionagi/operations/instruct/__init__.py

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

lionagi/operations/instruct/instruct.py

@@ -1,5 +1,4 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
 from typing import TYPE_CHECKING, Any

lionagi/operations/interpret/__init__.py

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

lionagi/operations/interpret/interpret.py

@@ -1,43 +1,87 @@
-# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
-#
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
 from typing import TYPE_CHECKING
 
+from ..types import ChatParam, InterpretParam
+
 if TYPE_CHECKING:
+    from lionagi.service.imodel import iModel
     from lionagi.session.branch import Branch
 
 
-async def interpret(
+def prepare_interpret_kw(
     branch: "Branch",
     text: str,
     domain: str | None = None,
     style: str | None = None,
     sample_writing: str | None = None,
-    interpret_model: str | None = None,
+    interpret_model: "iModel | None" = None,
     **kwargs,
 ) -> str:
+    """Interpret and refine user input into clearer prompts."""
+
+    # Build InterpretParam
+    intp_param = InterpretParam(
+        domain=domain or "general",
+        style=style or "concise",
+        sample_writing=sample_writing or "",
+        imodel=interpret_model or branch.chat_model,
+        imodel_kw=kwargs,
+    )
+    return {
+        "text": text,
+        "intp_param": intp_param,
+    }
+
+
+async def interpret(
+    branch: "Branch",
+    text: str,
+    intp_param: InterpretParam,
+) -> str:
+    """Execute interpretation with context - clean implementation."""
+
+    from ..chat.chat import chat
+
     instruction = (
-        "You are given a user's raw instruction or question. Your task is to rewrite it into a clearer,"
+        "You are given a user's raw instruction or question. Your task is to rewrite it into a clearer, "
         "more structured prompt for an LLM or system, making any implicit or missing details explicit. "
         "Return only the re-written prompt. Do not assume any details not mentioned in the input, nor "
         "give additional instruction than what is explicitly stated."
     )
-    guidance = f"Domain hint: {domain or 'general'}. Desired style: {style or 'concise'}. "
-    if sample_writing:
-        guidance += f" Sample writing: {sample_writing}"
-
-    context = [f"User input: {text}"]
-
-    # Default temperature if none provided
-    kwargs["guidance"] = guidance + "\n" + kwargs.get("guidance", "")
-    kwargs["instruction"] = instruction + "\n" + kwargs.get("instruction", "")
-    kwargs["temperature"] = kwargs.get("temperature", 0.1)
-    if interpret_model:
-        kwargs["chat_model"] = interpret_model
-
-    refined_prompt = await branch.chat(
-        context=context,
-        **kwargs,
+
+    guidance = (
+        f"Domain hint: {intp_param.domain}. Desired style: {intp_param.style}."
     )
-    return str(refined_prompt)
+    if intp_param.sample_writing:
+        guidance += f" Sample writing: {intp_param.sample_writing}"
+
+    # Build ChatParam
+    chat_param = ChatParam(
+        guidance=guidance,
+        context=[f"User input: {text}"],
+        sender=branch.user or "user",
+        recipient=branch.id,
+        response_format=None,
+        progression=None,
+        tool_schemas=[],
+        images=[],
+        image_detail="auto",
+        plain_content="",
+        include_token_usage_to_model=False,
+        imodel=intp_param.imodel,
+        imodel_kw={
+            **intp_param.imodel_kw,
+            "temperature": intp_param.imodel_kw.get("temperature", 0.1),
+        },
+    )
+
+    result = await chat(
+        branch,
+        instruction=instruction,
+        chat_param=chat_param,
+        return_ins_res_message=False,
+    )
+
+    return str(result)

lionagi/operations/operate/__init__.py

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