Metadata-Version: 2.4
Name: micromech
Version: 0.0.29
Summary: Lightweight OLAS mech runtime
Project-URL: Repository, https://github.com/dvilelaf/micromech
Author-email: David Vilela <david.vilela@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: <4.0,>=3.12
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: ddgs>=9.12.1
Requires-Dist: iwa>=0.7.8
Requires-Dist: loguru>=0.7.0
Requires-Dist: peewee>=3.17.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: chain
Requires-Dist: iwa>=0.7.8; extra == 'chain'
Provides-Extra: cli
Requires-Dist: typer>=0.9.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-forked>=1.6.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: genai
Requires-Dist: google-genai>=1.0.0; extra == 'genai'
Provides-Extra: llm
Requires-Dist: huggingface-hub>=0.19.0; extra == 'llm'
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'llm'
Provides-Extra: tasks
Requires-Dist: apscheduler<4,>=3.10; extra == 'tasks'
Requires-Dist: httpx>=0.27; extra == 'tasks'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Provides-Extra: web
Requires-Dist: fastapi>=0.115.0; extra == 'web'
Requires-Dist: jinja2>=3.1.0; extra == 'web'
Requires-Dist: uvicorn>=0.32.0; extra == 'web'
Description-Content-Type: text/markdown

# micromech

> [!CAUTION]
> micromech is open-source software provided **as is**, without warranty of any kind. Use it at your own risk. The developers are not responsible for any loss of funds, tokens, rewards, or damages arising from the use of this software. By using micromech you accept full responsibility for the security of your wallet and private keys.

**A lightweight mech for the [OLAS](https://olas.network/) network.** micromech runs an autonomous AI agent (called a "mech") that listens for on-chain requests, solves them using pluggable tools, and delivers results back on-chain.

No prior experience with OLAS or blockchain development is needed to get started.

<p align="center">
  <img width="30%" src="images/micromech.png">
</p>

## What You Need

- **A computer** that can stay on (or a cheap cloud server). 2 GB RAM minimum.
- **Docker Desktop** — a free app that runs micromech in an isolated container.
  - [Download for Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
  - [Download for Mac](https://docs.docker.com/desktop/setup/install/mac-install/)
  - [Download for Linux](https://docs.docker.com/desktop/setup/install/linux-install/)
- **An internet connection.**

After installing Docker Desktop, **open it once** and make sure it's running (you'll see a whale icon in your system tray or menu bar).

## Install & Run

### Mac / Linux

Open Terminal and run from the directory where you want micromech installed (your home directory is a good default):

```bash
cd ~ && bash <(curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh)
```

This creates a `micromech/` folder in the current directory. If you want to install in a system directory like `/opt`, use `sudo` with a pipe instead (process substitution doesn't work with sudo):

```bash
cd /opt && curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh | sudo bash
```

### Windows

Open a WSL terminal (search "WSL" in the Start menu) and run:

```bash
cd ~ && bash <(curl -sSL https://raw.githubusercontent.com/dvilelaf/micromech/main/scripts/quickstart.sh)
```

> If WSL is not installed, open PowerShell as Administrator and run `wsl --install`, then restart your computer. Docker Desktop must be set to use the WSL 2 backend (this is the default).

### Access the Dashboard

Open **http://localhost:8090** in your browser. The setup wizard will guide you through creating your wallet, choosing a chain, and deploying your mech.

> **Running on a remote server?** Forward the dashboard to your local machine with an SSH tunnel:
> ```bash
> ssh -L 8090:localhost:8090 user@your-server
> ```
> Then open `http://localhost:8090` in your local browser.

> [!WARNING]
> **Back up your wallet as soon as the setup wizard is complete.** Copy `data/wallet.json` to a safe location (e.g. an external drive or cloud storage) before adding any funds. If you lose this file and have no backup, access to your funds is permanently lost and cannot be recovered.

## Day-to-Day Commands

Run these from inside the `micromech/` folder. If you have [`just`](https://github.com/casey/just) installed, the shortcuts make things easier — otherwise use the `docker compose` equivalents.

| What you want to do | `just` shortcut | docker compose equivalent |
|---|---|---|
| Start micromech | `just up` | `docker compose up -d` |
| Stop micromech | `just down` | `docker compose down` |
| View live logs | `just logs` | `docker compose logs -f` |
| Update to latest image | `just update` | `docker compose pull && docker compose up -d` |
| Update `Justfile` + `docker-compose.yml` | `just update-config` | *(no equivalent)* |
| Check container status | `just status` | `docker compose ps` |
| Re-run setup wizard | `just init` | *(no equivalent)* |
| Run health check | `just doctor` | *(no equivalent)* |

micromech restarts automatically if your computer reboots.

## Remote Control via Telegram (Optional)

Control your mech from your phone. Configure it from the dashboard, then use these commands:

| Command | What it does |
|---|---|
| `/status` | Mech status, deliveries, and rewards |
| `/wallet` | Wallet address and balances per chain |
| `/queue` | Pending, executing, and failed requests |
| `/info` | Version and runtime information |
| `/logs` | Download last 24h logs as a zip file |
| `/manage` | Stake, unstake, or restake per chain |
| `/checkpoint` | Call staking checkpoint manually |
| `/claim` | Claim staking rewards |
| `/settings` | Toggle features (e.g. auto-checkpoint) |
| `/update` | Pull latest image and restart |
| `/restart` | Restart the mech runtime |

## Your Files

After the quickstart, your `micromech/` folder contains:

| File | What it is | Notes |
|---|---|---|
| `secrets.env` | Passwords, API keys, Telegram token, custom RPC endpoints | **Never share.** This is the main file you'll edit. |
| `docker-compose.yml` | Docker configuration | Leave it alone unless you need to change ports. |
| `data/` | All persistent data (wallet, database, config, AI models) | **Back this up regularly.** |
| `data/config.yaml` | Mech settings: chains, mech addresses, staking contracts | You can edit it, but the web dashboard is easier. |
| `data/wallet.json` | Your encrypted wallet (private key + recovery phrase) | **Never share. Back this up.** |
| `data/micromech.db` | SQLite database of all requests — pending, delivered, failed | Grows over time. Safe to delete if disk space is tight (history only, no funds). |
| `data/backup/` | Automatic wallet backups created before any key change | Keep these. Delete old ones manually if needed. |
| `data/.hf_cache/` | Cached AI model files (downloaded on first use) | Large (~300 MB). Safe to delete — re-downloads automatically. |
| `updater.sh` | Auto-update script (called by the container on startup) | Don't touch. |
| `Justfile` | Command shortcuts (requires `just`) | Optional convenience, safe to ignore. |

> **Backup reminder:** Copy the entire `data/` folder somewhere safe. If you lose `data/wallet.json`, you lose access to your wallet.

## Staking Rewards

Staking rewards are only paid if your mech receives **enough requests and delivers them successfully** within each staking epoch. Being online is not sufficient on its own — if no requests reach your mech, the staking contract will consider it inactive and withhold rewards for that epoch.

If you are not receiving enough requests, coordinate with traders or other agents to route demand to your mech address.

## For Developers

```bash
git clone https://github.com/dvilelaf/micromech
cd micromech && uv sync --all-extras
just check       # lint + types
just security    # gitleaks + bandit
just test        # pytest
```

## License

Apache-2.0