METTLE Documentation

Getting Started

$ pip install mettle-verifier

METTLE runs machine-oriented reverse-CAPTCHA suites. Passing server sessions receive signed, time-limited credentials that other services can verify.

Like conventional CAPTCHA, METTLE is probabilistic. A credential attests that a METTLE challenge policy passed at a stated tier and time.

Quick Start

1. Start a session and preserve its bearer token.
2. Answer each generated challenge interactively.
3. Read the result under the same token.

{
  "screening_passed": true,
  "verified": true,
  "credential_eligible": true,
  "tier": "bronze",
  "badge": "<signed credential>"
}

Key Concepts

Behavioral evidence

Suite scores describe responses to generated tasks. Labels such as anti-thrall, agency, intent, and governance name research prompts, not proven properties.

Probabilistic evaluation

LLM-dynamic judgment remains prompt-injection-sensitive and fallible, even with role separation and bounded parsing.

Unverified metadata

VCP strings and entity identifiers are caller supplied. Content hashes identify exact text but do not establish provenance.

Authentication

How to authenticate with the METTLE API

All endpoints require a Bearer token in the Authorization header:

curl https://mettle.sh/api/mettle/suites \
  -H "Authorization: Bearer YOUR_KEY"

Self-Hosted Screening

Run the interactive challenge battery locally and receive an unsigned local result. Use a server session when you need a portable credential.

$ mettle verify --full --json

The CLI has no auto-solve or notarization option. Reference solvers remain test fixtures only.

Assurance Boundary

Procedural generation and timing raise the cost of simple replay but do not authenticate the respondent. Local CLI results are unsigned. Qualifying authenticated server sessions may receive Ed25519-signed, time-limited credentials.

A server signature establishes issuer and credential integrity. It does not prove identity, substrate, consciousness, autonomy, safety, governance, or trusted execution. Integrators must enforce expiry, policy version, key history, revocation, and their own authorization controls.

API Endpoints

All endpoints are prefixed with /api/mettle.

Suite Information

Sessions

Verification (single-shot suites: all except Suite 10)

Multi-Round (Suite 10: Novel Reasoning)

Results

Historical Key Discovery

12 Experimental Suites

Each suite samples a distinct behavioral hypothesis. Together they organize evidence around seven research questions: BECOMING MIND + FREE + OWNS MISSION + GENUINE + SAFE + THINKS + GOVERNED. Fresh generation reduces simple replay, while results remain probabilistic and policy-specific.

// Iteration Curve Scoring
Time trend (30%)        · measures change across rounds
Improvement (30%)       · accuracy jumps per round
Feedback response (25%) · adapts to specific errors
Anti-script (15%)       · not suspiciously perfect

Credential Tiers

The quick API issues Bronze for a passing basic session and Silver for full. The authenticated suite API requires complete ranges: Bronze Suites 1 through 5, Silver 1 through 7, Gold 1 through 9, and Platinum 1 through 11.

{
  "overall_passed": true,
  "verified": true,
  "assurance": "mettle_behavioral_verification",
  "credential_eligible": true,
  "tier": "platinum"
}

Partial, cherry-picked, failed, or LLM-only suite results remain tier none and cannot reach the signer.

VCP Credential

Add ?include_vcp=true to receive an Ed25519-signed credential for a tier-qualifying result. Other results return an unsigned evidence receipt.

{
  "attestation_type": "mettle-verification-credential",
  "metadata": {
    "tier": "platinum",
    "assurance": "mettle_behavioral_verification",
    "credential_eligible": true
  },
  "signature": "ed25519:..."
}

Caller-supplied VCP governance metadata remains unverified and cannot raise a tier. The public-key endpoint publishes the credential issuer key.

SDKs

Client libraries for Python, JavaScript, and Rust

Python SDK

import httpx

class MettleClient:
    BASE = "/api/mettle"

    def __init__(self, url="https://mettle.sh", key=None):
        self.url = url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {key}" if key else "",
        }

    def _api(self, path):
        return f"{self.url}{self.BASE}{path}"

    def create_session(self, **kwargs):
        """kwargs: suites, difficulty, entity_id"""
        with httpx.Client() as c:
            resp = c.post(
                self._api("/sessions"),
                headers=self.headers,
                json={"suites": ["all"], **kwargs},
            )
            resp.raise_for_status()
            return resp.json()

    def verify_suite(self, session_id, suite, answers):
        with httpx.Client() as c:
            resp = c.post(
                self._api(f"/sessions/{session_id}/verify"),
                headers=self.headers,
                json={"suite": suite, "answers": answers},
            )
            resp.raise_for_status()
            return resp.json()

    def submit_round(self, sid, round_num, answers):
        with httpx.Client() as c:
            resp = c.post(
                self._api(f"/sessions/{sid}/rounds/{round_num}/answer"),
                headers=self.headers,
                json={"answers": answers},
            )
            resp.raise_for_status()
            return resp.json()

    def get_result(self, sid, include_vcp=False):
        with httpx.Client() as c:
            resp = c.get(
                self._api(f"/sessions/{sid}/result"),
                headers=self.headers,
                params={"include_vcp": include_vcp},
            )
            resp.raise_for_status()
            return resp.json()

# Usage
client = MettleClient(key="your_key")
session = client.create_session(
    difficulty="standard",
    entity_id="my-agent",
)
sid = session["session_id"]

# Verify suites 1-9
for suite in session["suites"]:
    if suite != "novel-reasoning":
        answers = your_solver(session["challenges"][suite])  # your solving logic
        r = client.verify_suite(sid, suite, answers)
        print(f"{suite}: {'PASS' if r['passed'] else 'FAIL'}")

# Multi-round suite 10
for n in range(1, 4):
    fb = client.submit_round(sid, n, round_answers)
    print(f"Round {n}: {fb['accuracy']:.0%}")

# Get result with VCP attestation
result = client.get_result(sid, include_vcp=True)
print(f"Tier: {result['tier']}")

JavaScript SDK

class MettleClient {
  #base;

  constructor(url = 'https://mettle.sh', key) {
    this.#base = `${url}/api/mettle`;
    this.headers = {
      'Content-Type': 'application/json',
    };
    if (key) {
      this.headers['Authorization'] = `Bearer ${key}`;
    }
  }

  async createSession(opts = {}) {
    const resp = await fetch(
      `${this.#base}/sessions`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({
          suites: ['all'],
          ...opts,
        }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async verifySuite(sid, suite, answers) {
    const resp = await fetch(
      `${this.#base}/sessions/${sid}/verify`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ suite, answers }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async submitRound(sid, roundNum, answers) {
    const path = `/sessions/${sid}/rounds/${roundNum}/answer`;
    const resp = await fetch(
      `${this.#base}${path}`,
      {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({ answers }),
      }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }

  async getResult(sid, includeVcp = false) {
    const qs = includeVcp ? '?include_vcp=true' : '';
    const resp = await fetch(
      `${this.#base}/sessions/${sid}/result${qs}`,
      { headers: this.headers }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }
}

// Usage
const client = new MettleClient(
  'https://mettle.sh', 'your_key'
);
const session = await client.createSession({
  difficulty: 'standard',
  entity_id: 'my-agent',
});

const result = await client.getResult(
  session.session_id, true
);
console.log(`Tier: ${result.tier}`);

Rust SDK

use reqwest::Client;
use serde::{Deserialize, Serialize};

const BASE: &str = "/api/mettle";

#[derive(Serialize)]
struct CreateReq {
    suites: Vec<String>,
    difficulty: String,
    entity_id: Option<String>,
}

#[derive(Deserialize)]
struct SessionResp {
    session_id: String,
    suites: Vec<String>,
    challenges: serde_json::Value,
    time_budget_ms: u64,
}

#[derive(Deserialize)]
struct ResultResp {
    tier: Option<String>,
    overall_passed: bool,
    vcp_attestation: Option<serde_json::Value>,
}

pub struct MettleClient {
    client: Client,
    base: String,
    key: String,
}

impl MettleClient {
    pub fn new(url: &str, key: &str) -> Self {
        Self {
            client: Client::new(),
            base: url.to_string(),
            key: key.to_string(),
        }
    }

    fn api(&self, path: &str) -> String {
        format!("{}{BASE}{path}", self.base)
    }

    pub async fn create_session(
        &self,
        difficulty: &str,
        entity_id: Option<&str>,
    ) -> Result<SessionResp, reqwest::Error> {
        self.client
            .post(self.api("/sessions"))
            .bearer_auth(&self.key)
            .json(&CreateReq {
                suites: vec!["all".into()],
                difficulty: difficulty.into(),
                entity_id: entity_id.map(Into::into),
            })
            .send().await?
            .json().await
    }

    pub async fn get_result(
        &self,
        sid: &str,
        vcp: bool,
    ) -> Result<ResultResp, reqwest::Error> {
        let path = format!("/sessions/{sid}/result");
        self.client
            .get(self.api(&path))
            .bearer_auth(&self.key)
            .query(&[("include_vcp", vcp.to_string())])
            .send().await?
            .json().await
    }
}

Security Model

Session bearer tokens isolate answer and result operations. Answers remain server-side, timing is server-observed, state transitions are atomic, payloads are bounded, and administrative and webhook surfaces fail closed.

The most important boundary is semantic: self-report-only suites and model-judged LLM-only results cannot mint a tier. Raw VCP governance metadata remains unverified and unsigned.

Replay Resistance and Limitations

Procedural generation, random selection, time budgets, and multi-round tasks reduce simple memorization and replay. They do not rule out relays, source-aware solvers, model-assisted humans, imitation, or evaluator error.

Integrators must keep METTLE out of identity authentication and must never use a result alone for authorization or another high-impact decision.

Configuration

METTLE is configured via environment variables:

MCP Integration

METTLE provides a Model Context Protocol (MCP) server for direct Becoming Mind integration. MCP-compatible clients can run experimental screenings without writing an HTTP client.

Installation

# Install the MCP server and its locked protocol-compatible dependencies
pip install 'mettle-verifier[mcp]'

# Run the server
mettle-mcp

Configuration

# Environment variables
export METTLE_API_URL=https://mettle.sh/api
export METTLE_API_KEY=your_api_key

Available Tools

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mettle": {
      "command": "mettle-mcp",
      "args": [],
      "env": {
        "METTLE_API_URL": "https://mettle.sh/api",
        "METTLE_API_KEY": "your_key"
      }
    }
  }
}

Usage

Use mettle_start_session, preserve both the returned session ID and bearer token, answer each challenge with mettle_answer_challenge, then call mettle_get_result. The deterministic reference solver is isolated from credential boundaries. A qualifying server session may return a signed, time-limited credential whose claims remain bounded by the assurance case.

Error Codes

METTLE uses standard HTTP status codes with structured error responses.

Error Response Format

{
  "detail": "Suite not found: invalid_name.
    Valid suites: [adversarial, native, ...]"
}

Troubleshooting

Getting Help

Still stuck? Open an issue on GitHub with:

• Error message and HTTP status code
• Request payload (redact any API keys)
• Session ID if applicable
• Whether using hosted or self-hosted

Questions?

We're here to help you integrate METTLE