Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc/celo updates #34

Merged
merged 8 commits into from
Apr 3, 2024
Merged

Doc/celo updates #34

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9ca1461
add flow for calling the mech-client on celo, improve flwo from setti…
GigaHierz Mar 25, 2024
2a3f49f
add getting the address to get funding, add info about the key file flag
GigaHierz Mar 26, 2024
806d47a
Add overview
GigaHierz Mar 26, 2024
780671e
remove instructions to create a private key as it's needed for settin…
GigaHierz Mar 27, 2024
c0eefa1
Merge commit '780671e3b3a8cc0f1b12828a7eef84b793942535' into doc/celo…
jmoreira-valory Apr 2, 2024
1ba1792
doc: updated README
jmoreira-valory Apr 2, 2024
b1051b2
doc: rearrange warning
jmoreira-valory Apr 2, 2024
d26c140
doc: typo
jmoreira-valory Apr 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 176 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,38 @@
# mech-client
Basic client to interact with a mech
# Mech Client

> **Warning**<br />
> **This is a hacky alpha version of the client - don't rely on it as production software.**
A basic client to interact with an AI Mech. [AI Mechs](https://github.com/valory-xyz/mech) allow users to post requests for AI tasks on-chain, and get their result delivered.

> **:warning: Warning** <br />
> **This is a *hacky* alpha version of the client. Don't rely on it as production software.**

## Installation

Find the latest available release on [PyPi](https://pypi.org/project/mech-client/#description).

We recommend that you create a virtual Python environment using [Poetry](https://python-poetry.org/). Set up your virtual environment as follows:

```bash
pip install mech-client
poetry new my_project
cd my_project
poetry shell
poetry add mech-client
```

Note: If you encounter an "Out of gas" error when executing the tool, you will need to increase the gas limit by setting, e.g.,
Alternatively, you can also install the Mech Client in your local Python installation:

```bash
export MECHX_GAS_LIMIT=200000
pip install mech-client
```

## CLI:
If you require to use the Mech Client programmatically, please see [this section](#programmatic-usage) below.

## CLI Usage

Display the available options:

```bash
mechx --help
```

```bash
Usage: mechx [OPTIONS] COMMAND [ARGS]...
Expand All @@ -31,84 +47,107 @@ 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...
```

## CLI Usage:
### Set up the EOA and private key

First, create a private key in file `ethereum_private_key.txt` with this command:
To use the Mech Client you need an EOA account and its associated private key stored in a text file `ethereum_private_key.txt`. You can set it up in two ways:

```bash
aea generate-key ethereum
```
Ensure the private key carries funds on Gnosis Chain.
- Use the Open AEA command `generate-key`:

A keyfile is just a file with your ethereum private key as a hex-string, example:
```
0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcd
```
In case you add your own, make sure you don't have any extra characters in the file, like newlines or spaces.
```bash
aea generate-key ethereum
```

and display the corresponding EOA:

```bash
python -c "from web3 import Web3; print(Web3().eth.account.from_key(open('ethereum_private_key.txt').read()).address)"
```

Second, run the following command to instruct the mech with `<prompt>` and `<agent_id>`:
- Alternatively, use any software of your choice (e.g., [Metamask](https://metamask.io/)) and copy the private key:

```bash
echo -n YOUR_PRIVATE_KEY > ethereum_private_key.txt
```

Do not include any leading or trailing spaces, tabs or newlines, or any other character in the file `ethereum_private_key.txt`.

The EOA you use must have enough funds to pay for the Mech requests, or alternatively, use a Nevermined subscription.

> **:warning: Warning** <br />
> **If the generated EOA account is for development purposes, make sure it does not contain large amounts of funds.**

### Generate Mech requests

The basic usage of the Mech Client is as follows:

```bash
mechx interact <prompt> <agent_id>
```

The command will prompt you with all available tools for the agent and you can select which tool you want to use
where agent with `<agent_id>` will process `<prompt>` with the default options. Each chain has its own set of Mech agents. You can find the agent IDs for each chain on the [Mech Hub](https://aimechs.autonolas.network/registry) or on the [Mech repository](https://github.com/valory-xyz/mech?tab=readme-ov-file#examples-of-deployed-mechs).

```
Select prompting tool
|--------------------------------------------------|
| ID | Tool |
|--------------------------------------------------|
| 0 | openai-text-davinci-002 |
| ...| ... |
|--------------------------------------------------|
Tool ID >
```
Some useful options:

If you are aware about the tools that are provided by an agent you can directly provide tool as a command line argument
- `--key <private_key_path>`: Specifies the path of the private key. The default value is `./ethereum_private_key.txt`.
- `--tool <name>`: Name of the tool to process the prompt. If you are aware about the tools that are provided by an agent you can directly provide its name using this option. If not provided, it will show a list of available tools for the agent so that you can select which one you want to use:

```bash
mechx interact <prompt> <agent_id> --tool <tool>
```
```text
Select prompting tool
|--------------------------------------------------|
| ID | Tool |
|--------------------------------------------------|
| 0 | openai-text-davinci-002 |
| ...| ... |
|--------------------------------------------------|
Tool ID >
```

If you already have a funded key file on locally you can provide path the key using `--key` flag.
- `--chain-config <name>`: Use default chain configuration parameters (RPC, WSS, ...). [See below](#chain-configuration) for more details. Available values are
- `arbitrum`
- `base`
- `celo`
- `gnosis` (Default)
- `optimism`
- `polygon`

```bash
mechx interact <prompt> <agent_id> --key <key_file>
```
- `--confirm <type>`: Specify how to wait for the result of your request:
- `off-chain`: Wait for the result using the ACN.
- `on-chain`: Wait for the result using the Subgraph and the Websocket subscription (whichever arrives first).
- `wait-for-both` (Default): Wait for the result using both `off-chain` and `on-chain` (whichever arrives first).

### Example

Example of a request specifying a key file and tool:

Example output:
```bash
mechx interact "write a short poem" 3 --key ~/gnosis_key --tool openai-text-davinci-003
Chain configuration: gnosis
Prompt uploaded: https://gateway.autonolas.tech/ipfs/f01701220ad773628911d12e28f005e3f249e990d684e5dba07542259195602f9afed30bf
Transaction sent: https://gnosisscan.io/tx/0x0d9209e32e965a820b9e80accfcd71ea3b1174b9758dd251c2e627a60ec426a5
Created on-chain request with ID 111240237160304797537720810617416341148235899500021985333360197012735240803849
Data arrived: https://gateway.autonolas.tech/ipfs/bafybeifk2h35ncszlze7t64rpblfo45rezc33xzbya3cjiyumtaioyat3e
Data from agent: {'requestId': 111240237160304797537720810617416341148235899500021985333360197012735240803849, 'result': "\n\nI am brave and I'm strong\nI don't hide away my song\nI am here and I'm proud\nMy voice will be heard loud!"}
mechx interact "write a short poem" 6 --key ~/ethereum_private_key.txt --tool openai-text-davinci-003 --chain-config gnosis --confirm on-chain
```

By default the client will wait for data to arrive from on-chain using the websocket subscription and subgraph, and off-chain using the ACN and show you the result which arrives first. You can specify the type of confirmation you want using `--confirm` flag like this
In your terminal you will see this as an output:

```bash
mechx interact "write a short poem" 3 --key ~/gnosis_key --tool openai-text-davinci-003 --confirm on-chain
Chain configuration: gnosis
Prompt uploaded: https://gateway.autonolas.tech/ipfs/f017012205e37f761221a8ba4005e91c36b94153e9432b8888ff2acae6b101dd5a5de6768
Transaction sent: https://gnosisscan.io/tx/0xf1ef63f617717bbb8deb09699af99aa39f10155d33796de2fd7eb61c9c1458b6
Waiting for transaction receipt...
Created on-chain request with ID 81653153529124597849081567361606842861262371002932574194580478443414142139857
Data arrived: https://gateway.autonolas.tech/ipfs/f0170122069b55e077430a00f3cbc3b069347e901396f978ff160eb2b0a947872be1848b7
Data from agent: {'requestId': 81653153529124597849081567361606842861262371002932574194580478443414142139857, 'result': "\n\nA summer breeze, so sweet,\nA gentle reminder of summer's heat.\nThe sky so blue, no cloud in sight,\nA perfect day, a wondrous sight."}
```

### Chain configuration
> **: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.,**
>
> ```bash
> export MECHX_GAS_LIMIT=200000
> ```

Configurations for different chains are stored in the file `configs/mechs.json`. By default, `mech interact` will choose the first configuration on the JSON. You can specify which config you want to use using the `--chain-config` flag, for example,
### Chain configuration

```bash
mechx interact <prompt> <agent_id> --chain-config gnosis
```
Default configurations for different chains are stored in the file [configs/mechs.json](./mech_client/configs/mechs.json). If `--chain-config` parameter is not specified, the Mech Client will choose the first configuration on the JSON.

Additionally, you can override any configuration parameter by exporting any of the following environment variables:

Expand All @@ -126,37 +165,99 @@ MECHX_LEDGER_DEFAULT_GAS_PRICE_STRATEGY
MECHX_LEDGER_IS_GAS_ESTIMATION_ENABLED
```

## Programmatic Usage:
## Programmatic usage

```python
from mech_client.interact import interact, ConfirmationType
You can also use the Mech Client as a library on your Python project.

prompt_text = 'Will gnosis pay reach 100k cards in 2024?'
agent_id = 3
tool_name = "prediction-online"
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.

result = interact(
prompt=prompt_text,
agent_id=agent_id,
tool=tool_name,
confirmation_type=ConfirmationType.ON_CHAIN,
private_key_path='PATH_HERE'
)
print(result)
```
> **:warning: Warning** <br />
> **If you store the key file in a local Git repository, we recommend that you add it to `.gitignore` in order to avoid publishing it unintentionally:**
>
> ```bash
> echo ethereum_private_key.txt >> .gitignore
> ```

2. Create Python script `my_script.py`:

```bash
touch my_script.py
```

3. Edit `my_script.py` as follows:

```python
from mech_client.interact import interact, ConfirmationType

# Developer installation
To setup the development environment, run the following commands:
prompt_text = 'Will Gnosis pay reach 100k cards in 2024?'
agent_id = 6
tool_name = "prediction-online"
chain_config = "gnosis"
private_key_path="ethereum_private_key.txt"

result = interact(
prompt=prompt_text,
agent_id=agent_id,
tool=tool_name,
chain_config=chain_config,
confirmation_type=ConfirmationType.ON_CHAIN,
private_key_path=private_key_path
)
print(result)
```

## Developer installation

To setup the development environment for this project, clone the repository and run the following commands:

```bash
poetry install && poetry shell
poetry install
poetry shell
```

## Release guide:
## Release guide

- Bump versions in `pyproject.toml`, `mech_client/__init__.py` and `SECURITY.md`
- Bump versions in `pyproject.toml`.`mech_client/__init__.py` and `SECURITY.md`
- `poetry lock`
- `rm -rf dist`
- `autonomy packages sync --update-packages`
- `make eject-packages`
- then create release PR and tag release
- Then, create a release PR and tag the release.

## FAQ

<details>

<summary><b>On which chains are AI Mechs deployed?</b></summary>

The [Mech repository](https://github.com/valory-xyz/mech?tab=readme-ov-file#examples-of-deployed-mechs) contains the latest information on deployed Mechs.

</details>

<details>

<summary><b>Are AI Mechs deployed on testnets?</b></summary>

No. AI Mechs are currently deployed on mainnets.

</details>

<details>

<summary><b>Where can I find the agent ID?</b></summary>

You can find the agent IDs for each chain on the [Mech Hub](https://aimechs.autonolas.network/registry) or on the [Mech repository](https://github.com/valory-xyz/mech?tab=readme-ov-file#examples-of-deployed-mechs).

</details>

<details>

<summary><b>How do I access an AI Mech on a different chains?</b></summary>

Use the `--chain-config <name>` parameter together with a valid `<agent_id>`, for example:

```bash
mechx interact "write a short poem" 2 --key ./ethereum_private_key.txt --tool openai-gpt-4 --chain-config celo --confirm on-chain
```

</details>
Loading