Merge pull request #49 from valory-xyz/tool-management-enhancements

Add tool search, description, and schema query functionalities

Author: gauravlochab

README.md

@@ -48,10 +48,14 @@ Options:
   --help     Show this message and exit.
 
 Commands:
-  interact        Interact with a mech specifying a prompt and tool.
-  prompt-to-ipfs  Upload a prompt and tool to IPFS as metadata.
-  push-to-ipfs    Upload a file to IPFS.
-  to-png          Convert a stability AI API's diffusion model output...
+  interact         Interact with a mech specifying a prompt and tool.
+  prompt-to-ipfs   Upload a prompt and tool to IPFS as metadata.
+  push-to-ipfs     Upload a file to IPFS.
+  to-png           Convert a stability AI API's diffusion model output.
+  tools-for-agents List tools available for all agents or a specific agent.
+  tool-description Get the description of a specific tool.
+  tool_io_schema   Get the input/output schema of a specific tool.
+
  ```
 
 ### Set up the EOA and private key
@@ -152,6 +156,102 @@ Data arrived: https://gateway.autonolas.tech/ipfs/f01701220a462120d5bb03f406fa5e
 Data from agent: {'requestId': 100407405856633966395081711430940962809568685031934329025999216833965518452765, 'result': "In a world of chaos and strife,\nThere's beauty in the simplest of life.\nA gentle breeze whispers through the trees,\nAnd birds sing melodies with ease.\n\nThe sun sets in a fiery hue,\nPainting the sky in shades of blue.\nStars twinkle in the darkness above,\nGuiding us with their light and love.\n\nSo take a moment to pause and see,\nThe wonders of this world so free.\nEmbrace the joy that each day brings,\nAnd let your heart soar on gentle wings.", 'prompt': 'write a short poem', 'cost_dict': {}, 'metadata': {'model': None, 'tool': 'openai-gpt-3.5-turbo'}}
 ```
 
+
+### List tools available for agents
+
+To list the tools available for a specific agent or for all agents, use the `tools-for-agents` command. You can specify an agent ID to get tools for a specific agent, or omit it to list tools for all agents.
+
+```bash
+mechx tools-for-agents
+```
+```bash
+You will see an output like this:
++------------+---------------------------------------------+-----------------------------------------------+
+|   Agent ID | Tool Name                                   | UniqueIdentifier                             |
++============+=============================================+===============================================+
+|          3 | claude-prediction-offline                   | 3-claude-prediction-offline                   |
++------------+---------------------------------------------+-----------------------------------------------+
+|          3 | claude-prediction-online                    | 3-claude-prediction-online                    |
++------------+---------------------------------------------+-----------------------------------------------+
+|          3 | deepmind-optimization                       | 3-deepmind-optimization                       |
++------------+---------------------------------------------+-----------------------------------------------+
+|          3 | deepmind-optimization-strong                | 3-deepmind-optimization-strong                |
++------------+---------------------------------------------+-----------------------------------------------+
+```
+
+```bash
+mechx tools-for-agents --agent-id "agent_id"
+```
+Eaxmple usage 
+```bash
+mechx tools-for-agents --agent-id 6
+```
+```bash
+You will see an output like this:
++---------------------------------------------+-----------------------------------------------+
+| Tool Name                                   | Unique Identifier                             |
++=============================================+===============================================+
+| claude-prediction-offline                   | 6-claude-prediction-offline                   |
++---------------------------------------------+-----------------------------------------------+
+| claude-prediction-online                    | 6-claude-prediction-online                    |
++---------------------------------------------+-----------------------------------------------+
+| deepmind-optimization                       | 6-deepmind-optimization                       |
++---------------------------------------------+-----------------------------------------------+
+```
+
+### Get Tool Description
+
+To get the description of a specific tool, use the `tool-description` command. You need to specify the unique identifier of the tool.
+
+```bash
+mechx tool-description --unique-identifier <unique_identifier> --chain-config <chain_config>
+```
+Example usage:
+
+```bash
+mechx tool-description --unique-identifier "6-claude-prediction-offline" --chain-config gnosis
+```
+You will see an output like this:
+```bash
+Description for tool 6-claude-prediction-offline: Makes a prediction using Claude
+```
+
+
+### Get Tool Input/Output Schema
+
+To get the input/output schema of a specific tool, use the `tool_io_schema` command. You need to specify the unique identifier of the tool.
+
+```bash
+mechx tool-io-schema --unique-identifier <unique_identifier> --chain-config <chain_config>
+```
+
+Example usage:
+
+```bash
+mechx tool-io-schema --unique-identifier "6-prediction-offline" --chain-config gnosis
+```
+You will see an output like this:
+```bash
+Input Schema:
++-------------+----------------------------------+
+| Field       | Value                            |
++=============+==================================+
+| type        | text                             |
++-------------+----------------------------------+
+| description | The text to make a prediction on |
++-------------+----------------------------------+
+Output Schema:
++-----------+---------+-----------------------------------------------+
+| Field     | Type    | Description                                   |
++===========+=========+===============================================+
+| requestId | integer | Unique identifier for the request             |
++-----------+---------+-----------------------------------------------+
+| result    | string  | Result information in JSON format as a string |
++-----------+---------+-----------------------------------------------+
+| prompt    | string  | Prompt used for probability estimation.       |
++-----------+---------+-----------------------------------------------+
+```
+
 > **:pencil2: Note** <br />
 > **If you encounter an "Out of gas" error when executing the Mech Client, you will need to increase the gas limit, e.g.,**
 >
@@ -214,6 +314,45 @@ You can also use the Mech Client as a library on your Python project.
     print(result)
     ```
 
+You can also use the Mech Client to programmatically fetch tools for agents in your Python project, as well as retrieve descriptions and input/output schemas for specific tools given their unique identifier.
+
+1. Set up the private key as specified [above](#set-up-the-private-key). Store the resulting key file (e.g., `ethereum_private_key.txt`) in a convenient and secure location.
+
+2. Create a Python script `fetch_tools_script.py`:
+
+    ```bash
+    touch fetch_tools_script.py
+    ```
+
+3. Edit `fetch_tools_script.py` as follows:
+
+    ```python
+    from mech_client.mech_tool_management import get_tools_for_agents, get_tool_description, get_tool_io_schema
+
+    # Fetching tools for a specific agent or all agents
+    agent_id = 6  # Specify the agent ID or set to None to fetch tools for all agents
+    chain_config = "gnosis"  # Specify the chain configuration
+    tools = get_tools_for_agents(agent_id=agent_id, chain_config=chain_config)
+    print(f"Tools for agent {agent_id}:", tools)
+
+    # Assuming you know the tool name, construct the unique identifier
+    tool_name = "claude-prediction-offline"  # Example tool name
+    unique_identifier = f"{agent_id}-{tool_name}"  # Construct the unique identifier
+
+    # Fetching description and I/O schema for a specific tool using the unique identifier
+    description = get_tool_description(unique_identifier, chain_config)
+    print(f"Description for {unique_identifier}:", description)
+
+    io_schema = get_tool_io_schema(unique_identifier, chain_config)
+    print(f"Input/Output Schema for {unique_identifier}:", io_schema)
+    ```
+
+This script will:
+- Fetch and print the tools available for a specified agent or for all agents if `agent_id` is set to `None`.
+- Construct the unique identifier for a tool using the format `agentId-toolName`.
+- Retrieve and display the description of a specific tool using its unique identifier.
+- Retrieve and display the input and output schema of a specific tool using its unique identifier.
+
 ## Developer installation
 
 To setup the development environment for this project, clone the repository and run the following commands:

mech_client/cli.py

@@ -18,14 +18,20 @@
 # ------------------------------------------------------------------------------
 
 """Mech client CLI module."""
-
-from typing import Any, Dict, List, Optional
+import json
+from typing import Any, Dict, List, Optional, Tuple
 
 import click
+from tabulate import tabulate  # type: ignore
 
 from mech_client import __version__
 from mech_client.interact import ConfirmationType
 from mech_client.interact import interact as interact_
+from mech_client.mech_tool_management import (
+    get_tool_description,
+    get_tool_io_schema,
+    get_tools_for_agents,
+)
 from mech_client.prompt_to_ipfs import main as prompt_to_ipfs_main
 from mech_client.push_to_ipfs import main as push_to_ipfs_main
 from mech_client.to_png import main as to_png_main
@@ -148,10 +154,97 @@ def to_png(ipfs_hash: str, path: str, request_id: str) -> None:
     to_png_main(ipfs_hash, path, request_id)
 
 
+@click.command(name="tools-for-agents")
+@click.option(
+    "--agent-id",
+    type=int,
+    help="Agent ID to fetch tools for. If not provided, fetches for all agents.",
+)
+@click.option("--chain-config", default="gnosis", help="Chain configuration to use.")
+def tools_for_agents(agent_id: Optional[int], chain_config: str) -> None:
+    """Fetch and display tools for agents."""
+    try:
+        result = get_tools_for_agents(agent_id, chain_config)
+
+        if agent_id is not None:
+            headers = ["Tool Name", "Unique Identifier"]
+            data: List[Tuple[str, ...]] = [
+                (str(tool["tool_name"]), str(tool["unique_identifier"]))
+                for tool in result["tools"]
+            ]
+        else:
+            headers = ["Agent ID", "Tool Name", "Unique Identifier"]
+            data = [
+                (str(agent_id), str(tool_name), f"{agent_id}-{tool_name}")
+                for agent_id, tools in result["agent_tools_map"].items()
+                for tool_name in tools
+            ]
+
+        click.echo(tabulate(data, headers=headers, tablefmt="grid"))
+    except (KeyError, TypeError) as e:
+        click.echo(f"Error processing tool data: {str(e)}")
+    except json.JSONDecodeError as e:
+        click.echo(f"Error decoding JSON response: {str(e)}")
+    except IOError as e:
+        click.echo(f"Network or I/O error: {str(e)}")
+
+
+@click.command(name="tool-description")
+@click.argument("tool_id")
+@click.option("--chain-config", default="gnosis", help="Chain configuration to use.")
+def tool_description(tool_id: str, chain_config: str) -> None:
+    """Fetch and display the description of a specific tool."""
+    try:
+        description = get_tool_description(tool_id, chain_config)
+        click.echo(f"Description for tool {tool_id}: {description}")
+    except KeyError as e:
+        click.echo(f"Tool not found or missing description: {str(e)}")
+    except json.JSONDecodeError as e:
+        click.echo(f"Error decoding JSON response: {str(e)}")
+    except IOError as e:
+        click.echo(f"Network or I/O error: {str(e)}")
+
+
+@click.command(name="tool-io-schema")
+@click.argument("tool_id")
+@click.option("--chain-config", default="gnosis", help="Chain configuration to use.")
+def tool_io_schema(tool_id: str, chain_config: str) -> None:
+    """Fetch and display the input/output schema for a specific tool."""
+    try:
+        io_schema = get_tool_io_schema(tool_id, chain_config)
+        # Prepare data for tabulation
+        input_schema = [(key, io_schema["input"][key]) for key in io_schema["input"]]
+
+        # Handling nested output schema
+        output_schema = []
+        if "properties" in io_schema["output"]["schema"]:
+            for key, value in io_schema["output"]["schema"]["properties"].items():
+                output_schema.append((key, value["type"], value.get("description", "")))
+
+        # Display schemas in tabulated format
+        click.echo("Input Schema:")
+        click.echo(tabulate(input_schema, headers=["Field", "Value"], tablefmt="grid"))
+        click.echo("Output Schema:")
+        click.echo(
+            tabulate(
+                output_schema, headers=["Field", "Type", "Description"], tablefmt="grid"
+            )
+        )
+    except KeyError as e:
+        click.echo(f"Error accessing schema data: {str(e)}")
+    except json.JSONDecodeError as e:
+        click.echo(f"Error decoding JSON response: {str(e)}")
+    except IOError as e:
+        click.echo(f"Network or I/O error: {str(e)}")
+
+
 cli.add_command(interact)
 cli.add_command(prompt_to_ipfs)
 cli.add_command(push_to_ipfs)
 cli.add_command(to_png)
+cli.add_command(tools_for_agents)
+cli.add_command(tool_io_schema)
+cli.add_command(tool_description)
 
 
 if __name__ == "__main__":

mech_client/interact.py

@@ -35,7 +35,7 @@
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import requests
 import websocket
@@ -160,18 +160,10 @@ def get_mech_config(chain_config: Optional[str] = None) -> MechConfig:
         if chain_config is None:
             chain_config = next(iter(data))
 
-        print("Chain configuration:")
         entry = data[chain_config].copy()
         ledger_config = LedgerConfig(**entry.pop("ledger_config"))
         mech_config = MechConfig(**entry, ledger_config=ledger_config)
 
-        print(f"  - Chain ID: {chain_config}")
-        print(f"  - Gas limit: {mech_config.gas_limit}")
-        print(f"  - Contract ABI URL: {mech_config.contract_abi_url}")
-        print(f"  - Transation URL: {mech_config.transaction_url}")
-        print(f"  - Subgraph URL: {mech_config.subgraph_url}")
-        print("")
-
         return mech_config
 
 
@@ -303,12 +295,16 @@ def verify_or_retrieve_tool(
     :return: The result of the verification or retrieval.
     :rtype: str
     """
-    available_tools = fetch_tools(
+    # Fetch tools, possibly including metadata
+    tools_data = fetch_tools(
         agent_id=agent_id,
         ledger_api=ledger_api,
         agent_registry_contract=agent_registry_contract,
         contract_abi_url=contract_abi_url,
+        include_metadata=False,  # Ensure this is False to only get the list of tools
     )
+    # Ensure only the list of tools is used
+    available_tools = tools_data if isinstance(tools_data, list) else tools_data[0]
     if tool is not None and tool not in available_tools:
         raise ValueError(
             f"Provided tool `{tool}` not in the list of available tools; Available tools={available_tools}"
@@ -323,16 +319,22 @@ def fetch_tools(
     ledger_api: EthereumApi,
     agent_registry_contract: str,
     contract_abi_url: str,
-) -> List[str]:
-    """Fetch tools for specified agent ID."""
+    include_metadata: bool = False,
+) -> Union[List[str], Tuple[List[str], Dict[str, Any]]]:
+    """Fetch tools for specified agent ID, optionally include metadata."""
     mech_registry = get_contract(
         contract_address=agent_registry_contract,
         abi=get_abi(agent_registry_contract, contract_abi_url),
         ledger_api=ledger_api,
     )
     token_uri = mech_registry.functions.tokenURI(agent_id).call()
     response = requests.get(token_uri).json()
-    return response["tools"]
+    tools = response.get("tools", [])
+
+    if include_metadata:
+        tool_metadata = response.get("toolMetadata", {})
+        return tools, tool_metadata
+    return tools
 
 
 def send_request(  # pylint: disable=too-many-arguments,too-many-locals