Add docstring to RemoteGraph (#2217)

docs/docs/reference/remote_graph.md

@@ -0,0 +1,6 @@
+# RemoteGraph
+
+::: langgraph.pregel.remote
+    options:
+      members:
+        - RemoteGraph

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

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)