zvec 0.8.0__cp313-cp313-win_arm64.whl

zvec/__init__.py

@@ -0,0 +1,205 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from importlib.metadata import PackageNotFoundError
+
+# zvec ships a native C++ extension that is only built and tested for 64-bit
+# CPython. A 32-bit interpreter would fail to load the extension with an
+# obscure error, so fail fast here with an actionable message.
+if sys.maxsize <= 2**32:
+    raise ImportError(
+        "zvec requires a 64-bit Python interpreter; "
+        "the current interpreter is 32-bit and is not supported."
+    )
+
+
+from zvec._zvec import io_backend_description, io_backend_type
+
+# ==============================
+# Public API — grouped by category
+# ==============================
+from . import model as model
+
+# —— Extensions ——
+from .extension import (
+    BM25EmbeddingFunction,
+    DefaultLocalDenseEmbedding,
+    DefaultLocalReRanker,
+    DefaultLocalSparseEmbedding,
+    DenseEmbeddingFunction,
+    OpenAIDenseEmbedding,
+    OpenAIFunctionBase,
+    QwenDenseEmbedding,
+    QwenFunctionBase,
+    QwenReRanker,
+    QwenSparseEmbedding,
+    ReRanker,
+    RrfReRanker,
+    SentenceTransformerFunctionBase,
+    SparseEmbeddingFunction,
+    WeightedReRanker,
+)
+
+# —— Typing ——
+from .model import param as param
+from .model import schema as schema
+
+# —— Core data structures ——
+from .model.collection import Collection
+from .model.doc import Doc, DocList, GroupResult
+
+# —— Query & index parameters ——
+# —— FTS params (C++ binding) ——
+from .model.param import (
+    AddColumnOption,
+    AlterColumnOption,
+    CollectionOption,
+    DiskAnnIndexParam,
+    DiskAnnQueryParam,
+    FlatIndexParam,
+    FtsIndexParam,
+    FtsQueryParam,
+    HnswIndexParam,
+    HnswQueryParam,
+    HnswRabitqIndexParam,
+    HnswRabitqQueryParam,
+    IndexOption,
+    InvertIndexParam,
+    IVFIndexParam,
+    IVFQueryParam,
+    IvfRabitqIndexParam,
+    IvfRabitqQueryParam,
+    OptimizeOption,
+    QuantizerParam,
+    VamanaIndexParam,
+    VamanaQueryParam,
+)
+from .model.param.query import Fts, Query, VectorQuery
+
+# —— Schema & field definitions ——
+from .model.schema import CollectionSchema, CollectionStats, FieldSchema, VectorSchema
+
+# —— tools ——
+from .tool import require_module
+from .typing import (
+    DataType,
+    IndexType,
+    IOBackendType,
+    MetricType,
+    QuantizeType,
+    Status,
+    StatusCode,
+)
+from .typing.enum import LogLevel, LogType
+
+# —— lifecycle ——
+from .zvec import create_and_open, init, open
+
+# ==============================
+# Public interface declaration
+# ==============================
+__all__ = [
+    # Zvec functions
+    "create_and_open",
+    "init",
+    "open",
+    "io_backend_type",
+    "io_backend_description",
+    # Core classes
+    "Collection",
+    "Doc",
+    "DocList",
+    # Schema
+    "CollectionSchema",
+    "FieldSchema",
+    "VectorSchema",
+    "CollectionStats",
+    # Parameters
+    "GroupResult",
+    "Query",
+    "VectorQuery",
+    "Fts",
+    "FtsIndexParam",
+    "FtsQueryParam",
+    "InvertIndexParam",
+    "HnswIndexParam",
+    "HnswRabitqIndexParam",
+    "IvfRabitqIndexParam",
+    "FlatIndexParam",
+    "IVFIndexParam",
+    "DiskAnnIndexParam",
+    "DiskAnnQueryParam",
+    "CollectionOption",
+    "IndexOption",
+    "OptimizeOption",
+    "AddColumnOption",
+    "AlterColumnOption",
+    "HnswQueryParam",
+    "HnswRabitqQueryParam",
+    "IvfRabitqQueryParam",
+    "IVFQueryParam",
+    "QuantizerParam",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
+    # Extensions
+    "DenseEmbeddingFunction",
+    "SparseEmbeddingFunction",
+    "QwenFunctionBase",
+    "OpenAIFunctionBase",
+    "SentenceTransformerFunctionBase",
+    "ReRanker",
+    "DefaultLocalDenseEmbedding",
+    "DefaultLocalSparseEmbedding",
+    "BM25EmbeddingFunction",
+    "OpenAIDenseEmbedding",
+    "QwenDenseEmbedding",
+    "QwenSparseEmbedding",
+    "RrfReRanker",
+    "WeightedReRanker",
+    "DefaultLocalReRanker",
+    "QwenReRanker",
+    # Typing
+    "DataType",
+    "IOBackendType",
+    "MetricType",
+    "QuantizeType",
+    "IndexType",
+    "LogLevel",
+    "LogType",
+    "Status",
+    "StatusCode",
+    # Tools
+    "require_module",
+]
+
+# ==============================
+# Version handling
+# ==============================
+__version__: str
+
+try:
+    from importlib.metadata import version
+except ImportError:
+    from importlib_metadata import version  # Python < 3.8
+
+try:
+    __version__ = version("zvec")
+except Exception:
+    __version__ = "unknown"

zvec/__init__.pyi

@@ -0,0 +1,242 @@
+"""
+Zvec core module
+"""
+
+from __future__ import annotations
+
+import collections
+
+from . import typing
+from .extension import ReRanker, RrfReRanker, WeightedReRanker
+from .extension.embedding import DenseEmbeddingFunction
+from .model import param, schema
+from .model.collection import Collection
+from .model.doc import Doc, DocList, GroupResult
+from .model.param import (
+    AddColumnOption,
+    AlterColumnOption,
+    CollectionOption,
+    DiskAnnIndexParam,
+    DiskAnnQueryParam,
+    FlatIndexParam,
+    FtsIndexParam,
+    FtsQueryParam,
+    HnswIndexParam,
+    HnswQueryParam,
+    HnswRabitqIndexParam,
+    HnswRabitqQueryParam,
+    IndexOption,
+    InvertIndexParam,
+    IVFIndexParam,
+    IVFQueryParam,
+    IvfRabitqIndexParam,
+    IvfRabitqQueryParam,
+    OptimizeOption,
+    QuantizerParam,
+    VamanaIndexParam,
+    VamanaQueryParam,
+)
+from .model.param.query import Fts, Query, VectorQuery
+from .model.schema import CollectionSchema, CollectionStats, FieldSchema, VectorSchema
+from .tool import require_module
+from .typing import (
+    DataType,
+    IndexType,
+    IOBackendType,
+    MetricType,
+    QuantizeType,
+    Status,
+    StatusCode,
+)
+from .typing.enum import LogLevel, LogType
+from .zvec import create_and_open, init, open
+
+def io_backend_type() -> IOBackendType:
+    """Returns the current I/O backend type for DiskAnn disk reads.
+
+    Linux selects IOBackendType.IO_URING, IOBackendType.LIBAIO, or
+    IOBackendType.PREAD in that order. macOS ARM64 uses IOBackendType.PREAD.
+    Windows uses IOBackendType.WINDOWS_OVERLAPPED.
+    """
+
+def io_backend_description() -> str:
+    """Returns a human-readable description of the current I/O backend.
+
+    The description identifies io_uring, libaio, or pread. On Linux, the
+    pread description includes guidance for enabling io_uring or installing
+    libaio. Windows reports its overlapped-I/O backend.
+    """
+
+__all__: list = [
+    "AddColumnOption",
+    "AlterColumnOption",
+    "Collection",
+    "CollectionOption",
+    "CollectionSchema",
+    "CollectionStats",
+    "DataType",
+    "DenseEmbeddingFunction",
+    "DiskAnnIndexParam",
+    "DiskAnnQueryParam",
+    "Doc",
+    "DocList",
+    "FieldSchema",
+    "FlatIndexParam",
+    "Fts",
+    "FtsIndexParam",
+    "FtsQueryParam",
+    "GroupResult",
+    "HnswIndexParam",
+    "HnswQueryParam",
+    "HnswRabitqIndexParam",
+    "HnswRabitqQueryParam",
+    "IOBackendType",
+    "IVFIndexParam",
+    "IVFQueryParam",
+    "IndexOption",
+    "IndexType",
+    "InvertIndexParam",
+    "IvfRabitqIndexParam",
+    "IvfRabitqQueryParam",
+    "LogLevel",
+    "LogType",
+    "MetricType",
+    "OptimizeOption",
+    "QuantizeType",
+    "QuantizerParam",
+    "Query",
+    "ReRanker",
+    "RrfReRanker",
+    "Status",
+    "StatusCode",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
+    "VectorQuery",
+    "VectorSchema",
+    "WeightedReRanker",
+    "create_and_open",
+    "init",
+    "io_backend_description",
+    "io_backend_type",
+    "open",
+    "require_module",
+]
+
+class _Collection:
+    @staticmethod
+    def CreateAndOpen(
+        arg0: str, arg1: schema._CollectionSchema, arg2: param.CollectionOption
+    ) -> _Collection: ...
+    @staticmethod
+    def Open(arg0: str, arg1: param.CollectionOption) -> _Collection: ...
+    def AddColumn(
+        self,
+        arg0: schema._FieldSchema,
+        arg1: str,
+        arg2: param.AddColumnOption,
+    ) -> None: ...
+    def AlterColumn(
+        self,
+        arg0: str,
+        arg1: str,
+        arg2: schema._FieldSchema,
+        arg3: param.AlterColumnOption,
+    ) -> None: ...
+    def Close(self) -> None: ...
+    def CreateIndex(
+        self, arg0: str, arg1: param.IndexParam, arg2: param.IndexOption
+    ) -> None: ...
+    def Delete(self, arg0: collections.abc.Sequence[str]) -> list[typing.Status]: ...
+    def DeleteByFilter(self, arg0: str) -> None: ...
+    def Destroy(self) -> None: ...
+    def DropColumn(self, arg0: str) -> None: ...
+    def DropIndex(self, arg0: str) -> None: ...
+    def Fetch(
+        self,
+        pks: collections.abc.Sequence[str],
+        output_fields: list[str] | None = None,
+        include_vector: bool = True,
+    ) -> dict[str, _Doc]: ...
+    def Flush(self) -> None: ...
+    def GroupByQuery(self, arg0: param._GroupByVectorQuery) -> list[_GroupResult]: ...
+    def Insert(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
+    def Optimize(self, arg0: param.OptimizeOption) -> None: ...
+    def Options(self) -> param.CollectionOption: ...
+    def Path(self) -> str: ...
+    def Query(
+        self, arg0: param._SearchQuery
+    ) -> list[tuple[str, float, dict | None, dict | None] | None]: ...
+    def QueryInternalIds(
+        self, query: param._SearchQuery, return_scores: bool = False
+    ) -> typing.Any: ...
+    def ResolveInternalIds(
+        self, ids: collections.abc.Sequence[int]
+    ) -> list[str | None]: ...
+    def Schema(self) -> schema._CollectionSchema: ...
+    def Stats(self) -> schema.CollectionStats: ...
+    def Update(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
+    def Upsert(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
+    def _debug_hnsw_storage_mode(self, column_name: str) -> str:
+        """Debug-only: returns the storage mode of the HNSW entity on the
+        given vector column. One of 'mmap', 'buffer_pool', 'contiguous'.
+        Raises KeyError if no HNSW index exists on the column, or
+        ValueError if the column's index is not an HNSW index. Intended
+        for introspection and testing only; not part of the stable API."""
+
+    def __getstate__(self) -> tuple: ...
+    def __setstate__(self, arg0: tuple) -> None: ...
+
+class _Doc:
+    def __getstate__(self) -> bytes: ...
+    def __init__(self) -> None: ...
+    def __setstate__(self, arg0: bytes) -> None: ...
+    def field_names(self) -> list[str]: ...
+    def get_any(self, arg0: str, arg1: typing.DataType) -> typing.Any: ...
+    def has_field(self, arg0: str) -> bool: ...
+    def pk(self) -> str: ...
+    def score(self) -> float: ...
+    def set_any(self, arg0: str, arg1: typing.DataType, arg2: typing.Any) -> bool: ...
+    def set_pk(self, arg0: str) -> None: ...
+    def set_score(self, arg0: typing.SupportsFloat) -> None: ...
+
+class _GroupResult:
+    @property
+    def docs(self) -> list[_Doc]: ...
+    @property
+    def group_by_value(self) -> str: ...
+
+class _DocOp:
+    """
+    Members:
+
+      INSERT
+
+      UPDATE
+
+      DELETE
+
+      UPSERT
+    """
+
+    DELETE: typing.ClassVar[_DocOp]  # value = <_DocOp.DELETE: 3>
+    INSERT: typing.ClassVar[_DocOp]  # value = <_DocOp.INSERT: 0>
+    UPDATE: typing.ClassVar[_DocOp]  # value = <_DocOp.UPDATE: 2>
+    UPSERT: typing.ClassVar[_DocOp]  # value = <_DocOp.UPSERT: 1>
+    __members__: typing.ClassVar[
+        dict[str, _DocOp]
+    ]  # value = {'INSERT': <_DocOp.INSERT: 0>, 'UPDATE': <_DocOp.UPDATE: 2>, 'DELETE': <_DocOp.DELETE: 3>, 'UPSERT': <_DocOp.UPSERT: 1>}
+
+    def __eq__(self, other: typing.Any) -> bool: ...
+    def __getstate__(self) -> int: ...
+    def __hash__(self) -> int: ...
+    def __index__(self) -> int: ...
+    def __init__(self, value: typing.SupportsInt) -> None: ...
+    def __int__(self) -> int: ...
+    def __ne__(self, other: typing.Any) -> bool: ...
+    def __repr__(self) -> str: ...
+    def __setstate__(self, state: typing.SupportsInt) -> None: ...
+    def __str__(self) -> str: ...
+    @property
+    def name(self) -> str: ...
+    @property
+    def value(self) -> int: ...

zvec/common/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from .constants import DenseVectorType, SparseVectorType, VectorType
+
+__all__ = ["DenseVectorType", "SparseVectorType", "VectorType"]

zvec/common/constants.py

@@ -0,0 +1,33 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import Optional, TypeVar, Union
+
+import numpy as np
+
+# VectorType: DenseVectorType | SparseVectorType
+DenseVectorType = Union[list[float], list[int], np.ndarray]
+SparseVectorType = dict[int, float]
+VectorType = Optional[Union[DenseVectorType, SparseVectorType]]
+
+# Embeddable: Text | Image | Audio
+TEXT = str
+IMAGE = Union[str, bytes, np.ndarray]  # file path, raw bytes, or numpy array
+AUDIO = Union[str, bytes, np.ndarray]  # file path, raw bytes, or numpy array
+
+Embeddable = Optional[Union[TEXT, IMAGE, AUDIO]]
+
+# Multimodal Embeddable
+MD = TypeVar("MD", bound=Embeddable, contravariant=True)

zvec/executor/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from .query_executor import (
+    QueryContext,
+    QueryExecutor,
+)
+
+__all__ = [
+    "QueryContext",
+    "QueryExecutor",
+]