feat(convert): enhance dict and struct encoding with type awareness

Author: vumichien

python/cocoindex/convert.py

@@ -22,6 +22,42 @@
 )
 
 
+def _is_ktable_dict(value: dict[Any, Any]) -> bool:
+    """Check if a dict is being used as a KTable (dict[key, struct])."""
+    if not value:
+        return False
+    first_val = next(iter(value.values()))
+    return is_struct_type(type(first_val))
+
+
+def encode_engine_value_with_type(value: Any, target_type: Any = None) -> Any:
+    """Encode a Python value to an engine value with optional type awareness."""
+    # Handle dict-to-struct conversion when target type is a struct
+    if (isinstance(value, dict) and 
+        target_type is not None and 
+        not _is_ktable_dict(value)):
+        
+        from .typing import analyze_type_info
+        try:
+            type_info = analyze_type_info(target_type)
+            if type_info.kind == "Struct" and type_info.struct_type:
+                # Convert dict to struct format
+                if dataclasses.is_dataclass(type_info.struct_type):
+                    # Extract values in dataclass field order
+                    fields = dataclasses.fields(type_info.struct_type)
+                    return [encode_engine_value_with_type(value.get(f.name), f.type) for f in fields]
+                elif is_namedtuple_type(type_info.struct_type):
+                    # Extract values in namedtuple field order
+                    field_names = getattr(type_info.struct_type, "_fields", ())
+                    return [encode_engine_value_with_type(value.get(name), 
+                           type_info.struct_type.__annotations__.get(name)) for name in field_names]
+        except:
+            # If type analysis fails, fall back to regular encoding
+            pass
+    
+    return encode_engine_value(value)
+
+
 def encode_engine_value(value: Any) -> Any:
     """Encode a Python value to an engine value."""
     if dataclasses.is_dataclass(value):
@@ -37,16 +73,11 @@ def encode_engine_value(value: Any) -> Any:
         return value
     if isinstance(value, (list, tuple)):
         return [encode_engine_value(v) for v in value]
-    if isinstance(value, dict):
-        if not value:
-            return {}
-
-        first_val = next(iter(value.values()))
-        if is_struct_type(type(first_val)):  # KTable
-            return [
-                [encode_engine_value(k)] + encode_engine_value(v)
-                for k, v in value.items()
-            ]
+    if isinstance(value, dict) and _is_ktable_dict(value):
+        return [
+            [encode_engine_value(k)] + encode_engine_value(v)
+            for k, v in value.items()
+        ]
     return value
 
 
@@ -258,6 +289,17 @@ def _make_engine_struct_value_decoder(
             )
             for name in fields
         }
+    elif dst_struct_type is dict or (hasattr(dst_struct_type, "__origin__") and 
+                                    getattr(dst_struct_type, "__origin__") is dict):
+        parameters = {
+            f["name"]: inspect.Parameter(
+                name=f["name"],
+                kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=inspect.Parameter.empty,
+                annotation=Any,
+            )
+            for f in src_fields
+        }
     else:
         raise ValueError(f"Unsupported struct type: {dst_struct_type}")
 
@@ -288,10 +330,18 @@ def make_closure_for_value(
     field_value_decoder = [
         make_closure_for_value(name, param) for (name, param) in parameters.items()
     ]
-
-    return lambda values: dst_struct_type(
-        *(decoder(values) for decoder in field_value_decoder)
-    )
+    if dst_struct_type is dict or (hasattr(dst_struct_type, "__origin__") and 
+                                  getattr(dst_struct_type, "__origin__") is dict):
+        def dict_decoder(values: list[Any]) -> dict[str, Any]:
+            return {
+                name: decoder(values)
+                for (name, _), decoder in zip(parameters.items(), field_value_decoder)
+            }
+        return dict_decoder
+    else:
+        return lambda values: dst_struct_type(
+            *(decoder(values) for decoder in field_value_decoder)
+        )
 
 
 def dump_engine_object(v: Any) -> Any:

python/cocoindex/tests/test_convert.py

@@ -1229,3 +1229,112 @@ class MixedStruct:
         annotated_float=2.0,
     )
     validate_full_roundtrip(instance, MixedStruct)
+
+
+def test_dict_struct_encoding() -> None:
+    # Test encoding dict as struct - this should only happen in type-aware context
+    # For generic encoding, dict is passed through as-is
+    from cocoindex.convert import encode_engine_value
+    dict_value = {"name": "Alice", "age": 30, "city": "New York"}
+    result = encode_engine_value(dict_value)
+    assert result == {"name": "Alice", "age": 30, "city": "New York"}  # Dict preserved
+
+
+def test_dict_struct_decoding() -> None:
+    # Test decoding to dict as struct
+    from cocoindex.convert import _make_engine_struct_value_decoder
+    from typing import Dict, Any
+    
+    src_fields = [
+        {"name": "name", "type": {"kind": "Str"}},
+        {"name": "age", "type": {"kind": "Int64"}},
+        {"name": "city", "type": {"kind": "Str"}},
+    ]
+    
+    decoder = _make_engine_struct_value_decoder([], src_fields, Dict[str, Any])
+    result = decoder(["Alice", 30, "New York"])
+    assert result == {"name": "Alice", "age": 30, "city": "New York"}
+
+
+def test_dict_untyped_struct_decoding() -> None:
+    # Test decoding to untyped dict as struct
+    from cocoindex.convert import _make_engine_struct_value_decoder
+    
+    src_fields = [
+        {"name": "name", "type": {"kind": "Str"}},
+        {"name": "age", "type": {"kind": "Int64"}},
+        {"name": "city", "type": {"kind": "Str"}},
+    ]
+    
+    decoder = _make_engine_struct_value_decoder([], src_fields, dict)
+    result = decoder(["Alice", 30, "New York"])
+    assert result == {"name": "Alice", "age": 30, "city": "New York"}
+
+
+def test_dict_struct_vs_ktable() -> None:
+    # Test that dict-as-struct and dict-as-KTable are handled differently
+    from cocoindex.convert import encode_engine_value, _is_ktable_dict
+    
+    # Dict as struct (simple values) - should be passed through in generic encoding
+    dict_struct = {"name": "Alice", "age": 30}
+    assert not _is_ktable_dict(dict_struct)
+    struct_result = encode_engine_value(dict_struct)
+    assert struct_result == {"name": "Alice", "age": 30}  # Preserved as dict
+    
+    # Dict as KTable (struct values)
+    @dataclass
+    class Person:
+        name: str
+        age: int
+    
+    dict_ktable = {"p1": Person("Alice", 30), "p2": Person("Bob", 25)}
+    assert _is_ktable_dict(dict_ktable)
+    ktable_result = encode_engine_value(dict_ktable)
+    assert ktable_result == [["p1", "Alice", 30], ["p2", "Bob", 25]]
+
+
+def test_dict_to_struct_conversion() -> None:
+    # Test dict to struct conversion with existing struct types
+    from cocoindex.convert import encode_engine_value_with_type
+    from dataclasses import dataclass
+    
+    @dataclass
+    class Person:
+        name: str
+        age: int
+        city: str
+    
+    dict_value = {"name": "Alice", "age": 30, "city": "New York"}
+    
+    # Test encoding dict as struct
+    result = encode_engine_value_with_type(dict_value, Person)
+    assert result == ["Alice", 30, "New York"]
+
+
+def test_struct_to_dict_conversion() -> None:
+    # Test struct to dict conversion
+    from cocoindex.convert import _make_engine_struct_value_decoder
+    from dataclasses import dataclass
+    from typing import Dict, Any
+    
+    @dataclass
+    class Person:
+        name: str
+        age: int
+        city: str
+    
+    src_fields = [
+        {"name": "name", "type": {"kind": "Str"}},
+        {"name": "age", "type": {"kind": "Int64"}}, 
+        {"name": "city", "type": {"kind": "Str"}},
+    ]
+    
+    # Test decoding struct to dict
+    decoder = _make_engine_struct_value_decoder([], src_fields, Dict[str, Any])
+    result = decoder(["Alice", 30, "New York"])
+    assert result == {"name": "Alice", "age": 30, "city": "New York"}
+    
+    # Test decoding struct to untyped dict
+    decoder = _make_engine_struct_value_decoder([], src_fields, dict)
+    result = decoder(["Alice", 30, "New York"])
+    assert result == {"name": "Alice", "age": 30, "city": "New York"}