luxferre/bantam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

retired all ports except go and mb-perl

Browse Source
This commit is contained in:
Luxferre
2026-08-15 09:41:08 +03:00
parent e4140bce67
commit 4b55c27fee
4 changed files with 15 additions and 995 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+15 -29
View File
@@ -2,7 +2,7 @@
## About
Bantam is a minimalist, dependency-free AI agent specification with reference implementations in **Python** (`bantam.py`, ~280 SLOC), **Go** (`main.go` + `term_*.go`, module `code.luxferre.top/luxferre/bantam`), and **Perl 5** (`bantam.pl`, ~360 SLOC). It provides an agentic loop capable of autonomous tool execution, shell interaction, real-time response streaming, Fibonacci backoff network resilience, and subagent delegation using any OpenAI-compatible completions API.
Bantam is a minimalist, dependency-free AI agent specification with reference implementations in **Go** (`main.go` + `term_*.go`, module `code.luxferre.top/luxferre/bantam`) and **Perl 5** as **MicroBantam** (`mb`, under 100 SLOC). It provides an agentic loop capable of autonomous tool execution, shell interaction, real-time response streaming, markdown terminal rendering with box-drawing tables, Fibonacci backoff network resilience, and subagent delegation using any OpenAI-compatible completions API.
The entire philosophy of Bantam is built upon two principles:
@@ -14,7 +14,7 @@ Because of the second principle, Bantam itself was named after Victorinox Bantam
## Usage
### Prerequisites
- **Python 3.7+**, **Go 1.21+**, or **Perl 5.14+** (standard library / core modules only)
- **Go 1.21+** or **Perl 5.14+** (standard library / core modules only)
- An OpenAI-compatible API endpoint (or OpenAI API key)
### Installation (Go)
@@ -31,7 +31,7 @@ go build ./... # produces ./bantam
go run . prompt.txt
```
The Go port is a single `main.go` plus four platform files (`term_linux.go`, `term_bsd.go`, `term_windows.go`, `term_other.go`) for the built-in raw-terminal line editor — zero external dependencies, same as the Python and Perl versions.
The Go port is a single `main.go` plus four platform files (`term_linux.go`, `term_bsd.go`, `term_windows.go`, `term_other.go`) for the built-in raw-terminal line editor — zero external dependencies.
### Running Bantam
@@ -49,11 +49,10 @@ All implementations read the same `model.cfg` and `system.txt` from the current
2. Interactive mode:
```bash
bantam # Go (or: go run .)
python3 bantam.py # Python
perl bantam.pl # Perl 5
./mb # MicroBantam (Perl 5)
```
In interactive mode, prompts can span multiple lines: press **Ctrl+J** to insert a real line break (the cursor moves to the next line), then **Enter** to submit the whole multi-line prompt. The Go port ships its own raw-mode line editor (arrow keys move the cursor, Up/Down browse history, Backspace edits, Ctrl+C/Ctrl+D exit), so this works everywhere without dependencies; the Python and Perl ports use `readline` when available and fall back to single-line prompts otherwise.
In interactive mode, prompts can span multiple lines: press **Ctrl+J** to insert a real line break (the cursor moves to the next line), then **Enter** to submit the whole multi-line prompt. The Go port ships its own raw-mode line editor (arrow keys move the cursor, Up/Down browse history, Backspace edits, Ctrl+C/Ctrl+D exit), so this works everywhere without dependencies.
Sessions are saved under `~/.bantam/sessions/` and can be managed with these commands:
- `/save` — save the entire conversation to a new session file (auto-id like `20260808-190038`) and generate its summary
@@ -69,9 +68,8 @@ All implementations read the same `model.cfg` and `system.txt` from the current
3. File input mode:
```bash
python3 bantam.py prompt.txt # Python
bantam prompt.txt # Go
perl bantam.pl prompt.txt # Perl 5
./mb prompt.txt # MicroBantam (Perl 5)
```
## Rules of Bantam (The Algorithm)
@@ -126,11 +124,11 @@ If the API rejects the request with an `Invalid assistant message: content or to
- `api_key` (API key / Bearer token, optional; fall back to `OPENAI_API_KEY` env var)
- `stream` (stream response tokens in real-time, default `true`)
- `color` (ANSI coloring: `auto` (TTY-detected, default), `always`, or `never`; also disabled by `NO_COLOR`/`BANTAM_NO_COLOR` env vars)
- `timeout` (HTTP timeout in seconds for LLM API calls, default 300; in the Go port it bounds connection setup and time-to-first-byte, so long streaming responses are not cut off mid-stream, matching the Python and Perl ports' per-operation socket timeouts)
- `timeout` (HTTP timeout in seconds for LLM API calls, default 300; in the Go port it bounds connection setup and time-to-first-byte, so long streaming responses are not cut off mid-stream)
- `shell_timeout` (timeout in seconds for `shell_exec` commands, default 120)
- `max_al_iterations` (max tool-call loop iterations per `AL()` invocation, default 1000)
All implementations keep the interactive prompt safe against the classic "long line overwrites the prompt" readline bug: the Python and Perl ports wrap the ANSI escapes in `\001`/`\002` (`RL_PROMPT_START_IGNORE`/`RL_PROMPT_END_IGNORE`) markers (disabling `Term::ReadLine` ornaments in Perl), and the Go port's built-in editor tracks the cursor with its own column math (terminal auto-wrap aware) and redraws from the first line of the buffer, so wrapped input stays clean at any terminal width.
The Go port's built-in editor tracks the cursor with its own column math (terminal auto-wrap aware) and redraws from the first line of the buffer, so wrapped input stays clean at any terminal width.
When enabled, the interactive console uses a subtle ANSI palette: the pending-request status `...requesting...` is darkened bold, reasoning markers are cyan, reasoning text is dim, `[tool call: ...]` traces are yellow, `[tool result: ...]` headers are green, tool result bodies are dim (red for tool errors/unknown tools), and errors/network retries are red. Tool result payloads fed back to the LLM are never colored.
@@ -156,29 +154,20 @@ MicroBantam (`mb`) is a compressed Perl 5 reference implementation of the same a
- Full agentic loop: LLM calls, `shell_exec` / `run_subagent` tool execution with JSON argument validation (invalid args are fed back so the model can self-correct), and the 5-level subagent recursion depth limit
- A `...requesting...` in-flight indicator: in-place on a TTY (`\r` overwrite, erased on completion), a plain line when output is piped
- Session management: `/save`, `/list`, `/load <id>` (exact id only, no prefix matching), and auto-save to `~/.bantam/sessions/autosave.json` after every turn and on exit; session ids get `-1`, `-2`, ... suffixes on same-second collisions
- Interactive mode (`/quit`, `/clear`, `/save`, `/list`, `/load <id>`, `/help`) and file input mode
- Same built-in default system prompt and `OPENAI_API_KEY` fallback as the full implementation
- Session management: `/save`, `/list`, `/load <id>` (exact id only, no prefix matching), `/cfg <param> [val]`, and auto-save to `~/.bantam/sessions/autosave.json` after every turn and on exit; session ids get `-1`, `-2`, ... suffixes on same-second collisions
- Interactive mode (`/quit`, `/clear`, `/save`, `/list`, `/load <id>`, `/cfg`, `/help`) and file input mode
- Same built-in default system prompt and `OPENAI_API_KEY` fallback as the Go implementation
- Automatic recovery from `Invalid assistant message: content or tool_calls must be set` API errors: strips the last assistant message and retries
### What it drops
- Streaming (requests are non-streaming; `stream` is ignored)
- ANSI coloring/styling (`color` is ignored)
- `Term::ReadLine` line editing, Ctrl+J multi-line prompts and readline history (plain single-line prompts)
- Line editing, Ctrl+J multi-line prompts and history (plain single-line prompts)
- Fibonacci backoff network retries (a failed request aborts with an `API error` message)
- `/compact` context summarization
### Jim Tcl port
`mb.tcl` is a **highly experimental** Jim Tcl port of the same agent (under 100 SLOC) with the same feature set as the Perl `mb`. It differs in three ways: it ships its own minimal HTTP client (raw sockets with chunked-transfer decoding) instead of `HTTP::Tiny`; it retries failed requests up to 3 times with a 2-second backoff instead of aborting on the first failure; and it relies on the external `timeout` command for `shell_exec` timeouts instead of `SIGALRM`. Run it the same way:
```bash
./mb.tcl # interactive (or: jimsh mb.tcl)
./mb.tcl prompt.txt # file input mode
```
### Running
### Running MicroBantam
```bash
./mb # interactive (or: perl mb)
@@ -187,11 +176,8 @@ MicroBantam (`mb`) is a compressed Perl 5 reference implementation of the same a
## Repository layout
- `bantam.py` — Python reference implementation (stdlib only)
- `main.go`, `term_linux.go`, `term_bsd.go`, `term_windows.go`, `term_other.go` — Go implementation (stdlib only, module `code.luxferre.top/luxferre/bantam`)
- `bantam.pl` — Perl 5 implementation (core modules only)
- `mb` — MicroBantam, compressed Perl 5 implementation (core modules only, under 100 SLOC)
- `mb.tcl` — MicroBantam, Jim Tcl port (requires `jimsh` with the `json` and `ssl` extensions; under 100 SLOC)
- `model.cfg`, `system.txt` — shared configuration and system prompt
- `README.md` — this document
@@ -219,9 +205,9 @@ You can pair Bantam with the [Dynagate](https://code.luxferre.top/luxferre/dynag
### How to run on mobiles?
On Android, any current Bantam/MicroBantam implementation is easily runnable within the Termux environment. Go implementation is preferred for performance reasons.
On Android, Bantam (Go) and MicroBantam (`mb`) are easily runnable within the Termux environment. The Go implementation is preferred for performance reasons.
On iOS/iPadOS, the easiest way to use Bantam is to run the Perl version (or MicroBantam) inside iSH. Some terminal features may not be available (run with `rlwrap` to bring them back), but the agent itself is fully functional.
On iOS/iPadOS, the easiest way to use Bantam is to run MicroBantam (`mb`) inside iSH. Some terminal features may not be available (run with `rlwrap` to bring them back), but the agent itself is fully functional.
## Credits