clarifai 11.4.3rc1__py3-none-any.whl → 11.4.5__py3-none-any.whl

clarifai/runners/models/model_builder.py

@@ -413,6 +413,12 @@ class ModelBuilder:
     def get_method_signatures(self, mocking=True):
         """
         Returns the method signatures for the model class.
+
+        Args:
+          mocking (bool): Whether to mock the model class or not. Defaults to False.
+
+        Returns:
+          list: A list of method signatures for the model class.
         """
         model_class = self.load_model_class(mocking=mocking)
         method_info = model_class._get_method_info()
@@ -436,22 +442,42 @@ class ModelBuilder:
         return self._client
 
     @property
-    def model_url(self):
+    def model_ui_url(self):
+        url_helper = ClarifaiUrlHelper(self._client.auth_helper)
+        # Note(zeiler): the UI experience isn't the best when including version id right now.
+        # if self.model_version_id is not None:
+        #     return url_helper.clarifai_url(
+        #         self.client.user_app_id.user_id,
+        #         self.client.user_app_id.app_id,
+        #         "models",
+        #         self.model_id,
+        #         self.model_version_id,
+        #     )
+        # else:
+        return url_helper.clarifai_url(
+            self.client.user_app_id.user_id,
+            self.client.user_app_id.app_id,
+            "models",
+            self.model_id,
+        )
+
+    @property
+    def model_api_url(self):
         url_helper = ClarifaiUrlHelper(self._client.auth_helper)
         if self.model_version_id is not None:
-            return url_helper.clarifai_url(
+            return url_helper.api_url(
                 self.client.user_app_id.user_id,
                 self.client.user_app_id.app_id,
                 "models",
                 self.model_id,
+                self.model_version_id,
             )
         else:
-            return url_helper.clarifai_url(
+            return url_helper.api_url(
                 self.client.user_app_id.user_id,
                 self.client.user_app_id.app_id,
                 "models",
                 self.model_id,
-                self.model_version_id,
             )
 
     def _get_model_proto(self):
@@ -930,44 +956,20 @@ class ModelBuilder:
             return
         self.model_version_id = response.model_version_id
         logger.info(f"Created Model Version ID: {self.model_version_id}")
-        logger.info(f"Full url to that version is: {self.model_url}")
+        logger.info(f"Full url to that version is: {self.model_ui_url}")
         try:
             is_uploaded = self.monitor_model_build()
             if is_uploaded:
-                # Provide an mcp client config
-                if model_type_id == "mcp":
-                    snippet = (
-                        """
-import asyncio
-import os
-from fastmcp import Client
-from fastmcp.client.transports import StreamableHttpTransport
-
-transport = StreamableHttpTransport(url="%s/mcp",
-                                    headers={"Authorization": "Bearer " + os.environ["CLARIFAI_PAT"]})
-
-async def main():
-  async with Client(transport) as client:
-    tools = await client.list_tools()
-    print(f"Available tools: {tools}")
-    result = await client.call_tool(tools[0].name, {"a": 5, "b": 3})
-    print(f"Result: {result[0].text}")
-
-if __name__ == "__main__":
-  asyncio.run(main())
-"""
-                        % self.model_url
-                    )
-                else:  # python code to run the model.
-                    from clarifai.runners.utils import code_script
-
-                    method_signatures = self.get_method_signatures()
-                    snippet = code_script.generate_client_script(
-                        method_signatures,
-                        user_id=self.client.user_app_id.user_id,
-                        app_id=self.client.user_app_id.app_id,
-                        model_id=self.model_proto.id,
-                    )
+                # python code to run the model.
+                from clarifai.runners.utils import code_script
+
+                method_signatures = self.get_method_signatures()
+                snippet = code_script.generate_client_script(
+                    method_signatures,
+                    user_id=self.client.user_app_id.user_id,
+                    app_id=self.client.user_app_id.app_id,
+                    model_id=self.model_proto.id,
+                )
                 logger.info("""\n
 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 # Here is a code snippet to use this model:
@@ -1074,7 +1076,7 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                 logger.info("Model build complete!")
                 logger.info(f"Build time elapsed {time.time() - st:.1f}s)")
                 logger.info(
-                    f"Check out the model at {self.model_url} version: {self.model_version_id}"
+                    f"Check out the model at {self.model_ui_url} version: {self.model_version_id}"
                 )
                 return True
             else:
@@ -1099,10 +1101,12 @@ def upload_model(folder, stage, skip_dockerfile):
     exists = builder.check_model_exists()
     if exists:
         logger.info(
-            f"Model already exists at {builder.model_url}, this upload will create a new version for it."
+            f"Model already exists at {builder.model_ui_url}, this upload will create a new version for it."
         )
     else:
-        logger.info(f"New model will be created at {builder.model_url} with it's first version.")
+        logger.info(
+            f"New model will be created at {builder.model_ui_url} with it's first version."
+        )
 
     input("Press Enter to continue...")
     builder.upload_model_version()

clarifai/runners/models/openai_class.py

@@ -0,0 +1,219 @@
+"""Base class for creating OpenAI-compatible API server."""
+
+import json
+from typing import Any, Dict, Iterator
+
+from clarifai.runners.models.model_class import ModelClass
+
+
+class OpenAIModelClass(ModelClass):
+    """Base class for wrapping OpenAI-compatible servers as a model running in Clarifai.
+    This handles all the transport between the API and the OpenAI-compatible server.
+
+    To use this class, create a subclass and set the following class attributes:
+    - openai_client: The OpenAI-compatible client instance
+    - model_name: The name of the model to use with the client
+
+    Example:
+        class MyOpenAIModel(OpenAIModelClass):
+            openai_client = OpenAI(api_key="your-key")
+            model_name = "gpt-4"
+    """
+
+    # These should be overridden in subclasses
+    openai_client = None
+    model_name = None
+
+    def __init__(self) -> None:
+        if self.openai_client is None:
+            raise NotImplementedError("Subclasses must set the 'openai_client' class attribute")
+        if self.model_name is None:
+            self.model_name = self.openai_client.models.list().data[0].id
+
+        self.client = self.openai_client
+        self.model = self.model_name
+
+    def _extract_request_params(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract and validate common openai arguments parameters from the request data.
+
+        Args:
+            request_data: The parsed JSON request data
+
+        Returns:
+            Dict containing the extracted parameters
+        """
+        return {
+            "messages": request_data.get("messages", []),
+            "temperature": request_data.get("temperature", 1.0),
+            "max_tokens": request_data.get("max_tokens"),
+            "max_completion_tokens": request_data.get("max_completion_tokens"),
+            "n": request_data.get("n", 1),
+            "frequency_penalty": request_data.get("frequency_penalty"),
+            "presence_penalty": request_data.get("presence_penalty"),
+            "top_p": request_data.get("top_p", 1.0),
+            "reasoning_effort": request_data.get("reasoning_effort"),
+            "response_format": request_data.get("response_format"),
+            "stop": request_data.get("stop"),
+            "tools": request_data.get("tools"),
+            "tool_choice": request_data.get("tool_choice"),
+            "tool_resources": request_data.get("tool_resources"),
+            "modalities": request_data.get("modalities"),
+            "stream_options": request_data.get("stream_options", {"include_usage": True}),
+        }
+
+    def _create_completion_args(
+        self, params: Dict[str, Any], stream: bool = False
+    ) -> Dict[str, Any]:
+        """Create the completion arguments dictionary from parameters.
+
+        Args:
+            params: Dictionary of parameters extracted from request
+            stream: Whether this is a streaming request
+
+        Returns:
+            Dict containing the completion arguments
+        """
+        completion_args = {
+            "model": self.model,
+            "messages": params["messages"],
+            "temperature": params["temperature"],
+        }
+
+        if stream:
+            completion_args["stream"] = True
+            if params.get("stream_options"):
+                completion_args["stream_options"] = params["stream_options"]
+
+        # Add optional parameters if they exist
+        optional_params = [
+            "max_tokens",
+            "max_completion_tokens",
+            "n",
+            "frequency_penalty",
+            "presence_penalty",
+            "top_p",
+            "reasoning_effort",
+            "response_format",
+            "stop",
+            "tools",
+            "tool_choice",
+            "tool_resources",
+            "modalities",
+        ]
+
+        for param in optional_params:
+            if params.get(param) is not None:
+                completion_args[param] = params[param]
+
+        return completion_args
+
+    def _format_error_response(self, error: Exception) -> str:
+        """Format an error response in OpenAI-compatible format.
+
+        Args:
+            error: The exception that occurred
+
+        Returns:
+            JSON string containing the error response
+        """
+        error_response = {
+            "error": {
+                "message": str(error),
+                "type": "InvalidRequestError",
+                "code": "invalid_request_error",
+            }
+        }
+        return json.dumps(error_response)
+
+    @ModelClass.method
+    def openai_transport(self, msg: str) -> str:
+        """The single model method to get the OpenAI-compatible request and send it to the OpenAI server
+        then return its response.
+
+        Args:
+            msg: JSON string containing the request parameters
+
+        Returns:
+            JSON string containing the response or error
+        """
+        try:
+            request_data = json.loads(msg)
+            params = self._extract_request_params(request_data)
+            stream = request_data.get("stream", False)
+
+            if stream:
+                chunks = self._process_streaming_request(**params)
+                response_list = []
+                for chunk in chunks:
+                    response_list.append(chunk)
+                return json.dumps(response_list)
+            else:
+                completion = self._process_request(**params)
+                if completion.get('usage'):
+                    if completion['usage'].get('prompt_tokens') and completion['usage'].get(
+                        'completion_tokens'
+                    ):
+                        self.set_output_context(
+                            prompt_tokens=completion['usage']['prompt_tokens'],
+                            completion_tokens=completion['usage']['completion_tokens'],
+                        )
+
+                return json.dumps(completion)
+
+        except Exception as e:
+            return self._format_error_response(e)
+
+    @ModelClass.method
+    def openai_stream_transport(self, msg: str) -> Iterator[str]:
+        """Process an OpenAI-compatible request and return a streaming response iterator.
+        This method is used when stream=True and returns an iterator of strings directly,
+        without converting to a list or JSON serializing.
+
+        Args:
+            msg: The request as a JSON string.
+
+        Returns:
+            Iterator[str]: An iterator yielding text chunks from the streaming response.
+        """
+        try:
+            request_data = json.loads(msg)
+            params = self._extract_request_params(request_data)
+            for chunk in self._process_streaming_request(**params):
+                if chunk.get('usage'):
+                    if chunk['usage'].get('prompt_tokens') and chunk['usage'].get(
+                        'completion_tokens'
+                    ):
+                        self.set_output_context(
+                            prompt_tokens=chunk['usage']['prompt_tokens'],
+                            completion_tokens=chunk['usage']['completion_tokens'],
+                        )
+                yield json.dumps(chunk)
+        except Exception as e:
+            yield f"Error: {str(e)}"
+
+    def _process_request(self, **kwargs) -> Any:
+        """Process a standard (non-streaming) request using the OpenAI client.
+
+        Args:
+            **kwargs: Request parameters
+
+        Returns:
+            The completion response from the OpenAI client
+        """
+        completion_args = self._create_completion_args(kwargs)
+        return self.client.chat.completions.create(**completion_args).to_dict()
+
+    def _process_streaming_request(self, **kwargs) -> Iterator[str]:
+        """Process a streaming request using the OpenAI client.
+
+        Args:
+            **kwargs: Request parameters
+
+        Returns:
+            Iterator yielding response chunks
+        """
+        completion_args = self._create_completion_args(kwargs, stream=True)
+        completion_stream = self.client.chat.completions.create(**completion_args)
+
+        for chunk in completion_stream:
+            yield chunk.to_dict()

clarifai/runners/utils/code_script.py

@@ -4,6 +4,7 @@ from typing import List
 from clarifai_grpc.grpc.api import resources_pb2
 
 from clarifai.runners.utils import data_utils
+from clarifai.urls.helper import ClarifaiUrlHelper
 
 
 def generate_client_script(
@@ -15,6 +16,38 @@ def generate_client_script(
     deployment_id: str = None,
     use_ctx: bool = False,
 ) -> str:
+    url_helper = ClarifaiUrlHelper()
+
+    # Provide an mcp client config
+    if len(method_signatures) == 1 and method_signatures[0].name == "mcp_transport":
+        api_url = url_helper.api_url(
+            user_id,
+            app_id,
+            "models",
+            model_id,
+        )
+
+        _CLIENT_TEMPLATE = """
+import asyncio
+import os
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(url="%s/mcp",
+                                    headers={"Authorization": "Bearer " + os.environ["CLARIFAI_PAT"]})
+
+async def main():
+  async with Client(transport) as client:
+    tools = await client.list_tools()
+    print(f"Available tools: {tools}")
+    result = await client.call_tool(tools[0].name, {"a": 5, "b": 3})
+    print(f"Result: {result[0].text}")
+
+if __name__ == "__main__":
+  asyncio.run(main())
+"""
+        return _CLIENT_TEMPLATE % api_url
+
     _CLIENT_TEMPLATE = """\
 import os
 
@@ -35,8 +68,9 @@ from clarifai.runners.utils import data_types
         model_section = """
 model = Model.from_current_context()"""
     else:
+        model_ui_url = url_helper.clarifai_url(user_id, app_id, "models", model_id)
         model_section = f"""
-model = Model("https://clarifai.com/{user_id}/{app_id}/models/{model_id}",
+model = Model({model_ui_url},
                deployment_id = {deployment_id}, # Only needed for dedicated deployed models
                {base_url_str}
  )
@@ -53,13 +87,10 @@ model = Model("https://clarifai.com/{user_id}/{app_id}/models/{model_id}",
         method_name = method_signature.name
         client_script_str = f'response = model.{method_name}('
         annotations = _get_annotations_source(method_signature)
-        for param_name, (param_type, default_value) in annotations.items():
-            print(
-                f"param_name: {param_name}, param_type: {param_type}, default_value: {default_value}"
-            )
+        for param_name, (param_type, default_value, required) in annotations.items():
             if param_name == "return":
                 continue
-            if default_value is None:
+            if default_value is None and required:
                 default_value = _set_default_value(param_type)
             client_script_str += f"{param_name}={default_value}, "
         client_script_str = client_script_str.rstrip(", ") + ")"
@@ -98,7 +129,7 @@ def _get_annotations_source(method_signature: resources_pb2.MethodSignature) ->
         default_value = None
         if data_utils.Param.get_default(input_field):
             default_value = _parse_default_value(input_field)
-        annotations[param_name] = (param_type, default_value)
+        annotations[param_name] = (param_type, default_value, input_field.required)
     if not method_signature.output_fields:
         raise ValueError("MethodSignature must have at least one output field")
     for output_field in method_signature.output_fields:
@@ -106,7 +137,7 @@ def _get_annotations_source(method_signature: resources_pb2.MethodSignature) ->
         param_type = _get_base_type(output_field)
         if output_field.iterator:
             param_type = f"Iterator[{param_type}]"
-        annotations[param_name] = (param_type, None)
+        annotations[param_name] = (param_type, None, output_field.required)
     return annotations
 
 
@@ -155,7 +186,7 @@ def _map_default_value(field_type):
     default_value = None
 
     if field_type == "str":
-        default_value = 'What is the future of AI?'
+        default_value = repr('What is the future of AI?')
     elif field_type == "bytes":
         default_value = b""
     elif field_type == "int":
@@ -190,11 +221,9 @@ def _set_default_value(field_type):
     Set the default value of a field if it is not set.
     """
     is_iterator = False
-    print(f"before field_type: {field_type}")
     if field_type.startswith("Iterator["):
         is_iterator = True
         field_type = field_type[9:-1]
-    print(f"after field_type: {field_type}")
     default_value = None
     default_value = _map_default_value(field_type)
     if field_type.startswith("List["):
@@ -211,11 +240,8 @@ def _set_default_value(field_type):
         element_type_defaults = [_map_default_value(et) for et in element_types]
         default_value = f"{{{', '.join([str(et) for et in element_type_defaults])}}}"
 
-    if field_type == 'str':
-        default_value = repr(default_value)
     if is_iterator:
         default_value = f'iter([{default_value}])'
-    print(f"after default_value: {default_value}")
     return default_value
 
 
@@ -233,7 +259,7 @@ def _parse_default_value(field: resources_pb2.ModelTypeField):
         elif data_type == resources_pb2.ModelTypeField.DataType.BOOL:
             return 'True' if default_str.lower() == 'true' else 'False'
         elif data_type == resources_pb2.ModelTypeField.DataType.STR:
-            return repr(default_str)
+            return default_str
         elif data_type == resources_pb2.ModelTypeField.DataType.BYTES:
             return f"b{repr(default_str.encode('utf-8'))}"
         elif data_type == resources_pb2.ModelTypeField.DataType.JSON_DATA:

clarifai/runners/utils/data_types/data_types.py

@@ -395,6 +395,22 @@ class Image(MessageData):
             raise ValueError("Image has no bytes")
         return PILImage.open(io.BytesIO(self.proto.base64))
 
+    def to_base64_str(self) -> str:
+        if not self.proto.base64:
+            raise ValueError("Image has no bytes")
+        if isinstance(self.proto.base64, str):
+            return self.proto.base64
+        if isinstance(self.proto.base64, bytes):
+            try:
+                # trying direct decode (if already a base64 bytes)
+                return self.proto.base64.decode('utf-8')
+            except UnicodeDecodeError:
+                import base64
+
+                return base64.b64encode(self.proto.base64).decode('utf-8')
+        else:
+            raise TypeError("Expected str or bytes for Image.base64")
+
     def to_numpy(self) -> np.ndarray:
         return np.asarray(self.to_pil())
 
@@ -466,6 +482,22 @@ class Audio(MessageData):
     def to_proto(self) -> AudioProto:
         return self.proto
 
+    def to_base64_str(self) -> str:
+        if not self.proto.base64:
+            raise ValueError("Audio has no bytes")
+        if isinstance(self.proto.base64, str):
+            return self.proto.base64
+        if isinstance(self.proto.base64, bytes):
+            try:
+                # trying direct decode (if already a base64 bytes)
+                return self.proto.base64.decode('utf-8')
+            except UnicodeDecodeError:
+                import base64
+
+                return base64.b64encode(self.proto.base64).decode('utf-8')
+        else:
+            raise TypeError("Expected str or bytes for Audio.base64")
+
     @classmethod
     def from_proto(cls, proto: AudioProto) -> "Audio":
         return cls(proto)
@@ -578,6 +610,22 @@ class Video(MessageData):
     def to_proto(self) -> VideoProto:
         return self.proto
 
+    def to_base64_str(self) -> str:
+        if not self.proto.base64:
+            raise ValueError("Video has no bytes")
+        if isinstance(self.proto.base64, str):
+            return self.proto.base64
+        if isinstance(self.proto.base64, bytes):
+            try:
+                # trying direct decode (if already a base64 bytes)
+                return self.proto.base64.decode('utf-8')
+            except UnicodeDecodeError:
+                import base64
+
+                return base64.b64encode(self.proto.base64).decode('utf-8')
+        else:
+            raise TypeError("Expected str or bytes for Video.base64")
+
     @classmethod
     def from_proto(cls, proto: VideoProto) -> "Video":
         return cls(proto)