{"id":7082,"library":"clarifai-protocol","title":"Clarifai Protocol","description":"clarifai-protocol is a Python library that provides the core Protocol Buffer definitions and generated Python code for interacting with Clarifai's gRPC services. It encapsulates the data structures (messages) and service interfaces (stubs) used for communication within the Clarifai platform, especially relevant for custom model deployment and advanced integrations. The current version is 0.0.61, and it follows a frequent release cadence to align with protocol definition updates.","status":"active","version":"0.0.61","language":"en","source_language":"en","source_url":"https://github.com/Clarifai/clarifai-protocol","tags":["clarifai","protocol","grpc","protobuf","mlops","ai","low-level"],"install":[{"cmd":"pip install clarifai-protocol","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for gRPC client/server functionality, which is the underlying communication protocol.","package":"grpcio","optional":false},{"reason":"Provides tools for working with gRPC, often used for code generation but also as a runtime dependency.","package":"grpcio-tools","optional":false},{"reason":"Google's Protocol Buffers library, essential for serializing and deserializing the structured data messages.","package":"protobuf","optional":false}],"imports":[{"note":"The generated Python code places the imports under `clarifai_grpc`, not `clarifai_protocol`.","wrong":"from clarifai_protocol.grpc.api.resources_pb2 import Image","symbol":"Image","correct":"from clarifai_grpc.grpc.api.resources_pb2 import Image"},{"note":"Service stubs are also found under the `clarifai_grpc` namespace.","wrong":"from clarifai_protocol.grpc.api.service_pb2_grpc import V2Stub","symbol":"V2Stub","correct":"from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub"},{"note":"Commonly used for authentication and context in gRPC requests.","symbol":"UserAppIDSet","correct":"from clarifai_grpc.grpc.api.resources_pb2 import UserAppIDSet"}],"quickstart":{"code":"from clarifai_grpc.grpc.api.resources_pb2 import Image, UserAppIDSet\nfrom clarifai_grpc.grpc.api.service_pb2 import PostModelOutputsRequest\nfrom clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub\nimport grpc\nimport os\n\n# This library primarily provides the definitions. Actual API calls require grpcio and a channel.\n\n# Example: Instantiate a protobuf message\nimage_message = Image(url=\"https://samples.clarifai.com/face-det.jpg\")\nprint(f\"Created Image message with URL: {image_message.url}\")\n\n# Example: Create a stub (though actual usage requires a gRPC channel and credentials)\n# For demonstration purposes, we'll just show the import and instantiation of the stub class.\n# In a real scenario, you'd pass a channel: V2Stub(grpc.insecure_channel('api.clarifai.com:443'))\ntry:\n    channel = grpc.insecure_channel('api.clarifai.com:443') # Using a dummy channel for concept\n    stub = V2Stub(channel)\n    print(f\"Successfully created a V2Stub instance.\")\n    channel.close()\nexcept Exception as e:\n    print(f\"Could not create a real gRPC channel for demonstration: {e}\")\n    print(\"Stub instantiation shown for clarity, but requires a functional gRPC channel.\")\n\n# Example: A request message, typically constructed using these resources\nrequest = PostModelOutputsRequest(\n    user_app_id=UserAppIDSet(user_id=os.environ.get('CLARIFAI_USER_ID', ''), app_id=os.environ.get('CLARIFAI_APP_ID', '')),\n    model_id=\"my-model\",\n    inputs=[] # inputs would go here\n)\nprint(f\"Created PostModelOutputsRequest for model: {request.model_id}\")","lang":"python","description":"This quickstart demonstrates how to import and instantiate core Protocol Buffer messages like `Image` and `UserAppIDSet`, and how to access a gRPC service stub like `V2Stub`. While it shows creating a request message, actual API interaction requires setting up a gRPC channel and credentials, which falls outside the scope of `clarifai-protocol` itself, but relies on its definitions."},"warnings":[{"fix":"Always check the release notes for `clarifai-protocol` and update your code to match the new field names, types, or message structures. Re-generating your own code from `.proto` files if you maintain a fork might also be necessary.","message":"Changes to the underlying Clarifai Protocol Buffer (.proto) definitions directly lead to breaking changes in the generated Python classes (e.g., field renames, type changes, field removals).","severity":"breaking","affected_versions":"All versions, as it reflects the protocol. Major changes often correspond to significant version bumps of clarifai-protocol."},{"fix":"If you intend to use a high-level SDK for interacting with Clarifai APIs, you likely want `pip install clarifai`. Use `clarifai-protocol` when building custom gRPC services, runners, or directly manipulating Protobuf messages for advanced integrations.","message":"The `clarifai-protocol` library is NOT the high-level Clarifai Python Client Library (which is typically `clarifai` or `clarifai-client`). This library provides the low-level gRPC/Protobuf definitions.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Remember that `resources_pb2` is for messages like `Image` or `Concept`, while `service_pb2_grpc` is for stubs like `V2Stub` or `PublicServiceStub`. Import carefully based on whether you need a data structure or a service interface.","message":"Confusing `*_pb2` and `*_pb2_grpc` modules. `_pb2` modules contain the generated Protobuf message classes (data structures), while `_pb2_grpc` modules contain the generated gRPC service stubs (client interfaces) and servicer classes (server interfaces).","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the library is installed with `pip install clarifai-protocol`. Verify that the import path is `from clarifai_grpc.grpc.api...` and not `from clarifai_protocol.grpc.api...`.","cause":"The `clarifai-protocol` library is not installed, or the import path is incorrect.","error":"ModuleNotFoundError: No module named 'clarifai_grpc.grpc.api.resources_pb2'"},{"fix":"Consult the `clarifai-protocol` documentation or the `.proto` files in the GitHub repository for the correct field name. For example, `image_url` might have been changed to simply `url`.","cause":"A Protobuf message field has been renamed or removed in a newer version of the protocol definition.","error":"AttributeError: 'Image' object has no attribute 'image_url'"}]}