From 726a85f26b3c0bce2ee481aa673a2630dfe3a02d Mon Sep 17 00:00:00 2001 From: Andrew Nguonly Date: Tue, 29 Oct 2024 15:31:21 -0700 Subject: [PATCH] Add docstring to `RemoteGraph` (#2217) --- docs/docs/reference/remote_graph.md | 6 + docs/mkdocs.yml | 1 + libs/langgraph/langgraph/pregel/remote.py | 194 +++++++++++++++++++++- 3 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 docs/docs/reference/remote_graph.md diff --git a/docs/docs/reference/remote_graph.md b/docs/docs/reference/remote_graph.md new file mode 100644 index 000000000..1a1d23832 --- /dev/null +++ b/docs/docs/reference/remote_graph.md @@ -0,0 +1,6 @@ +# RemoteGraph + +::: langgraph.pregel.remote + options: + members: + - RemoteGraph diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 660df887b..2fb8bbdd6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -86,6 +86,7 @@ nav: - Reference: - "reference/index.md" - Graphs: reference/graphs.md + - RemoteGraph: reference/remote_graph.md - Checkpointing: reference/checkpoints.md - Storage: reference/store.md - Prebuilt Components: reference/prebuilt.md diff --git a/libs/langgraph/langgraph/pregel/remote.py b/libs/langgraph/langgraph/pregel/remote.py index 48a594066..d055789f3 100644 --- a/libs/langgraph/langgraph/pregel/remote.py +++ b/libs/langgraph/langgraph/pregel/remote.py @@ -46,6 +46,16 @@ class RemoteException(Exception): class RemoteGraph(PregelProtocol): + """The `RemoteGraph` class is a client implementation for calling remote + APIs that implement the LangGraph Server API specification. + + For example, the `RemoteGraph` class can be used to call APIs from deployments + on LangGraph Cloud. + + `RemoteGraph` behaves the same way as a `Graph` and can be used directly as + a node in another `Graph`. + """ + name: str def __init__( @@ -63,7 +73,17 @@ class RemoteGraph(PregelProtocol): """Specify `url`, `api_key`, and/or `headers` to create default sync and async clients. If `client` or `sync_client` are provided, they will be used instead of the default clients. - See `LangGraphClient` and `SyncLangGraphClient` for details on the default clients. + See `LangGraphClient` and `SyncLangGraphClient` for details on the default clients. At least + one of `url`, `client`, or `sync_client` must be provided. + + Args: + name: The name of the graph. + url: The URL of the remote API. + api_key: The API key to use for authentication. If not provided, it will be read from the environment (`LANGGRAPH_API_KEY`, `LANGSMITH_API_KEY`, or `LANGCHAIN_API_KEY`). + headers: Additional headers to include in the requests. + client: A `LangGraphClient` instance to use instead of creating a default client. + sync_client: A `SyncLangGraphClient` instance to use instead of creating a default client. + config: An optional `RunnableConfig` instance with additional configuration. """ self.name = name self.config = config @@ -121,6 +141,19 @@ class RemoteGraph(PregelProtocol): *, xray: Union[int, bool] = False, ) -> DrawableGraph: + """Get graph by graph name. + + This method calls `GET /assistants/{assistant_id}/graph`. + + Args: + config: This parameter is not used. + xray: Include graph representation of subgraphs. If an integer + value is provided, only subgraphs with a depth less than or + equal to the value will be included. + + Returns: + The graph information for the assistant in JSON format. + """ sync_client = self._validate_sync_client() graph = sync_client.assistants.get_graph( assistant_id=self.name, @@ -137,6 +170,19 @@ class RemoteGraph(PregelProtocol): *, xray: Union[int, bool] = False, ) -> DrawableGraph: + """Get graph by graph name. + + This method calls `GET /assistants/{assistant_id}/graph`. + + Args: + config: This parameter is not used. + xray: Include graph representation of subgraphs. If an integer + value is provided, only subgraphs with a depth less than or + equal to the value will be included. + + Returns: + The graph information for the assistant in JSON format. + """ client = self._validate_client() graph = await client.assistants.get_graph( assistant_id=self.name, @@ -268,6 +314,20 @@ class RemoteGraph(PregelProtocol): def get_state( self, config: RunnableConfig, *, subgraphs: bool = False ) -> StateSnapshot: + """Get the state of a thread. + + This method calls `POST /threads/{thread_id}/state/checkpoint` if a + checkpoint is specified in the config or `GET /threads/{thread_id}/state` + if no checkpoint is specified. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + subgraphs: Include subgraphs in the state. + + Returns: + The latest state of the thread. + """ sync_client = self._validate_sync_client() merged_config = merge_configs(self.config, config) @@ -281,6 +341,20 @@ class RemoteGraph(PregelProtocol): async def aget_state( self, config: RunnableConfig, *, subgraphs: bool = False ) -> StateSnapshot: + """Get the state of a thread. + + This method calls `POST /threads/{thread_id}/state/checkpoint` if a + checkpoint is specified in the config or `GET /threads/{thread_id}/state` + if no checkpoint is specified. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + subgraphs: Include subgraphs in the state. + + Returns: + The latest state of the thread. + """ client = self._validate_client() merged_config = merge_configs(self.config, config) @@ -299,6 +373,20 @@ class RemoteGraph(PregelProtocol): before: Optional[RunnableConfig] = None, limit: Optional[int] = None, ) -> Iterator[StateSnapshot]: + """Get the state history of a thread. + + This method calls `POST /threads/{thread_id}/history`. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + filter: Metadata to filter on. + before: A `RunnableConfig` that includes checkpoint metadata. + limit: Max number of states to return. + + Returns: + States of the thread. + """ sync_client = self._validate_sync_client() merged_config = merge_configs(self.config, config) @@ -320,6 +408,20 @@ class RemoteGraph(PregelProtocol): before: Optional[RunnableConfig] = None, limit: Optional[int] = None, ) -> AsyncIterator[StateSnapshot]: + """Get the state history of a thread. + + This method calls `POST /threads/{thread_id}/history`. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + filter: Metadata to filter on. + before: A `RunnableConfig` that includes checkpoint metadata. + limit: Max number of states to return. + + Returns: + States of the thread. + """ client = self._validate_client() merged_config = merge_configs(self.config, config) @@ -339,6 +441,19 @@ class RemoteGraph(PregelProtocol): values: Optional[Union[dict[str, Any], Any]], as_node: Optional[str] = None, ) -> RunnableConfig: + """Update the state of a thread. + + This method calls `POST /threads/{thread_id}/state`. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + values: Values to update to the state. + as_node: Update the state as if this node had just executed. + + Returns: + `RunnableConfig` for the updated thread. + """ sync_client = self._validate_sync_client() merged_config = merge_configs(self.config, config) @@ -356,6 +471,19 @@ class RemoteGraph(PregelProtocol): values: Optional[Union[dict[str, Any], Any]], as_node: Optional[str] = None, ) -> RunnableConfig: + """Update the state of a thread. + + This method calls `POST /threads/{thread_id}/state`. + + Args: + config: A `RunnableConfig` that includes `thread_id` in the + `configurable` field. + values: Values to update to the state. + as_node: Update the state as if this node had just executed. + + Returns: + `RunnableConfig` for the updated thread. + """ client = self._validate_client() merged_config = merge_configs(self.config, config) @@ -408,6 +536,23 @@ class RemoteGraph(PregelProtocol): interrupt_after: Optional[Union[All, Sequence[str]]] = None, subgraphs: bool = False, ) -> Iterator[Union[dict[str, Any], Any]]: + """Create a run and stream the results. + + This method calls `POST /threads/{thread_id}/runs/stream` if a `thread_id` + is speciffed in the `configurable` field of the config or + `POST /runs/stream` otherwise. + + Args: + input: Input to the graph. + config: A `RunnableConfig` for graph invocation. + stream_mode: Stream mode(s) to use. + interrupt_before: Interrupt the graph before these nodes. + interrupt_after: Interrupt the graph after these nodes. + subgraphs: Stream from subgraphs. + + Yields: + The output of the graph. + """ sync_client = self._validate_sync_client() merged_config = merge_configs(self.config, config) sanitized_config = self._sanitize_config(merged_config) @@ -456,6 +601,23 @@ class RemoteGraph(PregelProtocol): interrupt_after: Optional[Union[All, Sequence[str]]] = None, subgraphs: bool = False, ) -> AsyncIterator[Union[dict[str, Any], Any]]: + """Create a run and stream the results. + + This method calls `POST /threads/{thread_id}/runs/stream` if a `thread_id` + is speciffed in the `configurable` field of the config or + `POST /runs/stream` otherwise. + + Args: + input: Input to the graph. + config: A `RunnableConfig` for graph invocation. + stream_mode: Stream mode(s) to use. + interrupt_before: Interrupt the graph before these nodes. + interrupt_after: Interrupt the graph after these nodes. + subgraphs: Stream from subgraphs. + + Yields: + The output of the graph. + """ client = self._validate_client() merged_config = merge_configs(self.config, config) sanitized_config = self._sanitize_config(merged_config) @@ -518,6 +680,21 @@ class RemoteGraph(PregelProtocol): interrupt_before: Optional[Union[All, Sequence[str]]] = None, interrupt_after: Optional[Union[All, Sequence[str]]] = None, ) -> Union[dict[str, Any], Any]: + """Create a run, wait until it finishes and return the final state. + + This method calls `POST /threads/{thread_id}/runs/wait` if a `thread_id` + is speciffed in the `configurable` field of the config or + `POST /runs/wait` otherwise. + + Args: + input: Input to the graph. + config: A `RunnableConfig` for graph invocation. + interrupt_before: Interrupt the graph before these nodes. + interrupt_after: Interrupt the graph after these nodes. + + Returns: + The output of the graph. + """ sync_client = self._validate_sync_client() merged_config = merge_configs(self.config, config) sanitized_config = self._sanitize_config(merged_config) @@ -540,6 +717,21 @@ class RemoteGraph(PregelProtocol): interrupt_before: Optional[Union[All, Sequence[str]]] = None, interrupt_after: Optional[Union[All, Sequence[str]]] = None, ) -> Union[dict[str, Any], Any]: + """Create a run, wait until it finishes and return the final state. + + This method calls `POST /threads/{thread_id}/runs/wait` if a `thread_id` + is speciffed in the `configurable` field of the config or + `POST /runs/wait` otherwise. + + Args: + input: Input to the graph. + config: A `RunnableConfig` for graph invocation. + interrupt_before: Interrupt the graph before these nodes. + interrupt_after: Interrupt the graph after these nodes. + + Returns: + The output of the graph. + """ client = self._validate_client() merged_config = merge_configs(self.config, config) sanitized_config = self._sanitize_config(merged_config)