LoopKit

LoopKit makes invisible automation loops noticeable and repairable.

It turns a site inventory of background automation into:

1. per-loop exposure scores (impact, autonomy, cycle frequency),
2. required kit tiers (full_loop / pause_ready / noticeable / ambient),
3. gap analysis against installed affordances,
4. repair statuses (repairable / partially_equipped / opaque / ambient),
5. a kit prescription and bill of materials, as JSON or Markdown reports.

This is a legibility assessment and planning aid. It does not control devices, verify interruption latency, certify safety, or replace hazard analysis.

Install

python -m pip install -e .

Quick Start

python -m loopkit sample -o examples/site_case.json
python -m loopkit run -i examples/site_case.json --full -o examples/kit_report.json
python -m loopkit run -i examples/site_case.json --markdown -o examples/kit_report.md

Why It Exists

Homes, clinics, farms, and factory floors run automation loops nobody can see. When one misbehaves, people file a support ticket — because the loop offers no in-context way to notice it, pause it, read what it did, or take over. LoopKit treats repair as an ordinary action: every loop gets a standing prescription of four physical affordances:

Kit element	Question it answers
status_light	is the loop running, and in what state?
pause_gesture	can one simple gesture halt it?
paper_receipt	what did the last cycle actually do?
handoff_checklist	how does a human take over?

How It Works

For each automation loop, the kit:

1. scores exposure (0.5 * impact + 0.3 * autonomy + 0.2 * frequency_factor, frequency capped at 24 cycles/day),
2. assigns a required tier — full_loop (≥ 0.70, all four elements), pause_ready (≥ 0.40, light + gesture + receipt), noticeable (≥ 0.15, light), or ambient (nothing required),
3. compares the requirement to installed affordances (unknown affordances never count),
4. classifies the loop and prescribes the missing elements with install effort,
5. aggregates site repair coverage and a bill of materials.

Development

python -m pytest -q

Runtime dependencies: none beyond the Python standard library.