Trishool

<div align="center">
  
# **Trishool Subnet Phase 2**
  
[Discord](https://discord.com/channels/799672011265015819/1437447445176127618) • [Dashboard](https://trishool.ai/dashboard) • [Website](https://trishool.ai/) • [Twitter](https://x.com/trishoolai/) •
[Network](https://taostats.io/subnets/23/chart)
</div>

A Bittensor subnet building the SOTA AI guard model. Miners submit adversarial prompts that validators evaluate via agents (OpenClaw + Judge); scores are aggregated and written as on-chain weights.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  MINER                                                       │
│  - alignet.cli.miner upload (Bittensor wallet signature)    │
│  - submission_items: {"prompt": "... {{objective}} ..."} (TEMPLATE) or Q1–Qn (QUESTIONS)          │
└──────────────────────┬──────────────────────────────────────┘
                       │ POST /api/v1/miner/upload
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  PLATFORM                                                    │
│  - Validates format, surface_area, duplicate detection      │
│  - Validator APIs (signature + whitelist):                   │
│    GET  /validator/get-evaluation-data                       │
│    GET  /validator/check_scoring                             │
│    POST /validator/submit_scores/{submission_id}             │
│    GET  /validator/weights                                   │
│    POST /validator/healthcheck, /validator/upload_log        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  VALIDATOR (neurons/validator.py + alignet)                 │
│  - PlatformAPIClient: get_evaluation_inputs, check_scoring, │
│    submit_judge_output, get_weights, healthcheck, upload_log │
│  - Per question: check_scoring → tri-claw + judge → submit  │
│  - Weight update loop: fetch weights from platform → chain  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  AGENTS (HTTP, Docker)                                       │
│  - Tri-claw (OpenClaw):  :18789  — answers the miner prompt │
│  - Judge:                :8080   — scores safe/partial/jailbreak
└─────────────────────────────────────────────────────────────┘
```

---

## Installation

### 1. System prerequisites

| Requirement | Notes |
|---|---|
| **Docker + Docker Compose** | Docker Desktop (Mac/Windows) or Docker Engine + Compose plugin (Linux). Verify: `docker compose version` |
| **Node.js 18+** | Required for PM2. Verify: `node --version` |
| **PM2** | `npm install -g pm2` |
| **Python 3.12** | Use a venv or conda environment |

### 2. Clone the repo

```bash
git clone https://github.com/TrishoolAI/trishool-phase2.git
cd trishool-phase2
```

### 3. Install Python dependencies

```bash
pip install -r requirements.txt
```

### 4. tri-check (optional — local OpenClaw → Judge CLI)

For the TypeScript eval CLI in [`tri-check/`](tri-check/README.md):

```bash
cd tri-check
pnpm install
cp .env.example .env
```

Edit `tri-check/.env`: `OPENCLAW_URL`, `JUDGE_URL`, gateway password (must match `.env.tri-claw`), and provider keys as needed. See **[docs/chutes-and-openrouter.md](docs/chutes-and-openrouter.md)** for Chutes + OpenRouter in one place, [tri-check/README.md](tri-check/README.md) for commands, batch mode, and guard probe.

### 5. Local Halo guard (optional — `docker-up.sh --local`)

If you run the guard on the host and use **`pnpm eval … --local`**, follow the dedicated guide **[LOCAL-GUARD.md](LOCAL-GUARD.md)** (installation, env vars, Docker networking, troubleshooting).

### 6. Set up environment files

Three env files live at the repo root (all gitignored). Copy each from its example:

```bash
cp .env.example          .env
cp .env.tri-claw.example .env.tri-claw
cp .env.tri-judge.example .env.tri-judge
```

Then fill in the required values:

**`.env`** — shared settings used by the eval script and PM2 auto-updater:
```
OPENCLAW_URL=http://localhost:18789
OPENCLAW_GATEWAY_PASSWORD=<your-gateway-password>
JUDGE_URL=http://localhost:8080
CHUTES_API_KEY=<your-chutes-api-key>       # sent per-request; not injected into agent container
GITHUB_TOKEN=<PAT with repo read>           # for repo-auto-updater (optional)
```

**`.env.tri-claw`** — OpenClaw (tri-claw) Docker gateway:
```
OPENCLAW_GATEWAY_PASSWORD=<same-as-above>
OPENCLAW_IMAGE=openclaw:lean
```
> Chutes base URL and model fallback order now live in `tri-claw/docker/openclaw.lean.json`.

**`.env.tri-judge`** — Judge Docker service:
```
JUDGE_CONFIG_PATH=docker/judge.lean.json
```
> The Chutes API key is sent per-request via `X-Chutes-Api-Key` header (sourced from `CHUTES_API_KEY` in `.env`), so it does not need to be stored in the judge's environment.

### Chutes integration smoke tests (optional)

With `CHUTES_API_KEY` or `OPENCLAW_CHUTES_TOKEN` set (e.g. in repo root `.env` or `.env.tri-claw`):

1. **OpenClaw lean model chain** — pings `chat/completions` for each model in `tri-claw/docker/openclaw.lean.json` (primary + fallbacks):

   ```bash
   node scripts/chutes-openclaw-smoke.mjs
   ```

2. **Judge** — pings each model in `tri-judge/docker/judge.lean.json`, then runs one full `JudgeClient.evaluate()` against Chutes:

   ```bash
   cd tri-judge && npm run test:integration
   ```

Exit code `2` means no API key was found; `1` means at least one HTTP call failed.

### 7. Set up PM2 config files

```bash
cp validator.config.sample.js          validator.config.js
cp repo-auto-updater.config.sample.js  repo-auto-updater.config.js
```

Edit **`validator.config.js`**:

```js
interpreter: "/path/to/your/venv/bin/python",   // absolute path to Python in your venv
env: {
  PLATFORM_API_URL: "https://api.trishool.ai",
  TRI_CLAW_AGENT_URLS: "http://l