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

lionagi/operations/operate/operative.py

@@ -1,361 +1,198 @@
 # Copyright (c) 2023-2025, HaiyangLi <quantocean.li at gmail dot com>
 # SPDX-License-Identifier: Apache-2.0
 
-from typing import Any
+from typing import TYPE_CHECKING, Any, Literal
 
-from pydantic import BaseModel
-from pydantic.fields import FieldInfo
+from lionagi.ln.types import Operable
 
-from lionagi.ln import extract_json, fuzzy_match_keys
-from lionagi.ln.types import Undefined
-from lionagi.models import FieldModel, ModelParams, OperableModel
+if TYPE_CHECKING:
+    from pydantic import BaseModel
 
 
 class Operative:
-    """Class representing an operative that handles request and response models for operations.
+    """Framework-agnostic operation handler using Spec/Operable system.
 
-    This implementation uses OperableModel internally for better performance while
-    maintaining backward compatibility with the existing API.
+    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,
-        request_type: type[BaseModel] | None = None,
-        response_type: type[BaseModel] | None = None,
-        response_model: BaseModel | None = None,
-        response_str_dict: dict | str | None = None,
+        adapter: Literal["pydantic"] = "pydantic",
+        strict: bool = False,
         auto_retry_parse: bool = True,
         max_retries: int = 3,
-        parse_kwargs: dict | None = None,
-        request_params: (
-            ModelParams | None
-        ) = None,  # Deprecated, for backward compatibility
-        **_kwargs,  # Ignored for backward compatibility
+        base_type: type["BaseModel"] | None = None,
+        operable: Operable | None = None,
+        request_exclude: set[str] | None = None,
     ):
-        """Initialize the Operative.
+        """Initialize Operative with a single immutable Operable.
 
         Args:
-            name: Name of the operative
-            request_type: Pydantic model type for requests
-            response_type: Pydantic model type for responses
-            response_model: Current response model instance
-            response_str_dict: Raw response string/dict
-            auto_retry_parse: Whether to auto-retry parsing
-            max_retries: Maximum parse retries
-            parse_kwargs: Additional parse arguments
-            request_params: Deprecated - use direct field addition
-            response_params: Deprecated - use direct field addition
+            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
-        self.request_type = request_type
-        self.response_type = response_type
-        self.response_model = response_model
-        self.response_str_dict = response_str_dict
+        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.parse_kwargs = parse_kwargs or {}
-        self._should_retry = None
+        self.base_type = base_type
 
-        # Internal OperableModel instances
-        self._request_operable = OperableModel()
-        self._response_operable = OperableModel()
+        # Single source of truth
+        self.operable = operable or Operable((), name=self.name)
+        self.request_exclude = request_exclude or set()
 
-        # Handle deprecated ModelParams for backward compatibility
-        if request_params:
-            self._init_from_model_params(request_params)
+        # Materialized models (cached)
+        self._request_model_cls = None
+        self._response_model_cls = None
 
-        # Set default name if not provided
-        if not self.name:
-            self.name = (
-                self.request_type.__name__
-                if self.request_type
-                else "Operative"
-            )
-
-    def _init_from_model_params(self, params: ModelParams):
-        """Initialize from ModelParams for backward compatibility."""
-        # Add field models to the request operable
-        if params.field_models:
-            # Coerce to list if single FieldModel instance
-            field_models_list = (
-                [params.field_models]
-                if isinstance(params.field_models, FieldModel)
-                else params.field_models
-            )
-            for field_model in field_models_list:
-                self._request_operable.add_field(
-                    field_model.name,
-                    field_model=field_model,
-                    annotation=field_model.base_type,
-                )
-
-        # Add parameter fields (skip if already added from field_models)
-        if params.parameter_fields:
-            for name, field_info in params.parameter_fields.items():
-                if (
-                    name not in (params.exclude_fields or [])
-                    and name not in self._request_operable.all_fields
-                ):
-                    self._request_operable.add_field(
-                        name, field_obj=field_info
-                    )
+        # Response state
+        self.response_model = None
+        self.response_str_dict = None
+        self._should_retry = None
 
-        # Generate request_type if not provided
-        if not self.request_type:
-            exclude_fields = params.exclude_fields or []
-            use_fields = set(self._request_operable.all_fields.keys()) - set(
-                exclude_fields
-            )
+    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,
+        )
 
-            # Determine model name - prefer explicit name, then base_type name, then default
-            model_name = "RequestModel"
-            if not params._is_sentinel(params.name):
-                model_name = params.name
-            elif not params._is_sentinel(params.base_type):
-                model_name = params.base_type.__name__
-
-            self.request_type = self._request_operable.new_model(
-                name=model_name,
-                use_fields=use_fields,
-                base_type=params.base_type,
-                frozen=params.frozen,
-                config_dict=params.config_dict,
-                doc=params.doc,
-            )
+        return self._response_model_cls
 
-        # Update name if not set - prefer explicit name, then base_type name
-        if not self.name:
-            if not params._is_sentinel(params.name):
-                self.name = params.name
-            elif not params._is_sentinel(params.base_type):
-                self.name = params.base_type.__name__
+    def validate_response(self, text: str, strict: bool | None = None) -> Any:
+        """Validate response text using adapter.
 
-    def model_dump(self) -> dict[str, Any]:
-        """Convert to dictionary for backward compatibility.
+        Args:
+            text: Raw response text
+            strict: If True, raise on validation errors
 
-        Note: This returns a Python dict, not JSON-serializable data.
-        For JSON serialization, convert types appropriately.
+        Returns:
+            Validated model instance or None
         """
-        return {
-            "name": self.name,
-            "request_type": self.request_type,  # Python class object
-            "response_type": self.response_type,  # Python class object
-            "response_model": self.response_model,
-            "response_str_dict": self.response_str_dict,
-            "auto_retry_parse": self.auto_retry_parse,
-            "max_retries": self.max_retries,
-            "parse_kwargs": self.parse_kwargs,
-        }
-
-    def to_dict(self) -> dict[str, Any]:
-        """Alias for model_dump() - more appropriate name for non-Pydantic class."""
-        return self.model_dump()
-
-    def raise_validate_pydantic(self, text: str) -> None:
-        """Validates and updates the response model using strict matching.
+        strict = self.strict if strict is None else strict
 
-        Args:
-            text (str): The text to validate and parse into the response model.
+        if not self._response_model_cls:
+            self.create_response_model()
+
+        adapter_cls = self._get_adapter()
 
-        Raises:
-            Exception: If the validation fails.
-        """
-        d_ = extract_json(text, fuzzy_parse=True)
-        if isinstance(d_, list | tuple) and len(d_) == 1:
-            d_ = d_[0]
         try:
-            d_ = fuzzy_match_keys(
-                d_, self.request_type.model_fields, handle_unmatched="raise"
+            self.response_model = adapter_cls.validate_response(
+                text,
+                self._response_model_cls,
+                strict=strict,
+                fuzzy_parse=True,
             )
-            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:
-            self.response_str_dict = d_
-            self._should_retry = True
+            return self.response_model
 
-    def force_validate_pydantic(self, text: str):
-        """Forcibly validates and updates the response model, allowing unmatched fields.
+        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
 
-        Args:
-            text (str): The text to validate and parse into the response model.
-        """
-        d_ = text
-        try:
-            d_ = extract_json(text, fuzzy_parse=True)
-            if isinstance(d_, list | tuple) and len(d_) == 1:
-                d_ = d_[0]
-            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}
-            self.response_model = self.request_type.model_validate(d_)
-            self._should_retry = False
-        except Exception:
-            self.response_str_dict = d_
-            self.response_model = None
-            self._should_retry = True
+            return None
 
     def update_response_model(
         self, text: str | None = None, data: dict | None = None
-    ) -> BaseModel | dict | str | None:
-        """Updates the response model based on the provided text or data.
+    ) -> Any:
+        """Update response model from text or dict.
 
         Args:
-            text (str, optional): The text to parse and validate.
-            data (dict, optional): The data to update the response model with.
+            text: Raw response text to validate
+            data: Dictionary updates to merge
 
         Returns:
-            BaseModel | dict | str | None: The updated response model or raw data.
-
-        Raises:
-            ValueError: If neither text nor data is provided.
+            Updated model instance or raw data
         """
         if text is None and data is None:
-            raise ValueError("Either text or data must be provided.")
+            raise ValueError("Either text or data must be provided")
 
         if text:
             self.response_str_dict = text
-            try:
-                self.raise_validate_pydantic(text)
-            except Exception:
-                self.force_validate_pydantic(text)
-
-        if data and self.response_type:
-            d_ = self.response_model.model_dump()
-            d_.update(data)
-            self.response_model = self.response_type.model_validate(d_)
-
-        if not self.response_model and isinstance(
-            self.response_str_dict, list
-        ):
-            try:
-                self.response_model = [
-                    self.request_type.model_validate(d_)
-                    for d_ in self.response_str_dict
-                ]
-            except Exception:
-                pass
-
-        return self.response_model or self.response_str_dict
-
-    def create_response_type(
-        self,
-        response_params: ModelParams | None = None,
-        field_models: list[FieldModel] | None = None,
-        parameter_fields: dict[str, FieldInfo] | None = None,
-        exclude_fields: list[str] | None = None,
-        field_descriptions: dict[str, str] | None = None,
-        inherit_base: bool = True,
-        config_dict: dict | None = None,
-        doc: str | None = None,
-        frozen: bool = False,
-        validators: dict | None = None,
-    ) -> None:
-        """Creates a new response type based on the provided parameters.
+            self.validate_response(text, strict=False)
 
-        Args:
-            response_params (ModelParams, optional): Parameters for the new response model.
-            field_models (list[FieldModel], optional): List of field models.
-            parameter_fields (dict[str, FieldInfo], optional): Dictionary of parameter fields.
-            exclude_fields (list, optional): List of fields to exclude.
-            field_descriptions (dict, optional): Dictionary of field descriptions.
-            inherit_base (bool, optional): Whether to inherit the base model.
-            config_dict (dict | None, optional): Configuration dictionary.
-            doc (str | None, optional): Documentation string.
-            frozen (bool, optional): Whether the model is frozen.
-            validators (dict, optional): Dictionary of validators.
-        """
-        # Process response_params if provided (for backward compatibility)
-        if response_params:
-            # Extract values from ModelParams
-            field_models = field_models or response_params.field_models
-            parameter_fields = (
-                parameter_fields or response_params.parameter_fields
+        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
             )
-            exclude_fields = exclude_fields or response_params.exclude_fields
-            field_descriptions = (
-                field_descriptions or response_params.field_descriptions
-            )
-            inherit_base = (
-                response_params.inherit_base if inherit_base else False
-            )
-            config_dict = config_dict or response_params.config_dict
-            doc = doc or response_params.doc
-            frozen = frozen or response_params.frozen
-
-        # Clear response operable and rebuild
-        self._response_operable = OperableModel()
-
-        # Copy fields from request operable if inherit_base
-        if inherit_base and self._request_operable:
-            for (
-                field_name,
-                field_model,
-            ) in self._request_operable.extra_field_models.items():
-                self._response_operable.add_field(
-                    field_name, field_model=field_model
-                )
-
-        # Add field models (skip if already exists from inheritance)
-        if field_models:
-            # Coerce to list if single FieldModel instance
-            field_models_list = (
-                [field_models]
-                if isinstance(field_models, FieldModel)
-                else field_models
-            )
-            for field_model in field_models_list:
-                if field_model.name not in self._response_operable.all_fields:
-                    self._response_operable.add_field(
-                        field_model.name,
-                        field_model=field_model,
-                        annotation=field_model.base_type,
-                    )
 
-        # Add parameter fields (skip if already added)
-        if parameter_fields:
-            for name, field_info in parameter_fields.items():
-                if (
-                    name not in (exclude_fields or [])
-                    and name not in self._response_operable.all_fields
-                ):
-                    self._response_operable.add_field(
-                        name, field_obj=field_info
-                    )
+        return self.response_model or self.response_str_dict
 
-        # Add validators if provided
-        if validators:
-            for field_name, validator in validators.items():
-                if field_name in self._response_operable.all_fields:
-                    field_model = (
-                        self._response_operable.extra_field_models.get(
-                            field_name
-                        )
-                    )
-                    if field_model:
-                        field_model.validator = validator
+    @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
 
-        # Generate response type
-        exclude_fields = exclude_fields or []
-        use_fields = set(self._response_operable.all_fields.keys()) - set(
-            exclude_fields
-        )
+    @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
 
-        # Determine base type - use request_type if inheriting and no specific base provided
-        base_type = None
-        if response_params and response_params.base_type:
-            base_type = response_params.base_type
-        elif inherit_base and self.request_type:
-            base_type = self.request_type
-
-        self.response_type = self._response_operable.new_model(
-            name=(response_params.name if response_params else None)
-            or "ResponseModel",
-            use_fields=use_fields,
-            base_type=base_type,
-            frozen=frozen,
-            config_dict=config_dict,
-            doc=doc,
-        )
+
+__all__ = ("Operative",)