# zubble

A minimal, hackable agentic harness for LLM-driven repair and coding tasks.

`zubble` combines the simplicity of [mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent),
the anti-loop discipline of [Ralph Wiggum](https://github.com/fstandhartinger/ralph-wiggum),
the doom-loop detection of [ZeroStack](https://github.com/gi-dellav/zerostack),
and hard-won lessons from FestBench's ScenarioBench — in ~200 lines of readable Python.

## Why?

Heavyweight agent platforms (Goose, Crush, OpenHands) are powerful but opaque.
`zubble` is the opposite: a loop you can read in one sitting, extend with a
subclass, and run against any endpoint — no framework tax.

It was designed to make five failure modes structurally impossible:

1. **Conversation simulation** — stop sequences + proper messages array
2. **Degenerate repetition** — in-stream repetition detection + doom-loop detector
3. **Context poisoning** — response truncation + fresh-context reset
4. **Budget exhaustion** — per-call maxtok caps by thinking level
5. **Amnesia** — a disk-persisted trial journal that survives context resets

## Quickstart

```bash
# Install (when published)
pip install zubble-agent

# Run against any OpenAI-compatible endpoint (llama.cpp, vLLM, Ollama)
zubble run \
  --endpoint http://192.168.5.117:8000 \
  --task "fix the kubelet config on node-1" \
  --env docker --env-container bastion-03 \
  --level xhigh --minutes 15

# Run against a hosted API
zubble run --model anthropic/claude-sonnet-4 --task "refactor auth" --env local

# Run as a Ralph Wiggum loop (fresh context each iteration)
zubble loop --task spec.md --max-iterations 20 --fresh-context

# Run with trial journal + cross-run memory
zubble run --task "debug cert_expiry" --env kubectl --memory-dir ~/.zubble/memory
```

## Key features

- **Stop sequences** on every API call — prevents conversation simulation
- **In-stream repetition detection** — aborts degenerate output mid-generation
- **Proper messages array** — never flattens to `User:`/`Assistant:` text
- **Doom-loop detection** — 3 identical commands triggers a warning
- **Fresh-context reset** — on degenerate loop, restart with journal summary
- **Trial journal** — disk-persisted record of what worked and what didn't
- **Thinking level control** — `chat_template_kwargs` for reasoning models
- **Per-call maxtok by level** — off/low/medium/xhigh budgets
- **Temperature flag** — default 0 for reproducibility, overridable
- **Pluggable** — `Model`, `Environment`, `Observer`, `Protocol` are interfaces
- **MIT licensed** — no copyleft, no vendor lock-in

## Architecture

Four pluggable components:

| Component | Role | Examples |
|---|---|---|
| `Model` | LLM API client | `OpenAIModel`, `LitellmModel`, `CliModel` |
| `Environment` | Command execution sandbox | `LocalEnv`, `DockerEnv`, `KubectlEnv` |
| `Observer` | Loop/degeneration detector | `DoomLoopObserver`, `TextRepetitionObserver` |
| `Journal` | Disk-persisted trial memory | `TrialJournal` |

Plus `Protocol` classes that define task-specific message templates
(repair, SWE-bench, custom).

## Design document

See [DESIGN.md](DESIGN.md) for the full architecture, control flow,
feature catalog, comparison table, and roadmap.

## License

MIT — see [LICENSE](LICENSE).

## Attribution

`zubble` draws from mini-swe-agent (MIT, Princeton/Stanford), Ralph Wiggum
(MIT, fstandhartinger / Geoffrey Huntley), ZeroStack (GPL-3.0, gi-dellav),
and FestBench's ScenarioBench harness.