Banyan 🌳

A trellis for your agents — the frame grows nothing, everything grows on it.

Like a banyan whose aerial roots become new trunks, one agent recursively grows its own support structure: a conversational main agent decomposes goals into a task tree, executor agents do the work, and every completed task feeds a knowledge loop for the next run.

pip install banyan-ai        # PyPI (alpha)

Architecture: brain / brainstem

All LLM activity lives at the two ends — planning (main agent, heavy tier) and execution (executor agents, fast tier). Everything between is a deterministic zero-LLM kernel:

Design principles (full write-up in the design doc):

1. DB is the only authority — everything rendered is a projection.
2. The context window is a cache, not a home — cold-start assembly per unit.
3. Every boundary is lossy — contracts + summaries + pointers cross edges, never raw transcripts.
4. Determinism never touches an LLM — dispatch, leases, budgets, recovery are pure rules.

Quickstart

pip install "banyan-ai[dev]"
export BANYAN_LLM_API_KEY=<your-zhipu-api-key>

python -m banyan.cli chat "build a python package X with tests"   # 1. main agent builds the tree
python -m banyan.cli status                                       # 2. review the skeleton
python -m banyan.cli approve root                                 # 3. pass the approval gate
python -m banyan.cli run --workers 2                              # 4. kernel dispatches, agents execute
python -m banyan.cli consolidate transcript.txt                   # 5. nightly knowledge extraction
python -m banyan.cli status                                       # inspect results

Progressive refinement is built in: only the first slice gets a full contract; deeper slices are stored as sketches and expanded just before execution against the then-current world state.

The knowledge loop

consolidate runs a fast-tier extraction over the day's transcripts and completed tasks: candidate cards → schema gate → dedupe → contradiction detection (CONTRADICTS edges, human adjudication) → publish. Retrieval middleware injects a critical set + task-relevant cards into every executor window. Cards earn their keep: consumers rate them used | stale | wrong at commit time — wrong cards are quarantined immediately; repeatedly verified cards enter the critical set.

Completed trees are mined into plan templates; the next similar goal matches them and the planner starts from experience instead of scratch.

Commands

Configuration

The default endpoint is the GLM Coding-plan endpoint. The general api/paas/v4 endpoint only serves glm-4.5-flash without a general balance (error 1113).

Status

0.1.0a1 — all mechanisms implemented and machine-verified: kernel tests, parallel workers, background-task adjudication, knowledge extraction → publication → retrieval, template mining. Known gaps: git-worktree workspace isolation, escalation inbox CLI, multi-host coordination.

License

MIT