MechaHarness

Python agent harness for hosts that compose inference safely — not a thin chat-client wrapper. Founding principles:

1. Modular via dependency injection — pyiv MechaHarnessConfig; hosts subclass and compose (no forked enums / string registries)
2. Multi-model / lanes native — reason, judge, and media lanes; Completion / Judgement / Generation outcomes
3. Cost in the object model — CostAccountant on the harness path so runs cannot quietly go AWOL on spend
4. EventLog telemetry built in — queryable lifecycle, inference, tools, cost, and access events on every run

Also: deny-by-default grants / CompoundPolicy, and host-extendable open identity. Docs: https://rl337.org/mechaharness/

Install

pip install mechaharness

Requires Python 3.9+. Unreleased main:

pip install git+https://github.com/rl337/mechaharness.git

Quick start

# List backends / harness families
mechaharness backends
mechaharness families

# Local LM Studio (OpenAI-compatible)
mechaharness run "What is 2+2?" \
  --backend lmstudio \
  --family tool_loop \
  --model local-model

# OpenAI
export MECHA_API_KEY=sk-...
mechaharness run "Hello" --backend openai --model gpt-4o-mini

# HTTP API
mechaharness serve --port 8080
curl -s http://127.0.0.1:8080/health

Environment variables use the MECHA_ prefix (MECHA_API_KEY, MECHA_INFERENCE_BACKEND, MECHA_MODEL, MECHA_BASE_URL, …).

Library usage

Non-DI (OpenAPI-shaped):

import asyncio
from mechaharness import RunRequest, run

async def main() -> None:
    result = await run(RunRequest(prompt="What is 19 + 23?", backend="lmstudio"))
    print(result.final_text)

asyncio.run(main())

DI (pyiv Config hooks):

from pyiv import get_injector

from mechaharness.di import MechaHarnessConfig
from mechaharness.harness.base import AbstractHarness
from mechaharness.harness.tool_loop import ToolLoopHarness
from mechaharness.inference.openai_compat import OpenAICompatStrategy


class MyConfig(MechaHarnessConfig):
    def get_inference_class(self):
        return OpenAICompatStrategy

    def get_harness_class(self):
        return ToolLoopHarness


injector = get_injector(MyConfig)
harness = injector.inject(AbstractHarness)

See Dependency injection.

Extending

Subclass InferenceStrategy (constructor takes Settings) and return it from get_inference_class(), or merge it into SettingsConfig.inference_classes(). Subclass AbstractHarness and return it from get_harness_class().

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"
./run_checks.sh

run_checks.sh is what CI runs: ruff, mypy, pytest, Sphinx, and CLI smoke. EventLog + cost without a GPU:

mechaharness run "What is 2+2?" --backend mock --family pass_through --model mock --json

Design notes