feat: add basic toolbox-core implementation

Author: kurtisvg

.gitignore

@@ -3,3 +3,11 @@
 
 # vscode
 .vscode/
+
+# python
+env
+venv
+*.pyc
+.python-version
+**.egg-info/
+

packages/toolbox-core/pyproject.toml

@@ -9,9 +9,10 @@ authors = [
     {name = "Google LLC", email = "[email protected]"}
 ]
 
-# TODO: Add deps
-#dependencies = [
-#]
+dependencies = [
+    "pydantic>=2.7.0,<3.0.0",
+    "aiohttp>=3.8.6,<4.0.0",
+]
 
 classifiers = [
     "Intended Audience :: Developers",
@@ -43,6 +44,7 @@ test = [
     "isort==6.0.1",
     "mypy==1.15.0",
     "pytest==8.3.5",
+    "aioresponses==0.7.8"
 ]
 [build-system]
 requires = ["setuptools"]

packages/toolbox-core/requirements.txt

@@ -0,0 +1,2 @@
+aiohttp==3.11.14
+pydantic==2.10.6

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

@@ -12,6 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .client import DummyClass
+from .client import ToolboxClient
 
-__all__ = ["DummyClass"]
+__all__ = ["ToolboxClient"]

packages/toolbox-core/src/toolbox_core/__pycache__/__init__.cpython-313.pyc

@@ -4,15 +4,153 @@
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#      http://www.apache.org/licenses/LICENSE-2.0
+#     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from typing import Optional
 
-class DummyClass:
-    def __init__(self):
-        self.val = "dummy value"
+from aiohttp import ClientSession
+
+from .protocol import ManifestSchema, ToolSchema
+from .tool import ToolboxTool
+
+
+class ToolboxClient:
+    """
+    An asynchronous client for interacting with a Toolbox service.
+
+    Provides methods to discover and load tools defined by a remote Toolbox
+    service endpoint. It manages an underlying `aiohttp.ClientSession`.
+    """
+
+    __base_url: str
+    __session: ClientSession
+
+    def __init__(
+        self,
+        url: str,
+        session: Optional[ClientSession] = None,
+    ):
+        """
+        Initializes the ToolboxClient.
+
+        Args:
+            url: The base URL for the Toolbox service API (e.g., "http://localhost:8000").
+            session: An optional existing `aiohttp.ClientSession` to use.
+                If None (default), a new session is created internally. Note that
+                if a session is provided, its lifecycle (including closing)
+                should typically be managed externally.
+        """
+        self.__base_url = url
+
+        # If no aiohttp.ClientSession is provided, make our own
+        if session is None:
+            session = ClientSession()
+        self.__session = session
+
+    def __parse_tool(self, name: str, schema: ToolSchema) -> ToolboxTool:
+        """Internal helper to create a callable tool from its schema."""
+        tool = ToolboxTool(
+            session=self.__session,
+            base_url=self.__base_url,
+            name=name,
+            desc=schema.description,
+            params=[p.to_param() for p in schema.parameters],
+        )
+        return tool
+
+    async def __aenter__(self):
+        """
+        Enter the runtime context related to this client instance.
+
+        Allows the client to be used as an asynchronous context manager
+        (e.g., `async with ToolboxClient(...) as client:`).
+
+        Returns:
+            self: The client instance itself.
+        """
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """
+        Exit the runtime context and close the internally managed session.
+
+        Allows the client to be used as an asynchronous context manager
+        (e.g., `async with ToolboxClient(...) as client:`).
+        """
+        await self.close()
+
+    async def close(self):
+        """
+        Asynchronously closes the underlying client session. Doing so will cause
+        any tools created by this Client to cease to function.
+
+        If the session was provided externally during initialization, the caller
+        is responsible for its lifecycle, but calling close here will still
+        attempt to close it.
+        """
+        await self.__session.close()
+
+    async def load_tool(
+        self,
+        name: str,
+    ) -> ToolboxTool:
+        """
+        Asynchronously loads a tool from the server.
+
+        Retrieves the schema for the specified tool from the Toolbox server and
+        returns a callable object (`ToolboxTool`) that can be used to invoke the
+        tool remotely.
+
+        Args:
+            name: The unique name or identifier of the tool to load.
+
+        Returns:
+            ToolboxTool: A callable object representing the loaded tool, ready
+                for execution. The specific arguments and behavior of the callable
+                depend on the tool itself.
+
+        """
+
+        # request the definition of the tool from the server
+        url = f"{self.__base_url}/api/tool/{name}"
+        async with self.__session.get(url) as response:
+            json = await response.json()
+        manifest: ManifestSchema = ManifestSchema(**json)
+
+        # 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(name, manifest.tools[name])
+
+        return tool
+
+    async def load_toolset(
+        self,
+        name: str,
+    ) -> list[ToolboxTool]:
+        """
+        Asynchronously fetches a toolset and loads all tools defined within it.
+
+        Args:
+            name: Name of the toolset to load tools.
+
+        Returns:
+            list[ToolboxTool]: A list of callables, one for each tool defined
+            in the toolset.
+        """
+        # Request the definition of the tool from the server
+        url = f"{self.__base_url}/api/toolset/{name}"
+        async with self.__session.get(url) 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) for n, s in manifest.tools.items()]
+        return tools