Registry / ai-ml / clarifai-protocol

clarifai-protocol

JSON →
library0.0.62pypypi✓ verified 86d ago

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.

pip install clarifai-protocol
INSTALL
IMPORT
SIG · CLARIFAI-PROTOCOL
C
clarifai-protocol
ai-mlpythonv0.0.62
Install
16.3s avg
Import
474ms
Disk
234MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.62 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.856s · 231.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 16.3s · import 0.092s · 225MB
234MB installed
● package 234MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image
from clarifai_grpc.grpc.api.resources_pb2 import Image
from clarifai_protocol.grpc.api.resources_pb2 import Image
The generated Python code places the imports under `clarifai_grpc`, not `clarifai_protocol`.
V2Stub
from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub
from clarifai_protocol.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.

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}")
Debug
Known issues
breakingChanges 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.
affects: All versions, as it reflects the protocol. Major changes often correspond to significant version bumps of clarifai-protocol.
gotchaThe `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.
affects: All versions.
gotchaConfusing `*_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.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clarifai_grpc.grpc.api.resources_pb2'
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'
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`.
Upgrade
Version history
0.0.62latest on PyPI · released May 5, 2026
Audit
Dependencies
grpciorequiredRequired for gRPC client/server functionality, which is the underlying communication protocol.
grpcio-toolsrequiredProvides tools for working with gRPC, often used for code generation but also as a runtime dependency.
protobufrequiredGoogle's Protocol Buffers library, essential for serializing and deserializing the structured data messages.
Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources
clarifai-protocol — pip install clarifai-protocol · libregistry