fix(python-sdk): support relative data binding paths in v0.9 streaming parser (#1179)

Author: jacobsimionato

agent_sdks/python/src/a2ui/parser/streaming.py

@@ -76,6 +76,7 @@ def __new__(cls, catalog: "A2uiCatalog" = None, *args, **kwargs):
     return super().__new__(cls)
 
   def __init__(self, catalog: "A2uiCatalog" = None):
+    self._version = getattr(catalog, "version", None) if catalog else None
     self._ref_fields_map = extract_component_ref_fields(catalog) if catalog else {}
     self._required_fields_map = (
         extract_component_required_fields(catalog) if catalog else {}
@@ -1007,11 +1008,12 @@ def traverse(obj, parent_key=None):
         ):
           path = obj["path"]
           key = path.lstrip("/")
-          if "componentId" not in obj:
-            obj.clear()
-          obj.update({"path": "/" + key})
-        else:
-          # If not in data model, still ensure path has leading slash if it's a bindable object
+          if self._version != VERSION_0_9:
+            if "componentId" not in obj:
+              obj.clear()
+            obj.update({"path": "/" + key})
+        elif self._version != VERSION_0_9:
+          # If not in data model, still ensure path has leading slash if it's a bindable object (v0.8 only)
           current_path = obj.get("path")
           if current_path is not None:
             if not isinstance(current_path, str) or not current_path.startswith("/"):

agent_sdks/python/tests/parser/test_streaming_v08.py

@@ -273,3 +273,36 @@ def test_streaming_msg_type_deduplication(mock_catalog):
 
   # After completion, msg_types is reset
   assert parser.msg_types == []
+
+
+def test_v08_path_heuristic_adds_slash(mock_catalog):
+  """Tests that v0.8 adds a leading slash to relative paths."""
+  parser = A2uiStreamParser(catalog=mock_catalog)
+  # Disable validation for simplicity
+  parser._validator = None
+
+  # 1. Send beginRendering first to avoid buffering
+  chunk_br = (
+      A2UI_OPEN_TAG
+      + '[{"beginRendering": {"surfaceId": "s1", "root": "root"}}]'
+      + A2UI_CLOSE_TAG
+  )
+  list(parser.process_chunk(chunk_br))
+
+  # 2. Send surfaceUpdate with a relative path
+  chunk_su = (
+      A2UI_OPEN_TAG
+      + '[{"surfaceUpdate": {"surfaceId": "s1", "components": [{"id": "root",'
+      ' "component": {"Text": {"text": {"path": "some/relative/path"}}}}]}}]'
+      + A2UI_CLOSE_TAG
+  )
+
+  messages = []
+  for part in parser.process_chunk(chunk_su):
+    if part.a2ui_json:
+      messages.extend(part.a2ui_json)
+
+  # The path should have been prefixed with a slash
+  assert len(messages) > 0
+  comp = messages[0][MSG_TYPE_SURFACE_UPDATE]["components"][0]
+  assert comp["component"]["Text"]["text"]["path"] == "/some/relative/path"

agent_sdks/python/tests/parser/test_streaming_v09.py

@@ -388,3 +388,67 @@ def test_streaming_msg_type_deduplication(mock_catalog):
 
   # After completion, msg_types is reset
   assert not parser.msg_types
+
+
+def test_v09_path_heuristic_relative_path(mock_catalog):
+  """Tests that v0.9 allows relative paths (no leading slash)."""
+  parser = A2uiStreamParser(catalog=mock_catalog)
+  # Disable validation to avoid needing full catalog for this test
+  parser._validator = None
+
+  # 1. Create surface
+  chunk_cs = (
+      A2UI_OPEN_TAG
+      + '[{"version": "v0.9", "createSurface": {"surfaceId": "s1", "catalogId": "c1"}}]'
+      + A2UI_CLOSE_TAG
+  )
+  list(parser.process_chunk(chunk_cs))
+
+  # 2. Update components with a relative path
+  chunk_uc = (
+      A2UI_OPEN_TAG
+      + '[{"version": "v0.9", "updateComponents": {"surfaceId": "s1", "components":'
+      ' [{"id": "root", "component": "Text", "text": {"path":'
+      ' "some/relative/path"}}]}}]'
+      + A2UI_CLOSE_TAG
+  )
+
+  messages = []
+  for part in parser.process_chunk(chunk_uc):
+    if part.a2ui_json:
+      messages.extend(part.a2ui_json)
+
+  assert len(messages) > 0
+  comp = messages[0][MSG_TYPE_UPDATE_COMPONENTS]["components"][0]
+  assert comp["text"]["path"] == "some/relative/path"
+
+
+def test_v09_path_heuristic_absolute_path(mock_catalog):
+  """Tests that v0.9 still supports absolute paths (leading slash)."""
+  parser = A2uiStreamParser(catalog=mock_catalog)
+  parser._validator = None
+
+  # 1. Create surface
+  chunk_cs = (
+      A2UI_OPEN_TAG
+      + '[{"version": "v0.9", "createSurface": {"surfaceId": "s1", "catalogId": "c1"}}]'
+      + A2UI_CLOSE_TAG
+  )
+  list(parser.process_chunk(chunk_cs))
+
+  # 2. Update components with an absolute path
+  chunk_uc = (
+      A2UI_OPEN_TAG
+      + '[{"version": "v0.9", "updateComponents": {"surfaceId": "s1", "components":'
+      ' [{"id": "root", "component": "Text", "text": {"path": "/absolute/path"}}]}}]'
+      + A2UI_CLOSE_TAG
+  )
+
+  messages = []
+  for part in parser.process_chunk(chunk_uc):
+    if part.a2ui_json:
+      messages.extend(part.a2ui_json)
+
+  assert len(messages) > 0
+  comp = messages[0][MSG_TYPE_UPDATE_COMPONENTS]["components"][0]
+  assert comp["text"]["path"] == "/absolute/path"