88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
|
# 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.
|