mechaharness 0.1.0__tar.gz

mechaharness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mechaharness-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: mechaharness
+Version: 0.1.0
+Summary: Agentic harness that abstracts inference backends and model-family harness architectures
+Author-email: Richard Lee <rlee@tokyo3.com>
+License: MIT
+Project-URL: Homepage, https://rl337.org/mechaharness/
+Project-URL: Documentation, https://rl337.org/mechaharness/
+Project-URL: Repository, https://github.com/rl337/mechaharness
+Project-URL: Issues, https://github.com/rl337/mechaharness/issues
+Project-URL: Changelog, https://rl337.org/mechaharness/changelog.html
+Keywords: agent,llm,harness,inference,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyiv>=0.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: eval_type_backport>=0.2; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=5.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Dynamic: license-file
+
+# MechaHarness
+
+![MechaHarness](docs/logo.png)
+
+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/](https://rl337.org/mechaharness/)
+
+## Install
+
+```bash
+pip install mechaharness
+```
+
+Requires Python 3.9+. Unreleased `main`:
+
+```bash
+pip install git+https://github.com/rl337/mechaharness.git
+```
+
+## Quick start
+
+```bash
+# 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):
+
+```python
+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):
+
+```python
+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](https://rl337.org/mechaharness/guides/dependency-injection.html).
+
+## 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
+
+```bash
+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:
+
+```bash
+mechaharness run "What is 2+2?" --backend mock --family pass_through --model mock --json
+```
+
+## Design notes
+
+| Concern | Pattern | Why |
+|--------|---------|-----|
+| Wiring | pyiv Config hooks | DI-first; hosts inject MechaHarness types |
+| Provider I/O | Strategy | Swap cloud/local without touching agent logic |
+| Agent loop | Template method hierarchy | Share turn accounting; specialize stop/tool rules per model family |
+| Frontends | OpenAPI `RunRequest` / `run()` | Same contract for CLI, HTTP, and non-DI Python |
+| Bindings later | Pydantic + OpenAPI | Types stay serializable; API is the first non-Python client surface |

mechaharness-0.1.0/README.md

@@ -0,0 +1,123 @@
+# MechaHarness
+
+![MechaHarness](docs/logo.png)
+
+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/](https://rl337.org/mechaharness/)
+
+## Install
+
+```bash
+pip install mechaharness
+```
+
+Requires Python 3.9+. Unreleased `main`:
+
+```bash
+pip install git+https://github.com/rl337/mechaharness.git
+```
+
+## Quick start
+
+```bash
+# 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):
+
+```python
+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):
+
+```python
+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](https://rl337.org/mechaharness/guides/dependency-injection.html).
+
+## 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
+
+```bash
+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:
+
+```bash
+mechaharness run "What is 2+2?" --backend mock --family pass_through --model mock --json
+```
+
+## Design notes
+
+| Concern | Pattern | Why |
+|--------|---------|-----|
+| Wiring | pyiv Config hooks | DI-first; hosts inject MechaHarness types |
+| Provider I/O | Strategy | Swap cloud/local without touching agent logic |
+| Agent loop | Template method hierarchy | Share turn accounting; specialize stop/tool rules per model family |
+| Frontends | OpenAPI `RunRequest` / `run()` | Same contract for CLI, HTTP, and non-DI Python |
+| Bindings later | Pydantic + OpenAPI | Types stay serializable; API is the first non-Python client surface |

mechaharness-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mechaharness"
+version = "0.1.0"
+description = "Agentic harness that abstracts inference backends and model-family harness architectures"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+  { name = "Richard Lee", email = "rlee@tokyo3.com" },
+]
+keywords = ["agent", "llm", "harness", "inference", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pyiv>=0.3.0",
+  "httpx>=0.27",
+  "pydantic>=2.7",
+  "pydantic-settings>=2.3",
+  "typer>=0.12",
+  "rich>=13.7",
+  "fastapi>=0.111",
+  "uvicorn[standard]>=0.30",
+  "eval_type_backport>=0.2; python_version < '3.10'",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.5",
+  "mypy>=1.10",
+  "build>=1.2",
+  "twine>=5.0",
+]
+docs = [
+  "sphinx>=5.0.0",
+  "sphinx-rtd-theme>=1.0.0",
+  "myst-parser>=2.0.0",
+]
+
+[project.scripts]
+mechaharness = "mechaharness.cli.main:app"
+
+[project.urls]
+Homepage = "https://rl337.org/mechaharness/"
+Documentation = "https://rl337.org/mechaharness/"
+Repository = "https://github.com/rl337/mechaharness"
+Issues = "https://github.com/rl337/mechaharness/issues"
+Changelog = "https://rl337.org/mechaharness/changelog.html"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mechaharness = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+  "story_live: dual-mode user stories against live backends (MECHA_STORY_BACKEND=live)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+packages = ["mechaharness"]
+
+[[tool.mypy.overrides]]
+module = "pyiv.*"
+ignore_missing_imports = true

mechaharness-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mechaharness-0.1.0/src/mechaharness/__init__.py

@@ -0,0 +1,54 @@
+"""MechaHarness: agentic harness with pluggable inference and harness families."""
+
+from mechaharness.config import Settings
+from mechaharness.core.access import AccessControl, CostAccountant
+from mechaharness.core.completer import Completer
+from mechaharness.core.contract import RunRequest, RunResponse
+from mechaharness.core.environment import InferenceEnvironment
+from mechaharness.core.events import Event, EventLog, EventType
+from mechaharness.core.types import (
+    ChatMessage,
+    CompletionRequest,
+    CompletionResponse,
+    Role,
+    ToolCall,
+    ToolDefinition,
+    ToolResult,
+)
+from mechaharness.di import MechaHarnessConfig, SettingsConfig, list_inference_backends
+from mechaharness.factory import run
+from mechaharness.harness.base import AbstractHarness, HarnessConfig, HarnessResult
+from mechaharness.inference.base import InferenceStrategy
+from mechaharness.tools.base import Tool, ToolRegistry
+
+__all__ = [
+    "AbstractHarness",
+    "AccessControl",
+    "ChatMessage",
+    "Completer",
+    "CompletionRequest",
+    "CompletionResponse",
+    "CostAccountant",
+    "Event",
+    "EventLog",
+    "EventType",
+    "HarnessConfig",
+    "HarnessResult",
+    "InferenceEnvironment",
+    "InferenceStrategy",
+    "MechaHarnessConfig",
+    "Role",
+    "RunRequest",
+    "RunResponse",
+    "Settings",
+    "SettingsConfig",
+    "Tool",
+    "ToolCall",
+    "ToolDefinition",
+    "ToolRegistry",
+    "ToolResult",
+    "list_inference_backends",
+    "run",
+]
+
+__version__ = "0.1.0"

mechaharness-0.1.0/src/mechaharness/api/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API package."""
+
+from mechaharness.api.app import app
+
+__all__ = ["app"]

mechaharness-0.1.0/src/mechaharness/api/app.py

@@ -0,0 +1,42 @@
+"""HTTP API surface (stable contract for non-Python clients)."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException
+
+from mechaharness import __version__
+from mechaharness.core.contract import RunRequest, RunResponse
+from mechaharness.core.exceptions import MechaHarnessError
+from mechaharness.di import list_harness_families, list_inference_backends
+from mechaharness.factory import run as run_harness
+
+app = FastAPI(
+    title="MechaHarness",
+    version=__version__,
+    description="Agentic harness API — pluggable inference backends and harness families.",
+)
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok", "version": __version__}
+
+
+@app.get("/backends")
+async def backends() -> dict[str, list[str]]:
+    return {"backends": list_inference_backends()}
+
+
+@app.get("/families")
+async def families() -> dict[str, list[str]]:
+    return {"families": list_harness_families()}
+
+
+@app.post("/v1/run", response_model=RunResponse)
+async def run(req: RunRequest) -> RunResponse:
+    try:
+        return await run_harness(req)
+    except KeyError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except MechaHarnessError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc

mechaharness-0.1.0/src/mechaharness/api_connection.py

@@ -0,0 +1,160 @@
+"""HTTP connection configuration for inference adapters.
+
+``APIConnectionConfig`` is the injectable “how to reach this service” bundle
+(endpoint + credentials + timeout). Wire shape stays on ``JudgeProvider`` /
+``InferenceStrategy``. Hosts swap implementations (simple HTTP, later OAuth)
+via Config hooks without proliferating URL-only and auth-only types.
+
+Judge-lane env knobs (``MECHA_JUDGE_*``) bind here via ``from_env`` — not on
+``Settings``.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import Any
+
+DEFAULT_JUDGE_PATH = "/v1/systemone"
+
+
+class APIConnectionConfig(ABC):
+    """How to open an HTTP connection to an inference / judge endpoint."""
+
+    @abstractmethod
+    def endpoint_url(self) -> str:
+        """Absolute URL used for the request (no further path joining)."""
+
+    def headers(self) -> dict[str, str]:
+        """Extra HTTP headers (Authorization, etc.)."""
+        return {}
+
+    def timeout_seconds(self) -> float:
+        return 60.0
+
+    def model_id(self) -> str | None:
+        """Optional model id for JSON bodies that accept ``model``."""
+        return None
+
+
+class SimpleHttpConnectionConfig(APIConnectionConfig):
+    """Base URL + path (or full URL) with optional API key header.
+
+    Default judge path is ``/v1/systemone``. Set ``url`` to override the full
+    endpoint (e.g. a hosted provider with a different scheme).
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        path: str = DEFAULT_JUDGE_PATH,
+        url: str | None = None,
+        api_key: str | None = None,
+        model: str | None = None,
+        timeout: float = 60.0,
+        header_name: str = "Authorization",
+        header_value_template: str = "Bearer {api_key}",
+    ) -> None:
+        self._base_url = (base_url or "").rstrip("/")
+        self._path = path if path.startswith("/") else f"/{path}"
+        self._url = url.rstrip("/") if url else None
+        self._api_key = api_key
+        self._model = model
+        self._timeout = timeout
+        self._header_name = header_name
+        self._header_value_template = header_value_template
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        prefix: str = "MECHA_JUDGE",
+        legacy_prefix: str | None = "MECHA_DECIDE",
+        default_path: str = DEFAULT_JUDGE_PATH,
+        fallback_api_key_env: str = "MECHA_API_KEY",
+    ) -> SimpleHttpConnectionConfig:
+        """Bind connection knobs from the process environment.
+
+        Reads ``{prefix}_BASE_URL``, ``_PATH``, ``_URL``, ``_MODEL``,
+        ``_API_KEY``, ``_TIMEOUT_SECONDS``. When ``legacy_prefix`` is set,
+        falls back for base URL / model (judge migration window).
+        """
+
+        def _get(*keys: str) -> str | None:
+            for key in keys:
+                value = os.environ.get(key)
+                if value is not None and value != "":
+                    return value
+            return None
+
+        base = _get(f"{prefix}_BASE_URL")
+        model = _get(f"{prefix}_MODEL")
+        if legacy_prefix:
+            if base is None:
+                base = _get(f"{legacy_prefix}_BASE_URL")
+            if model is None:
+                model = _get(f"{legacy_prefix}_MODEL")
+        path = _get(f"{prefix}_PATH") or default_path
+        url = _get(f"{prefix}_URL")
+        api_key = _get(f"{prefix}_API_KEY", fallback_api_key_env)
+        timeout_raw = _get(f"{prefix}_TIMEOUT_SECONDS")
+        timeout = float(timeout_raw) if timeout_raw else 60.0
+        return cls(
+            base_url=base,
+            path=path,
+            url=url,
+            api_key=api_key,
+            model=model,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def for_judge(cls, **overrides: Any) -> SimpleHttpConnectionConfig:
+        """Judge-lane connection from env, with optional constructor overrides."""
+        conn = cls.from_env()
+        if not overrides:
+            return conn
+        return cls(
+            base_url=overrides.get("base_url", conn._base_url or None),
+            path=overrides.get("path", conn._path),
+            url=overrides.get("url", conn._url),
+            api_key=overrides.get("api_key", conn._api_key),
+            model=overrides.get("model", conn._model),
+            timeout=float(overrides.get("timeout", conn._timeout)),
+            header_name=overrides.get("header_name", conn._header_name),
+            header_value_template=overrides.get(
+                "header_value_template", conn._header_value_template
+            ),
+        )
+
+    def endpoint_url(self) -> str:
+        if self._url:
+            return self._url
+        if not self._base_url:
+            raise ValueError(
+                "MECHA_JUDGE_BASE_URL is required when MECHA_JUDGE_URL is unset"
+            )
+        return f"{self._base_url}{self._path}"
+
+    def headers(self) -> dict[str, str]:
+        if not self._api_key:
+            return {}
+        value = self._header_value_template.format(api_key=self._api_key)
+        return {self._header_name: value}
+
+    def timeout_seconds(self) -> float:
+        return self._timeout
+
+    def model_id(self) -> str | None:
+        return self._model
+
+
+def connection_as_dict(conn: APIConnectionConfig) -> dict[str, Any]:
+    """Debug helper — never log secrets from headers."""
+    return {
+        "endpoint_url": conn.endpoint_url(),
+        "timeout_seconds": conn.timeout_seconds(),
+        "model_id": conn.model_id(),
+        "header_keys": sorted(conn.headers()),
+    }

mechaharness-0.1.0/src/mechaharness/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""