Add optional protobuf response information in pythonic models with parameter validation

[Copilot]

Problem

When using pythonic models (subclasses of ModelClass), users could only access the processed/deserialized response from method calls like predict(), generate(), etc. However, the underlying protobuf API response contains valuable additional information such as:

• Status codes and error details
• Request IDs for debugging
• Performance metrics and timing information
• Raw metadata from the API

Users requested the ability to optionally access this underlying protobuf response while maintaining backward compatibility.

Solution

This PR adds support for an optional with_proto=True/False parameter to all pythonic model methods. When enabled, methods return both the processed result and the raw protobuf response as a tuple.

Key Features

• Universal Support: Works with any pythonic model method (predict, generate, stream, custom methods)
• Backward Compatible: Existing code unchanged - with_proto defaults to False
• Async Support: Full support for both sync and async model operations
• Streaming Support: Works with streaming methods like generate() and stream()
• Parameter Protection: Validates that user methods cannot use the reserved with_proto parameter name

Usage Examples

from clarifai.client import Model

model = Model(
    url="https://clarifai.com/user/app/models/my-model",
    pat="*****",
    deployment_id="my-deploy",
)

# Existing behavior (unchanged)
response = model.predict(
    prompt="What is the future of AI?", 
    reasoning_effort="medium"
)

# NEW: Access to protobuf response
response, proto = model.predict(
    prompt="What is the future of AI?", 
    reasoning_effort="medium",
    with_proto=True
)

# Access rich metadata for debugging and monitoring
print(f"Request ID: {proto.status.req_id}")
print(f"Status: {proto.status.code}")
print(f"Model Version: {proto.model.model_version.id}")

# Works with streaming operations
for response, proto in model.generate(prompt="Story", with_proto=True):
    print(f"Generated: {response}")
    print(f"Progress: {proto.status.percent_completed}")

# Works with any custom method defined in ModelClass
result, proto = model.my_custom_method(data="test", with_proto=True)

Parameter Name Protection

The framework now validates that user methods cannot use the reserved parameter name:

# This will raise a ValueError during method registration
@ModelClass.method
def predict(self, text: str, with_proto: bool) -> str:  # ❌ Error!
    return text

# This works fine  
@ModelClass.method  
def predict(self, text: str, temperature: float) -> str:  # ✅ Valid
    return text

Implementation Details

Core Changes

1. ModelClient Method Binding: Modified the dynamic method binding in bind_f() to extract and handle the with_proto parameter before argument validation
2. Core Methods Updated: All _predict, _generate, _stream methods (both sync and async versions) now accept with_proto parameter
3. Return Value Logic: When with_proto=True, methods return (result, proto_response) tuple; otherwise return just the result
4. Parameter Validation: Added RESERVED_PARAM_WITH_PROTO constant and validation in build_function_signature() to prevent conflicts
5. Code Quality: Fixed indentation issues in async streaming methods

Files Modified

• clarifai/client/model_client.py: Core implementation and constant usage
• clarifai/runners/utils/method_signatures.py: Parameter validation and constant definition
• tests/test_with_proto_feature.py: Comprehensive test suite (14 tests)
• examples/with_proto_demo.py: Usage examples and documentation

Backward Compatibility

The implementation is fully backward compatible:

• Default behavior (with_proto=False) unchanged
• Existing method signatures preserved
• No breaking changes to any APIs
• All existing tests continue to pass

Testing & Quality

• 14 comprehensive unit tests covering all scenarios including parameter validation
• Integration tests validate end-to-end functionality
• Security scan passed with zero vulnerabilities
• Code follows project linting and formatting standards

This enhancement provides powerful debugging and inspection capabilities while maintaining the clean, pythonic interface that users expect and preventing parameter name conflicts through proactive validation.

[!WARNING]

Original prompt

---

This section details on the original issue you should resolve

<filter_complete></filter_complete>

<issue_title>Optionally return additional information in pythonic models</issue_title>
<issue_description>When calling a pythonic model that is a sublcass of ModelClass we allow using the model_client.py code to call the function directly. So if the subclass of ModelClass has a method predict(prompt, reasoning_effort) then the client side can do:

rom clarifai.client import Model

model = Model(
  url = "https://clarifai.com/user/app/models/my-model",
  pat = "*****",
  deployment_id = "my-deploy",
)
response = model.predict(
    prompt = "What is the future of AI?", 
    reasoning_effort = "medium"
)
print(response)

We would like to allow any of those methods to accept an additional parameter like with_proto=True/False that would change the client side function call to return two pieces of information: 1) the current response as it does today and 2) additional details we have from the underlying protobuf by returning the underlying proto that the API returns.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #809

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Optionally return additional information in pythonic models</issue_title>
<issue_description>When calling a pythonic model that is a sublcass of ModelClass we allow using the model_client.py code to call the function directly. So if the subclass of ModelClass has a method predict(prompt, reasoning_effort) then the client side can do:

rom clarifai.client import Model

model = Model(
  url = "https://clarifai.com/user/app/models/my-model",
  pat = "*****",
  deployment_id = "my-deploy",
)
response = model.predict(
    prompt = "What is the future of AI?", 
    reasoning_effort = "medium"
)
print(response)

We would like to allow any of those methods to accept an additional parameter like with_proto=True/False that would change the client side function call to return two pieces of information: 1) the current response as it does today and 2) additional details we have from the underlying protobuf by returning the underlying proto that the API returns.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #809

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[zeiler]

can we ad "with_proto" as a constant and then in ModelClass verify that a user provided method does not have that argument name when they subclass ModelClass. That vailidation should be in method_signatures.py.

[Copilot]

Added RESERVED_PARAM_WITH_PROTO constant in method_signatures.py and validation in build_function_signature() to prevent user methods from using this reserved parameter name. ModelClient now uses the constant instead of hardcoded strings. Commit: 3b8ff57

[zeiler]

why did this get indented?

[Copilot]

Fixed the indentation issue - the "subsequent items are just the stream items" comment and async for loop were incorrectly indented inside the _input_proto_stream function. They should be at the module level. Commit: 3b8ff57

[zeiler]

@copilot please address comment.s

[github-actions]

Package	Line Rate	Health
clarifai	43%	❌
clarifai.cli	44%	❌
clarifai.cli.templates	33%	❌
clarifai.client	67%	➖
clarifai.client.auth	67%	➖
clarifai.constants	100%	✔
clarifai.datasets	100%	✔
clarifai.datasets.export	80%	✔
clarifai.datasets.upload	75%	➖
clarifai.datasets.upload.loaders	37%	❌
clarifai.models	100%	✔
clarifai.modules	0%	❌
clarifai.rag	72%	➖
clarifai.runners	53%	➖
clarifai.runners.models	58%	➖
clarifai.runners.pipeline_steps	41%	❌
clarifai.runners.pipelines	70%	➖
clarifai.runners.utils	63%	➖
clarifai.runners.utils.data_types	72%	➖
clarifai.schema	100%	✔
clarifai.urls	60%	➖
clarifai.utils	60%	➖
clarifai.utils.evaluation	67%	➖
clarifai.workflows	95%	✔
Summary	61% (8120 / 13219)	➖

Minimum allowed line rate is 50%