vortexdb 0.1.0__py3-none-any.whl

vortexdb/__init__.py

@@ -0,0 +1,35 @@
+# vortexdb/__init__.py
+
+from vortexdb.client import VortexDB
+from vortexdb.async_client import AsyncVortexDB
+from vortexdb.models import (
+    DenseVector,
+    Payload,
+    Point,
+    Similarity,
+)
+from vortexdb.exceptions import (
+    VortexDBError,
+    AuthenticationError,
+    NotFoundError,
+    InvalidArgumentError,
+    TimeoutError,
+    ServiceUnavailableError,
+    InternalServerError,
+)
+
+__all__ = [
+    "VortexDB",
+    "AsyncVortexDB",
+    "DenseVector",
+    "Payload",
+    "Point",
+    "Similarity",
+    "VortexDBError",
+    "AuthenticationError",
+    "NotFoundError",
+    "InvalidArgumentError",
+    "TimeoutError",
+    "ServiceUnavailableError",
+    "InternalServerError",
+]

vortexdb/_grpc_common.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+import grpc
+
+from vortexdb.exceptions import (
+    AuthenticationError,
+    InternalServerError,
+    InvalidArgumentError,
+    NotFoundError,
+    ServiceUnavailableError,
+    TimeoutError,
+    VortexDBError,
+)
+
+
+def build_auth_metadata(api_key: str) -> tuple[tuple[str, str], ...]:
+    return (("authorization", f"Bearer {api_key}"),)
+
+
+def map_grpc_error(error: Any) -> VortexDBError:
+    code = error.code()
+
+    if code == grpc.StatusCode.UNAUTHENTICATED:
+        return AuthenticationError(error.details())
+
+    if code == grpc.StatusCode.NOT_FOUND:
+        return NotFoundError(error.details())
+
+    if code == grpc.StatusCode.INVALID_ARGUMENT:
+        return InvalidArgumentError(error.details())
+
+    if code == grpc.StatusCode.DEADLINE_EXCEEDED:
+        return TimeoutError(error.details())
+
+    if code == grpc.StatusCode.UNAVAILABLE:
+        return ServiceUnavailableError(error.details())
+
+    return InternalServerError(error.details())

vortexdb/async_client.py

@@ -0,0 +1,120 @@
+from typing import List
+
+from vortexdb import protoutils as proto
+from vortexdb.async_connection import AsyncGRPCConnection
+from vortexdb.config import VortexDBConfig
+from vortexdb.models import DenseVector, Payload, Point, Similarity
+
+
+class AsyncVortexDB:
+    """High-level async Python client for VortexDB."""
+
+    def __init__(
+        self,
+        *,
+        grpc_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ):
+        # Config order followed - args -> env vars -> defaults
+        self._config = VortexDBConfig.from_env(
+            grpc_url=grpc_url,
+            api_key=api_key,
+            timeout=timeout,
+        )
+
+        self._conn = AsyncGRPCConnection(self._config)
+
+    async def insert(self, *, vector: DenseVector, payload: Payload) -> str:
+        """
+        Insert a vector with payload.
+        Returns: point_id (str)
+        """
+        if not isinstance(vector, DenseVector):
+            raise TypeError(
+                "vector must be a DenseVector. "
+                "Use: DenseVector([1.0, 2.0, 3.0])"
+            )
+
+        request = proto.build_insert_request(
+            vector=vector,
+            payload=payload,
+        )
+
+        response = await self._conn.call(
+            self._conn.stub.InsertVector,
+            request,
+        )
+
+        return response.id.value
+
+    async def get(self, *, point_id: str) -> Point | None:
+        """
+        Retrieve a point by ID.
+        """
+        request = proto.build_point_id_request(point_id)
+
+        response = await self._conn.call(
+            self._conn.stub.GetPoint,
+            request,
+        )
+
+        if response is None:
+            return None
+
+        return Point.from_proto(response)
+
+    async def delete(self, *, point_id: str) -> None:
+        """
+        Delete a point by ID.
+        """
+        request = proto.build_point_id_request(point_id)
+
+        await self._conn.call(
+            self._conn.stub.DeletePoint,
+            request,
+        )
+
+    async def search(
+        self,
+        *,
+        vector: DenseVector,
+        similarity: Similarity,
+        limit: int,
+        ef: int | None = None,
+    ) -> List[str]:
+        """
+        Search for nearest neighbors.
+        Returns: List of point IDs
+        """
+        if not isinstance(vector, DenseVector):
+            raise TypeError(
+                "vector must be a DenseVector. "
+                "Use: DenseVector([1.0, 2.0, 3.0])"
+            )
+
+        request = proto.build_search_request(
+            vector=vector,
+            similarity=similarity,
+            limit=limit,
+            ef=ef,
+        )
+
+        response = await self._conn.call(
+            self._conn.stub.SearchPoints,
+            request,
+        )
+
+        return [pid.id.value for pid in response.result_point_ids]
+
+    async def close(self) -> None:
+        """
+        Close the async gRPC connection.
+        """
+        await self._conn.close()
+
+    async def __aenter__(self) -> "AsyncVortexDB":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()

vortexdb/async_connection.py

@@ -0,0 +1,41 @@
+from typing import Any, Callable
+
+import grpc
+
+from vortexdb._grpc_common import build_auth_metadata, map_grpc_error
+from vortexdb.config import VortexDBConfig
+from vortexdb.grpc.vector_db_pb2_grpc import VectorDBStub
+
+
+class AsyncGRPCConnection:
+    """Async gRPC connection wrapper for VortexDB."""
+
+    def __init__(self, config: VortexDBConfig):
+        self._config = config
+        self._channel = grpc.aio.insecure_channel(config.grpc_url)
+        self._stub = VectorDBStub(self._channel)
+        self._metadata = build_auth_metadata(config.api_key)
+
+    @property
+    def stub(self) -> VectorDBStub:
+        return self._stub
+
+    async def call(
+        self,
+        rpc: Callable[..., Any],
+        request: Any,
+    ) -> Any:
+        """Execute an async gRPC call with standard error handling."""
+        try:
+            return await rpc(
+                request,
+                timeout=self._config.timeout,
+                metadata=self._metadata,
+            )
+
+        except grpc.aio.AioRpcError as e:
+            raise map_grpc_error(e) from e
+
+    async def close(self) -> None:
+        """Close the underlying async gRPC channel."""
+        await self._channel.close()

vortexdb/client.py

@@ -0,0 +1,182 @@
+from typing import List, Sequence
+
+from vortexdb.connection import GRPCConnection
+from vortexdb.config import VortexDBConfig
+from vortexdb.models import (
+    DenseVector,
+    Payload,
+    Point,
+    Similarity,
+)
+
+from vortexdb import protoutils as proto
+
+
+class VortexDB:
+    """ High-level Python client for VortexDB """
+
+    def __init__(
+        self,
+        *,
+        grpc_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ):
+    # Config order followed - args -> env vars -> defaults
+        self._config = VortexDBConfig.from_env(
+            grpc_url=grpc_url,
+            api_key=api_key,
+            timeout=timeout,
+        )
+
+        self._conn = GRPCConnection(self._config)
+
+# The basic operations
+
+    def insert(self, *, vector: DenseVector, payload: Payload) -> str:
+        """
+        Insert a vector with payload.
+        Returns: point_id (str)
+        """
+        self._validate_dense_vector(vector)
+
+        request = proto.build_insert_request(
+            vector=vector,
+            payload=payload,
+        )
+
+        response = self._conn.call(
+            self._conn.stub.InsertVector,
+            request,
+        )
+
+        return response.id.value
+
+    def insert_batch(
+        self,
+        *,
+        points: Sequence[tuple[DenseVector, Payload]],
+    ) -> List[str]:
+        """
+        Insert multiple vectors with payloads.
+        Returns: List of point IDs
+        """
+        for vector, _ in points:
+            self._validate_dense_vector(vector)
+
+        request = proto.build_batch_insert_request(
+            points=list(points),
+        )
+
+        response = self._conn.call(
+            self._conn.stub.InsertVectorsBatch,
+            request,
+        )
+
+        return [pid.id.value for pid in response.ids]
+
+    def get(self, *, point_id: str) -> Point | None:
+        """
+        Retrieve a point by ID.
+        """
+        request = proto.build_point_id_request(point_id)
+
+        response = self._conn.call(
+            self._conn.stub.GetPoint,
+            request,
+        )
+
+        if response is None:
+            return None
+
+        return Point.from_proto(response)
+
+
+    def delete(self, *, point_id: str) -> None:
+        """
+        Delete a point by ID.
+        """
+        request = proto.build_point_id_request(point_id)
+
+        self._conn.call(
+            self._conn.stub.DeletePoint,
+            request,
+        )
+
+    def search(
+        self,
+        *,
+        vector: DenseVector,
+        similarity: Similarity,
+        limit: int,
+        ef: int | None = None,
+    ) -> List[str]:
+        """
+        Search for nearest neighbors.
+        Returns: List of point IDs
+        """
+        self._validate_dense_vector(vector)
+
+        request = proto.build_search_request(
+            vector=vector,
+            similarity=similarity,
+            limit=limit,
+            ef=ef,
+        )
+
+        response = self._conn.call(
+            self._conn.stub.SearchPoints,
+            request,
+        )
+
+        return [pid.id.value for pid in response.result_point_ids]
+
+    def search_batch(
+        self,
+        *,
+        queries: Sequence[tuple[DenseVector, Similarity, int]],
+        ef: int | None = None,
+    ) -> List[List[str]]:
+        """
+        Search nearest neighbors for multiple query vectors.
+        Returns: List of result point ID lists
+        """
+        for vector, _, _ in queries:
+            self._validate_dense_vector(vector)
+
+        request = proto.build_batch_search_request(
+            queries=list(queries),
+            ef=ef,
+        )
+
+        response = self._conn.call(
+            self._conn.stub.SearchPointsBatch,
+            request,
+        )
+
+        return [
+            [pid.id.value for pid in result.result_point_ids]
+            for result in response.results
+        ]
+
+    @staticmethod
+    def _validate_dense_vector(vector: DenseVector) -> None:
+        if not isinstance(vector, DenseVector):
+            raise TypeError(
+                "vector must be a DenseVector. "
+                "Use: DenseVector([1.0, 2.0, 3.0])"
+            )
+
+    def close(self) -> None:
+        """
+        Close the gRPC connection.
+        """
+        self._conn.close()
+
+    # Context Manager
+    # Will allow the usage of VortexDB with the 'with' keyword (Example given in examples/context_manager_usage.py)
+    def __enter__(self) -> "VortexDB":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()

vortexdb/config.py

@@ -0,0 +1,48 @@
+import os
+from dataclasses import dataclass
+from vortexdb.exceptions import ConfigurationError
+
+DEFAULT_GRPC_HOST = "localhost"
+DEFAULT_GRPC_PORT = 50051
+DEFAULT_TIMEOUT = 5.0
+@dataclass(frozen=True)
+class VortexDBConfig:
+    """Configuration for the VortexDB Python client"""
+
+    grpc_url: str | None = None
+    api_key: str | None = None
+    timeout: float = DEFAULT_TIMEOUT
+
+    @staticmethod
+    def from_env(
+        *,
+        grpc_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ) -> "VortexDBConfig":
+        """ Load configuration from explicit arguments with environment variable fallback """
+
+        resolved_grpc_url = (
+            grpc_url
+            or os.getenv("VORTEXDB_GRPC_URL")
+            or f"{DEFAULT_GRPC_HOST}:{DEFAULT_GRPC_PORT}"
+        )
+
+        resolved_api_key = api_key or os.getenv("VORTEXDB_API_KEY")
+        if not resolved_api_key:
+            raise ConfigurationError(
+                "VortexDB API key is required. "
+                "Provide api_key argument or set VORTEXDB_API_KEY."
+            )
+
+        resolved_timeout = (
+            timeout
+            if timeout is not None
+            else float(os.getenv("VORTEXDB_TIMEOUT", DEFAULT_TIMEOUT))
+        )
+
+        return VortexDBConfig(
+            grpc_url=resolved_grpc_url,
+            api_key=resolved_api_key,
+            timeout=resolved_timeout,
+        )

vortexdb/connection.py

@@ -0,0 +1,42 @@
+import grpc
+from typing import Any, Callable
+
+from vortexdb._grpc_common import build_auth_metadata, map_grpc_error
+from vortexdb.config import VortexDBConfig
+
+from vortexdb.grpc.vector_db_pb2_grpc import VectorDBStub
+
+
+class GRPCConnection:
+    """ gRPC connection wrapper for VortexDB"""
+
+    def __init__(self, config: VortexDBConfig):
+        self._config = config
+        self._channel = grpc.insecure_channel(config.grpc_url)
+        self._stub = VectorDBStub(self._channel)
+        # Because this is required in every request
+        self._metadata = build_auth_metadata(config.api_key)
+
+    @property
+    def stub(self) -> VectorDBStub:
+        return self._stub
+
+    def call(
+        self,
+        rpc: Callable[..., Any],
+        request: Any,
+    ) -> Any:
+        """ Execute a gRPC call with standard error handling """
+        try:
+            return rpc(
+                request,
+                timeout=self._config.timeout,
+                metadata=self._metadata,
+            )
+
+        except grpc.RpcError as e:
+            raise map_grpc_error(e) from e
+
+    def close(self) -> None:
+        """ Close the underlying gRPC channel """
+        self._channel.close()

vortexdb/exceptions.py

@@ -0,0 +1,30 @@
+class VortexDBError(Exception):
+    """Base exception for all VortexDB client errors."""
+
+
+class AuthenticationError(VortexDBError):
+    """Authentication failed (invalid or missing API key)"""
+
+
+class NotFoundError(VortexDBError):
+    """Could not find requested resource"""
+
+
+class InvalidArgumentError(VortexDBError):
+    """Invalid input was provided"""
+
+
+class TimeoutError(VortexDBError):
+    """Request timed out while communicating with the server"""
+
+
+class ServiceUnavailableError(VortexDBError):
+    """The server is unavailable or unreachable"""
+
+
+class InternalServerError(VortexDBError):
+    """Internal error in the server"""
+
+class ConfigurationError(VortexDBError):
+    """Invalid or missing client configuration."""
+

vortexdb/grpc/__init__.py

@@ -0,0 +1 @@
+# vortexdb/grpc/__init__.py

vortexdb/grpc/vector_db_pb2.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: vector-db.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'vector-db.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0fvector-db.proto\x12\x08vectordb\x1a\x1bgoogle/protobuf/empty.proto\"\x15\n\x04UUID\x12\r\n\x05value\x18\x01 \x01(\t\"`\n\x13InsertVectorRequest\x12%\n\x06vector\x18\x01 \x01(\x0b\x32\x15.vectordb.DenseVector\x12\"\n\x07payload\x18\x02 \x01(\x0b\x32\x11.vectordb.Payload\"\x81\x01\n\rSearchRequest\x12+\n\x0cquery_vector\x18\x01 \x01(\x0b\x32\x15.vectordb.DenseVector\x12(\n\nsimilarity\x18\x02 \x01(\x0e\x32\x14.vectordb.Similarity\x12\r\n\x05limit\x18\x03 \x01(\x04\x12\n\n\x02\x65\x66\x18\x04 \x01(\x04\"=\n\x0eSearchResponse\x12+\n\x10result_point_ids\x18\x01 \x03(\x0b\x32\x11.vectordb.PointID\"\x1d\n\x0b\x44\x65nseVector\x12\x0e\n\x06values\x18\x01 \x03(\x02\"q\n\x05Point\x12\x1d\n\x02id\x18\x01 \x01(\x0b\x32\x11.vectordb.PointID\x12\"\n\x07payload\x18\x02 \x01(\x0b\x32\x11.vectordb.Payload\x12%\n\x06vector\x18\x03 \x01(\x0b\x32\x15.vectordb.DenseVector\"%\n\x07PointID\x12\x1a\n\x02id\x18\x01 \x01(\x0b\x32\x0e.vectordb.UUID\"G\n\x07Payload\x12+\n\x0c\x63ontent_type\x18\x01 \x01(\x0e\x32\x15.vectordb.ContentType\x12\x0f\n\x07\x63ontent\x18\x02 \x01(\t\"K\n\x19InsertVectorsBatchRequest\x12.\n\x07vectors\x18\x01 \x03(\x0b\x32\x1d.vectordb.InsertVectorRequest\"<\n\x1aInsertVectorsBatchResponse\x12\x1e\n\x03ids\x18\x01 \x03(\x0b\x32\x11.vectordb.PointID\"D\n\x18SearchPointsBatchRequest\x12(\n\x07queries\x18\x01 \x03(\x0b\x32\x17.vectordb.SearchRequest\"F\n\x19SearchPointsBatchResponse\x12)\n\x07results\x18\x01 \x03(\x0b\x32\x18.vectordb.SearchResponse*C\n\nSimilarity\x12\r\n\tEuclidean\x10\x00\x12\r\n\tManhattan\x10\x01\x12\x0b\n\x07Hamming\x10\x02\x12\n\n\x06\x43osine\x10\x03*\"\n\x0b\x43ontentType\x12\t\n\x05Image\x10\x00\x12\x08\n\x04Text\x10\x01\x32\xc4\x03\n\x08VectorDB\x12\x42\n\x0cInsertVector\x12\x1d.vectordb.InsertVectorRequest\x1a\x11.vectordb.PointID\"\x00\x12:\n\x0b\x44\x65letePoint\x12\x11.vectordb.PointID\x1a\x16.google.protobuf.Empty\"\x00\x12\x30\n\x08GetPoint\x12\x11.vectordb.PointID\x1a\x0f.vectordb.Point\"\x00\x12\x43\n\x0cSearchPoints\x12\x17.vectordb.SearchRequest\x1a\x18.vectordb.SearchResponse\"\x00\x12\x61\n\x12InsertVectorsBatch\x12#.vectordb.InsertVectorsBatchRequest\x1a$.vectordb.InsertVectorsBatchResponse\"\x00\x12^\n\x11SearchPointsBatch\x12\".vectordb.SearchPointsBatchRequest\x1a#.vectordb.SearchPointsBatchResponse\"\x00\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'vector_db_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_SIMILARITY']._serialized_start=913
+  _globals['_SIMILARITY']._serialized_end=980
+  _globals['_CONTENTTYPE']._serialized_start=982
+  _globals['_CONTENTTYPE']._serialized_end=1016
+  _globals['_UUID']._serialized_start=58
+  _globals['_UUID']._serialized_end=79
+  _globals['_INSERTVECTORREQUEST']._serialized_start=81
+  _globals['_INSERTVECTORREQUEST']._serialized_end=177
+  _globals['_SEARCHREQUEST']._serialized_start=180
+  _globals['_SEARCHREQUEST']._serialized_end=309
+  _globals['_SEARCHRESPONSE']._serialized_start=311
+  _globals['_SEARCHRESPONSE']._serialized_end=372
+  _globals['_DENSEVECTOR']._serialized_start=374
+  _globals['_DENSEVECTOR']._serialized_end=403
+  _globals['_POINT']._serialized_start=405
+  _globals['_POINT']._serialized_end=518
+  _globals['_POINTID']._serialized_start=520
+  _globals['_POINTID']._serialized_end=557
+  _globals['_PAYLOAD']._serialized_start=559
+  _globals['_PAYLOAD']._serialized_end=630
+  _globals['_INSERTVECTORSBATCHREQUEST']._serialized_start=632
+  _globals['_INSERTVECTORSBATCHREQUEST']._serialized_end=707
+  _globals['_INSERTVECTORSBATCHRESPONSE']._serialized_start=709
+  _globals['_INSERTVECTORSBATCHRESPONSE']._serialized_end=769
+  _globals['_SEARCHPOINTSBATCHREQUEST']._serialized_start=771
+  _globals['_SEARCHPOINTSBATCHREQUEST']._serialized_end=839
+  _globals['_SEARCHPOINTSBATCHRESPONSE']._serialized_start=841
+  _globals['_SEARCHPOINTSBATCHRESPONSE']._serialized_end=911
+  _globals['_VECTORDB']._serialized_start=1019
+  _globals['_VECTORDB']._serialized_end=1471
+# @@protoc_insertion_point(module_scope)