MechaHarness documentation

MechaHarness is a Python agent harness for hosts that must compose inference safely — not a thin chat-client wrapper. Provider I/O, agent-loop policy, cost accounting, and telemetry are first-class seams so you can swap models and policies without rewriting the run path, and so agents cannot quietly burn unbounded spend.

0.1.0

pyiv Config · multi-lane inference · cost + EventLog on every run · Python 3.9+

Quick Links: GitHub PyPI Changelog

Founding principles

  1. Modular through dependency injection. Wiring is pyiv MechaHarnessConfig and constructor injection. Hosts subclass Config hooks to bind strategies, harnesses, connections, and providers — they do not fork closed enums or grow string registries. See Dependency injection and Architecture.

  2. Multi-model and lanes are native. Reason, judge, and media (plus host-named lanes) are first-class via InferenceEnvironment.active_lane(). Generative work yields a Completion; closed-world decide yields a Judgement; media yields a Generation. Swap InferenceStrategy or JudgeProvider without rewriting the harness loop. See Judge (judge()) and Architecture.

  3. Cost lives in the object model. Ability-scaled units and CostAccountant sit on the harness path so every inference and tool invocation is priced as it happens. The design goal is to keep agents from going AWOL with unbounded spend — cost is not an optional after-the-fact report. See Cost.

  4. Event logging and telemetry are built in. A queryable EventLog records agent lifecycle, inference, tools, cost, and access checks (core:agent_*, core:inference, core:cost, …) on every run. Telemetry is part of the product surface, not a bolt-on sink. See Event log.

Also in the core model: deny-by-default tool grants and CompoundPolicy (Access control), plus host-extendable open identity for events and grants so third parties compose without patching this package (Architecture).

Installation

pip install mechaharness

Guides

Reference

API

Changelog