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

lionagi/operations/operate/operate.py

@@ -2,23 +2,26 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import warnings
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, Union
 
 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.types import Instruction, Progression, SenderRecipient
-from lionagi.session.branch import AlcallParams
+from lionagi.ln.types import Spec
+from lionagi.models import FieldModel
+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.protocols.operatives.step import Operative
     from lionagi.service.imodel import iModel
     from lionagi.session.branch import Branch, ToolRef
 
+    from .operative import Operative
+
 
 def prepare_operate_kw(
     branch: "Branch",
@@ -30,7 +33,7 @@ def prepare_operate_kw(
     sender: SenderRecipient = None,
     recipient: SenderRecipient = None,
     progression: Progression = None,
-    imodel: "iModel" = None,  # deprecated, alias of chat_model
+    imodel: "iModel" = None,  # deprecated
     chat_model: "iModel" = None,
     invoke_actions: bool = True,
     tool_schemas: list[dict] = None,
@@ -38,35 +41,32 @@ def prepare_operate_kw(
     image_detail: Literal["low", "high", "auto"] = None,
     parse_model: "iModel" = None,
     skip_validation: bool = False,
+    handle_validation: HandleValidation = "return_value",
     tools: "ToolRef" = None,
     operative: "Operative" = None,
-    response_format: type[BaseModel] = None,  # alias of operative.request_type
+    response_format: type[BaseModel] = None,
     actions: bool = False,
     reason: bool = False,
     call_params: AlcallParams = None,
     action_strategy: Literal["sequential", "concurrent"] = "concurrent",
     verbose_action: bool = False,
-    field_models: list[FieldModel] = None,
-    exclude_fields: list | dict | None = None,
-    request_params: ModelParams = None,
-    request_param_kwargs: dict = None,
-    handle_validation: HandleValidation = "return_value",
-    operative_model: type[BaseModel] = None,
-    request_model: type[BaseModel] = None,
+    field_models: list[FieldModel | Spec] = None,
+    operative_model: type[BaseModel] = None,  # deprecated
+    request_model: type[BaseModel] = None,  # deprecated
     include_token_usage_to_model: bool = False,
     clear_messages: bool = False,
     **kwargs,
-) -> list | BaseModel | None | dict | str:
+) -> dict:
     # Handle deprecated parameters
     if operative_model:
         warnings.warn(
-            "Parameter 'operative_model' is deprecated. Use 'response_format' instead.",
+            "Parameter 'operative_model' is deprecated. Use 'response_format'.",
             DeprecationWarning,
             stacklevel=2,
         )
     if imodel:
         warnings.warn(
-            "Parameter 'imodel' is deprecated. Use 'chat_model' instead.",
+            "Parameter 'imodel' is deprecated. Use 'chat_model'.",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -77,26 +77,23 @@ def prepare_operate_kw(
         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."
+            "Cannot specify multiple of: operative_model, response_format, request_model"
         )
 
     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
 
-    # Convert dict-based instructions to Instruct if needed
+    # Convert dict-based instructions
     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:
@@ -104,21 +101,40 @@ def prepare_operate_kw(
         if action_strategy:
             instruct.action_strategy = action_strategy
 
-    # Build the Operative - always create it for backwards compatibility
-    from lionagi.protocols.operatives.step import Step
-
-    operative = Step.request_operative(
-        request_params=request_params,
-        reason=instruct.reason,
-        actions=instruct.actions or actions,
-        exclude_fields=exclude_fields,
-        base_type=response_format,
-        field_models=field_models,
-        **(request_param_kwargs or {}),
+    # Convert field_models to Spec if needed
+    fields_dict = None
+    if field_models:
+        fields_dict = {}
+        for fm in field_models:
+            # Convert FieldModel to Spec
+            if isinstance(fm, FieldModel):
+                spec = fm.to_spec()
+            elif isinstance(fm, Spec):
+                spec = fm
+            else:
+                raise TypeError(f"Expected FieldModel or Spec, got {type(fm)}")
+
+            if spec.name:
+                fields_dict[spec.name] = spec
+
+    # Build Operative if needed
+    operative = None
+    if instruct.reason or instruct.actions or response_format or fields_dict:
+        from .step import Step
+
+        operative = Step.request_operative(
+            base_type=response_format,
+            reason=instruct.reason,
+            actions=instruct.actions or actions,
+            fields=fields_dict,
+        )
+
+        # Create response model
+        operative = Step.respond_operative(operative)
+
+    final_response_format = (
+        operative.response_type if operative else response_format
     )
-    # Use the operative's request_type which is a proper Pydantic model
-    # created from field_models if provided
-    final_response_format = operative.request_type
 
     # Build contexts
     chat_param = ChatParam(
@@ -144,7 +160,7 @@ def prepare_operate_kw(
         parse_param = ParseParam(
             response_format=final_response_format,
             fuzzy_match_params=FuzzyMatchKeysParams(),
-            handle_validation="return_value",
+            handle_validation=handle_validation,
             alcall_params=get_default_call(),
             imodel=parse_model,
             imodel_kw={},
@@ -173,25 +189,43 @@ def prepare_operate_kw(
         "invoke_actions": invoke_actions,
         "skip_validation": skip_validation,
         "clear_messages": clear_messages,
+        "operative": operative,
     }
 
 
 async def operate(
     branch: "Branch",
-    instruction: JsonValue | Instruction,
+    instruction: Union[JsonValue, Instruction],
     chat_param: ChatParam,
-    action_param: ActionParam | None = None,
-    parse_param: ParseParam | None = None,
+    action_param: Union[ActionParam, None] = None,
+    parse_param: Union[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
+    field_models: Union[list[Union[FieldModel, Spec]], None] = None,
+    operative: Union["Operative", None] = None,
+) -> Union[BaseModel, dict, str, None]:
+    """Execute operation with optional action handling.
+
+    Args:
+        branch: Branch instance
+        instruction: Instruction or JSON value
+        chat_param: Chat parameters
+        action_param: Action parameters
+        parse_param: Parse parameters
+        handle_validation: Validation handling strategy
+        invoke_actions: Whether to invoke actions
+        skip_validation: Whether to skip validation
+        clear_messages: Whether to clear messages
+        reason: Whether to include reasoning
+        field_models: List of FieldModel or Spec objects
+        operative: Operative instance
+
+    Returns:
+        Result of operation
+    """
     _cctx = chat_param
     _pctx = (
         parse_param.with_updates(handle_validation="return_value")
@@ -203,12 +237,12 @@ async def operate(
         )
     )
 
-    # Update tool schemas if needed
+    # Update tool schemas
     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)
+    # Extract model class
     model_class = None
     if chat_param.response_format is not None:
         if isinstance(chat_param.response_format, type) and issubclass(
@@ -218,36 +252,38 @@ async def operate(
         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 lionagi.protocols.operatives.step import Step
+    # Convert field_models to fields dict
+    fields_dict = None
+    if field_models:
+        fields_dict = {}
+        for fm in field_models:
+            if isinstance(fm, FieldModel):
+                spec = fm.to_spec()
+            elif isinstance(fm, Spec):
+                spec = fm
+            else:
+                raise TypeError(f"Expected FieldModel or Spec, got {type(fm)}")
+
+            if spec.name:
+                fields_dict[spec.name] = spec
+
+    # Create operative if needed
+    if not operative and (model_class or action_param or fields_dict):
+        from .step import Step
 
         operative = Step.request_operative(
-            reason=reason,
-            actions=bool(action_param is not None),
             base_type=model_class,
-            field_models=fms,
+            reason=reason,
+            actions=bool(action_param),
+            fields=fields_dict,
         )
-        # 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_)
+        operative = Step.respond_operative(operative)
+
+        # Update contexts
+        response_fmt = operative.response_type or model_class
+        if response_fmt:
+            _cctx = _cctx.with_updates(response_format=response_fmt)
+            _pctx = _pctx.with_updates(response_format=response_fmt)
 
     from ..communicate.communicate import communicate
 
@@ -260,8 +296,10 @@ async def operate(
         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":
@@ -269,12 +307,12 @@ async def operate(
             case "return_none":
                 return None
             case "raise":
-                raise ValueError(
-                    "Failed to parse the LLM response into the requested format."
-                )
+                raise ValueError("Failed to parse LLM response.")
+
     if not invoke_actions:
         return result
 
+    # Handle actions
     requests = (
         getattr(result, "action_requests", None)
         if model_class
@@ -285,32 +323,28 @@ async def operate(
     if action_param and requests is not None:
         from ..act.act import act
 
-        action_response_models = await act(
-            branch,
-            requests,
-            action_param,
-        )
+        action_response_models = await act(branch, requests, action_param)
 
     if not action_response_models:
         return result
 
-    # Filter out None values from action responses
+    # Filter None values
     action_response_models = [
         r for r in action_response_models if r is not None
     ]
 
-    if not action_response_models:  # All were None
+    if not action_response_models:
         return result
 
     if not model_class:  # Dict response
         result.update({"action_responses": action_response_models})
         return result
 
-    from lionagi.protocols.operatives.step import Step
-
+    # If we have model_class, we must have operative (created at line 268)
+    # First set the response_model to the existing result
     operative.response_model = result
-    operative = Step.respond_operative(
-        operative=operative,
-        additional_data={"action_responses": action_response_models},
+    # Then update it with action_responses
+    operative.update_response_model(
+        data={"action_responses": action_response_models}
     )
     return operative.response_model

lionagi/operations/operate/operative.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from lionagi.ln.types import Operable
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+class Operative:
+    """Framework-agnostic operation handler using Spec/Operable system.
+
+    Manages request/response field specifications, delegating framework-specific
+    operations to adapters. Single source of truth pattern with one Operable
+    containing all fields.
+
+    Architecture:
+        Spec Definition → Operable Collection → Adapter → Framework Model
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        adapter: Literal["pydantic"] = "pydantic",
+        strict: bool = False,
+        auto_retry_parse: bool = True,
+        max_retries: int = 3,
+        base_type: type["BaseModel"] | None = None,
+        operable: Operable | None = None,
+        request_exclude: set[str] | None = None,
+    ):
+        """Initialize Operative with a single immutable Operable.
+
+        Args:
+            name: Operation name
+            adapter: Validation framework ("pydantic" only for now)
+            strict: If True, raise on validation errors
+            auto_retry_parse: Auto-retry validation with fuzzy matching
+            max_retries: Maximum validation retry attempts
+            base_type: Base Pydantic model to extend
+            operable: Single Operable with all fields
+            request_exclude: Fields to exclude from request (e.g., {"action_responses"})
+        """
+        self.name = name or (base_type.__name__ if base_type else "Operative")
+        self.adapter = adapter
+        self.strict = strict
+        self.auto_retry_parse = auto_retry_parse
+        self.max_retries = max_retries
+        self.base_type = base_type
+
+        # Single source of truth
+        self.operable = operable or Operable((), name=self.name)
+        self.request_exclude = request_exclude or set()
+
+        # Materialized models (cached)
+        self._request_model_cls = None
+        self._response_model_cls = None
+
+        # Response state
+        self.response_model = None
+        self.response_str_dict = None
+        self._should_retry = None
+
+    def _get_adapter(self):
+        """Get adapter class for current adapter type."""
+        if self.adapter == "pydantic":
+            from lionagi.adapters.spec_adapters import PydanticSpecAdapter
+
+            return PydanticSpecAdapter
+        else:
+            raise ValueError(f"Unsupported adapter: {self.adapter}")
+
+    def create_request_model(self) -> type:
+        """Materialize request specs into model (excluding certain fields)."""
+        if self._request_model_cls:
+            return self._request_model_cls
+
+        self._request_model_cls = self.operable.create_model(
+            adapter=self.adapter,
+            model_name=f"{self.name}Request",
+            base_type=self.base_type,
+            exclude=self.request_exclude,
+        )
+        return self._request_model_cls
+
+    def create_response_model(self) -> type:
+        """Materialize all specs into response model."""
+        if self._response_model_cls:
+            return self._response_model_cls
+
+        # Ensure request model exists first
+        if not self._request_model_cls:
+            self.create_request_model()
+
+        # Response model uses ALL fields and inherits from request
+        self._response_model_cls = self.operable.create_model(
+            adapter=self.adapter,
+            model_name=f"{self.name}Response",
+            base_type=self._request_model_cls,
+        )
+
+        return self._response_model_cls
+
+    def validate_response(self, text: str, strict: bool | None = None) -> Any:
+        """Validate response text using adapter.
+
+        Args:
+            text: Raw response text
+            strict: If True, raise on validation errors
+
+        Returns:
+            Validated model instance or None
+        """
+        strict = self.strict if strict is None else strict
+
+        if not self._response_model_cls:
+            self.create_response_model()
+
+        adapter_cls = self._get_adapter()
+
+        try:
+            self.response_model = adapter_cls.validate_response(
+                text,
+                self._response_model_cls,
+                strict=strict,
+                fuzzy_parse=True,
+            )
+            self._should_retry = False
+            return self.response_model
+
+        except Exception as e:
+            self.response_str_dict = text
+            self._should_retry = strict
+
+            if strict:
+                raise e
+
+            # Try fuzzy validation if auto-retry enabled
+            if self.auto_retry_parse and not strict:
+                try:
+                    self.response_model = adapter_cls.validate_response(
+                        text,
+                        self._response_model_cls,
+                        strict=False,
+                        fuzzy_parse=True,
+                    )
+                    self._should_retry = False
+                    return self.response_model
+                except Exception:
+                    pass
+
+            return None
+
+    def update_response_model(
+        self, text: str | None = None, data: dict | None = None
+    ) -> Any:
+        """Update response model from text or dict.
+
+        Args:
+            text: Raw response text to validate
+            data: Dictionary updates to merge
+
+        Returns:
+            Updated model instance or raw data
+        """
+        if text is None and data is None:
+            raise ValueError("Either text or data must be provided")
+
+        if text:
+            self.response_str_dict = text
+            self.validate_response(text, strict=False)
+
+        if data and self._response_model_cls and self.response_model:
+            adapter_cls = self._get_adapter()
+            self.response_model = adapter_cls.update_model(
+                self.response_model, data, self._response_model_cls
+            )
+
+        return self.response_model or self.response_str_dict
+
+    @property
+    def request_type(self) -> type | None:
+        """Get request model type."""
+        if not self._request_model_cls:
+            self.create_request_model()
+        return self._request_model_cls
+
+    @property
+    def response_type(self) -> type | None:
+        """Get response model type."""
+        if not self._response_model_cls:
+            self.create_response_model()
+        return self._response_model_cls
+
+
+__all__ = ("Operative",)