Metadata-Version: 2.5
Name: banyan-ai
Version: 0.1.0a1
Summary: Banyan — a trellis for your agents: recursive task-tree orchestration with a dumb deterministic kernel, conversational main agent, and a knowledge loop
Project-URL: Homepage, https://github.com/Z-JaDe/banyan-ai
Project-URL: Repository, https://github.com/Z-JaDe/banyan-ai
Project-URL: Issues, https://github.com/Z-JaDe/banyan-ai/issues
Author: Z-JaDe
License: MIT License
        
        Copyright (c) 2026 Z-JaDe
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,knowledge-graph,llm,multi-agent,orchestration,task-tree
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: langchain-openai>=0.2
Requires-Dist: langchain>=0.3
Requires-Dist: langgraph>=0.3
Requires-Dist: llama-index-core>=0.11
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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**:

| Layer | What it is | Intelligence |
|---|---|---|
| L3 | Conversational main agent — decompose, write contracts, replan | GLM heavy |
| L2 | **Kernel** — dispatch rule table, leases with fencing tokens, budgets, depth caps, capability envelopes, failure classification, pre-dispatch reconciliation, machine verification | **zero LLM** |
| L1 | Executor agents — five-segment assembled context, tools = permissions | GLM fast |
| L0 | SQLite (tasks / events / leases / cards) + knowledge card store | — |

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

```bash
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

| Command | Purpose |
|---|---|
| `chat <goal>` | Main agent builds the milestone tree (first milestone contracted, rest sketched) |
| `status` | Tree snapshot with per-node status and token burn |
| `approve <id>` | Pass a human approval gate |
| `run [--workers N] [--max-units M]` | Kernel dispatch loop (reconcile → rule table → lease → budget → execute) |
| `consolidate <transcripts.txt>` | Nightly-style knowledge extraction and publication |

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `BANYAN_LLM_API_KEY` | — | Zhipu GLM API key (required) |
| `BANYAN_LLM_BASE_URL` | `https://open.bigmodel.cn/api/coding/paas/v4` | GLM Coding-plan endpoint (covers glm-5.3*) |
| `BANYAN_HEAVY_MODEL` | `glm-5.3` | Planning / main agent tier |
| `BANYAN_FAST_MODEL` | `glm-5.3-flash` | Execution / extraction tier |
| `BANYAN_DB` | `.banyan/banyan.db` | Kernel state database |
| `BANYAN_WORKSPACE` | `.` | Executor working directory — **point this at your target project, never the repo itself** |

> 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
