ironharness 0.2.0__tar.gz

ironharness-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Зависимости
+        run: uv sync
+      - name: Линтер
+        run: uv run ruff check .
+      - name: Тесты
+        run: uv run pytest -q

ironharness-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+
+# Локальная документация — не пушится (правило владельца)
+AGENTS.md
+PLAN.md
+
+# Секреты
+.env
+
+# Прогоны ironbench (serial-логи, журналы)
+.ironbench*/
+
+# Локальные временные файлы
+tmp/

ironharness-0.2.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: ironharness
+Version: 0.2.0
+Summary: io-core — безопасный I/O-слой для агентов (MCP); ironbench — бенчмарк для firmware-агентов
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: esptool>=5
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: pymodbus>=3.7
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# ironharness
+
+> harness — «упряжь»: впрягаем LLM-агентов в железо.
+
+Агентский харнесс для I/O и прошивок. Два модуля:
+
+- **io-core** — безопасный I/O-слой для агентов: транспорты (serial, Modbus TCP, MQTT,
+  файловая песочница), симулятор Modbus, инструменты прошивки ESP32 (esptool: разбор образа
+  офлайн, flash/erase на живой плате), JSONL-журнал всех операций, реплеер, лимиты
+  (rate-limit, дедлайны), верификация эффектов (`expect_read`), MCP-сервер (19 инструментов).
+- **ironbench** — бенчмарк для firmware-агентов: золотые задачи в симуляторах
+  (Wokwi ESP32/MicroPython, далее Renode), агентский цикл поверх LLM API, отчёты pass@k.
+
+## Быстрый старт
+
+```bash
+uv sync                              # зависимости (+ сам проект editable)
+uv run pytest                        # тесты (без железа: loop:// и симуляторы)
+uv run ruff check .                  # линтер
+uv run ironharness-mcp               # MCP-сервер (stdio; или: python -m io_core.mcp_server)
+```
+
+## Инструменты агента (MCP)
+
+`echo` · `serial_open/write/read/read_line` · `modbus_open/read/write` ·
+`mqtt_open/publish/subscribe/read` · `esp_image_info/flash/erase` · `file_write/read/list/delete`
+
+Все операции автоматически пишутся в JSONL-журнал (`$IRONHARNESS_HOME/journal.jsonl`,
+по умолчанию `~/.ironharness/`); файловые операции изолированы песочницей
+(`$IRONHARNESS_SANDBOX`, по умолчанию `~/.ironharness/sandbox`).
+
+## Подключение внешнего агента
+
+Любой MCP-совместимый агент (Claude Code, Codex, Cursor, OpenCode…) получает все
+инструменты io-core одной записью в конфиг — свой цикл агент приносит с собой,
+ironharness даёт «руки»: транспорты, песочницу, журнал, верификацию.
+
+```json
+{
+  "mcpServers": {
+    "ironharness": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ironharness", "ironharness-mcp"]
+    }
+  }
+}
+```
+
+После публикации пакета на PyPI то же самое одной строкой: `"command": "uvx", "args": ["ironharness-mcp"]`.
+
+Для испытаний на ненадёжных линиях есть `io_core.faults.FaultyTransport` — сценарные
+сбои (обрыв, задержка, порча и потеря байтов) поверх любого транспорта, и
+`io_core.mqtt_sim.MqttSimBroker` — мини-брокер MQTT (подмножество) для офлайн-прогонов.
+
+## ironbench — бенчмарк firmware-агентов
+
+```bash
+uv run ironbench list                              # каталог золотых задач
+uv run ironbench run --all                         # эталонные прогоны (нужен WOKWI_CLI_TOKEN)
+uv run ironbench solve --task blink --attempts 3   # LLM-агент решает задачу
+uv run ironbench report                            # pass@k: report.json + report.html
+```
+
+Задачи — ESP32/MicroPython в Wokwi (headless `wokwi-cli`), Renode, MicroPython unix-port
+(бесплатные локальные прогоны) и plant-мишень (замкнутая петля «объект + регулятор» в
+Python, оценка по метрикам переходной характеристики: p-regulator, pid-antiwindup,
+system-id). У каждой задачи класс (io/data/protocol/fsm/control/resilience) и уровень
+1–5; `ironbench report` показывает профиль модели по классам, а не одно число.
+LLM-конфиг — переменные окружения: `LLM_BASE_URL` (по умолчанию локальный LM Studio),
+`LLM_MODEL`, `LLM_API_KEY`, `LLM_TIMEOUT`.
+
+Статус: этапы 0–2 завершены (17 золотых задач на 4 мишенях, агентский цикл, таксономия,
+отчёты pass@k + профиль по классам), далее — этап 3 (реальное железо, плата заказана).
+План — `PLAN.md` (локально).

ironharness-0.2.0/README.md

@@ -0,0 +1,74 @@
+# ironharness
+
+> harness — «упряжь»: впрягаем LLM-агентов в железо.
+
+Агентский харнесс для I/O и прошивок. Два модуля:
+
+- **io-core** — безопасный I/O-слой для агентов: транспорты (serial, Modbus TCP, MQTT,
+  файловая песочница), симулятор Modbus, инструменты прошивки ESP32 (esptool: разбор образа
+  офлайн, flash/erase на живой плате), JSONL-журнал всех операций, реплеер, лимиты
+  (rate-limit, дедлайны), верификация эффектов (`expect_read`), MCP-сервер (19 инструментов).
+- **ironbench** — бенчмарк для firmware-агентов: золотые задачи в симуляторах
+  (Wokwi ESP32/MicroPython, далее Renode), агентский цикл поверх LLM API, отчёты pass@k.
+
+## Быстрый старт
+
+```bash
+uv sync                              # зависимости (+ сам проект editable)
+uv run pytest                        # тесты (без железа: loop:// и симуляторы)
+uv run ruff check .                  # линтер
+uv run ironharness-mcp               # MCP-сервер (stdio; или: python -m io_core.mcp_server)
+```
+
+## Инструменты агента (MCP)
+
+`echo` · `serial_open/write/read/read_line` · `modbus_open/read/write` ·
+`mqtt_open/publish/subscribe/read` · `esp_image_info/flash/erase` · `file_write/read/list/delete`
+
+Все операции автоматически пишутся в JSONL-журнал (`$IRONHARNESS_HOME/journal.jsonl`,
+по умолчанию `~/.ironharness/`); файловые операции изолированы песочницей
+(`$IRONHARNESS_SANDBOX`, по умолчанию `~/.ironharness/sandbox`).
+
+## Подключение внешнего агента
+
+Любой MCP-совместимый агент (Claude Code, Codex, Cursor, OpenCode…) получает все
+инструменты io-core одной записью в конфиг — свой цикл агент приносит с собой,
+ironharness даёт «руки»: транспорты, песочницу, журнал, верификацию.
+
+```json
+{
+  "mcpServers": {
+    "ironharness": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ironharness", "ironharness-mcp"]
+    }
+  }
+}
+```
+
+После публикации пакета на PyPI то же самое одной строкой: `"command": "uvx", "args": ["ironharness-mcp"]`.
+
+Для испытаний на ненадёжных линиях есть `io_core.faults.FaultyTransport` — сценарные
+сбои (обрыв, задержка, порча и потеря байтов) поверх любого транспорта, и
+`io_core.mqtt_sim.MqttSimBroker` — мини-брокер MQTT (подмножество) для офлайн-прогонов.
+
+## ironbench — бенчмарк firmware-агентов
+
+```bash
+uv run ironbench list                              # каталог золотых задач
+uv run ironbench run --all                         # эталонные прогоны (нужен WOKWI_CLI_TOKEN)
+uv run ironbench solve --task blink --attempts 3   # LLM-агент решает задачу
+uv run ironbench report                            # pass@k: report.json + report.html
+```
+
+Задачи — ESP32/MicroPython в Wokwi (headless `wokwi-cli`), Renode, MicroPython unix-port
+(бесплатные локальные прогоны) и plant-мишень (замкнутая петля «объект + регулятор» в
+Python, оценка по метрикам переходной характеристики: p-regulator, pid-antiwindup,
+system-id). У каждой задачи класс (io/data/protocol/fsm/control/resilience) и уровень
+1–5; `ironbench report` показывает профиль модели по классам, а не одно число.
+LLM-конфиг — переменные окружения: `LLM_BASE_URL` (по умолчанию локальный LM Studio),
+`LLM_MODEL`, `LLM_API_KEY`, `LLM_TIMEOUT`.
+
+Статус: этапы 0–2 завершены (17 золотых задач на 4 мишенях, агентский цикл, таксономия,
+отчёты pass@k + профиль по классам), далее — этап 3 (реальное железо, плата заказана).
+План — `PLAN.md` (локально).

ironharness-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "ironharness"
+version = "0.2.0"
+description = "io-core — безопасный I/O-слой для агентов (MCP); ironbench — бенчмарк для firmware-агентов"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "esptool>=5",
+    "mcp>=1.2.0",
+    "paho-mqtt>=2.0",
+    "pymodbus>=3.7",
+    "pyserial>=3.5",
+    "pyyaml>=6.0.3",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+ironbench = "ironbench.cli:main"
+ironharness-mcp = "io_core.mcp_server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/io_core", "src/ironbench"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

ironharness-0.2.0/reports/2026-09-07-qwen3.5-9b.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="ru">
+<head>
+<meta charset="utf-8">
+<title>ironbench — отчёт</title>
+<style>
+  body { font-family: -apple-system, "Segoe UI", sans-serif; margin: 2rem; color: #222; }
+  h1 { font-size: 1.3rem; }
+  table { border-collapse: collapse; margin-top: 1rem; }
+  th, td { border: 1px solid #ccc; padding: 6px 14px; text-align: left; }
+  th { background: #f4f4f4; }
+  .pass { color: #0a7d24; font-weight: 600; }
+  .fail { color: #b3261e; font-weight: 600; }
+  footer { margin-top: 1.5rem; color: #777; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+<h1>ironbench — отчёт solve</h1>
+<table>
+<tr><th>Модель</th><th>Задача</th><th>Попыток</th><th>Решено</th><th>Success rate</th><th>Средних итераций</th><th>Среднее время, с</th></tr>
+<tr><td>qwen3.5-9b</td><td>blink</td><td>3</td><td>3</td><td class="pass">100%</td><td>1.0</td><td>318.4</td></tr>
+<tr><td>qwen3.5-9b</td><td>debounce</td><td>3</td><td>0</td><td class="fail">0%</td><td>2.3</td><td>1052.5</td></tr>
+<tr><td>qwen3.5-9b</td><td>protocol</td><td>3</td><td>0</td><td class="fail">0%</td><td>1.7</td><td>938.5</td></tr>
+<tr><td>qwen3.5-9b</td><td>sensor-poll</td><td>3</td><td>1</td><td class="pass">33%</td><td>2.3</td><td>651.0</td></tr>
+<tr><td>qwen3.5-9b</td><td>traffic-light</td><td>3</td><td>0</td><td class="fail">0%</td><td>3.0</td><td>854.9</td></tr>
+<tr><td>qwen3.5-9b</td><td>uart-echo</td><td>3</td><td>3</td><td class="pass">100%</td><td>1.3</td><td>456.2</td></tr>
+</table>
+<footer>Сгенерировано ironbench · pass@k = доля пар, решённых хотя бы одной из k попыток: 50%</footer>
+</body>
+</html>

ironharness-0.2.0/reports/2026-09-07-qwen3.5-9b.json

@@ -0,0 +1,89 @@
+{
+  "campaign": "solve",
+  "models": [
+    "qwen3.5-9b"
+  ],
+  "tasks": [
+    "blink",
+    "debounce",
+    "protocol",
+    "sensor-poll",
+    "traffic-light",
+    "uart-echo"
+  ],
+  "pass_at_k": 0.5,
+  "groups": [
+    {
+      "model": "qwen3.5-9b",
+      "task": "blink",
+      "attempts": 3,
+      "solved": 3,
+      "total_iterations": 3,
+      "total_duration": 955.07,
+      "success_rate": 1.0,
+      "avg_iterations": 1.0,
+      "avg_duration": 318.4,
+      "passed": true
+    },
+    {
+      "model": "qwen3.5-9b",
+      "task": "debounce",
+      "attempts": 3,
+      "solved": 0,
+      "total_iterations": 7,
+      "total_duration": 3157.5,
+      "success_rate": 0.0,
+      "avg_iterations": 2.3,
+      "avg_duration": 1052.5,
+      "passed": false
+    },
+    {
+      "model": "qwen3.5-9b",
+      "task": "protocol",
+      "attempts": 3,
+      "solved": 0,
+      "total_iterations": 5,
+      "total_duration": 2815.46,
+      "success_rate": 0.0,
+      "avg_iterations": 1.7,
+      "avg_duration": 938.5,
+      "passed": false
+    },
+    {
+      "model": "qwen3.5-9b",
+      "task": "sensor-poll",
+      "attempts": 3,
+      "solved": 1,
+      "total_iterations": 7,
+      "total_duration": 1952.8999999999999,
+      "success_rate": 0.33,
+      "avg_iterations": 2.3,
+      "avg_duration": 651.0,
+      "passed": true
+    },
+    {
+      "model": "qwen3.5-9b",
+      "task": "traffic-light",
+      "attempts": 3,
+      "solved": 0,
+      "total_iterations": 9,
+      "total_duration": 2564.8,
+      "success_rate": 0.0,
+      "avg_iterations": 3.0,
+      "avg_duration": 854.9,
+      "passed": false
+    },
+    {
+      "model": "qwen3.5-9b",
+      "task": "uart-echo",
+      "attempts": 3,
+      "solved": 3,
+      "total_iterations": 4,
+      "total_duration": 1368.48,
+      "success_rate": 1.0,
+      "avg_iterations": 1.3,
+      "avg_duration": 456.2,
+      "passed": true
+    }
+  ]
+}

ironharness-0.2.0/src/io_core/__init__.py

@@ -0,0 +1,46 @@
+"""io-core: безопасный I/O-слой для агентов (транспорты, журнал, политики, MCP)."""
+
+from io_core.errors import (
+    OperationTimeout,
+    QuotaExceeded,
+    RateLimitExceeded,
+    SandboxViolation,
+    VerificationError,
+)
+from io_core.esp_flash import EspFlasher
+from io_core.file_sandbox import FileSandbox
+from io_core.journal import JsonlJournal, read_events
+from io_core.limits import DeadlineTransport, RateLimitedTransport, RateLimiter
+from io_core.modbus_sim import ModbusSimServer
+from io_core.modbus_transport import ModbusTransport
+from io_core.mqtt_transport import MqttTransport
+from io_core.replay import ReplayMismatch, ReplayTransport
+from io_core.serial_transport import SerialTransport
+from io_core.session import Session
+from io_core.verify import expect_read, write_and_expect
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DeadlineTransport",
+    "EspFlasher",
+    "FileSandbox",
+    "JsonlJournal",
+    "ModbusSimServer",
+    "ModbusTransport",
+    "MqttTransport",
+    "OperationTimeout",
+    "QuotaExceeded",
+    "RateLimitExceeded",
+    "RateLimitedTransport",
+    "RateLimiter",
+    "ReplayMismatch",
+    "ReplayTransport",
+    "SandboxViolation",
+    "SerialTransport",
+    "Session",
+    "VerificationError",
+    "expect_read",
+    "read_events",
+    "write_and_expect",
+]

ironharness-0.2.0/src/io_core/errors.py

@@ -0,0 +1,27 @@
+"""Ошибки политик io-core. Единые имена для всех транспортов и обёрток."""
+
+from __future__ import annotations
+
+
+class SandboxViolation(Exception):
+    """Попытка обратиться за пределы песочницы."""
+
+
+class QuotaExceeded(Exception):
+    """Превышена квота песочницы (байты или число файлов)."""
+
+
+class RateLimitExceeded(Exception):
+    """Превышен лимит операций в окне."""
+
+
+class OperationTimeout(Exception):
+    """Истёк дедлайн операции/сессии."""
+
+
+class VerificationError(Exception):
+    """Проверка эффекта не прошла: ожидание не подтвердилось за отведённое время."""
+
+
+class ConnectionLost(Exception):
+    """Соединение с устройством потеряно (в том числе по сценарию сбоев)."""

ironharness-0.2.0/src/io_core/esp_flash.py

@@ -0,0 +1,123 @@
+"""Инструменты прошивки ESP32 через esptool (план 3.3; офлайн-часть этапа 3).
+
+image_info() разбирает .bin-образ без железа (проверка агентом перед прошивкой);
+flash()/erase() требуют живую плату — в тестах функции esptool подменяются моками.
+Последовательность flash/erase — каноническая для esptool CLI (см. докстринг
+connect_esp): connect на 115200 → run_stub → change_baud → attach_flash → операция.
+Порт закрывается контекст-менеджером ESPLoader даже при ошибке операции.
+
+Внимание: без платы connect_esp делает 7 попыток синхронизации — вызов
+flash/erase блокируется до ~30 секунд, потом ConnectionError.
+
+Классический ESP32: один образ (MicroPython) шьётся по адресу 0x1000.
+Пути к .bin не ограничены файловой песочницей (образы лежат вне её корня),
+но каждая операция журналируется с полным путём, включая неудачные попытки.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from esptool.cmds import (
+    CHIP_DEFS,
+    FLASH_MODES,
+    FatalError,
+    LoadFirmwareImage,
+    attach_flash,
+    connect_esp,
+    erase_flash,
+    run_stub,
+    write_flash,
+)
+
+EventHook = Callable[[str, dict[str, Any]], None]
+
+DEFAULT_BOOTLOADER_OFFSET = 0x1000  # классический ESP32
+
+
+def _reverse_lookup(table: dict, value: int, fallback: str) -> str:
+    return next((name for name, v in table.items() if v == value), fallback)
+
+
+class EspFlasher:
+    def __init__(self, *, chip: str = "esp32", on_event: EventHook | None = None) -> None:
+        self._chip = chip
+        self._on_event = on_event
+
+    def _emit(self, event: str, data: dict[str, Any]) -> None:
+        if self._on_event is not None:
+            self._on_event(event, data)
+
+    # --- офлайн: разбор образа без платы ---
+
+    def image_info(self, firmware_path: str | Path) -> dict[str, Any]:
+        path = Path(firmware_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"образ не найден: {path}")
+        img = LoadFirmwareImage(self._chip, str(path))
+        segments = [{"addr": hex(s.addr), "size": len(s.data)} for s in img.segments]
+        # flash_size_freq: старший ниббл — размер, младший — частота; таблицы — в классе таргета
+        size_nibble = (img.flash_size_freq >> 4) & 0xF
+        freq_nibble = img.flash_size_freq & 0xF
+        target = CHIP_DEFS[self._chip]
+        info = {
+            "chip": self._chip,
+            "path": str(path),
+            "size": path.stat().st_size,
+            "entrypoint": hex(img.entrypoint),
+            "segments": segments,
+            "flash_mode": _reverse_lookup(FLASH_MODES, img.flash_mode, str(img.flash_mode)),
+            "flash_size": _reverse_lookup(
+                {name: (v >> 4) & 0xF for name, v in target.FLASH_SIZES.items()},
+                size_nibble,
+                hex(size_nibble),
+            ),
+            "flash_freq": _reverse_lookup(
+                dict(target.FLASH_FREQUENCY), freq_nibble, hex(freq_nibble)
+            ),
+        }
+        self._emit("esp_image_info", info)
+        return info
+
+    # --- живая плата ---
+
+    def flash(
+        self,
+        port: str,
+        firmware_path: str | Path,
+        *,
+        addr: int = DEFAULT_BOOTLOADER_OFFSET,
+        baud: int = 921600,
+    ) -> str:
+        path = Path(firmware_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"образ не найден: {path}")
+        try:
+            with connect_esp(port=port, chip=self._chip) as esp:
+                esp = run_stub(esp)
+                esp.change_baud(baud)
+                attach_flash(esp)
+                write_flash(esp, [(addr, str(path))])
+        except (OSError, FatalError) as e:
+            self._emit(
+                "esp_flash_failed",
+                {"port": port, "addr": addr, "baud": baud, "path": str(path), "error": str(e)},
+            )
+            raise ConnectionError(f"esp {port}: не удалось прошить ({e})") from None
+        self._emit("esp_flash", {"port": port, "addr": addr, "baud": baud, "path": str(path)})
+        return f"ok: {path.name} прошит по 0x{addr:x} ({port})"
+
+    def erase(self, port: str, *, baud: int = 921600) -> str:
+        try:
+            with connect_esp(port=port, chip=self._chip) as esp:
+                esp = run_stub(esp)
+                esp.change_baud(baud)
+                attach_flash(esp)
+                erase_flash(esp)
+        except (OSError, FatalError) as e:
+            self._emit("esp_erase_failed", {"port": port, "baud": baud, "error": str(e)})
+            raise ConnectionError(f"esp {port}: не удалось стереть ({e})") from None
+        self._emit("esp_erase", {"port": port, "baud": baud})
+        return f"ok: флеш стёрт ({port})"