docs(toolbox-core): Update README to include guidance on session lifecycle management (#259)

* docs: Update README to include guidance on session lifecycle management

* docs: Improve README

* docs: Improve README

* docs: Improve README

* docs: Improve README

* docs: Add client lifecycle management for sync client

* docs: Improve README

* docs: Improve the README doc

Author: anubhav756

packages/toolbox-core/README.md

@@ -21,31 +21,31 @@ involving Large Language Models (LLMs).
 - [Quickstart](#quickstart)
 - [Usage](#usage)
 - [Loading Tools](#loading-tools)
-  - [Load a toolset](#load-a-toolset)
-  - [Load a single tool](#load-a-single-tool)
+    - [Load a toolset](#load-a-toolset)
+    - [Load a single tool](#load-a-single-tool)
 - [Invoking Tools](#invoking-tools)
 - [Synchronous Usage](#synchronous-usage)
 - [Use with LangGraph](#use-with-langgraph)
-- [Authenticating to the Toolbox Server](#authenticating-to-the-toolbox-server)
-  - [When is Client-to-Server Authentication Needed?](#when-is-client-to-server-authentication-needed)
-  - [How it works](#how-it-works)
-  - [Configuration](#configuration)
-  - [Authenticating with Google Cloud Servers](#authenticating-with-google-cloud-servers)
-  - [Step by Step Guide for Cloud Run](#step-by-step-guide-for-cloud-run)
+- [Client to Server Authentication](#client-to-server-authentication)
+    - [When is Client-to-Server Authentication Needed?](#when-is-client-to-server-authentication-needed)
+    - [How it works](#how-it-works)
+    - [Configuration](#configuration)
+    - [Authenticating with Google Cloud Servers](#authenticating-with-google-cloud-servers)
+    - [Step by Step Guide for Cloud Run](#step-by-step-guide-for-cloud-run)
 - [Authenticating Tools](#authenticating-tools)
-  - [When is Authentication Needed?](#when-is-authentication-needed)
-  - [Supported Authentication Mechanisms](#supported-authentication-mechanisms)
-  - [Step 1: Configure Tools in Toolbox Service](#step-1-configure-tools-in-toolbox-service)
-  - [Step 2: Configure SDK Client](#step-2-configure-sdk-client)
-    - [Provide an ID Token Retriever Function](#provide-an-id-token-retriever-function)
-    - [Option A: Add Authentication to a Loaded Tool](#option-a-add-authentication-to-a-loaded-tool)
-    - [Option B: Add Authentication While Loading Tools](#option-b-add-authentication-while-loading-tools)
-  - [Complete Authentication Example](#complete-authentication-example)
+    - [When is Authentication Needed?](#when-is-authentication-needed)
+    - [Supported Authentication Mechanisms](#supported-authentication-mechanisms)
+    - [Step 1: Configure Tools in Toolbox Service](#step-1-configure-tools-in-toolbox-service)
+    - [Step 2: Configure SDK Client](#step-2-configure-sdk-client)
+        - [Provide an ID Token Retriever Function](#provide-an-id-token-retriever-function)
+        - [Option A: Add Authentication to a Loaded Tool](#option-a-add-authentication-to-a-loaded-tool)
+        - [Option B: Add Authentication While Loading Tools](#option-b-add-authentication-while-loading-tools)
+    - [Complete Authentication Example](#complete-authentication-example)
 - [Binding Parameter Values](#binding-parameter-values)
-  - [Why Bind Parameters?](#why-bind-parameters)
-  - [Option A: Binding Parameters to a Loaded Tool](#option-a-binding-parameters-to-a-loaded-tool)
-  - [Option B: Binding Parameters While Loading Tools](#option-b-binding-parameters-while-loading-tools)
-  - [Binding Dynamic Values](#binding-dynamic-values)
+    - [Why Bind Parameters?](#why-bind-parameters)
+    - [Option A: Binding Parameters to a Loaded Tool](#option-a-binding-parameters-to-a-loaded-tool)
+    - [Option B: Binding Parameters While Loading Tools](#option-b-binding-parameters-while-loading-tools)
+    - [Binding Dynamic Values](#binding-dynamic-values)
 - [Contributing](#contributing)
 - [License](#license)
 - [Support](#support)
@@ -69,6 +69,14 @@ pip install toolbox-core
 > - If you prefer synchronous execution, refer to the [Synchronous
 >   Usage](#synchronous-usage) section below.
 
+> [!IMPORTANT]
+>
+> The `ToolboxClient` (and its synchronous counterpart `ToolboxSyncClient`)
+> interacts with network resources using an underlying HTTP client session. You
+> should remember to use a context manager or explicitly call `close()` to clean
+> up these resources. If you provide your own session, you'll need to close it
+> in addition to calling `ToolboxClient.close()`. 
+
 ## Quickstart
 
 Here's a minimal example to get you started. Ensure your Toolbox service is
@@ -80,15 +88,29 @@ from toolbox_core import ToolboxClient
 
 async def main():
     # Replace with the actual URL where your Toolbox service is running
-    toolbox = ToolboxClient("http://127.0.0.1:5000")
-    weather_tool = await toolbox.load_tool("get_weather")
-    result = await weather_tool(location="London")
-    print(result)
+    async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
+        weather_tool = await toolbox.load_tool("get_weather")
+        result = await weather_tool(location="London")
+        print(result)
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+> [!IMPORTANT]
+> If you initialize `ToolboxClient` without providing an external session and
+> cannot use `async with`, you must explicitly close the client using `await
+> toolbox.close()` in a `finally` block. This ensures the internally created
+> session is closed.
+>
+>  ```py
+>  toolbox = ToolboxClient("http://127.0.0.1:5000")
+>  try:
+>      # ... use toolbox ...
+>  finally:
+>      await toolbox.close()
+>  ```
+
 ## Usage
 
 Import and initialize a Toolbox client, pointing it to the URL of your running
@@ -98,11 +120,23 @@ Toolbox service.
 from toolbox_core import ToolboxClient
 
 # Replace with your Toolbox service's URL
-toolbox = ToolboxClient("http://127.0.0.1:5000")
+async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
 ```
 
 All interactions for loading and invoking tools happen through this client.
 
+> [!NOTE]
+> For advanced use cases, you can provide an external `aiohttp.ClientSession`
+> during initialization (e.g., `ToolboxClient(url, session=my_session)`). If you
+> provide your own session, you are responsible for managing its lifecycle;
+> `ToolboxClient` *will not* close it.
+
+> [!IMPORTANT]
+> Closing the `ToolboxClient` also closes the underlying network session shared by
+> all tools loaded from that client. As a result, any tool instances you have
+> loaded will cease to function and will raise an error if you attempt to invoke
+> them after the client is closed.
+
 ## Loading Tools
 
 You can load tools individually or in groups (toolsets) as defined in your
@@ -161,10 +195,10 @@ The `ToolboxSyncClient` handles communication with the Toolbox service synchrono
 ```py
 from toolbox_core import ToolboxSyncClient
 
-toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
-weather_tool = toolbox.load_tool("get_weather")
-result = weather_tool(location="Paris")
-print(result)
+with ToolboxSyncClient("http://127.0.0.1:5000") as toolbox:
+    weather_tool = toolbox.load_tool("get_weather")
+    result = weather_tool(location="Paris")
+    print(result)
 ```
 
 > [!TIP]
@@ -199,33 +233,33 @@ from langgraph.graph import StateGraph, MessagesState, START, END
 from langgraph.prebuilt import ToolNode
 from langchain.tools import StructuredTool
 
-toolbox = ToolboxClient("http://127.0.0.1:5000")
-tools = await toolbox.load_toolset()
-wrapped_tools = [StructuredTool.from_function(tool, parse_docstring=True) for tool in tools]
-model_with_tools = ChatVertexAI(model="gemini-2.0-flash-001").bind_tools(wrapped_tools)
+async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
+    tools = await toolbox.load_toolset()
+    wrapped_tools = [StructuredTool.from_function(tool, parse_docstring=True) for tool in tools]
+    model_with_tools = ChatVertexAI(model="gemini-2.0-flash-001").bind_tools(wrapped_tools)
 
-def call_model(state: MessagesState):
-    messages = state["messages"]
-    response = model_with_tools.invoke(messages)
-    return {"messages": [response]}
+    def call_model(state: MessagesState):
+        messages = state["messages"]
+        response = model_with_tools.invoke(messages)
+        return {"messages": [response]}
 
-def should_continue(state: MessagesState):
-    messages = state["messages"]
-    last_message = messages[-1]
-    if last_message.tool_calls:
-        return "tools"
-    return END
+    def should_continue(state: MessagesState):
+        messages = state["messages"]
+        last_message = messages[-1]
+        if last_message.tool_calls:
+            return "tools"
+        return END
 
-workflow = StateGraph(MessagesState)
+    workflow = StateGraph(MessagesState)
 
-workflow.add_node("agent", call_model)
-workflow.add_node("tools", ToolNode(wrapped_tools))
+    workflow.add_node("agent", call_model)
+    workflow.add_node("tools", ToolNode(wrapped_tools))
 
-workflow.add_edge(START, "agent")
-workflow.add_conditional_edges("agent", should_continue, ["tools", END])
-workflow.add_edge("tools", "agent")
+    workflow.add_edge(START, "agent")
+    workflow.add_conditional_edges("agent", should_continue, ["tools", END])
+    workflow.add_edge("tools", "agent")
 
-app = workflow.compile()
+    app = workflow.compile()
 ```
 
 ## Client to Server Authentication
@@ -264,16 +298,16 @@ You can configure these dynamic headers in two ways:
     ```python
     from toolbox_core import ToolboxClient
 
-    client = ToolboxClient("toolbox-url", headers={"header1": header1_getter, "header2": header2_getter, ...})
+    async with ToolboxClient("toolbox-url", headers={"header1": header1_getter, "header2": header2_getter, ...}) as client:
     ```
 
 1. **After Client Initialization**
 
     ```python
     from toolbox_core import ToolboxClient
 
-    client = ToolboxClient("toolbox-url")
-    client.add_headers({"header1": header1_getter, "header2": header2_getter, ...})
+    async with ToolboxClient("toolbox-url") as client:
+        client.add_headers({"header1": header1_getter, "header2": header2_getter, ...})
     ```
 
 ### Authenticating with Google Cloud Servers
@@ -299,13 +333,13 @@ For Toolbox servers hosted on Google Cloud (e.g., Cloud Run) and requiring
     from toolbox_core import auth_methods
 
     auth_token_provider = auth_methods.aget_google_id_token # can also use sync method
-    client = ToolboxClient(
+    async with ToolboxClient(
         URL,
         client_headers={"Authorization": auth_token_provider},
-    )
-    tools = await client.load_toolset()
+    ) as client:
+        tools = await client.load_toolset()
 
-    # Now, you can use the client as usual.
+        # Now, you can use the client as usual.
     ```
 
 ## Authenticating Tools
@@ -378,17 +412,17 @@ You can add the token retriever function to a tool object *after* it has been
 loaded. This modifies the specific tool instance.
 
 ```py
-toolbox = ToolboxClient("http://127.0.0.1:5000")
-tool = await toolbox.load_tool("my-tool")
+async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
+    tool = await toolbox.load_tool("my-tool")
 
-auth_tool = tool.add_auth_token_getter("my_auth", get_auth_token)  # Single token
+    auth_tool = tool.add_auth_token_getter("my_auth", get_auth_token)  # Single token
 
-# OR
+    # OR
 
-multi_auth_tool = tool.add_auth_token_getters({
-    "my_auth_1", get_auth_token_1,
-    "my_auth_2", get_auth_token_2,
-})  # Multiple tokens
+    multi_auth_tool = tool.add_auth_token_getters({
+        "my_auth_1": get_auth_token_1,
+        "my_auth_2": get_auth_token_2,
+    })  # Multiple tokens
 ```
 
 #### Option B: Add Authentication While Loading Tools
@@ -421,12 +455,12 @@ async def get_auth_token():
     # This example just returns a placeholder. Replace with your actual token retrieval.
     return "YOUR_ID_TOKEN" # Placeholder
 
-toolbox = ToolboxClient("http://127.0.0.1:5000")
-tool = await toolbox.load_tool("my-tool")
+async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
+    tool = await toolbox.load_tool("my-tool")
 
-auth_tool = tool.add_auth_token_getters({"my_auth": get_auth_token})
-result = auth_tool(input="some input")
-print(result)
+    auth_tool = tool.add_auth_token_getters({"my_auth": get_auth_token})
+    result = auth_tool(input="some input")
+    print(result)
 ```
 
 ## Binding Parameter Values
@@ -456,14 +490,14 @@ Bind values to a tool object *after* it has been loaded. This modifies the
 specific tool instance.
 
 ```py
-toolbox = ToolboxClient("http://127.0.0.1:5000")
-tool = await toolbox.load_tool("my-tool")
+async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
+    tool = await toolbox.load_tool("my-tool")
 
-bound_tool = tool.bind_param("param", "value")
+    bound_tool = tool.bind_param("param", "value")
 
-# OR
+    # OR
 
-bound_tool = tool.bind_params({"param": "value"})
+    bound_tool = tool.bind_params({"param": "value"})
 ```
 
 ### Option B: Binding Parameters While Loading Tools
@@ -490,8 +524,8 @@ invoked to dynamically determine the parameter's value at runtime.
 
 ```py
 async def get_dynamic_value():
-  # Logic to determine the value
-  return "dynamic_value"
+    # Logic to determine the value
+    return "dynamic_value"
 
 dynamic_bound_tool = tool.bind_param("param", get_dynamic_value)
 ```