Metadata-Version: 2.1
Name: mech-server
Version: 0.6.0
Summary: 
Home-page: https://github.com/valory-xyz/mech-server
Keywords: mech,tool,developer,autonomy,autonomous,autonolas,olas,service,multi,agent
Author: David Minarsch
Author-email: david.minarsch@googlemail.com
Requires-Python: >=3.10,<3.12
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Topic :: System
Requires-Dist: PyYAML (==6.0.1)
Requires-Dist: aiohttp (>=3.8.5,<4.0.0)
Requires-Dist: asn1crypto (>=1.4.0,<1.5.0)
Requires-Dist: attrs
Requires-Dist: certifi
Requires-Dist: click (==8.1.8)
Requires-Dist: ecdsa (>=0.15)
Requires-Dist: eth-abi (==5.2.0)
Requires-Dist: eth-utils (==5.3.0)
Requires-Dist: eth_typing
Requires-Dist: grpcio (==1.53.0)
Requires-Dist: hexbytes
Requires-Dist: hypothesis (==6.21.6)
Requires-Dist: ipfshttpclient (==0.8.0a2)
Requires-Dist: mech-client (==0.18.8)
Requires-Dist: mkdocs (>=1.6.1,<2.0.0)
Requires-Dist: multidict
Requires-Dist: olas-operate-middleware (>=0.14.16)
Requires-Dist: open-aea-cli-ipfs (==2.0.8)
Requires-Dist: open-aea-ledger-cosmos
Requires-Dist: open-aea-ledger-ethereum (==2.0.8)
Requires-Dist: open-aea-test-autonomy (==0.21.11)
Requires-Dist: open-autonomy (==0.21.11)
Requires-Dist: openai (==1.30.2)
Requires-Dist: openapi-core (==0.15.0)
Requires-Dist: openapi-spec-validator (>=0.4.0,<0.5.0)
Requires-Dist: packaging
Requires-Dist: pebble (==5.1.3)
Requires-Dist: prometheus_client (==0.23.1)
Requires-Dist: protobuf (>=4.21.6,<4.25.0)
Requires-Dist: py-ecc (==8.0.0)
Requires-Dist: py-multibase (==1.0.3)
Requires-Dist: py-multicodec (==0.2.1)
Requires-Dist: pycryptodome (==3.20.0)
Requires-Dist: pytest (==7.4.4)
Requires-Dist: pytest-asyncio
Requires-Dist: pytz (==2022.2.1)
Requires-Dist: requests (==2.28.2)
Requires-Dist: safe-eth-py (>=7.18.0,<8.0.0)
Requires-Dist: toml (==0.10.2)
Requires-Dist: typing_extensions (>=3.10.0.2,<=4.13.2)
Requires-Dist: web3 (>=7.0.0,<8)
Requires-Dist: websocket_client (>=0.32.0,<1)
Requires-Dist: werkzeug
Project-URL: Repository, https://github.com/valory-xyz/mech-server
Description-Content-Type: text/markdown

<h1 align="center">
    <b>Mech Server</b>
</h1>

<p align="center">
  <a href="https://pypi.org/project/mech-server/">
    <img alt="PyPI" src="https://img.shields.io/pypi/v/mech-server">
  </a>
  <a href="https://pypi.org/project/mech-server/">
    <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/mech-server">
  </a>
  <a href="https://pypi.org/project/mech-server/">
    <img alt="PyPI - Wheel" src="https://img.shields.io/pypi/wheel/mech-server">
  </a>
  <a href="https://github.com/valory-xyz/mech-server/blob/main/LICENSE">
    <img alt="License" src="https://img.shields.io/pypi/l/mech-server">
  </a>
  <a href="https://pypi.org/project/mech-server/">
    <img alt="Downloads" src="https://img.shields.io/pypi/dm/mech-server">
  </a>
</p>
<p align="center">
  <a href="https://github.com/valory-xyz/mech-server/actions/workflows/common_checks.yaml">
    <img alt="Sanity checks and tests" src="https://github.com/valory-xyz/mech-server/actions/workflows/common_checks.yaml/badge.svg?branch=main">
  </a>
  <a href="https://codecov.io/gh/valory-xyz/mech-server">
    <img alt="Coverage" src="https://img.shields.io/codecov/c/github/valory-xyz/mech-server">
  </a>
  <a href="https://flake8.pycqa.org">
    <img alt="flake8" src="https://img.shields.io/badge/lint-flake8-yellow">
  </a>
  <a href="https://github.com/python/mypy">
    <img alt="mypy" src="https://img.shields.io/badge/static%20check-mypy-blue">
  </a>
  <a href="https://github.com/psf/black">
    <img alt="Black" src="https://img.shields.io/badge/code%20style-black-black">
  </a>
  <a href="https://github.com/PyCQA/bandit">
    <img alt="bandit" src="https://img.shields.io/badge/security-bandit-lightgrey">
  </a>
</p>

A CLI to create, deploy and manage Mechs — AI agents that execute tasks on-chain for payment — on the [Olas Marketplace](https://olas.network/mech-marketplace).

> **Note:** The codebase uses the term *service* (from the underlying Open Autonomy framework) interchangeably with *AI agent*.

## Quick Start

```bash
poetry add mech-server
poetry run mech setup -c <chain>
poetry run mech run -c <chain>
```

## Supported Chains

| Chain | Native | OLAS Token | USDC Token | Nevermined |
|-------|--------|------------|------------|------------|
| Gnosis | ✅ | ✅ | ❌ | ✅ |
| Base | ✅ | ✅ | ❌ | ✅ |
| Polygon | ✅ | ✅ | ✅ | ✅ |
| Optimism | ✅ | ✅ | ❌ | ✅ |

## Requirements

- [Python](https://www.python.org/) `>=3.10, <3.12`
- [Poetry](https://python-poetry.org/docs/)
- [Docker Engine](https://docs.docker.com/engine/install/) + [Docker Compose](https://docs.docker.com/compose/install/)

## Commands

| Command | Description |
|---|---|
| `poetry run mech setup -c <chain>` | Full first-time setup: workspace, agent build, mech deployment, env config, key setup |
| `poetry run mech add-tool <author> <name>` | Scaffold a new mech tool |
| `poetry run mech prepare-metadata` | Recompute package fingerprints, push packages and metadata to IPFS, and write `METADATA_HASH` and `TOOLS_TO_PACKAGE_HASH` to `.env` |
| `poetry run mech update-metadata` | Update the metadata hash on-chain via Safe transaction |
| `poetry run mech run -c <chain>` | Run the mech AI agent via Docker |
| `poetry run mech stop -c <chain>` | Stop a running mech AI agent |

## Developing a new tool

### New service (no existing mech)

1. Set up the workspace and deploy the mech on-chain:
    ```bash
    poetry run mech setup -c <chain>
    ```

2. Scaffold a tool:
    ```bash
    poetry run mech add-tool <author> <tool_name> -d "Tool description"
    ```

3. Implement the tool logic in `~/.operate-mech/packages/<author>/customs/<tool_name>/<tool_name>.py`. The scaffold generates a working stub with the correct structure:
    ```python
    ALLOWED_TOOLS = ["tool_name"]

    def run(**kwargs: Any) -> MechResponse:
        prompt = kwargs.get("prompt")
        if prompt is None:
            return error_response("No prompt has been given.")
        result = do_work(prompt)
        context = None
        artifact = None
        callback = None
        return result, prompt, context, artifact, callback
    ```

4. If your tool requires API keys or other secrets, add them to `~/.operate-mech/.env`.

5. Generate and publish metadata (to IPFS), then update the on-chain registry:
    ```bash
    poetry run mech prepare-metadata
    poetry run mech update-metadata
    ```

6. Run:
    ```bash
    poetry run mech run -c <chain>
    ```

### Existing service (mech already running)

1. Stop the service:
    ```bash
    poetry run mech stop -c <chain>
    ```

2. Scaffold, implement, and set any required API keys (same as steps 2–4 above).

3. Generate and publish metadata (to IPFS), then update:
    ```bash
    poetry run mech prepare-metadata
    poetry run mech update-metadata
    ```

4. Restart:
    ```bash
    poetry run mech run -c <chain>
    ```

## Documentation

Find the full tutorial (tool development, publishing, sending requests) at [stack.olas.network](https://stack.olas.network).

