cocoindex 0.1.72__tar.gz → 0.1.73__tar.gz

{cocoindex-0.1.72 → cocoindex-0.1.73}/Cargo.lock

@@ -1297,7 +1297,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.1.72"
+version = "0.1.73"
 dependencies = [
  "anyhow",
  "async-openai",

{cocoindex-0.1.72 → cocoindex-0.1.73}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cocoindex"
 # Version used for local development is always higher than others to take precedence.
 # Will be overridden for specific release versions.
-version = "0.1.72"
+version = "0.1.73"
 edition = "2024"
 rust-version = "1.88"
 

{cocoindex-0.1.72 → cocoindex-0.1.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.72
+Version: 0.1.73
 Requires-Dist: click>=8.1.8
 Requires-Dist: rich>=14.0.0
 Requires-Dist: python-dotenv>=1.1.0

{cocoindex-0.1.72 → cocoindex-0.1.73}/docs/docs/core/data_types.mdx

@@ -88,8 +88,8 @@ Optionally, it can have a fixed dimension. Noted as *Vector[Type]* or *Vector[Ty
 It supports the following Python types:
 
 *   `cocoindex.Vector[T]` or `cocoindex.Vector[T, typing.Literal[Dim]]`, e.g. `cocoindex.Vector[cocoindex.Float32]` or `cocoindex.Vector[cocoindex.Float32, typing.Literal[384]]`
-    *   The underlying Python type is `numpy.typing.NDArray[T]` where `T` is a numpy numeric type (`numpy.int64`, `numpy.float32` or `numpy.float64`), or `list[T]` otherwise
-*   `numpy.typing.NDArray[T]` where `T` is a numpy numeric type
+    *   The underlying Python type is `numpy.typing.NDArray[T]` where `T` is a numpy numeric type (`numpy.int64`, `numpy.float32` or `numpy.float64`) or array type (`numpy.typing.NDArray[T]`), or `list[T]` otherwise
+*   `numpy.typing.NDArray[T]` where `T` is a numpy numeric type or array type
 *   `list[T]`
 
 

{cocoindex-0.1.72 → cocoindex-0.1.73}/docs/docs/ops/targets.md

@@ -63,11 +63,16 @@ Here's how CocoIndex data elements map to Qdrant elements during export:
 | a collected row   | a point |
 | a field           | a named vector, if fits into Qdrant vector; or a field within payload otherwise |
 
-*Vector[Float32, N]*, *Vector[Float64, N]* and *Vector[Int64, N]* types fit into Qdrant vector.
+The following vector types fit into Qdrant vector:
+*   One-dimensional vectors with fixed dimension, e.g. *Vector[Float32, N]*, *Vector[Float64, N]* and *Vector[Int64, N]*.
+    We map them to [dense vectors](https://qdrant.tech/documentation/concepts/vectors/#dense-vectors).
+*   Two-dimensional vectors whose inner layer is a one-dimensional vector with fixed dimension, e.g. *Vector[Vector[Float32, N]]*, *Vector[Vector[Int64, N]]*, *Vector[Vector[Float64, N]]*. The outer layer may or may not have a fixed dimension.
+    We map them to [multivectors](https://qdrant.tech/documentation/concepts/vectors/#multivectors).
+
 
 :::warning vector type mapping to Qdrant
 
-Since vectors in Qdrant must have fixed dimension, we only map vectors of number types with fixed dimension (i.e. *Vector[cocoindex.Float32, N]*, *Vector[cocoindex.Float64, N]*, and *Vector[cocoindex.Int64, N]*) to Qdrant vectors.
+Since vectors in Qdrant must have fixed dimension, we only map vectors of number types with fixed dimension to Qdrant vectors.
 For all other vector types, we map to Qdrant payload as JSON arrays.
 
 :::

{cocoindex-0.1.72 → cocoindex-0.1.73}/examples/face_recognition/README.md

@@ -21,7 +21,12 @@ We appreciate a star ⭐ at [CocoIndex Github](https://github.com/cocoindex-io/c
 
 1.  [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
 
-2.  dependencies:
+2.  Install Qdrant
+    ```bash
+    docker run -d -p 6334:6334 -p 6333:6333 qdrant/qdrant
+    ```
+
+3.  Install dependencies:
 
     ```bash
     pip install -e .

{cocoindex-0.1.72 → cocoindex-0.1.73}/examples/face_recognition/main.py

@@ -1,12 +1,15 @@
 import cocoindex
-import io
 import dataclasses
 import datetime
-import typing
+import io
+import os
 
 import face_recognition
-from PIL import Image
 import numpy as np
+from PIL import Image
+
+QDRANT_URL = os.getenv("QDRANT_URL", "http://localhost:6334/")
+QDRANT_COLLECTION = "face_embeddings"
 
 
 @dataclasses.dataclass
@@ -35,7 +38,7 @@ MAX_IMAGE_WIDTH = 1280
     arg_relationship=(cocoindex.op.ArgRelationship.RECTS_BASE_IMAGE, "content"),
 )
 def extract_faces(content: bytes) -> list[FaceBase]:
-    """Extract the first pages of a PDF."""
+    """Extract the faces from a image."""
     orig_img = Image.open(io.BytesIO(content)).convert("RGB")
 
     # The model is too slow on large images, so we resize them if too large.
@@ -90,7 +93,7 @@ def face_recognition_flow(
     flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope
 ) -> None:
     """
-    Define an example flow that embeds files into a vector database.
+    Define an example flow that embeds files into Qdrant vector database.
     """
     data_scope["images"] = flow_builder.add_source(
         cocoindex.sources.LocalFile(path="images", binary=True),
@@ -108,13 +111,14 @@ def face_recognition_flow(
 
             # Collect embeddings
             face_embeddings.collect(
+                id=cocoindex.GeneratedField.UUID,
                 filename=image["filename"],
                 rect=face["rect"],
                 embedding=face["embedding"],
             )
 
     face_embeddings.export(
-        "face_embeddings",
-        cocoindex.targets.Postgres(),
-        primary_key_fields=["filename", "rect"],
+        QDRANT_COLLECTION,
+        cocoindex.targets.Qdrant(collection_name=QDRANT_COLLECTION),
+        primary_key_fields=["id"],
     )

{cocoindex-0.1.72 → cocoindex-0.1.73}/python/cocoindex/convert.py

@@ -13,12 +13,19 @@ import numpy as np
 from .typing import (
     KEY_FIELD_NAME,
     TABLE_TYPES,
-    DtypeRegistry,
     analyze_type_info,
     encode_enriched_type,
-    extract_ndarray_scalar_dtype,
     is_namedtuple_type,
     is_struct_type,
+    AnalyzedTypeInfo,
+    AnalyzedAnyType,
+    AnalyzedDictType,
+    AnalyzedListType,
+    AnalyzedBasicType,
+    AnalyzedUnionType,
+    AnalyzedUnknownType,
+    AnalyzedStructType,
+    is_numpy_number_type,
 )
 
 
@@ -79,46 +86,88 @@ def make_engine_value_decoder(
     Returns:
         A decoder from an engine value to a Python value.
     """
+
     src_type_kind = src_type["kind"]
 
-    dst_is_any = (
-        dst_annotation is None
-        or dst_annotation is inspect.Parameter.empty
-        or dst_annotation is Any
-    )
-    if dst_is_any:
-        if src_type_kind == "Union":
-            return lambda value: value[1]
-        if src_type_kind == "Struct":
-            return _make_engine_struct_to_dict_decoder(field_path, src_type["fields"])
-        if src_type_kind in TABLE_TYPES:
-            if src_type_kind == "LTable":
+    dst_type_info = analyze_type_info(dst_annotation)
+    dst_type_variant = dst_type_info.variant
+
+    if isinstance(dst_type_variant, AnalyzedUnknownType):
+        raise ValueError(
+            f"Type mismatch for `{''.join(field_path)}`: "
+            f"declared `{dst_type_info.core_type}`, an unsupported type"
+        )
+
+    if src_type_kind == "Struct":
+        return _make_engine_struct_value_decoder(
+            field_path,
+            src_type["fields"],
+            dst_type_info,
+        )
+
+    if src_type_kind in TABLE_TYPES:
+        field_path.append("[*]")
+        engine_fields_schema = src_type["row"]["fields"]
+
+        if src_type_kind == "LTable":
+            if isinstance(dst_type_variant, AnalyzedAnyType):
                 return _make_engine_ltable_to_list_dict_decoder(
-                    field_path, src_type["row"]["fields"]
+                    field_path, engine_fields_schema
+                )
+            if not isinstance(dst_type_variant, AnalyzedListType):
+                raise ValueError(
+                    f"Type mismatch for `{''.join(field_path)}`: "
+                    f"declared `{dst_type_info.core_type}`, a list type expected"
                 )
-            elif src_type_kind == "KTable":
+            row_decoder = _make_engine_struct_value_decoder(
+                field_path,
+                engine_fields_schema,
+                analyze_type_info(dst_type_variant.elem_type),
+            )
+
+            def decode(value: Any) -> Any | None:
+                if value is None:
+                    return None
+                return [row_decoder(v) for v in value]
+
+        elif src_type_kind == "KTable":
+            if isinstance(dst_type_variant, AnalyzedAnyType):
                 return _make_engine_ktable_to_dict_dict_decoder(
-                    field_path, src_type["row"]["fields"]
+                    field_path, engine_fields_schema
+                )
+            if not isinstance(dst_type_variant, AnalyzedDictType):
+                raise ValueError(
+                    f"Type mismatch for `{''.join(field_path)}`: "
+                    f"declared `{dst_type_info.core_type}`, a dict type expected"
                 )
-        return lambda value: value
 
-    # Handle struct -> dict binding for explicit dict annotations
-    is_dict_annotation = False
-    if dst_annotation is dict:
-        is_dict_annotation = True
-    elif getattr(dst_annotation, "__origin__", None) is dict:
-        args = getattr(dst_annotation, "__args__", ())
-        if args == (str, Any):
-            is_dict_annotation = True
-    if is_dict_annotation and src_type_kind == "Struct":
-        return _make_engine_struct_to_dict_decoder(field_path, src_type["fields"])
+            key_field_schema = engine_fields_schema[0]
+            field_path.append(f".{key_field_schema.get('name', KEY_FIELD_NAME)}")
+            key_decoder = make_engine_value_decoder(
+                field_path, key_field_schema["type"], dst_type_variant.key_type
+            )
+            field_path.pop()
+            value_decoder = _make_engine_struct_value_decoder(
+                field_path,
+                engine_fields_schema[1:],
+                analyze_type_info(dst_type_variant.value_type),
+            )
 
-    dst_type_info = analyze_type_info(dst_annotation)
+            def decode(value: Any) -> Any | None:
+                if value is None:
+                    return None
+                return {key_decoder(v[0]): value_decoder(v[1:]) for v in value}
+
+        field_path.pop()
+        return decode
 
     if src_type_kind == "Union":
+        if isinstance(dst_type_variant, AnalyzedAnyType):
+            return lambda value: value[1]
+
         dst_type_variants = (
-            dst_type_info.union_variant_types
-            if dst_type_info.union_variant_types is not None
+            dst_type_variant.variant_types
+            if isinstance(dst_type_variant, AnalyzedUnionType)
             else [dst_annotation]
         )
         src_type_variants = src_type["types"]
@@ -142,43 +191,33 @@ def make_engine_value_decoder(
             decoders.append(decoder)
         return lambda value: decoders[value[0]](value[1])
 
-    if not _is_type_kind_convertible_to(src_type_kind, dst_type_info.kind):
-        raise ValueError(
-            f"Type mismatch for `{''.join(field_path)}`: "
-            f"passed in {src_type_kind}, declared {dst_annotation} ({dst_type_info.kind})"
-        )
-
-    if dst_type_info.kind in ("Float32", "Float64", "Int64"):
-        dst_core_type = dst_type_info.core_type
-
-        def decode_scalar(value: Any) -> Any | None:
-            if value is None:
-                if dst_type_info.nullable:
-                    return None
-                raise ValueError(
-                    f"Received null for non-nullable scalar `{''.join(field_path)}`"
-                )
-            return dst_core_type(value)
-
-        return decode_scalar
+    if isinstance(dst_type_variant, AnalyzedAnyType):
+        return lambda value: value
 
     if src_type_kind == "Vector":
         field_path_str = "".join(field_path)
+        if not isinstance(dst_type_variant, AnalyzedListType):
+            raise ValueError(
+                f"Type mismatch for `{''.join(field_path)}`: "
+                f"declared `{dst_type_info.core_type}`, a list type expected"
+            )
         expected_dim = (
-            dst_type_info.vector_info.dim if dst_type_info.vector_info else None
+            dst_type_variant.vector_info.dim
+            if dst_type_variant and dst_type_variant.vector_info
+            else None
         )
 
-        elem_decoder = None
+        vec_elem_decoder = None
         scalar_dtype = None
-        if dst_type_info.np_number_type is None:  # for Non-NDArray vector
-            elem_decoder = make_engine_value_decoder(
+        if dst_type_variant and dst_type_info.base_type is np.ndarray:
+            if is_numpy_number_type(dst_type_variant.elem_type):
+                scalar_dtype = dst_type_variant.elem_type
+        else:
+            vec_elem_decoder = make_engine_value_decoder(
                 field_path + ["[*]"],
                 src_type["element_type"],
-                dst_type_info.elem_type,
+                dst_type_variant and dst_type_variant.elem_type,
             )
-        else:  # for NDArray vector
-            scalar_dtype = extract_ndarray_scalar_dtype(dst_type_info.np_number_type)
-            _ = DtypeRegistry.validate_dtype_and_get_kind(scalar_dtype)
 
         def decode_vector(value: Any) -> Any | None:
             if value is None:
@@ -197,54 +236,33 @@ def make_engine_value_decoder(
                     f"expected {expected_dim}, got {len(value)}"
                 )
 
-            if elem_decoder is not None:  # for Non-NDArray vector
-                return [elem_decoder(v) for v in value]
+            if vec_elem_decoder is not None:  # for Non-NDArray vector
+                return [vec_elem_decoder(v) for v in value]
             else:  # for NDArray vector
                 return np.array(value, dtype=scalar_dtype)
 
         return decode_vector
 
-    if dst_type_info.struct_type is not None:
-        return _make_engine_struct_value_decoder(
-            field_path, src_type["fields"], dst_type_info.struct_type
-        )
-
-    if src_type_kind in TABLE_TYPES:
-        field_path.append("[*]")
-        elem_type_info = analyze_type_info(dst_type_info.elem_type)
-        if elem_type_info.struct_type is None:
+    if isinstance(dst_type_variant, AnalyzedBasicType):
+        if not _is_type_kind_convertible_to(src_type_kind, dst_type_variant.kind):
             raise ValueError(
                 f"Type mismatch for `{''.join(field_path)}`: "
-                f"declared `{dst_type_info.kind}`, a dataclass or NamedTuple type expected"
-            )
-        engine_fields_schema = src_type["row"]["fields"]
-        if elem_type_info.key_type is not None:
-            key_field_schema = engine_fields_schema[0]
-            field_path.append(f".{key_field_schema.get('name', KEY_FIELD_NAME)}")
-            key_decoder = make_engine_value_decoder(
-                field_path, key_field_schema["type"], elem_type_info.key_type
-            )
-            field_path.pop()
-            value_decoder = _make_engine_struct_value_decoder(
-                field_path, engine_fields_schema[1:], elem_type_info.struct_type
+                f"passed in {src_type_kind}, declared {dst_annotation} ({dst_type_variant.kind})"
             )
 
-            def decode(value: Any) -> Any | None:
-                if value is None:
-                    return None
-                return {key_decoder(v[0]): value_decoder(v[1:]) for v in value}
-        else:
-            elem_decoder = _make_engine_struct_value_decoder(
-                field_path, engine_fields_schema, elem_type_info.struct_type
-            )
+        if dst_type_variant.kind in ("Float32", "Float64", "Int64"):
+            dst_core_type = dst_type_info.core_type
 
-            def decode(value: Any) -> Any | None:
+            def decode_scalar(value: Any) -> Any | None:
                 if value is None:
-                    return None
-                return [elem_decoder(v) for v in value]
+                    if dst_type_info.nullable:
+                        return None
+                    raise ValueError(
+                        f"Received null for non-nullable scalar `{''.join(field_path)}`"
+                    )
+                return dst_core_type(value)
 
-        field_path.pop()
-        return decode
+            return decode_scalar
 
     return lambda value: value
 
@@ -252,11 +270,36 @@ def make_engine_value_decoder(
 def _make_engine_struct_value_decoder(
     field_path: list[str],
     src_fields: list[dict[str, Any]],
-    dst_struct_type: type,
+    dst_type_info: AnalyzedTypeInfo,
 ) -> Callable[[list[Any]], Any]:
     """Make a decoder from an engine field values to a Python value."""
 
+    dst_type_variant = dst_type_info.variant
+
+    use_dict = False
+    if isinstance(dst_type_variant, AnalyzedAnyType):
+        use_dict = True
+    elif isinstance(dst_type_variant, AnalyzedDictType):
+        analyzed_key_type = analyze_type_info(dst_type_variant.key_type)
+        analyzed_value_type = analyze_type_info(dst_type_variant.value_type)
+        use_dict = (
+            isinstance(analyzed_key_type.variant, AnalyzedAnyType)
+            or (
+                isinstance(analyzed_key_type.variant, AnalyzedBasicType)
+                and analyzed_key_type.variant.kind == "Str"
+            )
+        ) and isinstance(analyzed_value_type.variant, AnalyzedAnyType)
+    if use_dict:
+        return _make_engine_struct_to_dict_decoder(field_path, src_fields)
+
+    if not isinstance(dst_type_variant, AnalyzedStructType):
+        raise ValueError(
+            f"Type mismatch for `{''.join(field_path)}`: "
+            f"declared `{dst_type_info.core_type}`, a dataclass, NamedTuple or dict[str, Any] expected"
+        )
+
     src_name_to_idx = {f["name"]: i for i, f in enumerate(src_fields)}
+    dst_struct_type = dst_type_variant.struct_type
 
     parameters: Mapping[str, inspect.Parameter]
     if dataclasses.is_dataclass(dst_struct_type):

{cocoindex-0.1.72 → cocoindex-0.1.73}/python/cocoindex/tests/test_convert.py

@@ -105,7 +105,9 @@ def validate_full_roundtrip_to(
     for other_value, other_type in decoded_values:
         decoder = make_engine_value_decoder([], encoded_output_type, other_type)
         other_decoded_value = decoder(value_from_engine)
-        assert eq(other_decoded_value, other_value)
+        assert eq(other_decoded_value, other_value), (
+            f"Expected {other_value} but got {other_decoded_value} for {other_type}"
+        )
 
 
 def validate_full_roundtrip(
@@ -1096,6 +1098,25 @@ def test_full_roundtrip_vector_numeric_types() -> None:
         validate_full_roundtrip(value_u64, Vector[np.uint64, Literal[3]])
 
 
+def test_full_roundtrip_vector_of_vector() -> None:
+    """Test full roundtrip for vector of vector."""
+    value_f32 = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], dtype=np.float32)
+    validate_full_roundtrip(
+        value_f32,
+        Vector[Vector[np.float32, Literal[3]], Literal[2]],
+        ([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], list[list[np.float32]]),
+        ([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], list[list[cocoindex.Float32]]),
+        (
+            [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
+            list[Vector[cocoindex.Float32, Literal[3]]],
+        ),
+        (
+            value_f32,
+            np.typing.NDArray[np.typing.NDArray[np.float32]],
+        ),
+    )
+
+
 def test_full_roundtrip_vector_other_types() -> None:
     """Test full roundtrip for Vector with non-numeric basic types."""
     uuid_list = [uuid.uuid4(), uuid.uuid4()]
@@ -1216,7 +1237,7 @@ def test_full_roundtrip_scalar_with_python_types() -> None:
         numpy_float: np.float64
         python_float: float
         string: str
-        annotated_int: Annotated[np.int64, TypeKind("int")]
+        annotated_int: Annotated[np.int64, TypeKind("Int64")]
         annotated_float: Float32
 
     instance = MixedStruct(