Update Python client to support batch insert and search

Author: peopleig

client/python/USAGE.md

@@ -56,6 +56,11 @@ async with AsyncVortexDB(
         payload=Payload.text("hello async vortex"),
     )
 ```
+### Batch Insertion and Search Support  
+
+The client now supports batch insertion and batch search queries.  
+Methods of usage and examples available in:  
+```examples/batch_insert_usage.py``` & ```examples/search_query_usage.py```  
 
 ---
 
@@ -115,6 +120,22 @@ Raises
 
 ---
 
+#### **Batch Insert**
+
+Insert multiple vectors with payloads in a single request  
+```
+batch_insert(*, items: list[tuple[DenseVector, Payload]]) -> list[str]
+```
+
+Returns
+- List of `point_id` (UUID string)
+
+Raises
+- `TypeError` if input structure is invalid
+- gRPC-mapped errors (see Error Handling)
+
+---
+
 #### **Get**
 
 Fetch a point by its ID
@@ -149,6 +170,32 @@ Raises
 
 ---
 
+#### **Batch Search**
+
+Search for nearest neighbours for multiple queries in a single request
+```
+batch_search(
+    *,
+    queries,
+    similarity: Similarity | None = None,
+    limit: int | None = None,
+) -> list[list[str]]
+```
+
+Returns 
+- `TypeError` for invalid query formats
+- `ValueError` if required parameters are missing
+
+Supported Input Formats:  
+The `queries` parameter is flexible and supports multiple formats:
+- List of `SearchQuery` objects
+- List of `(DenseVector, Similarity, Limit)` tuples
+- List of `(DenseVector, Similarity)` tuples with a global `Limit`
+- List of `(DenseVector, Limit)` tuples with a global `Similarity`
+- List of `DenseVector` with global `Similarity` and `Limit`
+
+---
+
 #### **Delete**
 
 Delete a point by its ID
@@ -214,6 +261,19 @@ All fields are directly accessible:
 
 ---
 
+### `SearchQuery`
+
+```
+SearchQuery(
+    vector: DenseVector,
+    similarity: Similarity,
+    limit: int,
+)
+```
+Structured representation of a search request  
+
+---
+
 ### `Similarity`
 
 Enum representing distance functions: 

client/python/examples/async_usage.py

@@ -6,7 +6,7 @@
 async def main():
     async with AsyncVortexDB(
         grpc_url="localhost:50051",
-        api_key="your-api-key",
+        api_key="my-secret-password",
     ) as db:
         point_id = await db.insert(
             vector=DenseVector([0.1, 0.2, 0.3]),

client/python/examples/batch_insert_usage.py

@@ -0,0 +1,39 @@
+from vortexdb import VortexDB
+from vortexdb import DenseVector, Payload, to_dense_vectors
+
+
+def main():
+    db = VortexDB(
+        grpc_url="localhost:50051",
+        api_key="my-secret-password",
+    )
+
+    raw_vectors = [
+        [0.1, 0.2, 0.3],
+        [0.4, 0.5, 0.6],
+        [0.7, 0.8, 0.9],
+    ]
+    vectors = to_dense_vectors(raw_vectors)
+
+    p1 = Payload.text("hello world")
+    p2 = Payload.image("/img/a.png")
+    p3 = Payload.text("foo bar")
+
+    items = [
+        (vectors[0], p1),
+        (vectors[1], p2),
+        (vectors[2], p3),
+    ]
+
+    # Batch Insert
+    point_ids = db.batch_insert(items=items)
+    print("Inserted ids:\n", point_ids)
+
+    for pid in point_ids:
+        db.delete(point_id=pid)
+
+    db.close()
+
+
+if __name__ == "__main__":
+    main()

client/python/examples/search_query_usage.py

@@ -0,0 +1,69 @@
+from vortexdb import VortexDB
+from vortexdb import DenseVector, Similarity, SearchQuery, to_dense_vectors
+
+
+def main():
+    db = VortexDB(
+        grpc_url="localhost:50051",
+        api_key="my-secret-password",
+    )
+
+    raw_vectors = [
+        [0.1, 0.2, 0.3],
+        [0.4, 0.5, 0.6],
+        [0.7, 0.8, 0.9],
+    ]
+    vectors = to_dense_vectors(raw_vectors)
+
+    q = SearchQuery(
+        vector=vectors[0],
+        similarity=Similarity.COSINE,
+        limit=3,
+    )
+    res = db.search(query=q)
+    print("Single SearchQuery:\n", res)
+
+    # List of SearchQuery
+    queries = [
+        SearchQuery(vectors[0], Similarity.HAMMING, 3),
+        SearchQuery(vectors[1], Similarity.EUCLIDEAN, 2),
+        q,
+    ]
+    res = db.batch_search(queries=queries)
+    print("\nBatch SearchQuery:\n", res)
+
+    # List of vectors with global Similarity and Limit
+    res = db.batch_search(
+        queries=vectors,
+        similarity=Similarity.COSINE,
+        limit=3,
+    )
+    print("\nList of DenseVectors:\n", res)
+
+    # List of tuple (DenseVector, Similarity) with global Limit
+    queries = [
+        (vectors[0], Similarity.COSINE),
+        (vectors[1], Similarity.MANHATTAN),
+    ]
+    res = db.batch_search(
+        queries=queries,
+        limit=3,
+    )
+    print("\nList of (DenseVector, Similarity):\n", res)
+
+    # List of tuple (DenseVector, Limit) with global Similarity
+    queries = [
+        (vectors[0], 2),
+        (vectors[1], 4),
+    ]
+    res = db.batch_search(
+        queries=queries,
+        similarity=Similarity.COSINE,
+    )
+    print("\nList of (DenseVector, Limit):\n", res)
+
+    db.close()
+
+
+if __name__ == "__main__":
+    main()

client/python/pyproject.toml

@@ -24,13 +24,13 @@ classifiers = [
 ]
 
 dependencies = [
-    "grpcio>=1.60",
-    "protobuf>=4.25",
+    "grpcio>=1.81.1",
+    "protobuf>=6.33.5,<7.0.0",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "grpcio-tools>=1.60",
+    "grpcio-tools>=1.81.1,<2.0.0",
     "pytest>=7.0",
 ]