chore: Update auth_token(s) as auth_token_getter(s) and add_auth_token(s) as add_auth_token_getter(s) (#182)

This is to align with the toolbox-core APIs and also because the suffix of _getter(s) make these APIs more descriptive and accurate.

It actively encourages best practices regarding token security and lifecycle management (like refresh logic), which is crucial for production systems.

Author: anubhav756

packages/toolbox-langchain/README.md

@@ -225,21 +225,21 @@ async def get_auth_token():
 toolbox = ToolboxClient("http://127.0.0.1:5000")
 tools = toolbox.load_toolset()
 
-auth_tool = tools[0].add_auth_token("my_auth", get_auth_token) # Single token
+auth_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # Single token
 
-multi_auth_tool = tools[0].add_auth_tokens({"my_auth", get_auth_token}) # Multiple tokens
+multi_auth_tool = tools[0].add_auth_token_getters({"my_auth", get_auth_token}) # Multiple tokens
 
 # OR
 
-auth_tools = [tool.add_auth_token("my_auth", get_auth_token) for tool in tools]
+auth_tools = [tool.add_auth_token_getter("my_auth", get_auth_token) for tool in tools]
 ```
 
 #### Add Authentication While Loading
 
 ```py
-auth_tool = toolbox.load_tool(auth_tokens={"my_auth": get_auth_token})
+auth_tool = toolbox.load_tool(auth_token_getters={"my_auth": get_auth_token})
 
-auth_tools = toolbox.load_toolset(auth_tokens={"my_auth": get_auth_token})
+auth_tools = toolbox.load_toolset(auth_token_getters={"my_auth": get_auth_token})
 ```
 
 > [!NOTE]
@@ -260,7 +260,7 @@ async def get_auth_token():
 toolbox = ToolboxClient("http://127.0.0.1:5000")
 tool = toolbox.load_tool("my-tool")
 
-auth_tool = tool.add_auth_token("my_auth", get_auth_token)
+auth_tool = tool.add_auth_token_getter("my_auth", get_auth_token)
 result = auth_tool.invoke({"input": "some input"})
 print(result)
 ```

packages/toolbox-langchain/src/toolbox_langchain/async_client.py

@@ -44,7 +44,8 @@ def __init__(
     async def aload_tool(
         self,
         tool_name: str,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
+        auth_tokens: Optional[dict[str, Callable[[], str]]] = None,
         auth_headers: Optional[dict[str, Callable[[], str]]] = None,
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool = True,
@@ -54,9 +55,10 @@ async def aload_tool(
 
         Args:
             tool_name: The name of the tool to load.
-            auth_tokens: An optional mapping of authentication source names to
-                functions that retrieve ID tokens.
-            auth_headers: Deprecated. Use `auth_tokens` instead.
+            auth_token_getters: An optional mapping of authentication source
+                names to functions that retrieve ID tokens.
+            auth_tokens: Deprecated. Use `auth_token_getters` instead.
+            auth_headers: Deprecated. Use `auth_token_getters` instead.
             bound_params: An optional mapping of parameter names to their
                 bound values.
             strict: If True, raises a ValueError if any of the given bound
@@ -67,17 +69,30 @@ async def aload_tool(
             A tool loaded from the Toolbox.
         """
         if auth_headers:
-            if auth_tokens:
+            if auth_token_getters:
                 warn(
-                    "Both `auth_tokens` and `auth_headers` are provided. `auth_headers` is deprecated, and `auth_tokens` will be used.",
+                    "Both `auth_token_getters` and `auth_headers` are provided. `auth_headers` is deprecated, and `auth_token_getters` will be used.",
                     DeprecationWarning,
                 )
             else:
                 warn(
-                    "Argument `auth_headers` is deprecated. Use `auth_tokens` instead.",
+                    "Argument `auth_headers` is deprecated. Use `auth_token_getters` instead.",
                     DeprecationWarning,
                 )
-                auth_tokens = auth_headers
+                auth_token_getters = auth_headers
+
+        if auth_tokens:
+            if auth_token_getters:
+                warn(
+                    "Both `auth_token_getters` and `auth_tokens` are provided. `auth_tokens` is deprecated, and `auth_token_getters` will be used.",
+                    DeprecationWarning,
+                )
+            else:
+                warn(
+                    "Argument `auth_tokens` is deprecated. Use `auth_token_getters` instead.",
+                    DeprecationWarning,
+                )
+                auth_token_getters = auth_tokens
 
         url = f"{self.__url}/api/tool/{tool_name}"
         manifest: ManifestSchema = await _load_manifest(url, self.__session)
@@ -87,15 +102,16 @@ async def aload_tool(
             manifest.tools[tool_name],
             self.__url,
             self.__session,
-            auth_tokens,
+            auth_token_getters,
             bound_params,
             strict,
         )
 
     async def aload_toolset(
         self,
         toolset_name: Optional[str] = None,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
+        auth_tokens: Optional[dict[str, Callable[[], str]]] = None,
         auth_headers: Optional[dict[str, Callable[[], str]]] = None,
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool = True,
@@ -107,9 +123,10 @@ async def aload_toolset(
         Args:
             toolset_name: The name of the toolset to load. If not provided,
                 all tools are loaded.
-            auth_tokens: An optional mapping of authentication source names to
-                functions that retrieve ID tokens.
-            auth_headers: Deprecated. Use `auth_tokens` instead.
+            auth_token_getters: An optional mapping of authentication source
+                names to functions that retrieve ID tokens.
+            auth_tokens: Deprecated. Use `auth_token_getters` instead.
+            auth_headers: Deprecated. Use `auth_token_getters` instead.
             bound_params: An optional mapping of parameter names to their
                 bound values.
             strict: If True, raises a ValueError if any of the given bound
@@ -120,17 +137,30 @@ async def aload_toolset(
             A list of all tools loaded from the Toolbox.
         """
         if auth_headers:
-            if auth_tokens:
+            if auth_token_getters:
+                warn(
+                    "Both `auth_token_getters` and `auth_headers` are provided. `auth_headers` is deprecated, and `auth_token_getters` will be used.",
+                    DeprecationWarning,
+                )
+            else:
+                warn(
+                    "Argument `auth_headers` is deprecated. Use `auth_token_getters` instead.",
+                    DeprecationWarning,
+                )
+                auth_token_getters = auth_headers
+
+        if auth_tokens:
+            if auth_token_getters:
                 warn(
-                    "Both `auth_tokens` and `auth_headers` are provided. `auth_headers` is deprecated, and `auth_tokens` will be used.",
+                    "Both `auth_token_getters` and `auth_tokens` are provided. `auth_tokens` is deprecated, and `auth_token_getters` will be used.",
                     DeprecationWarning,
                 )
             else:
                 warn(
-                    "Argument `auth_headers` is deprecated. Use `auth_tokens` instead.",
+                    "Argument `auth_tokens` is deprecated. Use `auth_token_getters` instead.",
                     DeprecationWarning,
                 )
-                auth_tokens = auth_headers
+                auth_token_getters = auth_tokens
 
         url = f"{self.__url}/api/toolset/{toolset_name or ''}"
         manifest: ManifestSchema = await _load_manifest(url, self.__session)
@@ -143,7 +173,7 @@ async def aload_toolset(
                     tool_schema,
                     self.__url,
                     self.__session,
-                    auth_tokens,
+                    auth_token_getters,
                     bound_params,
                     strict,
                 )
@@ -153,7 +183,8 @@ async def aload_toolset(
     def load_tool(
         self,
         tool_name: str,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
+        auth_tokens: Optional[dict[str, Callable[[], str]]] = None,
         auth_headers: Optional[dict[str, Callable[[], str]]] = None,
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool = True,
@@ -163,7 +194,8 @@ def load_tool(
     def load_toolset(
         self,
         toolset_name: Optional[str] = None,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
+        auth_tokens: Optional[dict[str, Callable[[], str]]] = None,
         auth_headers: Optional[dict[str, Callable[[], str]]] = None,
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool = True,

packages/toolbox-langchain/src/toolbox_langchain/async_tools.py

@@ -45,7 +45,7 @@ def __init__(
         schema: ToolSchema,
         url: str,
         session: ClientSession,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool = True,
     ) -> None:
@@ -57,8 +57,8 @@ def __init__(
             schema: The tool schema.
             url: The base URL of the Toolbox service.
             session: The HTTP client session.
-            auth_tokens: A mapping of authentication source names to functions
-                that retrieve ID tokens.
+            auth_token_getters: A mapping of authentication source names to
+                functions that retrieve ID tokens.
             bound_params: A mapping of parameter names to their bound
                 values.
             strict: If True, raises a ValueError if any of the given bound
@@ -132,7 +132,7 @@ def __init__(
         self.__schema = schema
         self.__url = url
         self.__session = session
-        self.__auth_tokens = auth_tokens
+        self.__auth_token_getters = auth_token_getters
         self.__auth_params = auth_params
         self.__bound_params = bound_params
 
@@ -172,7 +172,7 @@ async def _arun(self, **kwargs: Any) -> dict[str, Any]:
         kwargs.update(evaluated_params)
 
         return await _invoke_tool(
-            self.__url, self.__session, self.__name, kwargs, self.__auth_tokens
+            self.__url, self.__session, self.__name, kwargs, self.__auth_token_getters
         )
 
     def __validate_auth(self, strict: bool = True) -> None:
@@ -199,7 +199,7 @@ def __validate_auth(self, strict: bool = True) -> None:
 
         # Check tool for at least 1 required auth source
         for src in self.__schema.authRequired:
-            if src in self.__auth_tokens:
+            if src in self.__auth_token_getters:
                 is_authenticated = True
                 break
 
@@ -211,7 +211,7 @@ def __validate_auth(self, strict: bool = True) -> None:
             for src in param.authSources:
 
                 # Find first auth source that is specified
-                if src in self.__auth_tokens:
+                if src in self.__auth_token_getters:
                     has_auth = True
                     break
             if not has_auth:
@@ -238,7 +238,7 @@ def __validate_auth(self, strict: bool = True) -> None:
     def __create_copy(
         self,
         *,
-        auth_tokens: dict[str, Callable[[], str]] = {},
+        auth_token_getters: dict[str, Callable[[], str]] = {},
         bound_params: dict[str, Union[Any, Callable[[], Any]]] = {},
         strict: bool,
     ) -> "AsyncToolboxTool":
@@ -253,8 +253,8 @@ def __create_copy(
         original instance, ensuring immutability.
 
         Args:
-            auth_tokens: A dictionary of auth source names to functions that
-                retrieve ID tokens. These tokens will be merged with the
+            auth_token_getters: A dictionary of auth source names to functions
+                that retrieve ID tokens. These tokens will be merged with the
                 existing auth tokens.
             bound_params: A dictionary of parameter names to their
                 bound values or functions to retrieve the values. These params
@@ -281,21 +281,21 @@ def __create_copy(
             schema=new_schema,
             url=self.__url,
             session=self.__session,
-            auth_tokens={**self.__auth_tokens, **auth_tokens},
+            auth_token_getters={**self.__auth_token_getters, **auth_token_getters},
             bound_params={**self.__bound_params, **bound_params},
             strict=strict,
         )
 
-    def add_auth_tokens(
-        self, auth_tokens: dict[str, Callable[[], str]], strict: bool = True
+    def add_auth_token_getters(
+        self, auth_token_getters: dict[str, Callable[[], str]], strict: bool = True
     ) -> "AsyncToolboxTool":
         """
         Registers functions to retrieve ID tokens for the corresponding
         authentication sources.
 
         Args:
-            auth_tokens: A dictionary of authentication source names to the
-                functions that return corresponding ID token.
+            auth_token_getters: A dictionary of authentication source names to
+                the functions that return corresponding ID token getters.
             strict: If True, a ValueError is raised if any of the provided auth
                 parameters is already bound. If False, only a warning is issued.
 
@@ -313,18 +313,18 @@ def add_auth_tokens(
 
         # Check if the authentication source is already registered.
         dupe_tokens: list[str] = []
-        for auth_token, _ in auth_tokens.items():
-            if auth_token in self.__auth_tokens:
+        for auth_token, _ in auth_token_getters.items():
+            if auth_token in self.__auth_token_getters:
                 dupe_tokens.append(auth_token)
 
         if dupe_tokens:
             raise ValueError(
                 f"Authentication source(s) `{', '.join(dupe_tokens)}` already registered in tool `{self.__name}`."
             )
 
-        return self.__create_copy(auth_tokens=auth_tokens, strict=strict)
+        return self.__create_copy(auth_token_getters=auth_token_getters, strict=strict)
 
-    def add_auth_token(
+    def add_auth_token_getter(
         self, auth_source: str, get_id_token: Callable[[], str], strict: bool = True
     ) -> "AsyncToolboxTool":
         """
@@ -346,7 +346,7 @@ def add_auth_token(
             ValueError: If the provided auth parameter is already bound and
                 strict is True.
         """
-        return self.add_auth_tokens({auth_source: get_id_token}, strict=strict)
+        return self.add_auth_token_getters({auth_source: get_id_token}, strict=strict)
 
     def bind_params(
         self,