diff --git a/pyproject.toml b/pyproject.toml index 346c47c..fc7102d 100644 --- a/pyproject.toml +++ b/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 = [] diff --git a/reference.md b/reference.md index ddd0baa..799785f 100644 --- a/reference.md +++ b/reference.md @@ -1462,7 +1462,9 @@ client.graph.add(
-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.
@@ -1681,7 +1683,13 @@ Nested objects and arrays are not allowed.
-**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.
@@ -1724,7 +1732,13 @@ Nested objects and arrays are not allowed.
-**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.
@@ -2314,7 +2328,7 @@ client.graph.search(
-**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.
@@ -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. @@ -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.
-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.
diff --git a/src/zep_cloud/__init__.py b/src/zep_cloud/__init__.py index 81b1e88..a4ab26a 100644 --- a/src/zep_cloud/__init__.py +++ b/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", diff --git a/src/zep_cloud/core/client_wrapper.py b/src/zep_cloud/core/client_wrapper.py index 55159b5..67fb3e0 100644 --- a/src/zep_cloud/core/client_wrapper.py +++ b/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}" diff --git a/src/zep_cloud/graph/client.py b/src/zep_cloud/graph/client.py index 6c7c25d..e258862 100644 --- a/src/zep_cloud/graph/client.py +++ b/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. diff --git a/src/zep_cloud/graph/raw_client.py b/src/zep_cloud/graph/raw_client.py index 7dc1f0f..112e15c 100644 --- a/src/zep_cloud/graph/raw_client.py +++ b/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. diff --git a/src/zep_cloud/thread/client.py b/src/zep_cloud/thread/client.py index bc16b58..90cba81 100644 --- a/src/zep_cloud/thread/client.py +++ b/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 ---------- diff --git a/src/zep_cloud/thread/raw_client.py b/src/zep_cloud/thread/raw_client.py index 35b17a9..8b207e5 100644 --- a/src/zep_cloud/thread/raw_client.py +++ b/src/zep_cloud/thread/raw_client.py @@ -512,7 +512,9 @@ def add_messages_batch( request_options: typing.Optional[RequestOptions] = None, ) -> HttpResponse[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 ---------- @@ -1144,7 +1146,9 @@ async def add_messages_batch( request_options: typing.Optional[RequestOptions] = None, ) -> AsyncHttpResponse[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 ---------- diff --git a/src/zep_cloud/types/__init__.py b/src/zep_cloud/types/__init__.py index d6ea240..247b46d 100644 --- a/src/zep_cloud/types/__init__.py +++ b/src/zep_cloud/types/__init__.py @@ -47,6 +47,7 @@ from .graph_list_response import GraphListResponse from .graph_nodes_request import GraphNodesRequest from .graph_observations_request import GraphObservationsRequest +from .graph_search_response_metadata import GraphSearchResponseMetadata from .graph_search_results import GraphSearchResults from .graph_search_scope import GraphSearchScope from .graph_thread_summaries_request import GraphThreadSummariesRequest @@ -129,6 +130,7 @@ "GraphListResponse", "GraphNodesRequest", "GraphObservationsRequest", + "GraphSearchResponseMetadata", "GraphSearchResults", "GraphSearchScope", "GraphThreadSummariesRequest", diff --git a/src/zep_cloud/types/batch_item_detail.py b/src/zep_cloud/types/batch_item_detail.py index 5bc0831..5db9b4c 100644 --- a/src/zep_cloud/types/batch_item_detail.py +++ b/src/zep_cloud/types/batch_item_detail.py @@ -10,7 +10,14 @@ class BatchItemDetail(UniversalBaseModel): created_at: typing.Optional[str] = None - episode_uuid: typing.Optional[str] = None + episode_uuid: typing.Optional[str] = pydantic.Field(default=None) + """ + EpisodeUUID is the UUID of the episode that will be (or has been) created + for this batch item. Populated for every item kind and always equal to + SourceUUID — the underlying source row's UUID is reused as the episode + UUID during processing. + """ + error: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = None graph_id: typing.Optional[str] = None item_id: typing.Optional[str] = None diff --git a/src/zep_cloud/types/derived_node.py b/src/zep_cloud/types/derived_node.py index ee14cda..05b398d 100644 --- a/src/zep_cloud/types/derived_node.py +++ b/src/zep_cloud/types/derived_node.py @@ -19,6 +19,13 @@ class DerivedNode(UniversalBaseModel): Creation time of the node """ + end_at: typing.Optional[str] = pydantic.Field(default=None) + """ + EndAt is the close timestamp of the evidence window. Set when the + underlying pattern is no longer supported (closed observations); + nil for active observations. + """ + episode_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None) """ Episode UUIDs that support this observation. Only populated for observation nodes in web API responses. @@ -29,6 +36,12 @@ class DerivedNode(UniversalBaseModel): Labels associated with the node """ + latest_evidence_at: typing.Optional[str] = pydantic.Field(default=None) + """ + LatestEvidenceAt is the most recent source-episode timestamp from + which this observation drew evidence. + """ + name: str = pydantic.Field() """ Name of the node @@ -50,6 +63,12 @@ class DerivedNode(UniversalBaseModel): SelectionRank is the global cross-scope rank assigned by auto scope selection. """ + start_at: typing.Optional[str] = pydantic.Field(default=None) + """ + StartAt is the earliest source-episode timestamp from which this + observation was derived. Only populated for observation nodes. + """ + summary: typing.Optional[str] = pydantic.Field(default=None) """ Region summary of member nodes diff --git a/src/zep_cloud/types/graph_search_response_metadata.py b/src/zep_cloud/types/graph_search_response_metadata.py new file mode 100644 index 0000000..0e173e1 --- /dev/null +++ b/src/zep_cloud/types/graph_search_response_metadata.py @@ -0,0 +1,22 @@ +# This file was auto-generated by Fern from our API Definition. + +import typing + +import pydantic +from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel + + +class GraphSearchResponseMetadata(UniversalBaseModel): + server_latency_ms: typing.Optional[int] = pydantic.Field(default=None) + """ + Server-side processing latency in milliseconds. + """ + + if IS_PYDANTIC_V2: + model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2 + else: + + class Config: + frozen = True + smart_union = True + extra = pydantic.Extra.allow diff --git a/src/zep_cloud/types/graph_search_results.py b/src/zep_cloud/types/graph_search_results.py index d1fb5a6..ec1273a 100644 --- a/src/zep_cloud/types/graph_search_results.py +++ b/src/zep_cloud/types/graph_search_results.py @@ -8,6 +8,7 @@ from .entity_edge import EntityEdge from .entity_node import EntityNode from .episode import Episode +from .graph_search_response_metadata import GraphSearchResponseMetadata from .graphiti_saga_node import GraphitiSagaNode @@ -17,6 +18,7 @@ class GraphSearchResults(UniversalBaseModel): episodes: typing.Optional[typing.List[Episode]] = None nodes: typing.Optional[typing.List[EntityNode]] = None observations: typing.Optional[typing.List[DerivedNode]] = None + response: typing.Optional[GraphSearchResponseMetadata] = None thread_summaries: typing.Optional[typing.List[GraphitiSagaNode]] = None if IS_PYDANTIC_V2: diff --git a/src/zep_cloud/types/graphiti_saga_node.py b/src/zep_cloud/types/graphiti_saga_node.py index 621c5b8..739d35a 100644 --- a/src/zep_cloud/types/graphiti_saga_node.py +++ b/src/zep_cloud/types/graphiti_saga_node.py @@ -21,7 +21,15 @@ class GraphitiSagaNode(UniversalBaseModel): last_summarized_at: typing.Optional[str] = pydantic.Field(default=None) """ - Timestamp of the most recent summary update. + Wall-clock timestamp of the most recent summary update. Used internally + as the watermark for filtering new episodes by ingestion time. + """ + + last_summarized_episode_valid_at: typing.Optional[str] = pydantic.Field(default=None) + """ + Maximum episode reference time (valid_at) covered by the most recent + summary. Use this field — not LastSummarizedAt — when answering "how + recent is this summary's content in event-time?". """ name: str = pydantic.Field() diff --git a/src/zep_cloud/types/thread_summary.py b/src/zep_cloud/types/thread_summary.py index 0f25c0c..db33c75 100644 --- a/src/zep_cloud/types/thread_summary.py +++ b/src/zep_cloud/types/thread_summary.py @@ -16,7 +16,17 @@ class ThreadSummary(UniversalBaseModel): last_summarized_at: typing.Optional[str] = pydantic.Field(default=None) """ - LastSummarizedAt is the timestamp of the most recent summary update. + LastSummarizedAt is the wall-clock timestamp of the most recent + summary update. This is an ingestion-time watermark; for the + event-time recency of the summary's content, use + LastSummarizedEpisodeValidAt instead. + """ + + last_summarized_episode_valid_at: typing.Optional[str] = pydantic.Field(default=None) + """ + LastSummarizedEpisodeValidAt is the maximum episode reference time + (valid_at) covered by the most recent summary. Use this when + answering "how recent is this summary's content in event-time?". """ summary: typing.Optional[str] = pydantic.Field(default=None)