refactor: simplify proto_utils metadata conversion and add utility functions

- Remove complex automatic type inference from translation layer
- Replace custom _convert_value_to_proto/_convert_proto_to_value with simple dict_to_struct and json_format.MessageToDict
- Add standalone utility functions for preprocessing/post-processing:
  - make_dict_serializable: converts non-serializable values to strings
  - normalize_large_integers_to_strings: handles JavaScript MAX_SAFE_INTEGER compatibility
  - parse_string_integers_in_dict: converts large integer strings back to integers
- Update tests to use new utility functions and add comprehensive test coverage
- Ensure bidirectional conversion consistency and user control over normalization

This addresses concerns about automatic string-to-integer inference causing
incompatibility between representations. The translation layer is now simple
and predictable, with normalization being the responsibility of consumers.

Author: sven-cy-yu

src/a2a/utils/proto_utils.py

@@ -23,9 +23,6 @@
     r'tasks/([\w-]+)/pushNotificationConfigs/([\w-]+)'
 )
 
-# Maximum safe integer digits (JavaScript MAX_SAFE_INTEGER is 2^53 - 1)
-_MAX_SAFE_INTEGER_DIGITS = 15
-
 
 class ToProto:
     """Converts Python types to proto types."""
@@ -49,59 +46,7 @@ def metadata(
     ) -> struct_pb2.Struct | None:
         if metadata is None:
             return None
-        return struct_pb2.Struct(
-            fields={
-                key: cls._convert_value_to_proto(value)
-                for key, value in metadata.items()
-            }
-        )
-
-    @classmethod
-    def _make_dict_serializable(cls, value: Any) -> Any:
-        if isinstance(value, dict):
-            return {k: cls._make_dict_serializable(v) for k, v in value.items()}
-        if isinstance(value, (list | tuple)):
-            return [cls._make_dict_serializable(item) for item in value]
-        if isinstance(value, (str | int | float | bool)) or value is None:
-            return value
-        return str(value)
-
-    @classmethod
-    def _convert_value_to_proto(cls, value: Any) -> struct_pb2.Value:
-        if value is None:
-            proto_value = struct_pb2.Value()
-            proto_value.null_value = struct_pb2.NullValue.NULL_VALUE
-            return proto_value
-
-        if isinstance(value, bool):
-            return struct_pb2.Value(bool_value=value)
-
-        if isinstance(value, int):
-            if abs(value) > (2**53 - 1):
-                return struct_pb2.Value(string_value=str(value))
-            return struct_pb2.Value(number_value=float(value))
-
-        if isinstance(value, float):
-            return struct_pb2.Value(number_value=value)
-
-        if isinstance(value, str):
-            return struct_pb2.Value(string_value=value)
-
-        if isinstance(value, dict):
-            serializable_dict = cls._make_dict_serializable(value)
-            json_data = json.dumps(serializable_dict, ensure_ascii=False)
-            struct_value = struct_pb2.Struct()
-            json_format.Parse(json_data, struct_value)
-            return struct_pb2.Value(struct_value=struct_value)
-
-        if isinstance(value, (list | tuple)):
-            list_value = struct_pb2.ListValue()
-            for item in value:
-                converted_item = cls._convert_value_to_proto(item)
-                list_value.values.append(converted_item)
-            return struct_pb2.Value(list_value=list_value)
-
-        return struct_pb2.Value(string_value=str(value))
+        return dict_to_struct(metadata)
 
     @classmethod
     def part(cls, part: types.Part) -> a2a_pb2.Part:
@@ -542,37 +487,9 @@ def message(cls, message: a2a_pb2.Message) -> types.Message:
 
     @classmethod
     def metadata(cls, metadata: struct_pb2.Struct) -> dict[str, Any]:
-        return {
-            key: cls._convert_proto_to_value(value)
-            for key, value in metadata.fields.items()
-        }
-
-    @classmethod
-    def _convert_proto_to_value(cls, value: struct_pb2.Value) -> Any:
-        if value.HasField('null_value'):
-            return None
-        if value.HasField('bool_value'):
-            return value.bool_value
-        if value.HasField('number_value'):
-            return value.number_value
-        if value.HasField('string_value'):
-            string_val = value.string_value
-            if (
-                string_val.lstrip('-').isdigit()
-                and len(string_val.lstrip('-')) > _MAX_SAFE_INTEGER_DIGITS
-            ):
-                return int(string_val)
-            return string_val
-        if value.HasField('struct_value'):
-            return {
-                k: cls._convert_proto_to_value(v)
-                for k, v in value.struct_value.fields.items()
-            }
-        if value.HasField('list_value'):
-            return [
-                cls._convert_proto_to_value(v) for v in value.list_value.values
-            ]
-        return None
+        if not metadata.fields:
+            return {}
+        return json_format.MessageToDict(metadata)
 
     @classmethod
     def part(cls, part: a2a_pb2.Part) -> types.Part:
@@ -1044,3 +961,85 @@ def dict_to_struct(dictionary: dict[str, Any]) -> struct_pb2.Struct:
         else:
             struct[key] = val
     return struct
+
+
+def make_dict_serializable(value: Any) -> Any:
+    """Dict preprocessing utility: converts non-serializable values to serializable form.
+
+    Use this when you want to normalize a dictionary before dict->Struct conversion.
+
+    Args:
+        value: The value to convert.
+
+    Returns:
+        A serializable value.
+    """
+    if isinstance(value, dict):
+        return {k: make_dict_serializable(v) for k, v in value.items()}
+    if isinstance(value, list | tuple):
+        return [make_dict_serializable(item) for item in value]
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    return str(value)
+
+
+def normalize_large_integers_to_strings(
+    value: Any, max_safe_digits: int = 15
+) -> Any:
+    """Integer preprocessing utility: converts large integers to strings.
+
+    Use this when you want to convert large integers to strings considering
+    JavaScript's MAX_SAFE_INTEGER (2^53 - 1) limitation.
+
+    Args:
+        value: The value to convert.
+        max_safe_digits: Maximum safe integer digits (default: 15).
+
+    Returns:
+        A normalized value.
+    """
+    if isinstance(value, dict):
+        return {
+            k: normalize_large_integers_to_strings(v, max_safe_digits)
+            for k, v in value.items()
+        }
+    if isinstance(value, list | tuple):
+        return [
+            normalize_large_integers_to_strings(item, max_safe_digits)
+            for item in value
+        ]
+    if isinstance(value, int) and abs(value) > (10**max_safe_digits - 1):
+        return str(value)
+    return value
+
+
+def parse_string_integers_in_dict(value: Any, max_safe_digits: int = 15) -> Any:
+    """String post-processing utility: converts large integer strings back to integers.
+
+    Use this when you want to restore large integer strings to integers
+    after Struct->dict conversion.
+
+    Args:
+        value: The value to convert.
+        max_safe_digits: Maximum safe integer digits (default: 15).
+
+    Returns:
+        A parsed value.
+    """
+    if isinstance(value, dict):
+        return {
+            k: parse_string_integers_in_dict(v, max_safe_digits)
+            for k, v in value.items()
+        }
+    if isinstance(value, list | tuple):
+        return [
+            parse_string_integers_in_dict(item, max_safe_digits)
+            for item in value
+        ]
+    if (
+        isinstance(value, str)
+        and value.lstrip('-').isdigit()
+        and len(value.lstrip('-')) > max_safe_digits
+    ):
+        return int(value)
+    return value

tests/utils/test_proto_utils.py

@@ -298,7 +298,7 @@ def test_metadata_conversion(self):
         assert roundtrip_metadata['complex_list'][0]['name'] == 'item1'
 
     def test_metadata_with_custom_objects(self):
-        """Test metadata conversion with custom objects that need str() fallback."""
+        """Test metadata conversion with custom objects using preprocessing utility."""
 
         class CustomObject:
             def __str__(self):
@@ -313,8 +313,11 @@ def __repr__(self):
             'nested_custom': {'obj': CustomObject(), 'normal': 'value'},
         }
 
+        # Use preprocessing utility to make it serializable
+        serializable_metadata = proto_utils.make_dict_serializable(metadata)
+
         # Convert to proto
-        proto_metadata = proto_utils.ToProto.metadata(metadata)
+        proto_metadata = proto_utils.ToProto.metadata(serializable_metadata)
         assert proto_metadata is not None
 
         # Convert back to Python
@@ -339,7 +342,7 @@ def test_metadata_edge_cases(self):
             'false': False,
             'empty_string': '',
             'unicode_string': 'string test',
-            'large_number': 9999999999999999,
+            'safe_number': 9007199254740991,  # JavaScript MAX_SAFE_INTEGER
             'negative_number': -42,
             'float_precision': 0.123456789,
             'numeric_string': '12345',
@@ -356,7 +359,156 @@ def test_metadata_edge_cases(self):
         assert roundtrip_metadata['false'] is False
         assert roundtrip_metadata['empty_string'] == ''
         assert roundtrip_metadata['unicode_string'] == 'string test'
-        assert roundtrip_metadata['large_number'] == 9999999999999999
+        assert roundtrip_metadata['safe_number'] == 9007199254740991
         assert roundtrip_metadata['negative_number'] == -42
         assert abs(roundtrip_metadata['float_precision'] - 0.123456789) < 1e-10
         assert roundtrip_metadata['numeric_string'] == '12345'
+
+    def test_make_dict_serializable(self):
+        """Test the make_dict_serializable utility function."""
+
+        class CustomObject:
+            def __str__(self):
+                return 'custom_str'
+
+        test_data = {
+            'string': 'hello',
+            'int': 42,
+            'float': 3.14,
+            'bool': True,
+            'none': None,
+            'custom': CustomObject(),
+            'list': [1, 'two', CustomObject()],
+            'tuple': (1, 2, CustomObject()),
+            'nested': {'inner_custom': CustomObject(), 'inner_normal': 'value'},
+        }
+
+        result = proto_utils.make_dict_serializable(test_data)
+
+        # Basic types should be unchanged
+        assert result['string'] == 'hello'
+        assert result['int'] == 42
+        assert result['float'] == 3.14
+        assert result['bool'] is True
+        assert result['none'] is None
+
+        # Custom objects should be converted to strings
+        assert result['custom'] == 'custom_str'
+        assert result['list'] == [1, 'two', 'custom_str']
+        assert result['tuple'] == [1, 2, 'custom_str']  # tuples become lists
+        assert result['nested']['inner_custom'] == 'custom_str'
+        assert result['nested']['inner_normal'] == 'value'
+
+    def test_normalize_large_integers_to_strings(self):
+        """Test the normalize_large_integers_to_strings utility function."""
+
+        test_data = {
+            'small_int': 42,
+            'large_int': 9999999999999999999,  # > 15 digits
+            'negative_large': -9999999999999999999,
+            'float': 3.14,
+            'string': 'hello',
+            'list': [123, 9999999999999999999, 'text'],
+            'nested': {'inner_large': 9999999999999999999, 'inner_small': 100},
+        }
+
+        result = proto_utils.normalize_large_integers_to_strings(test_data)
+
+        # Small integers should remain as integers
+        assert result['small_int'] == 42
+        assert isinstance(result['small_int'], int)
+
+        # Large integers should be converted to strings
+        assert result['large_int'] == '9999999999999999999'
+        assert isinstance(result['large_int'], str)
+        assert result['negative_large'] == '-9999999999999999999'
+        assert isinstance(result['negative_large'], str)
+
+        # Other types should be unchanged
+        assert result['float'] == 3.14
+        assert result['string'] == 'hello'
+
+        # Lists should be processed recursively
+        assert result['list'] == [123, '9999999999999999999', 'text']
+
+        # Nested dicts should be processed recursively
+        assert result['nested']['inner_large'] == '9999999999999999999'
+        assert result['nested']['inner_small'] == 100
+
+    def test_parse_string_integers_in_dict(self):
+        """Test the parse_string_integers_in_dict utility function."""
+
+        test_data = {
+            'regular_string': 'hello',
+            'numeric_string_small': '123',  # small, should stay as string
+            'numeric_string_large': '9999999999999999999',  # > 15 digits, should become int
+            'negative_large_string': '-9999999999999999999',
+            'float_string': '3.14',  # not all digits, should stay as string
+            'mixed_string': '123abc',  # not all digits, should stay as string
+            'int': 42,
+            'list': ['hello', '9999999999999999999', '123'],
+            'nested': {
+                'inner_large_string': '9999999999999999999',
+                'inner_regular': 'value',
+            },
+        }
+
+        result = proto_utils.parse_string_integers_in_dict(test_data)
+
+        # Regular strings should remain unchanged
+        assert result['regular_string'] == 'hello'
+        assert (
+            result['numeric_string_small'] == '123'
+        )  # too small, stays string
+        assert result['float_string'] == '3.14'  # not all digits
+        assert result['mixed_string'] == '123abc'  # not all digits
+
+        # Large numeric strings should be converted to integers
+        assert result['numeric_string_large'] == 9999999999999999999
+        assert isinstance(result['numeric_string_large'], int)
+        assert result['negative_large_string'] == -9999999999999999999
+        assert isinstance(result['negative_large_string'], int)
+
+        # Other types should be unchanged
+        assert result['int'] == 42
+
+        # Lists should be processed recursively
+        assert result['list'] == ['hello', 9999999999999999999, '123']
+
+        # Nested dicts should be processed recursively
+        assert result['nested']['inner_large_string'] == 9999999999999999999
+        assert result['nested']['inner_regular'] == 'value'
+
+    def test_large_integer_roundtrip_with_utilities(self):
+        """Test large integer handling with preprocessing and post-processing utilities."""
+
+        original_data = {
+            'large_int': 9999999999999999999,
+            'small_int': 42,
+            'nested': {'another_large': 12345678901234567890, 'normal': 'text'},
+        }
+
+        # Step 1: Preprocess to convert large integers to strings
+        preprocessed = proto_utils.normalize_large_integers_to_strings(
+            original_data
+        )
+
+        # Step 2: Convert to proto
+        proto_metadata = proto_utils.ToProto.metadata(preprocessed)
+        assert proto_metadata is not None
+
+        # Step 3: Convert back from proto
+        dict_from_proto = proto_utils.FromProto.metadata(proto_metadata)
+
+        # Step 4: Post-process to convert large integer strings back to integers
+        final_result = proto_utils.parse_string_integers_in_dict(
+            dict_from_proto
+        )
+
+        # Verify roundtrip preserved the original data
+        assert final_result['large_int'] == 9999999999999999999
+        assert isinstance(final_result['large_int'], int)
+        assert final_result['small_int'] == 42
+        assert final_result['nested']['another_large'] == 12345678901234567890
+        assert isinstance(final_result['nested']['another_large'], int)
+        assert final_result['nested']['normal'] == 'text'