Merge branch 'main' into twisha-auth-methods

Author: twishabansal

packages/toolbox-core/README.md

@@ -369,7 +369,7 @@ specific tool instance.
 toolbox = ToolboxClient("http://127.0.0.1:5000")
 tool = await toolbox.load_tool("my-tool")
 
-bound_tool = tool.bind_parameters({"param": "value"})
+bound_tool = tool.bind_params({"param": "value"})
 ```
 
 ### Option B: Binding Parameters While Loading Tools

packages/toolbox-core/src/toolbox_core/client.py

@@ -79,8 +79,11 @@ def __parse_tool(
             else:  # regular parameter
                 params.append(p)
 
-        authn_params = identify_required_authn_params(
-            authn_params, auth_token_getters.keys()
+        authn_params, _, used_auth_keys = identify_required_authn_params(
+            # TODO: Add schema.authRequired as second arg
+            authn_params,
+            [],
+            auth_token_getters.keys(),
         )
 
         tool = ToolboxTool(
@@ -97,9 +100,6 @@ def __parse_tool(
         )
 
         used_bound_keys = set(bound_params.keys())
-        used_auth_keys: set[str] = set()
-        for required_sources in authn_params.values():
-            used_auth_keys.update(required_sources)
 
         return tool, used_auth_keys, used_bound_keys
 
@@ -160,6 +160,9 @@ async def load_tool(
                 for execution. The specific arguments and behavior of the callable
                 depend on the tool itself.
 
+        Raises:
+            ValueError: If the loaded tool instance fails to utilize at least
+                one provided parameter or auth token (if any provided).
         """
         # Resolve client headers
         resolved_headers = {
@@ -176,56 +179,131 @@ async def load_tool(
         # parse the provided definition to a tool
         if name not in manifest.tools:
             # TODO: Better exception
-            raise Exception(f"Tool '{name}' not found!")
-        tool, _, _ = self.__parse_tool(
+            raise ValueError(f"Tool '{name}' not found!")
+        tool, used_auth_keys, used_bound_keys = self.__parse_tool(
             name,
             manifest.tools[name],
             auth_token_getters,
             bound_params,
             self.__client_headers,
         )
 
+        provided_auth_keys = set(auth_token_getters.keys())
+        provided_bound_keys = set(bound_params.keys())
+
+        unused_auth = provided_auth_keys - used_auth_keys
+        unused_bound = provided_bound_keys - used_bound_keys
+
+        if unused_auth or unused_bound:
+            error_messages = []
+            if unused_auth:
+                error_messages.append(f"unused auth tokens: {', '.join(unused_auth)}")
+            if unused_bound:
+                error_messages.append(
+                    f"unused bound parameters: {', '.join(unused_bound)}"
+                )
+            raise ValueError(
+                f"Validation failed for tool '{name}': { '; '.join(error_messages) }."
+            )
+
         return tool
 
     async def load_toolset(
         self,
         name: Optional[str] = None,
         auth_token_getters: dict[str, Callable[[], str]] = {},
         bound_params: Mapping[str, Union[Callable[[], Any], Any]] = {},
+        strict: bool = False,
     ) -> list[ToolboxTool]:
         """
         Asynchronously fetches a toolset and loads all tools defined within it.
 
         Args:
-            name: Name of the toolset to load tools.
+            name: Name of the toolset to load. If None, loads the default toolset.
             auth_token_getters: A mapping of authentication service names to
                 callables that return the corresponding authentication token.
             bound_params: A mapping of parameter names to bind to specific values or
                 callables that are called to produce values as needed.
+            strict: If True, raises an error if *any* loaded tool instance fails
+                to utilize at least one provided parameter or auth token (if any
+                provided). If False (default), raises an error only if a
+                user-provided parameter or auth token cannot be applied to *any*
+                loaded tool across the set.
 
         Returns:
             list[ToolboxTool]: A list of callables, one for each tool defined
             in the toolset.
+
+        Raises:
+            ValueError: If validation fails based on the `strict` flag.
         """
+
         # Resolve client headers
         original_headers = self.__client_headers
         resolved_headers = {
             header_name: await resolve_value(original_headers[header_name])
             for header_name in original_headers
         }
-        # Request the definition of the tool from the server
+        # Request the definition of the toolset from the server
         url = f"{self.__base_url}/api/toolset/{name or ''}"
         async with self.__session.get(url, headers=resolved_headers) as response:
             json = await response.json()
         manifest: ManifestSchema = ManifestSchema(**json)
 
-        # parse each tools name and schema into a list of ToolboxTools
-        tools = [
-            self.__parse_tool(
-                n, s, auth_token_getters, bound_params, self.__client_headers
-            )[0]
-            for n, s in manifest.tools.items()
-        ]
+        tools: list[ToolboxTool] = []
+        overall_used_auth_keys: set[str] = set()
+        overall_used_bound_params: set[str] = set()
+        provided_auth_keys = set(auth_token_getters.keys())
+        provided_bound_keys = set(bound_params.keys())
+
+        # parse each tool's name and schema into a list of ToolboxTools
+        for tool_name, schema in manifest.tools.items():
+            tool, used_auth_keys, used_bound_keys = self.__parse_tool(
+                tool_name,
+                schema,
+                auth_token_getters,
+                bound_params,
+                self.__client_headers,
+            )
+            tools.append(tool)
+
+            if strict:
+                unused_auth = provided_auth_keys - used_auth_keys
+                unused_bound = provided_bound_keys - used_bound_keys
+                if unused_auth or unused_bound:
+                    error_messages = []
+                    if unused_auth:
+                        error_messages.append(
+                            f"unused auth tokens: {', '.join(unused_auth)}"
+                        )
+                    if unused_bound:
+                        error_messages.append(
+                            f"unused bound parameters: {', '.join(unused_bound)}"
+                        )
+                    raise ValueError(
+                        f"Validation failed for tool '{tool_name}': { '; '.join(error_messages) }."
+                    )
+            else:
+                overall_used_auth_keys.update(used_auth_keys)
+                overall_used_bound_params.update(used_bound_keys)
+
+        unused_auth = provided_auth_keys - overall_used_auth_keys
+        unused_bound = provided_bound_keys - overall_used_bound_params
+
+        if unused_auth or unused_bound:
+            error_messages = []
+            if unused_auth:
+                error_messages.append(
+                    f"unused auth tokens could not be applied to any tool: {', '.join(unused_auth)}"
+                )
+            if unused_bound:
+                error_messages.append(
+                    f"unused bound parameters could not be applied to any tool: {', '.join(unused_bound)}"
+                )
+            raise ValueError(
+                f"Validation failed for toolset '{name or 'default'}': { '; '.join(error_messages) }."
+            )
+
         return tools
 
     async def add_headers(

packages/toolbox-core/src/toolbox_core/sync_tool.py

@@ -153,19 +153,37 @@ def add_auth_token_getters(
         new_async_tool = self.__async_tool.add_auth_token_getters(auth_token_getters)
         return ToolboxSyncTool(new_async_tool, self.__loop, self.__thread)
 
-    def bind_parameters(
+    def bind_params(
         self, bound_params: Mapping[str, Union[Callable[[], Any], Any]]
     ) -> "ToolboxSyncTool":
         """
         Binds parameters to values or callables that produce values.
 
-         Args:
-             bound_params: A mapping of parameter names to values or callables that
-                 produce values.
+        Args:
+            bound_params: A mapping of parameter names to values or callables that
+                produce values.
 
-         Returns:
-             A new ToolboxSyncTool instance with the specified parameters bound.
+        Returns:
+            A new ToolboxSyncTool instance with the specified parameters bound.
         """
 
-        new_async_tool = self.__async_tool.bind_parameters(bound_params)
+        new_async_tool = self.__async_tool.bind_params(bound_params)
         return ToolboxSyncTool(new_async_tool, self.__loop, self.__thread)
+
+    def bind_param(
+        self,
+        param_name: str,
+        param_value: Union[Callable[[], Any], Any],
+    ) -> "ToolboxSyncTool":
+        """
+        Binds a parameter to the value or callables that produce it.
+
+        Args:
+            param_name: The name of the bound parameter.
+            param_value: The value of the bound parameter, or a callable that
+                returns the value.
+
+        Returns:
+            A new ToolboxSyncTool instance with the specified parameter bound.
+        """
+        return self.bind_params({param_name: param_value})

packages/toolbox-core/src/toolbox_core/tool.py

@@ -94,7 +94,7 @@ def __init__(
         # Validate conflicting Headers/Auth Tokens
         request_header_names = client_headers.keys()
         auth_token_names = [
-            auth_token_name + "_token"
+            self.__get_auth_header(auth_token_name)
             for auth_token_name in auth_service_token_getters.keys()
         ]
         duplicates = request_header_names & auth_token_names
@@ -187,6 +187,10 @@ def __copy(
             client_headers=check(client_headers, self.__client_headers),
         )
 
+    def __get_auth_header(self, auth_token_name: str) -> str:
+        """Returns the formatted auth token header name."""
+        return f"{auth_token_name}_token"
+
     async def __call__(self, *args: Any, **kwargs: Any) -> str:
         """
         Asynchronously calls the remote tool with the provided arguments.
@@ -208,7 +212,7 @@ async def __call__(self, *args: Any, **kwargs: Any) -> str:
             req_auth_services = set()
             for s in self.__required_authn_params.values():
                 req_auth_services.update(s)
-            raise Exception(
+            raise ValueError(
                 f"One or more of the following authn services are required to invoke this tool"
                 f": {','.join(req_auth_services)}"
             )
@@ -228,7 +232,9 @@ async def __call__(self, *args: Any, **kwargs: Any) -> str:
         # create headers for auth services
         headers = {}
         for auth_service, token_getter in self.__auth_service_token_getters.items():
-            headers[f"{auth_service}_token"] = await resolve_value(token_getter)
+            headers[self.__get_auth_header(auth_service)] = await resolve_value(
+                token_getter
+            )
         for client_header_name, client_header_val in self.__client_headers.items():
             headers[client_header_name] = await resolve_value(client_header_val)
 
@@ -276,7 +282,8 @@ def add_auth_token_getters(
         # Validate duplicates with client headers
         request_header_names = self.__client_headers.keys()
         auth_token_names = [
-            auth_token_name + "_token" for auth_token_name in incoming_services
+            self.__get_auth_header(auth_token_name)
+            for auth_token_name in incoming_services
         ]
         duplicates = request_header_names & auth_token_names
         if duplicates:
@@ -292,32 +299,42 @@ def add_auth_token_getters(
         # create a read-only updated for params that are still required
         new_req_authn_params = MappingProxyType(
             identify_required_authn_params(
-                self.__required_authn_params, auth_token_getters.keys()
-            )
+                # TODO: Add authRequired
+                self.__required_authn_params,
+                [],
+                auth_token_getters.keys(),
+            )[0]
         )
 
         return self.__copy(
             auth_service_token_getters=new_getters,
             required_authn_params=new_req_authn_params,
         )
 
-    def bind_parameters(
+    def bind_params(
         self, bound_params: Mapping[str, Union[Callable[[], Any], Any]]
     ) -> "ToolboxTool":
         """
         Binds parameters to values or callables that produce values.
 
-         Args:
-             bound_params: A mapping of parameter names to values or callables that
-                 produce values.
+        Args:
+            bound_params: A mapping of parameter names to values or callables that
+                produce values.
 
-         Returns:
-             A new ToolboxTool instance with the specified parameters bound.
+        Returns:
+            A new ToolboxTool instance with the specified parameters bound.
         """
         param_names = set(p.name for p in self.__params)
         for name in bound_params.keys():
+            if name in self.__bound_parameters:
+                raise ValueError(
+                    f"cannot re-bind parameter: parameter '{name}' is already bound"
+                )
+
             if name not in param_names:
-                raise Exception(f"unable to bind parameters: no parameter named {name}")
+                raise ValueError(
+                    f"unable to bind parameters: no parameter named {name}"
+                )
 
         new_params = []
         for p in self.__params:
@@ -330,3 +347,21 @@ def bind_parameters(
             params=new_params,
             bound_params=MappingProxyType(all_bound_params),
         )
+
+    def bind_param(
+        self,
+        param_name: str,
+        param_value: Union[Callable[[], Any], Any],
+    ) -> "ToolboxTool":
+        """
+        Binds a parameter to the value or callables that produce it.
+
+        Args:
+            param_name: The name of the bound parameter.
+            param_value: The value of the bound parameter, or a callable that
+                returns the value.
+
+        Returns:
+            A new ToolboxTool instance with the specified parameters bound.
+        """
+        return self.bind_params({param_name: param_value})