feat: add response.server_latency_ms on graph search results (v3.23.0)

pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "zep-cloud"
-version = "3.22.0"
+version = "3.23.0"
 
 [tool.poetry]
 name = "zep-cloud"
-version = "3.22.0"
+version = "3.23.0"
 description = ""
 readme = "README.md"
 authors = []

reference.md

@@ -1462,7 +1462,9 @@ client.graph.add(
 <dl>
 <dd>
 
-Add data to the graph in batch mode. Episodes are processed sequentially in the order provided.
+Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*`) instead.
+
+Adds data to the graph in batch mode, processing episodes concurrently.
 </dd>
 </dl>
 </dd>
@@ -1681,7 +1683,13 @@ Nested objects and arrays are not allowed.
 <dl>
 <dd>
 
-**source_node_labels:** `typing.Optional[typing.Sequence[str]]` — The labels for the source node
+**source_node_labels:** `typing.Optional[typing.Sequence[str]]` 
+
+The labels for the source node. At most one entity-type label may be
+provided so that manually-added triples remain consistent with automatic
+episode extraction, which assigns one best-match entity type per node.
+The base "Entity" label is added implicitly by the graph layer on save
+and does not need to be supplied here.
 
 </dd>
 </dl>
@@ -1724,7 +1732,13 @@ Nested objects and arrays are not allowed.
 <dl>
 <dd>
 
-**target_node_labels:** `typing.Optional[typing.Sequence[str]]` — The labels for the target node
+**target_node_labels:** `typing.Optional[typing.Sequence[str]]` 
+
+The labels for the target node. At most one entity-type label may be
+provided so that manually-added triples remain consistent with automatic
+episode extraction, which assigns one best-match entity type per node.
+The base "Entity" label is added implicitly by the graph layer on save
+and does not need to be supplied here.
 
 </dd>
 </dl>
@@ -2314,7 +2328,7 @@ client.graph.search(
 <dl>
 <dd>
 
-**limit:** `typing.Optional[int]` — The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
+**limit:** `typing.Optional[int]` — The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.
 
 </dd>
 </dl>
@@ -2340,9 +2354,8 @@ client.graph.search(
 
 **reranker:** `typing.Optional[Reranker]` 
 
-Defaults to RRF. When scope=auto, this only affects graph-service retrieval
-shape for graph facts, observations, and thread summaries; source-episode
-retrieval uses RRF, and auto search applies its own internal rerank after retrieval.
+Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected;
+auto search always uses RRF retrieval and applies its own internal rerank after retrieval.
 
 </dd>
 </dl>
@@ -3117,7 +3130,7 @@ client = Zep(
 client.thread.get(
     thread_id="threadId",
     limit=1,
-    cursor=1,
+    cursor=1000000,
     lastn=1,
 )
 
@@ -3295,7 +3308,9 @@ that are added to a user's graph.
 <dl>
 <dd>
 
-Add messages to a thread in batch mode. This will process messages concurrently, which is useful for data migrations.
+Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*` with `type: "thread_message"`) instead.
+
+Adds messages to a thread in batch mode, processing messages concurrently.
 </dd>
 </dl>
 </dd>

src/zep_cloud/__init__.py

@@ -48,6 +48,7 @@
     GraphListResponse,
     GraphNodesRequest,
     GraphObservationsRequest,
+    GraphSearchResponseMetadata,
     GraphSearchResults,
     GraphSearchScope,
     GraphThreadSummariesRequest,
@@ -140,6 +141,7 @@
     "GraphListResponse",
     "GraphNodesRequest",
     "GraphObservationsRequest",
+    "GraphSearchResponseMetadata",
     "GraphSearchResults",
     "GraphSearchScope",
     "GraphThreadSummariesRequest",

src/zep_cloud/core/client_wrapper.py

@@ -22,10 +22,10 @@ def __init__(
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "zep-cloud/3.22.0",
+            "User-Agent": "zep-cloud/3.23.0",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "zep-cloud",
-            "X-Fern-SDK-Version": "3.22.0",
+            "X-Fern-SDK-Version": "3.23.0",
             **(self.get_custom_headers() or {}),
         }
         headers["Authorization"] = f"Api-Key {self.api_key}"

src/zep_cloud/graph/client.py

@@ -364,7 +364,9 @@ def add_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[Episode]:
         """
-        Add data to the graph in batch mode. Episodes are processed sequentially in the order provided.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*`) instead.
+
+        Adds data to the graph in batch mode, processing episodes concurrently.
 
         Parameters
         ----------
@@ -469,7 +471,11 @@ def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         source_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the source node
+            The labels for the source node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         source_node_name : typing.Optional[str]
             The name of the source node to add
@@ -485,7 +491,11 @@ def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         target_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the target node
+            The labels for the target node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         target_node_name : typing.Optional[str]
             The name of the target node to add
@@ -835,7 +845,7 @@ def search(
             The graph_id to search in. When searching user graph, please use user_id instead.
 
         limit : typing.Optional[int]
-            The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
+            The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.
 
         max_characters : typing.Optional[int]
             Maximum total characters across all selected results when scope=auto. Defaults to 2500. Limited to 50000.
@@ -844,9 +854,8 @@ def search(
             weighting for maximal marginal relevance
 
         reranker : typing.Optional[Reranker]
-            Defaults to RRF. When scope=auto, this only affects graph-service retrieval
-            shape for graph facts, observations, and thread summaries; source-episode
-            retrieval uses RRF, and auto search applies its own internal rerank after retrieval.
+            Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected;
+            auto search always uses RRF retrieval and applies its own internal rerank after retrieval.
 
         return_raw_results : typing.Optional[bool]
             When scope=auto, include the selected raw graph results alongside the materialized context block.
@@ -1381,7 +1390,9 @@ async def add_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[Episode]:
         """
-        Add data to the graph in batch mode. Episodes are processed sequentially in the order provided.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*`) instead.
+
+        Adds data to the graph in batch mode, processing episodes concurrently.
 
         Parameters
         ----------
@@ -1494,7 +1505,11 @@ async def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         source_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the source node
+            The labels for the source node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         source_node_name : typing.Optional[str]
             The name of the source node to add
@@ -1510,7 +1525,11 @@ async def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         target_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the target node
+            The labels for the target node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         target_node_name : typing.Optional[str]
             The name of the target node to add
@@ -1900,7 +1919,7 @@ async def search(
             The graph_id to search in. When searching user graph, please use user_id instead.
 
         limit : typing.Optional[int]
-            The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
+            The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.
 
         max_characters : typing.Optional[int]
             Maximum total characters across all selected results when scope=auto. Defaults to 2500. Limited to 50000.
@@ -1909,9 +1928,8 @@ async def search(
             weighting for maximal marginal relevance
 
         reranker : typing.Optional[Reranker]
-            Defaults to RRF. When scope=auto, this only affects graph-service retrieval
-            shape for graph facts, observations, and thread summaries; source-episode
-            retrieval uses RRF, and auto search applies its own internal rerank after retrieval.
+            Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected;
+            auto search always uses RRF retrieval and applies its own internal rerank after retrieval.
 
         return_raw_results : typing.Optional[bool]
             When scope=auto, include the selected raw graph results alongside the materialized context block.

src/zep_cloud/graph/raw_client.py

@@ -624,7 +624,9 @@ def add_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[typing.List[Episode]]:
         """
-        Add data to the graph in batch mode. Episodes are processed sequentially in the order provided.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*`) instead.
+
+        Adds data to the graph in batch mode, processing episodes concurrently.
 
         Parameters
         ----------
@@ -765,7 +767,11 @@ def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         source_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the source node
+            The labels for the source node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         source_node_name : typing.Optional[str]
             The name of the source node to add
@@ -781,7 +787,11 @@ def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         target_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the target node
+            The labels for the target node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         target_node_name : typing.Optional[str]
             The name of the target node to add
@@ -1337,7 +1347,7 @@ def search(
             The graph_id to search in. When searching user graph, please use user_id instead.
 
         limit : typing.Optional[int]
-            The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
+            The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.
 
         max_characters : typing.Optional[int]
             Maximum total characters across all selected results when scope=auto. Defaults to 2500. Limited to 50000.
@@ -1346,9 +1356,8 @@ def search(
             weighting for maximal marginal relevance
 
         reranker : typing.Optional[Reranker]
-            Defaults to RRF. When scope=auto, this only affects graph-service retrieval
-            shape for graph facts, observations, and thread summaries; source-episode
-            retrieval uses RRF, and auto search applies its own internal rerank after retrieval.
+            Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected;
+            auto search always uses RRF retrieval and applies its own internal rerank after retrieval.
 
         return_raw_results : typing.Optional[bool]
             When scope=auto, include the selected raw graph results alongside the materialized context block.
@@ -2254,7 +2263,9 @@ async def add_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[typing.List[Episode]]:
         """
-        Add data to the graph in batch mode. Episodes are processed sequentially in the order provided.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*`) instead.
+
+        Adds data to the graph in batch mode, processing episodes concurrently.
 
         Parameters
         ----------
@@ -2395,7 +2406,11 @@ async def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         source_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the source node
+            The labels for the source node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         source_node_name : typing.Optional[str]
             The name of the source node to add
@@ -2411,7 +2426,11 @@ async def add_fact_triple(
             Nested objects and arrays are not allowed.
 
         target_node_labels : typing.Optional[typing.Sequence[str]]
-            The labels for the target node
+            The labels for the target node. At most one entity-type label may be
+            provided so that manually-added triples remain consistent with automatic
+            episode extraction, which assigns one best-match entity type per node.
+            The base "Entity" label is added implicitly by the graph layer on save
+            and does not need to be supplied here.
 
         target_node_name : typing.Optional[str]
             The name of the target node to add
@@ -2967,7 +2986,7 @@ async def search(
             The graph_id to search in. When searching user graph, please use user_id instead.
 
         limit : typing.Optional[int]
-            The maximum number of facts to retrieve. Defaults to 10. Limited to 50.
+            The maximum number of facts to retrieve for non-auto scopes. Defaults to 10. Limited to 50. Ignored when scope=auto.
 
         max_characters : typing.Optional[int]
             Maximum total characters across all selected results when scope=auto. Defaults to 2500. Limited to 50000.
@@ -2976,9 +2995,8 @@ async def search(
             weighting for maximal marginal relevance
 
         reranker : typing.Optional[Reranker]
-            Defaults to RRF. When scope=auto, this only affects graph-service retrieval
-            shape for graph facts, observations, and thread summaries; source-episode
-            retrieval uses RRF, and auto search applies its own internal rerank after retrieval.
+            Defaults to RRF. Ignored when scope=auto except node_distance and episode_mentions are rejected;
+            auto search always uses RRF retrieval and applies its own internal rerank after retrieval.
 
         return_raw_results : typing.Optional[bool]
             When scope=auto, include the selected raw graph results alongside the materialized context block.

src/zep_cloud/thread/client.py

@@ -244,7 +244,7 @@ def get(
         client.thread.get(
             thread_id="threadId",
             limit=1,
-            cursor=1,
+            cursor=1000000,
             lastn=1,
         )
         """
@@ -325,7 +325,9 @@ def add_messages_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AddThreadMessagesResponse:
         """
-        Add messages to a thread in batch mode. This will process messages concurrently, which is useful for data migrations.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*` with `type: "thread_message"`) instead.
+
+        Adds messages to a thread in batch mode, processing messages concurrently.
 
         Parameters
         ----------
@@ -672,7 +674,7 @@ async def main() -> None:
             await client.thread.get(
                 thread_id="threadId",
                 limit=1,
-                cursor=1,
+                cursor=1000000,
                 lastn=1,
             )
 
@@ -764,7 +766,9 @@ async def add_messages_batch(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AddThreadMessagesResponse:
         """
-        Add messages to a thread in batch mode. This will process messages concurrently, which is useful for data migrations.
+        Deprecated. Use the [Batch API](/adding-batch-data) (`client.batch.*` with `type: "thread_message"`) instead.
+
+        Adds messages to a thread in batch mode, processing messages concurrently.
 
         Parameters
         ----------