pinecone 5.4.0.dev4__tar.gz → 5.4.0.dev5__tar.gz

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pinecone
-Version: 5.4.0.dev4
+Version: 5.4.0.dev5
 Summary: Pinecone client and SDK
 Home-page: https://www.pinecone.io
 License: Apache-2.0
@@ -35,7 +35,7 @@ Requires-Dist: grpcio (>=1.59.0) ; (python_version >= "3.11" and python_version
 Requires-Dist: lz4 (>=3.1.3) ; extra == "grpc"
 Requires-Dist: pinecone-plugin-inference (>=2.0.0,<3.0.0)
 Requires-Dist: pinecone-plugin-interface (>=0.0.7,<0.0.8)
-Requires-Dist: protobuf (>=5.28,<6.0) ; extra == "grpc"
+Requires-Dist: protobuf (>=4.25,<5.0) ; extra == "grpc"
 Requires-Dist: protoc-gen-openapiv2 (>=0.0.1,<0.0.2) ; extra == "grpc"
 Requires-Dist: python-dateutil (>=2.5.3)
 Requires-Dist: tqdm (>=4.64.1)

pinecone-5.4.0.dev5/pinecone/__version__

@@ -0,0 +1 @@
+5.4.0.dev5

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/control/pinecone.py

@@ -765,6 +765,14 @@ class Pinecone:
         # Now you're ready to perform data operations
         index.query(vector=[...], top_k=10)
         ```
+
+        Arguments:
+            name: The name of the index to target. If you specify the name of the index, the client will
+                fetch the host url from the Pinecone control plane.
+            host: The host url of the index to target. If you specify the host url, the client will use
+                the host url directly without making any additional calls to the control plane.
+            pool_threads: The number of threads to use when making parallel requests by calling index methods with optional kwarg async_req=True, or using methods that make use of parallelism automatically such as query_namespaces(). Default: 1
+            connection_pool_maxsize: The maximum number of connections to keep in the connection pool. Default: 5 * multiprocessing.cpu_count()
         """
         if name == "" and host == "":
             raise ValueError("Either name or host must be specified")

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/core/openapi/shared/api_client.py

@@ -2,12 +2,31 @@ import json
 import atexit
 import mimetypes
 from multiprocessing.pool import ThreadPool
+from concurrent.futures import ThreadPoolExecutor
 import io
 import os
 import re
 import typing
 from urllib.parse import quote
 from urllib3.fields import RequestField
+import time
+import random
+
+def retry_api_call(
+    func, args=(), kwargs={}, retries=3, backoff=1, jitter=0.5
+):
+    attempts = 0
+    while attempts < retries:
+        try:
+            return func(*args, **kwargs)  # Attempt to call __call_api
+        except Exception as e:
+            attempts += 1
+            if attempts >= retries:
+                print(f"API call failed after {attempts} attempts: {e}")
+                raise  # Re-raise exception if retries are exhausted
+            sleep_time = backoff * (2 ** (attempts - 1)) + random.uniform(0, jitter)
+            # print(f"Retrying ({attempts}/{retries}) in {sleep_time:.2f} seconds after error: {e}")
+            time.sleep(sleep_time)
 
 
 from pinecone.core.openapi.shared import rest
@@ -52,6 +71,7 @@ class ApiClient(object):
     """
 
     _pool = None
+    _threadpool_executor = None
 
     def __init__(self, configuration=None, header_name=None, header_value=None, cookie=None, pool_threads=1):
         if configuration is None:
@@ -74,6 +94,9 @@ class ApiClient(object):
         self.close()
 
     def close(self):
+        if self._threadpool_executor:
+            self._threadpool_executor.shutdown()
+            self._threadpool_executor = None
         if self._pool:
             self._pool.close()
             self._pool.join()
@@ -91,6 +114,12 @@ class ApiClient(object):
             self._pool = ThreadPool(self.pool_threads)
         return self._pool
 
+    @property
+    def threadpool_executor(self):
+        if self._threadpool_executor is None:
+            self._threadpool_executor = ThreadPoolExecutor(max_workers=self.pool_threads)
+        return self._threadpool_executor
+
     @property
     def user_agent(self):
         """User agent for this API client"""
@@ -316,6 +345,7 @@ class ApiClient(object):
         response_type: typing.Optional[typing.Tuple[typing.Any]] = None,
         auth_settings: typing.Optional[typing.List[str]] = None,
         async_req: typing.Optional[bool] = None,
+        async_threadpool_executor: typing.Optional[bool] = None,
         _return_http_data_only: typing.Optional[bool] = None,
         collection_formats: typing.Optional[typing.Dict[str, str]] = None,
         _preload_content: bool = True,
@@ -376,8 +406,9 @@ class ApiClient(object):
             If parameter async_req is False or missing,
             then the method will return the response directly.
         """
-        if not async_req:
-            return self.__call_api(
+        if async_threadpool_executor:
+            return self.threadpool_executor.submit(
+                self.__call_api,
                 resource_path,
                 method,
                 path_params,
@@ -396,9 +427,8 @@ class ApiClient(object):
                 _check_type,
             )
 
-        return self.pool.apply_async(
-            self.__call_api,
-            (
+        if not async_req:
+            return self.__call_api(
                 resource_path,
                 method,
                 path_params,
@@ -415,7 +445,35 @@ class ApiClient(object):
                 _request_timeout,
                 _host,
                 _check_type,
-            ),
+            )
+
+        return self.pool.apply_async(
+            retry_api_call,
+            args=(
+                self.__call_api,  # Pass the API call function as the first argument
+                (
+                    resource_path,
+                    method,
+                    path_params,
+                    query_params,
+                    header_params,
+                    body,
+                    post_params,
+                    files,
+                    response_type,
+                    auth_settings,
+                    _return_http_data_only,
+                    collection_formats,
+                    _preload_content,
+                    _request_timeout,
+                    _host,
+                    _check_type,
+                ),
+                {},  # empty kwargs dictionary
+                3,    # retries
+                1,    # backoff time
+                0.5   # jitter
+            )
         )
 
     def request(
@@ -665,6 +723,7 @@ class Endpoint(object):
         self.params_map["all"].extend(
             [
                 "async_req",
+                "async_threadpool_executor",
                 "_host_index",
                 "_preload_content",
                 "_request_timeout",
@@ -679,6 +738,7 @@ class Endpoint(object):
         self.openapi_types = root_map["openapi_types"]
         extra_types = {
             "async_req": (bool,),
+            "async_threadpool_executor": (bool, ),
             "_host_index": (none_type, int),
             "_preload_content": (bool,),
             "_request_timeout": (none_type, float, (float,), [float], int, (int,), [int]),
@@ -828,6 +888,7 @@ class Endpoint(object):
             response_type=self.settings["response_type"],
             auth_settings=self.settings["auth"],
             async_req=kwargs["async_req"],
+            async_threadpool_executor=kwargs.get("async_threadpool_executor", None),
             _check_type=kwargs["_check_return_type"],
             _return_http_data_only=kwargs["_return_http_data_only"],
             _preload_content=kwargs["_preload_content"],

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/core/openapi/shared/configuration.py

@@ -469,3 +469,23 @@ class Configuration(object):
         """Fix base path."""
         self._base_path = value
         self.server_index = None
+
+    def __repr__(self):
+        attrs = [
+            f"host={self.host}",
+            f"api_key=***",
+            f"api_key_prefix={self.api_key_prefix}",
+            f"access_token={self.access_token}",
+            f"connection_pool_maxsize={self.connection_pool_maxsize}",
+            f"username={self.username}",
+            f"password={self.password}",
+            f"discard_unknown_keys={self.discard_unknown_keys}",
+            f"disabled_client_side_validations={self.disabled_client_side_validations}",
+            f"server_index={self.server_index}",
+            f"server_variables={self.server_variables}",
+            f"server_operation_index={self.server_operation_index}",
+            f"server_operation_variables={self.server_operation_variables}",
+            f"ssl_ca_cert={self.ssl_ca_cert}",
+
+        ]
+        return f"Configuration({', '.join(attrs)})"

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/data/index.py

@@ -1,6 +1,7 @@
 from tqdm.autonotebook import tqdm
 
 import logging
+import json
 from typing import Union, List, Optional, Dict, Any
 
 from pinecone.config import ConfigBuilder
@@ -33,6 +34,10 @@ from ..utils import (
 )
 from .features.bulk_import import ImportFeatureMixin
 from .vector_factory import VectorFactory
+from .query_results_aggregator import QueryResultsAggregator, QueryNamespacesResults
+
+from multiprocessing.pool import ApplyResult
+from concurrent.futures import as_completed
 
 from pinecone_plugin_interface import load_and_install as install_plugins
 
@@ -65,6 +70,7 @@ _OPENAPI_ENDPOINT_PARAMS = (
     "_check_return_type",
     "_host_index",
     "async_req",
+    "async_threadpool_executor",
 )
 
 
@@ -103,6 +109,9 @@ class Index(ImportFeatureMixin):
         self._openapi_config = ConfigBuilder.build_openapi_config(self.config, openapi_config)
         self._pool_threads = pool_threads
 
+        if kwargs.get("connection_pool_maxsize", None):
+            self._openapi_config.connection_pool_maxsize = kwargs.get("connection_pool_maxsize")
+
         self._vector_api = setup_openapi_client(
             api_client_klass=ApiClient,
             api_klass=DataPlaneApi,
@@ -387,7 +396,7 @@ class Index(ImportFeatureMixin):
             Union[SparseValues, Dict[str, Union[List[float], List[int]]]]
         ] = None,
         **kwargs,
-    ) -> QueryResponse:
+    ) -> Union[QueryResponse, ApplyResult]:
         """
         The Query operation searches a namespace, using a query vector.
         It retrieves the ids of the most similar items in a namespace, along with their similarity scores.
@@ -429,6 +438,39 @@ class Index(ImportFeatureMixin):
                  and namespace name.
         """
 
+        response = self._query(
+            *args,
+            top_k=top_k,
+            vector=vector,
+            id=id,
+            namespace=namespace,
+            filter=filter,
+            include_values=include_values,
+            include_metadata=include_metadata,
+            sparse_vector=sparse_vector,
+            **kwargs,
+        )
+
+        if kwargs.get("async_req", False) or kwargs.get("async_threadpool_executor", False):
+            return response
+        else:
+            return parse_query_response(response)
+
+    def _query(
+        self,
+        *args,
+        top_k: int,
+        vector: Optional[List[float]] = None,
+        id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        filter: Optional[Dict[str, Union[str, float, int, bool, List, dict]]] = None,
+        include_values: Optional[bool] = None,
+        include_metadata: Optional[bool] = None,
+        sparse_vector: Optional[
+            Union[SparseValues, Dict[str, Union[List[float], List[int]]]]
+        ] = None,
+        **kwargs,
+    ) -> QueryResponse:
         if len(args) > 0:
             raise ValueError(
                 "The argument order for `query()` has changed; please use keyword arguments instead of positional arguments. Example: index.query(vector=[0.1, 0.2, 0.3], top_k=10, namespace='my_namespace')"
@@ -453,6 +495,7 @@ class Index(ImportFeatureMixin):
                 ("sparse_vector", sparse_vector),
             ]
         )
+
         response = self._vector_api.query(
             QueryRequest(
                 **args_dict,
@@ -461,7 +504,96 @@ class Index(ImportFeatureMixin):
             ),
             **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
         )
-        return parse_query_response(response)
+        return response
+
+    @validate_and_convert_errors
+    def query_namespaces(
+        self,
+        vector: List[float],
+        namespaces: List[str],
+        top_k: Optional[int] = None,
+        filter: Optional[Dict[str, Union[str, float, int, bool, List, dict]]] = None,
+        include_values: Optional[bool] = None,
+        include_metadata: Optional[bool] = None,
+        sparse_vector: Optional[
+            Union[SparseValues, Dict[str, Union[List[float], List[int]]]]
+        ] = None,
+        **kwargs,
+    ) -> QueryNamespacesResults:
+        """The query_namespaces() method is used to make a query to multiple namespaces in parallel and combine the results into one result set.
+
+        Since several asynchronous calls are made on your behalf when calling this method, you will need to tune the pool_threads and connection_pool_maxsize parameter of the Index constructor to suite your workload.
+
+        Examples:
+
+        ```python
+        from pinecone import Pinecone
+
+        pc = Pinecone(api_key="your-api-key")
+        index = pc.Index(
+            host="index-name",
+            pool_threads=32,
+            connection_pool_maxsize=32
+        )
+
+        query_vec = [0.1, 0.2, 0.3] # An embedding that matches the index dimension
+        combined_results = index.query_namespaces(
+            vector=query_vec,
+            namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
+            top_k=10,
+            filter={'genre': {"$eq": "drama"}},
+            include_values=True,
+            include_metadata=True
+        )
+        for vec in combined_results.matches:
+            print(vec.id, vec.score)
+        print(combined_results.usage)
+        ```
+
+        Args:
+            vector (List[float]): The query vector, must be the same length as the dimension of the index being queried.
+            namespaces (List[str]): The list of namespaces to query.
+            top_k (Optional[int], optional): The number of results you would like to request from each namespace. Defaults to 10.
+            filter (Optional[Dict[str, Union[str, float, int, bool, List, dict]]], optional): Pass an optional filter to filter results based on metadata. Defaults to None.
+            include_values (Optional[bool], optional): Boolean field indicating whether vector values should be included with results. Defaults to None.
+            include_metadata (Optional[bool], optional): Boolean field indicating whether vector metadata should be included with results. Defaults to None.
+            sparse_vector (Optional[ Union[SparseValues, Dict[str, Union[List[float], List[int]]]] ], optional): If you are working with a dotproduct index, you can pass a sparse vector as part of your hybrid search. Defaults to None.
+
+        Returns:
+            QueryNamespacesResults: A QueryNamespacesResults object containing the combined results from all namespaces, as well as the combined usage cost in read units.
+        """
+        if namespaces is None or len(namespaces) == 0:
+            raise ValueError("At least one namespace must be specified")
+        if len(vector) == 0:
+            raise ValueError("Query vector must not be empty")
+
+        overall_topk = top_k if top_k is not None else 10
+        aggregator = QueryResultsAggregator(top_k=overall_topk)
+
+        target_namespaces = set(namespaces)  # dedup namespaces
+        async_futures = [
+            self.query(
+                vector=vector,
+                namespace=ns,
+                top_k=overall_topk,
+                filter=filter,
+                include_values=include_values,
+                include_metadata=include_metadata,
+                sparse_vector=sparse_vector,
+                async_threadpool_executor=True,
+                _preload_content=False,
+                **kwargs,
+            )
+            for ns in target_namespaces
+        ]
+
+        for result in as_completed(async_futures):
+            raw_result = result.result()
+            response = json.loads(raw_result.data.decode("utf-8"))
+            aggregator.add_results(response)
+
+        final_results = aggregator.get_results()
+        return final_results
 
     @validate_and_convert_errors
     def update(

pinecone-5.4.0.dev5/pinecone/data/query_results_aggregator.py

@@ -0,0 +1,193 @@
+from typing import List, Tuple, Optional, Any, Dict
+import json
+import heapq
+from pinecone.core.openapi.data.models import Usage
+from pinecone.core.openapi.data.models import QueryResponse as OpenAPIQueryResponse
+
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class ScoredVectorWithNamespace:
+    namespace: str
+    score: float
+    id: str
+    values: List[float]
+    sparse_values: dict
+    metadata: dict
+
+    def __init__(self, aggregate_results_heap_tuple: Tuple[float, int, object, str]):
+        json_vector = aggregate_results_heap_tuple[2]
+        self.namespace = aggregate_results_heap_tuple[3]
+        self.id = json_vector.get("id")  # type: ignore
+        self.score = json_vector.get("score")  # type: ignore
+        self.values = json_vector.get("values")  # type: ignore
+        self.sparse_values = json_vector.get("sparse_values", None)  # type: ignore
+        self.metadata = json_vector.get("metadata", None)  # type: ignore
+
+    def __getitem__(self, key):
+        if hasattr(self, key):
+            return getattr(self, key)
+        else:
+            raise KeyError(f"'{key}' not found in ScoredVectorWithNamespace")
+
+    def get(self, key, default=None):
+        return getattr(self, key, default)
+
+    def __repr__(self):
+        return json.dumps(self._truncate(asdict(self)), indent=4)
+
+    def __json__(self):
+        return self._truncate(asdict(self))
+
+    def _truncate(self, obj, max_items=2):
+        """
+        Recursively traverse and truncate lists that exceed max_items length.
+        Only display the "... X more" message if at least 2 elements are hidden.
+        """
+        if obj is None:
+            return None  # Skip None values
+        elif isinstance(obj, list):
+            filtered_list = [self._truncate(i, max_items) for i in obj if i is not None]
+            if len(filtered_list) > max_items:
+                # Show the truncation message only if more than 1 item is hidden
+                remaining_items = len(filtered_list) - max_items
+                if remaining_items > 1:
+                    return filtered_list[:max_items] + [f"... {remaining_items} more"]
+                else:
+                    # If only 1 item remains, show it
+                    return filtered_list
+            return filtered_list
+        elif isinstance(obj, dict):
+            # Recursively process dictionaries, omitting None values
+            return {k: self._truncate(v, max_items) for k, v in obj.items() if v is not None}
+        return obj
+
+
+@dataclass
+class QueryNamespacesResults:
+    usage: Usage
+    matches: List[ScoredVectorWithNamespace]
+
+    def __getitem__(self, key):
+        if hasattr(self, key):
+            return getattr(self, key)
+        else:
+            raise KeyError(f"'{key}' not found in QueryNamespacesResults")
+
+    def get(self, key, default=None):
+        return getattr(self, key, default)
+
+    def __repr__(self):
+        return json.dumps(
+            {
+                "usage": self.usage.to_dict(),
+                "matches": [match.__json__() for match in self.matches],
+            },
+            indent=4,
+        )
+
+
+class QueryResultsAggregregatorNotEnoughResultsError(Exception):
+    def __init__(self):
+        super().__init__(
+            "Cannot interpret results without at least two matches. In order to aggregate results from multiple queries, top_k must be greater than 1 in order to correctly infer the similarity metric from scores."
+        )
+
+
+class QueryResultsAggregatorInvalidTopKError(Exception):
+    def __init__(self, top_k: int):
+        super().__init__(
+            f"Invalid top_k value {top_k}. To aggregate results from multiple queries the top_k must be at least 2."
+        )
+
+
+class QueryResultsAggregator:
+    def __init__(self, top_k: int):
+        if top_k < 2:
+            raise QueryResultsAggregatorInvalidTopKError(top_k)
+        self.top_k = top_k
+        self.usage_read_units = 0
+        self.heap: List[Tuple[float, int, object, str]] = []
+        self.insertion_counter = 0
+        self.is_dotproduct = None
+        self.read = False
+        self.final_results: Optional[QueryNamespacesResults] = None
+
+    def _is_dotproduct_index(self, matches):
+        # The interpretation of the score depends on the similar metric used.
+        # Unlike other index types, in indexes configured for dotproduct,
+        # a higher score is better. We have to infer this is the case by inspecting
+        # the order of the scores in the results.
+        for i in range(1, len(matches)):
+            if matches[i].get("score") > matches[i - 1].get("score"):  # Found an increase
+                return False
+        return True
+
+    def _dotproduct_heap_item(self, match, ns):
+        return (match.get("score"), -self.insertion_counter, match, ns)
+
+    def _non_dotproduct_heap_item(self, match, ns):
+        return (-match.get("score"), -self.insertion_counter, match, ns)
+
+    def _process_matches(self, matches, ns, heap_item_fn):
+        for match in matches:
+            self.insertion_counter += 1
+            if len(self.heap) < self.top_k:
+                heapq.heappush(self.heap, heap_item_fn(match, ns))
+            else:
+                # Assume we have dotproduct scores sorted in descending order
+                if self.is_dotproduct and match["score"] < self.heap[0][0]:
+                    # No further matches can improve the top-K heap
+                    break
+                elif not self.is_dotproduct and match["score"] > -self.heap[0][0]:
+                    # No further matches can improve the top-K heap
+                    break
+                heapq.heappushpop(self.heap, heap_item_fn(match, ns))
+
+    def add_results(self, results: Dict[str, Any]):
+        if self.read:
+            # This is mainly just to sanity check in test cases which get quite confusing
+            # if you read results twice due to the heap being emptied when constructing
+            # the ordered results.
+            raise ValueError("Results have already been read. Cannot add more results.")
+
+        matches = results.get("matches", [])
+        ns: str = results.get("namespace", "")
+        if isinstance(results, OpenAPIQueryResponse):
+            self.usage_read_units += results.usage.read_units
+        else:
+            self.usage_read_units += results.get("usage", {}).get("readUnits", 0)
+
+        if len(matches) == 0:
+            return
+
+        if self.is_dotproduct is None:
+            if len(matches) == 1:
+                # This condition should match the second time we add results containing
+                # only one match. We need at least two matches in a single response in order
+                # to infer the similarity metric
+                raise QueryResultsAggregregatorNotEnoughResultsError()
+            self.is_dotproduct = self._is_dotproduct_index(matches)
+
+        if self.is_dotproduct:
+            self._process_matches(matches, ns, self._dotproduct_heap_item)
+        else:
+            self._process_matches(matches, ns, self._non_dotproduct_heap_item)
+
+    def get_results(self) -> QueryNamespacesResults:
+        if self.read:
+            if self.final_results is not None:
+                return self.final_results
+            else:
+                # I don't think this branch can ever actually be reached, but the type checker disagrees
+                raise ValueError("Results have already been read. Cannot get results again.")
+        self.read = True
+
+        self.final_results = QueryNamespacesResults(
+            usage=Usage(read_units=self.usage_read_units),
+            matches=[
+                ScoredVectorWithNamespace(heapq.heappop(self.heap)) for _ in range(len(self.heap))
+            ][::-1],
+        )
+        return self.final_results

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/grpc/__init__.py

@@ -47,20 +47,24 @@ index.query(vector=[...], top_k=10)
 from .index_grpc import GRPCIndex
 from .pinecone import PineconeGRPC
 from .config import GRPCClientConfig
+from .future import PineconeGrpcFuture
 
 from pinecone.core.grpc.protos.vector_service_pb2 import (
     Vector as GRPCVector,
     SparseValues as GRPCSparseValues,
     Vector,
     SparseValues,
+    DeleteResponse as GRPCDeleteResponse,
 )
 
 __all__ = [
     "GRPCIndex",
     "PineconeGRPC",
+    "GRPCDeleteResponse",
     "GRPCClientConfig",
     "GRPCVector",
     "GRPCSparseValues",
     "Vector",
     "SparseValues",
+    "PineconeGrpcFuture",
 ]

{pinecone-5.4.0.dev4 → pinecone-5.4.0.dev5}/pinecone/grpc/base.py

@@ -10,6 +10,7 @@ from .channel_factory import GrpcChannelFactory
 from pinecone import Config
 from .config import GRPCClientConfig
 from .grpc_runner import GrpcRunner
+from concurrent.futures import ThreadPoolExecutor
 
 from pinecone_plugin_interface import load_and_install as install_plugins
 
@@ -29,10 +30,12 @@ class GRPCIndexBase(ABC):
         config: Config,
         channel: Optional[Channel] = None,
         grpc_config: Optional[GRPCClientConfig] = None,
+        pool_threads: Optional[int] = None,
         _endpoint_override: Optional[str] = None,
     ):
         self.config = config
         self.grpc_client_config = grpc_config or GRPCClientConfig()
+        self.pool_threads = pool_threads
 
         self._endpoint_override = _endpoint_override
 
@@ -58,6 +61,13 @@ class GRPCIndexBase(ABC):
         except Exception as e:
             _logger.error(f"Error loading plugins in GRPCIndex: {e}")
 
+    @property
+    def threadpool_executor(self):
+        if self._pool is None:
+            pt = self.pool_threads or 10
+            self._pool = ThreadPoolExecutor(max_workers=pt)
+        return self._pool
+
     @property
     @abstractmethod
     def stub_class(self):