pymh 0.1.0

Monadic Harness — structured entropy management for long-horizon agent tasks

Monadic Harness (pymh)

Structured entropy management for long-horizon agent tasks. pymh is a Claude Code Skill that wraps agent execution with a deterministic control loop — plan, execute, verify — with invariant guardrails, surprise-driven re-evaluation, and fuel management.

Why "Monadic"?

Long-horizon agent tasks fail because entropy accumulates unchecked — the agent forgets earlier discoveries, retries the same failing approach, drowns in its own context, and drifts from the original goal. Current agents rely on a single ReAct loop plus hope that the LLM stays on track.

pymh borrows the core insight from functional programming: manage computational effects with explicit, composable structures instead of implicit side effects. Each of the five entropy sources maps to a classic monad pattern:

Entropy Source	Problem	Monad Pattern	pymh Mechanism
State	Knowledge scattered across context, lost over time	State monad (s → (a, s))	Structured profile.yaml — discoveries are typed facts, not buried paragraphs
Control	Agent re-decides "what next" every step, loops	Free monad (reified program)	Condition-driven task graph compiled from a natural language plan
Side-effects	Tool results are unpredictable, cascade confusion	Writer monad (structured log)	Observation protocol — every action produces a typed signal with surprise score
Context	Context window grows, signal-to-noise drops	Reader monad (scoped env)	Context bundles — each subagent sees only what it needs, not the full history
Goal	Task goal drifts as execution unfolds	Except monad (checked abort)	Invariant system — loop detection, drift check, fuel bounds, zero token cost

The key: none of these rely on the LLM being disciplined. They are external constraints imposed by a deterministic Python driver. The LLM does what it's good at (reasoning, coding); the driver handles everything else.

For the full theoretical framework, see Entropy Sources and Monadic Structure.

Quick Start

pip install pymh
pymh setup

Then in Claude Code:

/mh migrate the project from webpack to vite

The /mh skill drives a structured 4-phase loop: plan the work, execute step by step (with parallel support), verify the result, and generate a report.

How It Works

plan ──→ exec ──→ verify ──┬──→ done
  ^                        │
  └────────────────────────┘  (verify fails → replan)

  + invariant guardrails at every step
  + fuel management (bounded execution)
  + surprise-driven re-evaluation

Phase 1: Init — User provides a goal. pymh creates a workspace with state files, fuel budget, and execution trace.

Phase 2: Plan — A plan subagent writes a YAML task plan. The compiler converts it to a task graph with conditional transitions and parallel groups.

Phase 3: Execute — The driver dispatches tasks one at a time (or in parallel). Each subagent writes a structured observation. The driver evaluates conditions, updates state, checks invariants (loop detection, drift, fuel), and advances the cursor.

Phase 4: Verify — A verify subagent independently assesses whether the goal was met. If not, the system replans with failure context.

Key Concepts

• Fuel — A bounded execution budget. Each dispatch costs 1 fuel. When fuel runs out, the task escalates. This prevents unbounded agent loops.
• Surprise — A float (0–1) attached to each observation. High surprise (> 0.5) triggers re-evaluation. Surprise accumulates across steps; accumulated surprise > threshold triggers replan.
• Invariants — Safety checks that run after every observation: loop detection (same task failing repeatedly), drift detection (too many replans), and fuel exhaustion.
• Observations — Structured JSON that subagents write after each step. Includes success/failure, quality score, completeness, confidence, and a human-readable narrative.

CLI Reference

Command	Description
pymh init --goal "..." --fuel 30	Initialize a new task workspace
pymh setup	Install skill files and templates
pymh decide [--phase plan|verify]	Get next dispatch instruction
pymh observe --node ID --attempt N	Process a subagent observation
pymh compile-plan	Compile NL plan to task graph
pymh status	Show current task state
pymh report	Generate task completion report
pymh resume	Resume after escalation resolution
pymh fuel --add N	Add fuel to running task
pymh abort	Abort task and generate report

All commands accept --workspace PATH to target a specific task. Without it, pymh auto-detects the most recent running task.

Workspace Layout

Each task gets a workspace under ~/.mh/tasks/<task-id>/:

workspace/
├── state.yaml              # task state: goal, fuel, cursor, status
├── ctrlflow/
│   ├── plans/current.yaml  # natural language plan
│   └── graph.json          # compiled task graph
└── dataflow/
    ├── observations/       # t1-0.json, t1-1.json, ...
    ├── instructions/       # dispatched instruction files
    └── profile.yaml        # accumulated task profile

Templates

pymh ships with 3 plan templates:

Template	Strategy
general (default)	analyze → execute → verify
migration	research guides → plan → parallel migrate → verify
research	search → evaluate → synthesize → verify

Use a template: pymh init --goal "..." --template migration

Custom templates: add YAML files to ~/.mh/templates/. See ~/.claude/skills/mh/plan-format.md for the format spec.

Development

git clone https://github.com/lulullama42/monadic-harness.git
cd monadic-harness
uv sync --dev
uv run pytest tests/ -v

Requires Python 3.9+. Only runtime dependency: PyYAML.

Architecture

Design documentation lives in docs/:

Document	Topic
00-overview	Architecture overview and problem statement
01-entropy-and-monads	Theoretical framework: entropy as a first-class concern
02-control-flow	Meta control flow, task graph, and state machine
03-data-flow	Workspace layout, observation schema, profile
04-python-driver	Driver commands and CLI protocol
05-skill-protocol	Claude Code skill integration
06-concurrency	Parallel dispatch and merge strategies
07-invariants-and-escalation	Safety guardrails and escalation
08-user-interface	Progress display and user commands
future-work	Deferred features and roadmap

License

MIT