Metadata-Version: 2.5
Name: bub
Version: 0.6.0a1
Summary: A tiny agent runtime, composable with plugins.
Project-URL: Homepage, https://bub.build
Project-URL: Repository, https://github.com/bubbuild/bub
Project-URL: Documentation, https://bub.build
Author-email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>, Yihong <zouzou0208@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Requires-Dist: aiohttp>=3.14.3
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: inquirer-textual>=0.8.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pluggy>=1.6.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-telegram-bot>=22.7
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rapidfuzz>=3.14.5
Requires-Dist: republic>=0.6.0a1
Requires-Dist: rich>=14.3.4
Requires-Dist: typer>=0.24.1
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: logfire
Requires-Dist: logfire>=4.32.0; extra == 'logfire'
Requires-Dist: opentelemetry-api>=1.39.0; extra == 'logfire'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.0; extra == 'logfire'
Requires-Dist: opentelemetry-sdk>=1.39.0; extra == 'logfire'
Provides-Extra: trace
Requires-Dist: opentelemetry-api>=1.39.0; extra == 'trace'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.0; extra == 'trace'
Requires-Dist: opentelemetry-sdk>=1.39.0; extra == 'trace'
Description-Content-Type: text/markdown

# Bub

<div align="center">

<picture>
  <source srcset="https://raw.githubusercontent.com/bubbuild/bub/refs/heads/main/website/src/assets/bub-logo-dark.png" media="(prefers-color-scheme: dark)">
  <img alt="Bub logo" src="https://raw.githubusercontent.com/bubbuild/bub/refs/heads/main/website/src/assets/bub-logo.png" width="200">
</picture>

<p><strong>A tiny agent runtime, composable with plugins.</strong></p>

[Website](https://bub.build) · [Docs](https://bub.build/docs/getting-started/) · [Hub](https://hub.bub.build)

</div>

Bub is a small Python runtime for building agents in shared environments. It started in group chats, where multiple humans and agents had to work in the same conversation without hidden state, hand-wavy memory, or framework-specific magic.

Built on [agents.md](https://agents.md/) and [Agent Skills](https://agentskills.io/), Bub stays intentionally small. Every turn stage is a [pluggy](https://pluggy.readthedocs.io/) hook, builtins are replaceable, and the same runtime drives CLI, Telegram, and any channel you add.

## Quick Start

macOS and Linux:

```bash
curl -fsSL https://bub.build/install.sh | bash
```

Windows PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://bub.build/install.ps1 | iex"
```

Then:

```bash
bub chat                         # interactive session
bub run "summarize this repo"    # one-shot task
bub gateway                      # channel listener mode
```

See [Getting Started](https://bub.build/docs/getting-started/) for installer presets and source installs, and [Configure](https://bub.build/docs/operate/configure/) for model and runtime settings.

## Why Bub

- **Composable by design.** Every turn stage is a plugin hook. Override one stage or replace the whole flow without forking the runtime.
- **Tape context.** Context is rebuilt from append-only records, not carried around as mutable session state. Easier to inspect, replay, and hand off.
- **One runtime across surfaces.** The same inbound pipeline runs across CLI, Telegram, and custom channels. Adapters change the surface, not the runtime model.
- **Batteries included.** CLI, Telegram, tools, skills, and model execution ship with the core runtime. Use the defaults first, replace them later.
- **Operator equivalence.** Humans and agents work inside the same runtime boundaries, with the same evidence trail and handoff model.
- **Embeddable Python SDK.** `bub.core` exposes the agent loop on its own — bring your own model, tools, prompts, and tape store, with no settings or plugins required.

## How It Works

Every inbound message goes through one turn pipeline. Each stage is a hook.

```
resolve_session → load_state → build_prompt → run_model
                                                   ↓
              dispatch_outbound ← render_outbound ← save_state
```

Builtins are registered first and external plugins load after them, so later plugins take precedence. There are no framework-only shortcuts.

## Docs

- [Getting Started](https://bub.build/docs/getting-started/) — install Bub and run the first turn
- [Concepts](https://bub.build/docs/concepts/) — the mental model behind the runtime
- [Python SDK](https://bub.build/docs/build/sdk/) — embed Bub's agent loop in your own application
- [Build](https://bub.build/docs/build/) — write plugins, override hooks, ship tools and skills
- [Bub Hub](https://hub.bub.build) — browse community plugins, skills, and distributions
- [Channels](https://bub.build/docs/operate/channels/) — run Bub in CLI, Telegram, or your own channel
- [Deployment](https://bub.build/docs/operate/deploy/) — Docker, environment, upgrades

## Background

- [Why We Rewrote Bub](https://bub.build/posts/why-rewrite-bub/)
- [Socialized Evaluation and Agent Partnership](https://bub.build/posts/socialized-evaluation/)
- [Context from Tape](https://tape.systems)

## License

[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)
