feat: Add proto conversion utilities (#420)

- Adds `make_dict_serializable` to prepare dictionaries for proto conversion. - Adds `normalize_large_integers_to_strings` to convert large integers to strings, preventing precision loss in JS clients. - Adds `parse_string_integers_in_dict` to convert the integer strings back to `int`. - Includes comprehensive unit tests. --------- Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Co-authored-by: Holt Skinner <holtskinner@google.com>

Author: youngchannelforyou

.ruff.toml

@@ -32,6 +32,7 @@ ignore = [
  "TRY003",
  "TRY201",
  "FIX002",
+ "UP038",
 ]
 
 select = [

src/a2a/utils/proto_utils.py

@@ -46,6 +46,86 @@ def dict_to_struct(dictionary: dict[str, Any]) -> struct_pb2.Struct:
  return struct
 
 
+def make_dict_serializable(value: Any) -> Any:
+ """Dict pre-processing 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, (str, int, float, bool)) or value is None:
+ return 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]
+ 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.
+ """
+ max_safe_int = 10**max_safe_digits - 1
+
+ def _normalize(item: Any) -> Any:
+ if isinstance(item, int) and abs(item) > max_safe_int:
+ return str(item)
+ if isinstance(item, dict):
+ return {k: _normalize(v) for k, v in item.items()}
+ if isinstance(item, list | tuple):
+ return [_normalize(i) for i in item]
+ return item
+
+ return _normalize(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):
+ # Handle potential negative numbers.
+ stripped_value = value.lstrip('-')
+ if stripped_value.isdigit() and len(stripped_value) > max_safe_digits:
+ return int(value)
+ return value
+
+
 class ToProto:
  """Converts Python types to proto types."""
 

tests/utils/test_proto_utils.py

@@ -251,3 +251,260 @@ def test_none_handling(self):
  assert proto_utils.ToProto.provider(None) is None
  assert proto_utils.ToProto.security(None) is None
  assert proto_utils.ToProto.security_schemes(None) is None
+
+ def test_metadata_conversion(self):
+ """Test metadata conversion with various data types."""
+ metadata = {
+ 'null_value': None,
+ 'bool_value': True,
+ 'int_value': 42,
+ 'float_value': 3.14,
+ 'string_value': 'hello',
+ 'dict_value': {'nested': 'dict', 'count': 10},
+ 'list_value': [1, 'two', 3.0, True, None],
+ 'tuple_value': (1, 2, 3),
+ 'complex_list': [
+ {'name': 'item1', 'values': [1, 2, 3]},
+ {'name': 'item2', 'values': [4, 5, 6]},
+ ],
+ }
+
+ # Convert to proto
+ proto_metadata = proto_utils.ToProto.metadata(metadata)
+ assert proto_metadata is not None
+
+ # Convert back to Python
+ roundtrip_metadata = proto_utils.FromProto.metadata(proto_metadata)
+
+ # Verify all values are preserved correctly
+ assert roundtrip_metadata['null_value'] is None
+ assert roundtrip_metadata['bool_value'] is True
+ assert roundtrip_metadata['int_value'] == 42
+ assert roundtrip_metadata['float_value'] == 3.14
+ assert roundtrip_metadata['string_value'] == 'hello'
+ assert roundtrip_metadata['dict_value']['nested'] == 'dict'
+ assert roundtrip_metadata['dict_value']['count'] == 10
+ assert roundtrip_metadata['list_value'] == [1, 'two', 3.0, True, None]
+ assert roundtrip_metadata['tuple_value'] == [
+ 1,
+ 2,
+ 3,
+ ] # tuples become lists
+ assert len(roundtrip_metadata['complex_list']) == 2
+ assert roundtrip_metadata['complex_list'][0]['name'] == 'item1'
+
+ def test_metadata_with_custom_objects(self):
+ """Test metadata conversion with custom objects using preprocessing utility."""
+
+ class CustomObject:
+ def __str__(self):
+ return 'custom_object_str'
+
+ def __repr__(self):
+ return 'CustomObject()'
+
+ metadata = {
+ 'custom_obj': CustomObject(),
+ 'list_with_custom': [1, CustomObject(), 'text'],
+ '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(serializable_metadata)
+ assert proto_metadata is not None
+
+ # Convert back to Python
+ roundtrip_metadata = proto_utils.FromProto.metadata(proto_metadata)
+
+ # Custom objects should be converted to strings
+ assert roundtrip_metadata['custom_obj'] == 'custom_object_str'
+ assert roundtrip_metadata['list_with_custom'] == [
+ 1,
+ 'custom_object_str',
+ 'text',
+ ]
+ assert roundtrip_metadata['nested_custom']['obj'] == 'custom_object_str'
+ assert roundtrip_metadata['nested_custom']['normal'] == 'value'
+
+ def test_metadata_edge_cases(self):
+ """Test metadata conversion with edge cases."""
+ metadata = {
+ 'empty_dict': {},
+ 'empty_list': [],
+ 'zero': 0,
+ 'false': False,
+ 'empty_string': '',
+ 'unicode_string': 'string test',
+ 'safe_number': 9007199254740991, # JavaScript MAX_SAFE_INTEGER
+ 'negative_number': -42,
+ 'float_precision': 0.123456789,
+ 'numeric_string': '12345',
+ }
+
+ # Convert to proto and back
+ proto_metadata = proto_utils.ToProto.metadata(metadata)
+ roundtrip_metadata = proto_utils.FromProto.metadata(proto_metadata)
+
+ # Verify edge cases are handled correctly
+ assert roundtrip_metadata['empty_dict'] == {}
+ assert roundtrip_metadata['empty_list'] == []
+ assert roundtrip_metadata['zero'] == 0
+ assert roundtrip_metadata['false'] is False
+ assert roundtrip_metadata['empty_string'] == ''
+ assert roundtrip_metadata['unicode_string'] == 'string test'
+ 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'