lionagi 0.17.11__py3-none-any.whl → 0.18.1__py3-none-any.whl

lionagi/operations/interpret/interpret.py

@@ -3,40 +3,85 @@
 
 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/node.py

@@ -6,7 +6,7 @@ from uuid import UUID
 from anyio import get_cancelled_exc_class
 from pydantic import BaseModel, Field
 
-from lionagi.protocols.types import ID, Event, EventStatus, IDType, Node
+from lionagi.protocols.types import ID, Event, EventStatus, Node
 
 if TYPE_CHECKING:
     from lionagi.session.branch import Branch
@@ -37,12 +37,12 @@ class Operation(Node, Event):
     )
 
     @property
-    def branch_id(self) -> IDType | None:
+    def branch_id(self) -> UUID | None:
         if a := self.metadata.get("branch_id"):
             return ID.get_id(a)
 
     @branch_id.setter
-    def branch_id(self, value: str | UUID | IDType | None):
+    def branch_id(self, value: str | UUID | None):
         if value is None:
             self.metadata.pop("branch_id", None)
         else:
@@ -54,7 +54,7 @@ class Operation(Node, Event):
             return ID.get_id(a)
 
     @graph_id.setter
-    def graph_id(self, value: str | UUID | IDType | None):
+    def graph_id(self, value: str | UUID | None):
         if value is None:
             self.metadata.pop("graph_id", None)
         else:

lionagi/operations/operate/operate.py

@@ -1,46 +1,28 @@
 # Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
-import logging
+import warnings
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, JsonValue
 
-from lionagi.fields.instruct import Instruct
+from lionagi.ln import AlcallParams
+from lionagi.ln.fuzzy import FuzzyMatchKeysParams
 from lionagi.models import FieldModel, ModelParams
-from lionagi.protocols.operatives.step import Operative, Step
-from lionagi.protocols.types import Instruction, Progression, SenderRecipient
-from lionagi.service.imodel import iModel
-from lionagi.session.branch import AlcallParams
+from lionagi.protocols.generic import Progression
+from lionagi.protocols.messages import Instruction, SenderRecipient
+
+from ..fields import Instruct
+from ..types import ActionParam, ChatParam, HandleValidation, ParseParam
 
 if TYPE_CHECKING:
+    from lionagi.service.imodel import iModel
     from lionagi.session.branch import Branch, ToolRef
 
-
-def _handle_response_format_kwargs(
-    operative_model: type[BaseModel] = None,
-    request_model: type[BaseModel] = None,
-    response_format: type[BaseModel] = 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 `request_model`) "
-            "as they are aliases of each other."
-        )
-
-    # Use the final chosen format
-    return response_format or operative_model or request_model
+    from .operative import Operative
 
 
-async def operate(
+def prepare_operate_kw(
     branch: "Branch",
     *,
     instruct: Instruct = None,
@@ -50,18 +32,17 @@ async def operate(
     sender: SenderRecipient = None,
     recipient: SenderRecipient = None,
     progression: Progression = None,
-    imodel: iModel = None,  # deprecated, alias of chat_model
-    chat_model: iModel = 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,
+    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,
     call_params: AlcallParams = None,
@@ -71,21 +52,38 @@ async def operate(
     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",
+    handle_validation: HandleValidation = "return_value",
     operative_model: type[BaseModel] = None,
     request_model: type[BaseModel] = None,
     include_token_usage_to_model: bool = False,
+    clear_messages: bool = False,
     **kwargs,
 ) -> list | BaseModel | None | dict | str:
-    response_format = _handle_response_format_kwargs(
-        operative_model, request_model, response_format
-    )
+    # Handle deprecated parameters
+    if operative_model:
+        warnings.warn(
+            "Parameter 'operative_model' is deprecated. Use 'response_format' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    if imodel:
+        warnings.warn(
+            "Parameter 'imodel' is deprecated. Use 'chat_model' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
-    # Decide which chat model to use
+    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."
+        )
+
+    response_format = response_format or operative_model or request_model
     chat_model = chat_model or imodel or branch.chat_model
     parse_model = parse_model or chat_model
 
@@ -108,103 +106,213 @@ async def operate(
         if action_strategy:
             instruct.action_strategy = action_strategy
 
-    # 1) Create or update the Operative
+    # Build the Operative - always create it for backwards compatibility
+    from .step import Step
+
     operative = Step.request_operative(
         request_params=request_params,
         reason=instruct.reason,
-        actions=instruct.actions,
+        actions=instruct.actions or actions,
         exclude_fields=exclude_fields,
         base_type=response_format,
         field_models=field_models,
         **(request_param_kwargs or {}),
     )
+    # Use the operative's request_type which is a proper Pydantic model
+    # created from field_models if provided
+    final_response_format = operative.request_type
 
-    # 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 = tool_schemas or branch.acts.get_tool_schema(tools=tools)
-
-    # 2) Send the instruction to the chat model
-    ins, res = await branch.chat(
-        instruction=instruct.instruction,
+    # Build contexts
+    chat_param = ChatParam(
         guidance=instruct.guidance,
         context=instruct.context,
-        sender=sender,
-        recipient=recipient,
-        response_format=operative.request_type,
+        sender=sender or branch.user or "user",
+        recipient=recipient or branch.id,
+        response_format=final_response_format,
         progression=progression,
-        imodel=chat_model,  # or the override
+        tool_schemas=tool_schemas,
         images=images,
         image_detail=image_detail,
-        tool_schemas=tool_schemas,
-        return_ins_res_message=True,
+        plain_content=None,
         include_token_usage_to_model=include_token_usage_to_model,
-        **kwargs,
+        imodel=chat_model,
+        imodel_kw=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
+    parse_param = None
+    if final_response_format and not skip_validation:
+        from ..parse.parse import get_default_call
 
-    # 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,
+        parse_param = ParseParam(
+            response_format=final_response_format,
+            fuzzy_match_params=FuzzyMatchKeysParams(),
             handle_validation="return_value",
+            alcall_params=get_default_call(),
+            imodel=parse_model,
+            imodel_kw={},
         )
-        operative.response_model = operative.update_response_model(
-            text=response_model
+
+    action_param = None
+    if invoke_actions and (instruct.actions or actions):
+        from ..act.act import _get_default_call_params
+
+        action_param = ActionParam(
+            action_call_params=call_params or _get_default_call_params(),
+            tools=tools,
+            strategy=action_strategy
+            or instruct.action_strategy
+            or "concurrent",
+            suppress_errors=True,
+            verbose_action=verbose_action,
+        )
+
+    return {
+        "instruction": instruct.instruction,
+        "chat_param": chat_param,
+        "parse_param": parse_param,
+        "action_param": action_param,
+        "handle_validation": handle_validation,
+        "invoke_actions": invoke_actions,
+        "skip_validation": skip_validation,
+        "clear_messages": clear_messages,
+    }
+
+
+async def operate(
+    branch: "Branch",
+    instruction: JsonValue | Instruction,
+    chat_param: ChatParam,
+    action_param: ActionParam | None = None,
+    parse_param: ParseParam | None = None,
+    handle_validation: HandleValidation = "return_value",
+    invoke_actions: bool = True,
+    skip_validation: bool = False,
+    clear_messages: bool = False,
+    reason: bool = False,
+    field_models: list[FieldModel] | None = None,
+) -> BaseModel | dict | str | None:
+
+    # 1. communicate chat context building to avoid changing parameters
+    # Start with base chat param
+    _cctx = chat_param
+    _pctx = (
+        parse_param.with_updates(handle_validation="return_value")
+        if parse_param
+        else ParseParam(
+            response_format=chat_param.response_format,
+            imodel=branch.parse_model,
+            handle_validation="return_value",
+        )
+    )
+
+    # Update tool schemas if needed
+    if tools := (action_param.tools or True) if action_param else None:
+        tool_schemas = branch.acts.get_tool_schema(tools=tools)
+        _cctx = _cctx.with_updates(tool_schemas=tool_schemas)
+
+    # Extract model class from response_format (can be class, instance, or dict)
+    model_class = None
+    if chat_param.response_format is not None:
+        if isinstance(chat_param.response_format, type) and issubclass(
+            chat_param.response_format, BaseModel
+        ):
+            model_class = chat_param.response_format
+        elif isinstance(chat_param.response_format, BaseModel):
+            model_class = type(chat_param.response_format)
+
+    def normalize_field_model(fms):
+        if not fms:
+            return []
+        if not isinstance(fms, list):
+            return [fms]
+        return fms
+
+    fms = normalize_field_model(field_models)
+    operative = None
+
+    if model_class:
+        from .step import Step
+
+        operative = Step.request_operative(
+            reason=reason,
+            actions=bool(action_param is not None),
+            base_type=model_class,
+            field_models=fms,
         )
+        # Update contexts with new response format
+        _cctx = _cctx.with_updates(response_format=operative.request_type)
+        _pctx = _pctx.with_updates(response_format=operative.request_type)
+    elif field_models:
+        dict_ = {}
+        for fm in fms:
+            if fm.name:
+                dict_[fm.name] = str(fm.annotated())
+        # Update contexts with dict format
+        _cctx = _cctx.with_updates(response_format=dict_)
+        _pctx = _pctx.with_updates(response_format=dict_)
+
+    from ..communicate.communicate import communicate
 
-    # If we still fail to parse, handle according to user preference
-    if not isinstance(response_model, BaseModel):
+    result = await communicate(
+        branch,
+        instruction,
+        _cctx,
+        _pctx,
+        clear_messages,
+        skip_validation=skip_validation,
+        request_fields=None,
+    )
+    if skip_validation:
+        return result
+    if model_class and not isinstance(result, model_class):
         match handle_validation:
             case "return_value":
-                return response_model
+                return result
             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
+        return result
 
-    # 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_strategy = (
-            action_strategy or instruct.action_strategy or "concurrent"
-        )
-        action_response_models = await branch.act(
-            response_model.action_requests,
-            strategy=action_strategy,
-            verbose_action=verbose_action,
-            call_params=call_params,
-        )
-        # 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 {}),
+    requests = (
+        getattr(result, "action_requests", None)
+        if model_class
+        else result.get("action_requests", None)
+    )
+
+    action_response_models = None
+    if action_param and requests is not None:
+        from ..act.act import act
+
+        action_response_models = await act(
+            branch,
+            requests,
+            action_param,
         )
 
-    # Return final result or the full operative
-    return operative if return_operative else operative.response_model
+    if not action_response_models:
+        return result
+
+    # Filter out None values from action responses
+    action_response_models = [
+        r for r in action_response_models if r is not None
+    ]
+
+    if not action_response_models:  # All were None
+        return result
+
+    if not model_class:  # Dict response
+        result.update({"action_responses": action_response_models})
+        return result
+
+    from .step import Step
+
+    operative.response_model = result
+    operative = Step.respond_operative(
+        operative=operative,
+        additional_data={"action_responses": action_response_models},
+    )
+    return operative.response_model

lionagi/{protocols/operatives → operations/operate}/operative.py

@@ -6,10 +6,9 @@ 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.ln import extract_json, fuzzy_match_keys
+from lionagi.ln.types import Undefined
 from lionagi.models import FieldModel, ModelParams, OperableModel
-from lionagi.utils import UNDEFINED
 
 
 class Operative:
@@ -169,7 +168,7 @@ class Operative:
             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}
+            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:
@@ -190,7 +189,7 @@ class Operative:
             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}
+            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:

lionagi/{protocols/operatives → operations/operate}/step.py

@@ -4,14 +4,10 @@
 from pydantic import BaseModel
 from pydantic.fields import FieldInfo
 
-from lionagi.fields.action import (
-    ACTION_REQUESTS_FIELD,
-    ACTION_REQUIRED_FIELD,
-    ACTION_RESPONSES_FIELD,
-)
-from lionagi.fields.reason import REASON_FIELD
 from lionagi.models import FieldModel, ModelParams
-from lionagi.protocols.operatives.operative import Operative
+
+from ..fields import get_default_field
+from .operative import Operative
 
 
 class Step:
@@ -71,18 +67,17 @@ class Step:
         field_models = field_models or []
         exclude_fields = exclude_fields or []
         field_descriptions = field_descriptions or {}
-        if reason and REASON_FIELD not in field_models:
-            field_models.append(REASON_FIELD)
-        if actions and ACTION_REQUESTS_FIELD not in field_models:
-            field_models.extend(
-                [
-                    ACTION_REQUESTS_FIELD,
-                    ACTION_REQUIRED_FIELD,
-                ]
-            )
-
+        if reason and (fm := get_default_field("reason")) not in field_models:
+            field_models.append(fm)
+        if (
+            actions
+            and (fm := get_default_field("action_requests"))
+            not in field_models
+        ):
+            fm2 = get_default_field("action_required")
+            field_models.extend([fm, fm2])
         if isinstance(request_params, ModelParams):
-            request_params = request_params.model_dump()
+            request_params = request_params.to_dict()
 
         request_params = request_params or {}
         request_params_fields = {
@@ -143,15 +138,17 @@ class Step:
         additional_data = additional_data or {}
         field_models = field_models or []
         if hasattr(operative.response_model, "action_required"):
-            field_models.extend(
-                [
-                    ACTION_RESPONSES_FIELD,
-                    ACTION_REQUIRED_FIELD,
-                    ACTION_REQUESTS_FIELD,
-                ]
-            )
+            for i in {
+                "action_requests",
+                "action_required",
+                "action_responses",
+            }:
+                fm = get_default_field(i)
+                if fm not in field_models:
+                    field_models.append(fm)
+
         if "reason" in type(operative.response_model).model_fields:
-            field_models.extend([REASON_FIELD])
+            field_models.append(get_default_field("reason"))
 
         operative = Step._create_response_type(
             operative=operative,
@@ -201,24 +198,22 @@ class Step:
             hasattr(operative.request_type, "action_required")
             and operative.response_model.action_required
         ):
-            field_models.extend(
-                [
-                    ACTION_RESPONSES_FIELD,
-                    ACTION_REQUIRED_FIELD,
-                    ACTION_REQUESTS_FIELD,
-                ]
-            )
-        if hasattr(operative.request_type, "reason"):
-            field_models.extend([REASON_FIELD])
+            for i in {
+                "action_requests",
+                "action_required",
+                "action_responses",
+            }:
+                fm = get_default_field(i)
+                if fm not in field_models:
+                    field_models.append(fm)
 
-        exclude_fields = exclude_fields or []
-        # Note: We no longer have access to request_params.exclude_fields
-        # since Operative doesn't store ModelParams anymore
+        if hasattr(operative.request_type, "reason"):
+            field_models.append(get_default_field("reason"))
 
         operative.create_response_type(
             response_params=response_params,
             field_models=field_models,
-            exclude_fields=exclude_fields,
+            exclude_fields=exclude_fields or [],
             doc=response_doc,
             config_dict=response_config_dict,
             frozen=frozen_response,