Clarifai Protocol

0.0.61 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'clarifai_grpc.grpc.api.resources_pb2'
```
cause The `clarifai-protocol` library is not installed, or the import path is incorrect.

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...`.
```
AttributeError: 'Image' object has no attribute 'image_url'
```
cause A Protobuf message field has been renamed or removed in a newer version of the protocol definition.

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`.

Warnings

breaking 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).
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.
gotcha 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.
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.
gotcha 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).
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.

Install

pip install clarifai-protocol Install stable version

Imports

Image

wrong:

from clarifai_protocol.grpc.api.resources_pb2 import Image

correct:

from clarifai_grpc.grpc.api.resources_pb2 import Image

The generated Python code places the imports under `clarifai_grpc`, not `clarifai_protocol`.

V2Stub

wrong:

from clarifai_protocol.grpc.api.service_pb2_grpc import V2Stub

correct:

from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub

Service stubs are also found under the `clarifai_grpc` namespace.

UserAppIDSet
```
from clarifai_grpc.grpc.api.resources_pb2 import UserAppIDSet
```
Commonly used for authentication and context in gRPC requests.

Quickstart

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.

from clarifai_grpc.grpc.api.resources_pb2 import Image, UserAppIDSet
from clarifai_grpc.grpc.api.service_pb2 import PostModelOutputsRequest
from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub
import grpc
import os

# This library primarily provides the definitions. Actual API calls require grpcio and a channel.

# Example: Instantiate a protobuf message
image_message = Image(url="https://samples.clarifai.com/face-det.jpg")
print(f"Created Image message with URL: {image_message.url}")

# Example: Create a stub (though actual usage requires a gRPC channel and credentials)
# For demonstration purposes, we'll just show the import and instantiation of the stub class.
# In a real scenario, you'd pass a channel: V2Stub(grpc.insecure_channel('api.clarifai.com:443'))
try:
    channel = grpc.insecure_channel('api.clarifai.com:443') # Using a dummy channel for concept
    stub = V2Stub(channel)
    print(f"Successfully created a V2Stub instance.")
    channel.close()
except Exception as e:
    print(f"Could not create a real gRPC channel for demonstration: {e}")
    print("Stub instantiation shown for clarity, but requires a functional gRPC channel.")

# Example: A request message, typically constructed using these resources
request = PostModelOutputsRequest(
    user_app_id=UserAppIDSet(user_id=os.environ.get('CLARIFAI_USER_ID', ''), app_id=os.environ.get('CLARIFAI_APP_ID', '')),
    model_id="my-model",
    inputs=[] # inputs would go here
)
print(f"Created PostModelOutputsRequest for model: {request.model_id}")

view raw JSON →