cocoindex 0.1.49__cp311-cp311-win_amd64.whl → 0.1.51__cp311-cp311-win_amd64.whl

cocoindex/tests/test_convert.py

@@ -1,11 +1,22 @@
 import uuid
 import datetime
 from dataclasses import dataclass, make_dataclass
-from typing import NamedTuple, Literal
+from typing import NamedTuple, Literal, Any, Callable, Union
 import pytest
 import cocoindex
-from cocoindex.typing import encode_enriched_type
-from cocoindex.convert import encode_engine_value, make_engine_value_decoder
+from cocoindex.typing import (
+    encode_enriched_type,
+    Vector,
+    Float32,
+    Float64,
+)
+from cocoindex.convert import (
+    encode_engine_value,
+    make_engine_value_decoder,
+    dump_engine_object,
+)
+import numpy as np
+from numpy.typing import NDArray
 
 
 @dataclass
@@ -23,7 +34,7 @@ class Tag:
 
 @dataclass
 class Basket:
-    items: list
+    items: list[str]
 
 
 @dataclass
@@ -53,7 +64,9 @@ class CustomerNamedTuple(NamedTuple):
     tags: list[Tag] | None = None
 
 
-def build_engine_value_decoder(engine_type_in_py, python_type=None):
+def build_engine_value_decoder(
+    engine_type_in_py: Any, python_type: Any | None = None
+) -> Callable[[Any], Any]:
     """
     Helper to build a converter for the given engine-side type (as represented in Python).
     If python_type is not specified, uses engine_type_in_py as the target.
@@ -62,19 +75,51 @@ def build_engine_value_decoder(engine_type_in_py, python_type=None):
     return make_engine_value_decoder([], engine_type, python_type or engine_type_in_py)
 
 
-def test_encode_engine_value_basic_types():
+def validate_full_roundtrip(
+    value: Any,
+    value_type: Any = None,
+    *other_decoded_values: tuple[Any, Any],
+) -> None:
+    """
+    Validate the given value doesn't change after encoding, sending to engine (using output_type), receiving back and decoding (using input_type).
+
+    `other_decoded_values` is a tuple of (value, type) pairs.
+    If provided, also validate the value can be decoded to the other types.
+    """
+    from cocoindex import _engine  # type: ignore
+
+    encoded_value = encode_engine_value(value)
+    value_type = value_type or type(value)
+    encoded_output_type = encode_enriched_type(value_type)["type"]
+    value_from_engine = _engine.testutil.seder_roundtrip(
+        encoded_value, encoded_output_type
+    )
+    decoded_value = build_engine_value_decoder(value_type, value_type)(
+        value_from_engine
+    )
+    np.testing.assert_array_equal(decoded_value, value)
+
+    if other_decoded_values is not None:
+        for other_value, other_type in other_decoded_values:
+            other_decoded_value = build_engine_value_decoder(other_type, other_type)(
+                value_from_engine
+            )
+            np.testing.assert_array_equal(other_decoded_value, other_value)
+
+
+def test_encode_engine_value_basic_types() -> None:
     assert encode_engine_value(123) == 123
     assert encode_engine_value(3.14) == 3.14
     assert encode_engine_value("hello") == "hello"
     assert encode_engine_value(True) is True
 
 
-def test_encode_engine_value_uuid():
+def test_encode_engine_value_uuid() -> None:
     u = uuid.uuid4()
     assert encode_engine_value(u) == u.bytes
 
 
-def test_encode_engine_value_date_time_types():
+def test_encode_engine_value_date_time_types() -> None:
     d = datetime.date(2024, 1, 1)
     assert encode_engine_value(d) == d
     t = datetime.time(12, 30)
@@ -83,7 +128,7 @@ def test_encode_engine_value_date_time_types():
     assert encode_engine_value(dt) == dt
 
 
-def test_encode_engine_value_struct():
+def test_encode_engine_value_struct() -> None:
     order = Order(order_id="O123", name="mixed nuts", price=25.0)
     assert encode_engine_value(order) == ["O123", "mixed nuts", 25.0, "default_extra"]
 
@@ -96,7 +141,7 @@ def test_encode_engine_value_struct():
     ]
 
 
-def test_encode_engine_value_list_of_structs():
+def test_encode_engine_value_list_of_structs() -> None:
     orders = [Order("O1", "item1", 10.0), Order("O2", "item2", 20.0)]
     assert encode_engine_value(orders) == [
         ["O1", "item1", 10.0, "default_extra"],
@@ -113,12 +158,12 @@ def test_encode_engine_value_list_of_structs():
     ]
 
 
-def test_encode_engine_value_struct_with_list():
+def test_encode_engine_value_struct_with_list() -> None:
     basket = Basket(items=["apple", "banana"])
     assert encode_engine_value(basket) == [["apple", "banana"]]
 
 
-def test_encode_engine_value_nested_struct():
+def test_encode_engine_value_nested_struct() -> None:
     customer = Customer(name="Alice", order=Order("O1", "item1", 10.0))
     assert encode_engine_value(customer) == [
         "Alice",
@@ -136,12 +181,12 @@ def test_encode_engine_value_nested_struct():
     ]
 
 
-def test_encode_engine_value_empty_list():
+def test_encode_engine_value_empty_list() -> None:
     assert encode_engine_value([]) == []
     assert encode_engine_value([[]]) == [[]]
 
 
-def test_encode_engine_value_tuple():
+def test_encode_engine_value_tuple() -> None:
     assert encode_engine_value(()) == []
     assert encode_engine_value((1, 2, 3)) == [1, 2, 3]
     assert encode_engine_value(((1, 2), (3, 4))) == [[1, 2], [3, 4]]
@@ -149,20 +194,23 @@ def test_encode_engine_value_tuple():
     assert encode_engine_value(((),)) == [[]]
 
 
-def test_encode_engine_value_none():
+def test_encode_engine_value_none() -> None:
     assert encode_engine_value(None) is None
 
 
-def test_make_engine_value_decoder_basic_types():
-    for engine_type_in_py, value in [
-        (int, 42),
-        (float, 3.14),
-        (str, "hello"),
-        (bool, True),
-        # (type(None), None),  # Removed unsupported NoneType
-    ]:
-        decoder = build_engine_value_decoder(engine_type_in_py)
-        assert decoder(value) == value
+def test_roundtrip_basic_types() -> None:
+    validate_full_roundtrip(42, int)
+    validate_full_roundtrip(3.25, float, (3.25, Float64))
+    validate_full_roundtrip(3.25, Float64, (3.25, float))
+    validate_full_roundtrip(3.25, Float32)
+    validate_full_roundtrip("hello", str)
+    validate_full_roundtrip(True, bool)
+    validate_full_roundtrip(False, bool)
+    validate_full_roundtrip(datetime.date(2025, 1, 1), datetime.date)
+    validate_full_roundtrip(datetime.datetime.now(), cocoindex.LocalDateTime)
+    validate_full_roundtrip(
+        datetime.datetime.now(datetime.UTC), cocoindex.OffsetDateTime
+    )
 
 
 @pytest.mark.parametrize(
@@ -280,18 +328,18 @@ def test_make_engine_value_decoder_basic_types():
         ),
     ],
 )
-def test_struct_decoder_cases(data_type, engine_val, expected):
+def test_struct_decoder_cases(data_type: Any, engine_val: Any, expected: Any) -> None:
     decoder = build_engine_value_decoder(data_type)
     assert decoder(engine_val) == expected
 
 
-def test_make_engine_value_decoder_collections():
+def test_make_engine_value_decoder_list_of_struct() -> None:
     # List of structs (dataclass)
-    decoder = build_engine_value_decoder(list[Order])
     engine_val = [
         ["O1", "item1", 10.0, "default_extra"],
         ["O2", "item2", 20.0, "default_extra"],
     ]
+    decoder = build_engine_value_decoder(list[Order])
     assert decoder(engine_val) == [
         Order("O1", "item1", 10.0, "default_extra"),
         Order("O2", "item2", 20.0, "default_extra"),
@@ -304,13 +352,15 @@ def test_make_engine_value_decoder_collections():
         OrderNamedTuple("O2", "item2", 20.0, "default_extra"),
     ]
 
+
+def test_make_engine_value_decoder_struct_of_list() -> None:
     # Struct with list field
-    decoder = build_engine_value_decoder(Customer)
     engine_val = [
         "Alice",
         ["O1", "item1", 10.0, "default_extra"],
         [["vip"], ["premium"]],
     ]
+    decoder = build_engine_value_decoder(Customer)
     assert decoder(engine_val) == Customer(
         "Alice",
         Order("O1", "item1", 10.0, "default_extra"),
@@ -325,8 +375,9 @@ def test_make_engine_value_decoder_collections():
         [Tag("vip"), Tag("premium")],
     )
 
+
+def test_make_engine_value_decoder_struct_of_struct() -> None:
     # Struct with struct field
-    decoder = build_engine_value_decoder(NestedStruct)
     engine_val = [
         ["Alice", ["O1", "item1", 10.0, "default_extra"], [["vip"]]],
         [
@@ -335,6 +386,7 @@ def test_make_engine_value_decoder_collections():
         ],
         2,
     ]
+    decoder = build_engine_value_decoder(NestedStruct)
     assert decoder(engine_val) == NestedStruct(
         Customer("Alice", Order("O1", "item1", 10.0, "default_extra"), [Tag("vip")]),
         [
@@ -345,11 +397,13 @@ def test_make_engine_value_decoder_collections():
     )
 
 
-def make_engine_order(fields):
+def make_engine_order(fields: list[tuple[str, type]]) -> type:
     return make_dataclass("EngineOrder", fields)
 
 
-def make_python_order(fields, defaults=None):
+def make_python_order(
+    fields: list[tuple[str, type]], defaults: dict[str, Any] | None = None
+) -> type:
     if defaults is None:
         defaults = {}
     # Move all fields with defaults to the end (Python dataclass requirement)
@@ -423,8 +477,12 @@ def make_python_order(fields, defaults=None):
     ],
 )
 def test_field_position_cases(
-    engine_fields, python_fields, python_defaults, engine_val, expected_python_val
-):
+    engine_fields: list[tuple[str, type]],
+    python_fields: list[tuple[str, type]],
+    python_defaults: dict[str, Any],
+    engine_val: list[Any],
+    expected_python_val: tuple[Any, ...],
+) -> None:
     EngineOrder = make_engine_order(engine_fields)
     PythonOrder = make_python_order(python_fields, python_defaults)
     decoder = build_engine_value_decoder(EngineOrder, PythonOrder)
@@ -434,57 +492,33 @@ def test_field_position_cases(
     assert decoder(engine_val) == PythonOrder(**expected_dict)
 
 
-def test_roundtrip_ltable():
+def test_roundtrip_ltable() -> None:
     t = list[Order]
     value = [Order("O1", "item1", 10.0), Order("O2", "item2", 20.0)]
-    encoded = encode_engine_value(value)
-    assert encoded == [
-        ["O1", "item1", 10.0, "default_extra"],
-        ["O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t)(encoded)
-    assert decoded == value
+    validate_full_roundtrip(value, t)
 
     t_nt = list[OrderNamedTuple]
     value_nt = [
         OrderNamedTuple("O1", "item1", 10.0),
         OrderNamedTuple("O2", "item2", 20.0),
     ]
-    encoded = encode_engine_value(value_nt)
-    assert encoded == [
-        ["O1", "item1", 10.0, "default_extra"],
-        ["O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t_nt)(encoded)
-    assert decoded == value_nt
+    validate_full_roundtrip(value_nt, t_nt)
 
 
-def test_roundtrip_ktable_str_key():
+def test_roundtrip_ktable_str_key() -> None:
     t = dict[str, Order]
     value = {"K1": Order("O1", "item1", 10.0), "K2": Order("O2", "item2", 20.0)}
-    encoded = encode_engine_value(value)
-    assert encoded == [
-        ["K1", "O1", "item1", 10.0, "default_extra"],
-        ["K2", "O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t)(encoded)
-    assert decoded == value
+    validate_full_roundtrip(value, t)
 
     t_nt = dict[str, OrderNamedTuple]
     value_nt = {
         "K1": OrderNamedTuple("O1", "item1", 10.0),
         "K2": OrderNamedTuple("O2", "item2", 20.0),
     }
-    encoded = encode_engine_value(value_nt)
-    assert encoded == [
-        ["K1", "O1", "item1", 10.0, "default_extra"],
-        ["K2", "O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t_nt)(encoded)
-    assert decoded == value_nt
+    validate_full_roundtrip(value_nt, t_nt)
 
 
-def test_roundtrip_ktable_struct_key():
+def test_roundtrip_ktable_struct_key() -> None:
     @dataclass(frozen=True)
     class OrderKey:
         shop_id: str
@@ -495,37 +529,25 @@ def test_roundtrip_ktable_struct_key():
         OrderKey("A", 3): Order("O1", "item1", 10.0),
         OrderKey("B", 4): Order("O2", "item2", 20.0),
     }
-    encoded = encode_engine_value(value)
-    assert encoded == [
-        [["A", 3], "O1", "item1", 10.0, "default_extra"],
-        [["B", 4], "O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t)(encoded)
-    assert decoded == value
+    validate_full_roundtrip(value, t)
 
     t_nt = dict[OrderKey, OrderNamedTuple]
     value_nt = {
         OrderKey("A", 3): OrderNamedTuple("O1", "item1", 10.0),
         OrderKey("B", 4): OrderNamedTuple("O2", "item2", 20.0),
     }
-    encoded = encode_engine_value(value_nt)
-    assert encoded == [
-        [["A", 3], "O1", "item1", 10.0, "default_extra"],
-        [["B", 4], "O2", "item2", 20.0, "default_extra"],
-    ]
-    decoded = build_engine_value_decoder(t_nt)(encoded)
-    assert decoded == value_nt
+    validate_full_roundtrip(value_nt, t_nt)
 
 
-IntVectorType = cocoindex.Vector[int, Literal[5]]
+IntVectorType = cocoindex.Vector[np.int64, Literal[5]]
 
 
 def test_vector_as_vector() -> None:
-    value: IntVectorType = [1, 2, 3, 4, 5]
+    value = np.array([1, 2, 3, 4, 5], dtype=np.int64)
     encoded = encode_engine_value(value)
-    assert encoded == [1, 2, 3, 4, 5]
+    assert np.array_equal(encoded, value)
     decoded = build_engine_value_decoder(IntVectorType)(encoded)
-    assert decoded == value
+    assert np.array_equal(decoded, value)
 
 
 ListIntType = list[int]
@@ -536,4 +558,257 @@ def test_vector_as_list() -> None:
     encoded = encode_engine_value(value)
     assert encoded == [1, 2, 3, 4, 5]
     decoded = build_engine_value_decoder(ListIntType)(encoded)
-    assert decoded == value
+    assert np.array_equal(decoded, value)
+
+
+Float64VectorTypeNoDim = Vector[np.float64]
+Float32VectorType = Vector[np.float32, Literal[3]]
+Float64VectorType = Vector[np.float64, Literal[3]]
+Int64VectorType = Vector[np.int64, Literal[3]]
+Int32VectorType = Vector[np.int32, Literal[3]]
+UInt8VectorType = Vector[np.uint8, Literal[3]]
+UInt16VectorType = Vector[np.uint16, Literal[3]]
+UInt32VectorType = Vector[np.uint32, Literal[3]]
+UInt64VectorType = Vector[np.uint64, Literal[3]]
+StrVectorType = Vector[str]
+NDArrayFloat32Type = NDArray[np.float32]
+NDArrayFloat64Type = NDArray[np.float64]
+NDArrayInt64Type = NDArray[np.int64]
+
+
+def test_encode_engine_value_ndarray() -> None:
+    """Test encoding NDArray vectors to lists for the Rust engine."""
+    vec_f32: Float32VectorType = np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    assert np.array_equal(encode_engine_value(vec_f32), [1.0, 2.0, 3.0])
+    vec_f64: Float64VectorType = np.array([1.0, 2.0, 3.0], dtype=np.float64)
+    assert np.array_equal(encode_engine_value(vec_f64), [1.0, 2.0, 3.0])
+    vec_i64: Int64VectorType = np.array([1, 2, 3], dtype=np.int64)
+    assert np.array_equal(encode_engine_value(vec_i64), [1, 2, 3])
+    vec_nd_f32: NDArrayFloat32Type = np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    assert np.array_equal(encode_engine_value(vec_nd_f32), [1.0, 2.0, 3.0])
+
+
+def test_make_engine_value_decoder_ndarray() -> None:
+    """Test decoding engine lists to NDArray vectors."""
+    decoder_f32 = build_engine_value_decoder(Float32VectorType)
+    result_f32 = decoder_f32([1.0, 2.0, 3.0])
+    assert isinstance(result_f32, np.ndarray)
+    assert result_f32.dtype == np.float32
+    assert np.array_equal(result_f32, np.array([1.0, 2.0, 3.0], dtype=np.float32))
+    decoder_f64 = build_engine_value_decoder(Float64VectorType)
+    result_f64 = decoder_f64([1.0, 2.0, 3.0])
+    assert isinstance(result_f64, np.ndarray)
+    assert result_f64.dtype == np.float64
+    assert np.array_equal(result_f64, np.array([1.0, 2.0, 3.0], dtype=np.float64))
+    decoder_i64 = build_engine_value_decoder(Int64VectorType)
+    result_i64 = decoder_i64([1, 2, 3])
+    assert isinstance(result_i64, np.ndarray)
+    assert result_i64.dtype == np.int64
+    assert np.array_equal(result_i64, np.array([1, 2, 3], dtype=np.int64))
+    decoder_nd_f32 = build_engine_value_decoder(NDArrayFloat32Type)
+    result_nd_f32 = decoder_nd_f32([1.0, 2.0, 3.0])
+    assert isinstance(result_nd_f32, np.ndarray)
+    assert result_nd_f32.dtype == np.float32
+    assert np.array_equal(result_nd_f32, np.array([1.0, 2.0, 3.0], dtype=np.float32))
+
+
+def test_roundtrip_ndarray_vector() -> None:
+    """Test roundtrip encoding and decoding of NDArray vectors."""
+    value_f32 = np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    encoded_f32 = encode_engine_value(value_f32)
+    np.array_equal(encoded_f32, [1.0, 2.0, 3.0])
+    decoded_f32 = build_engine_value_decoder(Float32VectorType)(encoded_f32)
+    assert isinstance(decoded_f32, np.ndarray)
+    assert decoded_f32.dtype == np.float32
+    assert np.array_equal(decoded_f32, value_f32)
+    value_i64 = np.array([1, 2, 3], dtype=np.int64)
+    encoded_i64 = encode_engine_value(value_i64)
+    assert np.array_equal(encoded_i64, [1, 2, 3])
+    decoded_i64 = build_engine_value_decoder(Int64VectorType)(encoded_i64)
+    assert isinstance(decoded_i64, np.ndarray)
+    assert decoded_i64.dtype == np.int64
+    assert np.array_equal(decoded_i64, value_i64)
+    value_nd_f64: NDArrayFloat64Type = np.array([1.0, 2.0, 3.0], dtype=np.float64)
+    encoded_nd_f64 = encode_engine_value(value_nd_f64)
+    assert np.array_equal(encoded_nd_f64, [1.0, 2.0, 3.0])
+    decoded_nd_f64 = build_engine_value_decoder(NDArrayFloat64Type)(encoded_nd_f64)
+    assert isinstance(decoded_nd_f64, np.ndarray)
+    assert decoded_nd_f64.dtype == np.float64
+    assert np.array_equal(decoded_nd_f64, value_nd_f64)
+
+
+def test_ndarray_dimension_mismatch() -> None:
+    """Test dimension enforcement for Vector with specified dimension."""
+    value = np.array([1.0, 2.0], dtype=np.float32)
+    encoded = encode_engine_value(value)
+    assert np.array_equal(encoded, [1.0, 2.0])
+    with pytest.raises(ValueError, match="Vector dimension mismatch"):
+        build_engine_value_decoder(Float32VectorType)(encoded)
+
+
+def test_list_vector_backward_compatibility() -> None:
+    """Test that list-based vectors still work for backward compatibility."""
+    value = [1, 2, 3, 4, 5]
+    encoded = encode_engine_value(value)
+    assert encoded == [1, 2, 3, 4, 5]
+    decoded = build_engine_value_decoder(IntVectorType)(encoded)
+    assert isinstance(decoded, np.ndarray)
+    assert decoded.dtype == np.int64
+    assert np.array_equal(decoded, np.array([1, 2, 3, 4, 5], dtype=np.int64))
+    value_list: ListIntType = [1, 2, 3, 4, 5]
+    encoded = encode_engine_value(value_list)
+    assert np.array_equal(encoded, [1, 2, 3, 4, 5])
+    decoded = build_engine_value_decoder(ListIntType)(encoded)
+    assert np.array_equal(decoded, [1, 2, 3, 4, 5])
+
+
+def test_encode_complex_structure_with_ndarray() -> None:
+    """Test encoding a complex structure that includes an NDArray."""
+
+    @dataclass
+    class MyStructWithNDArray:
+        name: str
+        data: NDArray[np.float32]
+        value: int
+
+    original = MyStructWithNDArray(
+        name="test_np", data=np.array([1.0, 0.5], dtype=np.float32), value=100
+    )
+    encoded = encode_engine_value(original)
+
+    assert encoded[0] == original.name
+    assert np.array_equal(encoded[1], original.data)
+    assert encoded[2] == original.value
+
+
+def test_decode_nullable_ndarray_none_or_value_input() -> None:
+    """Test decoding a nullable NDArray with None or value inputs."""
+    src_type_dict = {
+        "kind": "Vector",
+        "element_type": {"kind": "Float32"},
+        "dimension": None,
+    }
+    dst_annotation = NDArrayFloat32Type | None
+    decoder = make_engine_value_decoder([], src_type_dict, dst_annotation)
+
+    none_engine_value = None
+    decoded_array = decoder(none_engine_value)
+    assert decoded_array is None
+
+    engine_value = [1.0, 2.0, 3.0]
+    decoded_array = decoder(engine_value)
+
+    assert isinstance(decoded_array, np.ndarray)
+    assert decoded_array.dtype == np.float32
+    np.testing.assert_array_equal(
+        decoded_array, np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    )
+
+
+def test_decode_vector_string() -> None:
+    """Test decoding a vector of strings works for Python native list type."""
+    src_type_dict = {
+        "kind": "Vector",
+        "element_type": {"kind": "Str"},
+        "dimension": None,
+    }
+    decoder = make_engine_value_decoder([], src_type_dict, Vector[str])
+    assert decoder(["hello", "world"]) == ["hello", "world"]
+
+
+def test_decode_error_non_nullable_or_non_list_vector() -> None:
+    """Test decoding errors for non-nullable vectors or non-list inputs."""
+    src_type_dict = {
+        "kind": "Vector",
+        "element_type": {"kind": "Float32"},
+        "dimension": None,
+    }
+    decoder = make_engine_value_decoder([], src_type_dict, NDArrayFloat32Type)
+    with pytest.raises(ValueError, match="Received null for non-nullable vector"):
+        decoder(None)
+    with pytest.raises(TypeError, match="Expected NDArray or list for vector"):
+        decoder("not a list")
+
+
+def test_dump_vector_type_annotation_with_dim() -> None:
+    """Test dumping a vector type annotation with a specified dimension."""
+    expected_dump = {
+        "type": {
+            "kind": "Vector",
+            "element_type": {"kind": "Float32"},
+            "dimension": 3,
+        }
+    }
+    assert dump_engine_object(Float32VectorType) == expected_dump
+
+
+def test_dump_vector_type_annotation_no_dim() -> None:
+    """Test dumping a vector type annotation with no dimension."""
+    expected_dump_no_dim = {
+        "type": {
+            "kind": "Vector",
+            "element_type": {"kind": "Float64"},
+            "dimension": None,
+        }
+    }
+    assert dump_engine_object(Float64VectorTypeNoDim) == expected_dump_no_dim
+
+
+def test_full_roundtrip_vector_numeric_types() -> None:
+    """Test full roundtrip for numeric vector types using NDArray."""
+    value_f32: Vector[np.float32, Literal[3]] = np.array(
+        [1.0, 2.0, 3.0], dtype=np.float32
+    )
+    validate_full_roundtrip(value_f32, Vector[np.float32, Literal[3]])
+    value_f64: Vector[np.float64, Literal[3]] = np.array(
+        [1.0, 2.0, 3.0], dtype=np.float64
+    )
+    validate_full_roundtrip(value_f64, Vector[np.float64, Literal[3]])
+    value_i64: Vector[np.int64, Literal[3]] = np.array([1, 2, 3], dtype=np.int64)
+    validate_full_roundtrip(value_i64, Vector[np.int64, Literal[3]])
+    value_i32: Vector[np.int32, Literal[3]] = np.array([1, 2, 3], dtype=np.int32)
+    with pytest.raises(ValueError, match="type unsupported yet"):
+        validate_full_roundtrip(value_i32, Vector[np.int32, Literal[3]])
+    value_u8: Vector[np.uint8, Literal[3]] = np.array([1, 2, 3], dtype=np.uint8)
+    with pytest.raises(ValueError, match="type unsupported yet"):
+        validate_full_roundtrip(value_u8, Vector[np.uint8, Literal[3]])
+    value_u16: Vector[np.uint16, Literal[3]] = np.array([1, 2, 3], dtype=np.uint16)
+    with pytest.raises(ValueError, match="type unsupported yet"):
+        validate_full_roundtrip(value_u16, Vector[np.uint16, Literal[3]])
+    value_u32: Vector[np.uint32, Literal[3]] = np.array([1, 2, 3], dtype=np.uint32)
+    with pytest.raises(ValueError, match="type unsupported yet"):
+        validate_full_roundtrip(value_u32, Vector[np.uint32, Literal[3]])
+    value_u64: Vector[np.uint64, Literal[3]] = np.array([1, 2, 3], dtype=np.uint64)
+    with pytest.raises(ValueError, match="type unsupported yet"):
+        validate_full_roundtrip(value_u64, Vector[np.uint64, Literal[3]])
+
+
+def test_roundtrip_vector_no_dimension() -> None:
+    """Test full roundtrip for vector types without dimension annotation."""
+    value_f64: Vector[np.float64] = np.array([1.0, 2.0, 3.0], dtype=np.float64)
+    validate_full_roundtrip(value_f64, Vector[np.float64])
+
+
+def test_roundtrip_string_vector() -> None:
+    """Test full roundtrip for string vector using list."""
+    value_str: Vector[str] = ["hello", "world"]
+    validate_full_roundtrip(value_str, Vector[str])
+
+
+def test_roundtrip_empty_vector() -> None:
+    """Test full roundtrip for empty numeric vector."""
+    value_empty: Vector[np.float32] = np.array([], dtype=np.float32)
+    validate_full_roundtrip(value_empty, Vector[np.float32])
+
+
+def test_roundtrip_dimension_mismatch() -> None:
+    """Test that dimension mismatch raises an error during roundtrip."""
+    value_f32: Vector[np.float32, Literal[3]] = np.array([1.0, 2.0], dtype=np.float32)
+    with pytest.raises(ValueError, match="Vector dimension mismatch"):
+        validate_full_roundtrip(value_f32, Vector[np.float32, Literal[3]])
+
+
+def test_roundtrip_list_backward_compatibility() -> None:
+    """Test full roundtrip for list-based vectors for backward compatibility."""
+    value_list: list[int] = [1, 2, 3]
+    validate_full_roundtrip(value_list, list[int])