clarifai 11.8.4__tar.gz → 11.8.5__tar.gz

{clarifai-11.8.4/clarifai.egg-info → clarifai-11.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarifai
-Version: 11.8.4
+Version: 11.8.5
 Home-page: https://github.com/Clarifai/clarifai-python
 Author: Clarifai
 Author-email: support@clarifai.com

clarifai-11.8.5/clarifai/__init__.py

@@ -0,0 +1 @@
+__version__ = "11.8.5"

{clarifai-11.8.4 → clarifai-11.8.5}/clarifai/client/model_client.py

@@ -11,6 +11,7 @@ from clarifai.constants.model import MAX_MODEL_PREDICT_INPUTS
 from clarifai.errors import UserError
 from clarifai.runners.utils import code_script, method_signatures
 from clarifai.runners.utils.method_signatures import (
+    RESERVED_PARAM_WITH_PROTO,
     CompatibilitySerializer,
     deserialize,
     get_stream_from_signature,
@@ -204,6 +205,9 @@ class ModelClient:
 
             def bind_f(method_name, method_argnames, call_func, async_call_func):
                 def sync_f(*args, **kwargs):
+                    # Extract with_proto parameter if present
+                    with_proto = kwargs.pop(RESERVED_PARAM_WITH_PROTO, False)
+
                     if len(args) > len(method_argnames):
                         raise TypeError(
                             f"{method_name}() takes {len(method_argnames)} positional arguments but {len(args)} were given"
@@ -221,7 +225,7 @@ class ModelClient:
                         )
                         if is_batch_input_valid and (not is_openai_chat_format(batch_inputs)):
                             # If the batch input is valid, call the function with the batch inputs and the method name
-                            return call_func(batch_inputs, method_name)
+                            return call_func(batch_inputs, method_name, with_proto=with_proto)
 
                     for name, arg in zip(
                         method_argnames, args
@@ -229,10 +233,13 @@ class ModelClient:
                         if name in kwargs:
                             raise TypeError(f"Multiple values for argument {name}")
                         kwargs[name] = arg
-                    return call_func(kwargs, method_name)
+                    return call_func(kwargs, method_name, with_proto=with_proto)
 
                 async def async_f(*args, **kwargs):
                     # Async version to call the async function
+                    # Extract with_proto parameter if present
+                    with_proto = kwargs.pop(RESERVED_PARAM_WITH_PROTO, False)
+
                     if len(args) > len(method_argnames):
                         raise TypeError(
                             f"{method_name}() takes {len(method_argnames)} positional arguments but {len(args)} were given"
@@ -249,7 +256,9 @@ class ModelClient:
                         )
                         if is_batch_input_valid and (not is_openai_chat_format(batch_inputs)):
                             # If the batch input is valid, call the function with the batch inputs and the method name
-                            return async_call_func(batch_inputs, method_name)
+                            return async_call_func(
+                                batch_inputs, method_name, with_proto=with_proto
+                            )
 
                     for name, arg in zip(
                         method_argnames, args
@@ -258,7 +267,7 @@ class ModelClient:
                             raise TypeError(f"Multiple values for argument {name}")
                         kwargs[name] = arg
 
-                    return async_call_func(kwargs, method_name)
+                    return async_call_func(kwargs, method_name, with_proto=with_proto)
 
                 class MethodWrapper:
                     def __call__(self, *args, **kwargs):
@@ -364,6 +373,7 @@ class ModelClient:
         self,
         inputs,  # TODO set up functions according to fetched signatures?
         method_name: str = 'predict',
+        with_proto: bool = False,
     ) -> Any:
         input_signature = self._method_signatures[method_name].input_fields
         output_signature = self._method_signatures[method_name].output_fields
@@ -385,9 +395,12 @@ class ModelClient:
         outputs = []
         for output in response.outputs:
             outputs.append(deserialize(output.data, output_signature, is_output=True))
-        if batch_input:
-            return outputs
-        return outputs[0]
+
+        result = outputs if batch_input else outputs[0]
+
+        if with_proto:
+            return result, response
+        return result
 
     def _predict_by_proto(
         self,
@@ -448,15 +461,17 @@ class ModelClient:
         self,
         inputs,
         method_name: str = 'predict',
+        with_proto: bool = False,
     ) -> Any:
         """Asynchronously process inputs and make predictions.
 
         Args:
             inputs: Input data to process
             method_name (str): Name of the method to call
+            with_proto (bool): If True, return both the processed result and the raw protobuf response
 
         Returns:
-            Processed prediction results
+            Processed prediction results, optionally with protobuf response
         """
         # method_name is set to 'predict' by default, this is because to replicate the input and output signature behaviour of sync to async predict.
         input_signature = self._method_signatures[method_name].input_fields
@@ -477,7 +492,11 @@ class ModelClient:
         for output in response.outputs:
             outputs.append(deserialize(output.data, output_signature, is_output=True))
 
-        return outputs if batch_input else outputs[0]
+        result = outputs if batch_input else outputs[0]
+
+        if with_proto:
+            return result, response
+        return result
 
     async def _async_predict_by_proto(
         self,
@@ -551,6 +570,7 @@ class ModelClient:
         self,
         inputs,  # TODO set up functions according to fetched signatures?
         method_name: str = 'generate',
+        with_proto: bool = False,
     ) -> Any:
         input_signature = self._method_signatures[method_name].input_fields
         output_signature = self._method_signatures[method_name].output_fields
@@ -572,10 +592,13 @@ class ModelClient:
             outputs = []
             for output in response.outputs:
                 outputs.append(deserialize(output.data, output_signature, is_output=True))
-            if batch_input:
-                yield outputs
+
+            result = outputs if batch_input else outputs[0]
+
+            if with_proto:
+                yield result, response
             else:
-                yield outputs[0]
+                yield result
 
     def _generate_by_proto(
         self,
@@ -641,6 +664,7 @@ class ModelClient:
         self,
         inputs,
         method_name: str = 'generate',
+        with_proto: bool = False,
     ) -> Any:
         # method_name is set to 'generate' by default, this is because to replicate the input and output signature behaviour of sync to async generate.
         input_signature = self._method_signatures[method_name].input_fields
@@ -654,18 +678,21 @@ class ModelClient:
         proto_inputs = []
         for input in inputs:
             proto = resources_pb2.Input()
-        serialize(input, input_signature, proto.data)
-        proto_inputs.append(proto)
+            serialize(input, input_signature, proto.data)
+            proto_inputs.append(proto)
         response_stream = self._async_generate_by_proto(proto_inputs, method_name)
 
         async for response in response_stream:
             outputs = []
             for output in response.outputs:
                 outputs.append(deserialize(output.data, output_signature, is_output=True))
-            if batch_input:
-                yield outputs
+
+            result = outputs if batch_input else outputs[0]
+
+            if with_proto:
+                yield result, response
             else:
-                yield outputs[0]
+                yield result
 
     async def _async_generate_by_proto(
         self,
@@ -734,6 +761,7 @@ class ModelClient:
         self,
         inputs,
         method_name: str = 'stream',
+        with_proto: bool = False,
     ) -> Any:
         input_signature = self._method_signatures[method_name].input_fields
         output_signature = self._method_signatures[method_name].output_fields
@@ -775,7 +803,12 @@ class ModelClient:
 
         for response in response_stream:
             assert len(response.outputs) == 1, 'streaming methods must have exactly one output'
-            yield deserialize(response.outputs[0].data, output_signature, is_output=True)
+            result = deserialize(response.outputs[0].data, output_signature, is_output=True)
+
+            if with_proto:
+                yield result, response
+            else:
+                yield result
 
     def _req_iterator(
         self,
@@ -843,6 +876,7 @@ class ModelClient:
         self,
         inputs,
         method_name: str = 'stream',
+        with_proto: bool = False,
     ) -> Any:
         # method_name is set to 'stream' by default, this is because to replicate the input and output signature behaviour of sync to async stream.
         input_signature = self._method_signatures[method_name].input_fields
@@ -885,7 +919,12 @@ class ModelClient:
 
         async for response in response_stream:
             assert len(response.outputs) == 1, 'streaming methods must have exactly one output'
-            yield deserialize(response.outputs[0].data, output_signature, is_output=True)
+            result = deserialize(response.outputs[0].data, output_signature, is_output=True)
+
+            if with_proto:
+                yield result, response
+            else:
+                yield result
 
     async def _async_stream_by_proto(
         self,

{clarifai-11.8.4 → clarifai-11.8.5}/clarifai/runners/utils/method_signatures.py

@@ -23,6 +23,9 @@ from clarifai.runners.utils.serializers import (
     TupleSerializer,
 )
 
+# Reserved parameter name for protobuf response access
+RESERVED_PARAM_WITH_PROTO = 'with_proto'
+
 
 def build_function_signature(func):
     '''
@@ -45,6 +48,12 @@ def build_function_signature(func):
     input_sigs = []
     input_streaming = []
     for p in sig.parameters.values():
+        # Validate that user methods don't use reserved parameter names
+        if p.name == RESERVED_PARAM_WITH_PROTO:
+            raise ValueError(
+                f"Parameter name '{RESERVED_PARAM_WITH_PROTO}' is reserved and cannot be used in model methods. "
+                f"This parameter is automatically added by the framework to provide access to protobuf responses."
+            )
         model_type_field, _, streaming = build_variable_signature(p.name, p.annotation, p.default)
         input_sigs.append(model_type_field)
         input_streaming.append(streaming)

{clarifai-11.8.4 → clarifai-11.8.5/clarifai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarifai
-Version: 11.8.4
+Version: 11.8.5
 Home-page: https://github.com/Clarifai/clarifai-python
 Author: Clarifai
 Author-email: support@clarifai.com

{clarifai-11.8.4 → clarifai-11.8.5}/clarifai.egg-info/SOURCES.txt

@@ -148,4 +148,5 @@ tests/test_pipeline_client.py
 tests/test_rag.py
 tests/test_search.py
 tests/test_secrets.py
-tests/test_stub.py
+tests/test_stub.py
+tests/test_with_proto_feature.py

clarifai-11.8.5/tests/test_with_proto_feature.py

@@ -0,0 +1,222 @@
+"""
+Tests for the with_proto feature in pythonic models
+"""
+
+import unittest
+from unittest.mock import Mock, patch
+
+from clarifai_grpc.grpc.api import service_pb2
+from clarifai_grpc.grpc.api.status import status_code_pb2
+
+from clarifai.client.model_client import ModelClient
+
+
+class TestWithProtoFeature(unittest.TestCase):
+    """Test class for with_proto functionality"""
+
+    def test_predict_with_proto_parameter_exists(self):
+        """Test that _predict method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._predict)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_generate_with_proto_parameter_exists(self):
+        """Test that _generate method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._generate)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_stream_with_proto_parameter_exists(self):
+        """Test that _stream method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._stream)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_async_predict_with_proto_parameter_exists(self):
+        """Test that _async_predict method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._async_predict)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_async_generate_with_proto_parameter_exists(self):
+        """Test that _async_generate method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._async_generate)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_async_stream_with_proto_parameter_exists(self):
+        """Test that _async_stream method has with_proto parameter"""
+        import inspect
+
+        sig = inspect.signature(ModelClient._async_stream)
+        self.assertIn('with_proto', sig.parameters)
+        self.assertIs(sig.parameters['with_proto'].default, False)
+
+    def test_with_proto_parameter_extraction(self):
+        """Test that with_proto parameter is correctly extracted from kwargs"""
+        # Test the parameter extraction logic used in bind_f
+        test_kwargs = {'param1': 'value1', 'with_proto': True, 'param2': 'value2'}
+
+        # Extract with_proto parameter like the code does
+        with_proto = test_kwargs.pop('with_proto', False)
+
+        # Verify extraction worked correctly
+        self.assertIs(with_proto, True)
+        self.assertNotIn('with_proto', test_kwargs)
+        self.assertEqual(test_kwargs, {'param1': 'value1', 'param2': 'value2'})
+
+    def test_with_proto_default_behavior(self):
+        """Test that with_proto defaults to False when not provided"""
+        test_kwargs = {'param1': 'value1', 'param2': 'value2'}
+
+        # Extract with_proto parameter with default
+        with_proto = test_kwargs.pop('with_proto', False)
+
+        # Verify default behavior
+        self.assertIs(with_proto, False)
+        self.assertEqual(test_kwargs, {'param1': 'value1', 'param2': 'value2'})
+
+    @patch('clarifai.client.model_client.serialize')
+    @patch('clarifai.client.model_client.deserialize')
+    def test_predict_with_proto_false(self, mock_deserialize, mock_serialize):
+        """Test _predict method with with_proto=False returns only result"""
+        # Setup mocks
+        mock_deserialize.return_value = "test_result"
+        mock_serialize.return_value = None
+
+        # Create mock response
+        mock_response = service_pb2.MultiOutputResponse()
+        mock_response.status.code = status_code_pb2.SUCCESS
+        output = mock_response.outputs.add()
+
+        # Create mock stub
+        mock_stub = Mock()
+        mock_stub.PostModelOutputs.return_value = mock_response
+
+        # Create client with mock method signatures
+        request_template = service_pb2.PostModelOutputsRequest()
+        client = ModelClient(stub=mock_stub, request_template=request_template)
+
+        # Mock method signature
+        method_signature = Mock()
+        method_signature.input_fields = []
+        method_signature.output_fields = []
+
+        client._method_signatures = {'predict': method_signature}
+
+        # Test with with_proto=False
+        result = client._predict({'text': 'test'}, 'predict', with_proto=False)
+
+        # Should return only the result, not a tuple
+        self.assertEqual(result, "test_result")
+        self.assertNotIsInstance(result, tuple)
+
+    @patch('clarifai.client.model_client.serialize')
+    @patch('clarifai.client.model_client.deserialize')
+    def test_predict_with_proto_true(self, mock_deserialize, mock_serialize):
+        """Test _predict method with with_proto=True returns (result, proto) tuple"""
+        # Setup mocks
+        mock_deserialize.return_value = "test_result"
+        mock_serialize.return_value = None
+
+        # Create mock response
+        mock_response = service_pb2.MultiOutputResponse()
+        mock_response.status.code = status_code_pb2.SUCCESS
+        output = mock_response.outputs.add()
+
+        # Create mock stub
+        mock_stub = Mock()
+        mock_stub.PostModelOutputs.return_value = mock_response
+
+        # Create client with mock method signatures
+        request_template = service_pb2.PostModelOutputsRequest()
+        client = ModelClient(stub=mock_stub, request_template=request_template)
+
+        # Mock method signature
+        method_signature = Mock()
+        method_signature.input_fields = []
+        method_signature.output_fields = []
+
+        client._method_signatures = {'predict': method_signature}
+
+        # Test with with_proto=True
+        result = client._predict({'text': 'test'}, 'predict', with_proto=True)
+
+        # Should return tuple (result, proto)
+        self.assertIsInstance(result, tuple)
+        self.assertEqual(len(result), 2)
+        self.assertEqual(result[0], "test_result")  # The deserialized result
+        self.assertEqual(result[1], mock_response)  # The proto response
+
+    def test_backward_compatibility(self):
+        """Test that existing code without with_proto continues to work"""
+        # This test ensures that the changes don't break existing functionality
+
+        # Mock the method binding
+        method_argnames = ['text', 'temperature']
+
+        # Simulate existing call without with_proto
+        args = ('test input',)
+        kwargs = {'temperature': 0.7}
+
+        # Extract with_proto (should default to False)
+        with_proto = kwargs.pop('with_proto', False)
+
+        # Verify existing behavior is preserved
+        self.assertIs(with_proto, False)
+        self.assertEqual(len(args), 1)
+        self.assertEqual(kwargs, {'temperature': 0.7})
+
+        # Ensure parameter count validation still works
+        self.assertLessEqual(len(args), len(method_argnames))
+        self.assertLessEqual(len(args) + len(kwargs), len(method_argnames))
+
+    def test_documentation_shows_with_proto_support(self):
+        """Test that the feature is properly documented in method docstrings"""
+
+    def test_reserved_parameter_validation(self):
+        """Test that with_proto parameter name is properly validated in ModelClass methods"""
+        from clarifai.runners.utils.method_signatures import (
+            RESERVED_PARAM_WITH_PROTO,
+            build_function_signature,
+        )
+
+        # Test that a function with with_proto parameter raises an error
+        def invalid_method(self, text: str, with_proto: bool = False) -> str:
+            return text
+
+        with self.assertRaises(ValueError) as context:
+            build_function_signature(invalid_method)
+
+        error_msg = str(context.exception)
+        self.assertIn(RESERVED_PARAM_WITH_PROTO, error_msg)
+        self.assertIn("reserved", error_msg.lower())
+
+    def test_reserved_parameter_constant_usage(self):
+        """Test that the constant is used consistently in ModelClient"""
+        from clarifai.runners.utils.method_signatures import RESERVED_PARAM_WITH_PROTO
+
+        # Test parameter extraction using the constant
+        test_kwargs = {'param1': 'value1', RESERVED_PARAM_WITH_PROTO: True, 'param2': 'value2'}
+
+        # Extract with_proto parameter using the constant
+        with_proto = test_kwargs.pop(RESERVED_PARAM_WITH_PROTO, False)
+
+        # Verify extraction worked correctly
+        self.assertIs(with_proto, True)
+        self.assertNotIn(RESERVED_PARAM_WITH_PROTO, test_kwargs)
+        self.assertEqual(test_kwargs, {'param1': 'value1', 'param2': 'value2'})
+
+
+if __name__ == '__main__':
+    unittest.main()

clarifai-11.8.4/clarifai/__init__.py

@@ -1 +0,0 @@
-__version__ = "11.8.4"