Metadata-Version: 2.1
Name: bub
Version: 0.3.0a1
Summary: Bub it. Build it. Batteries-included, hook-first AI framework.
Author-Email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>, Yihong <zouzou0208@gmail.com>
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
Project-URL: Homepage, https://bub.build
Project-URL: Repository, https://github.com/bubbuild/bub
Project-URL: Documentation, https://bub.build
Requires-Python: <4.0,>=3.12
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pluggy>=1.6.0
Requires-Dist: typer>=0.9.0
Requires-Dist: republic>=0.5.3
Requires-Dist: any-llm-sdk[anthropic]
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: rapidfuzz>=3.14.3
Description-Content-Type: text/markdown

# Bub

Bub is a hook-first AI framework built on `pluggy`: the core stays small and orchestrates turns, while builtins and plugins provide behavior.

## Current Implementation

- CLI bootstrap: `src/bub/__main__.py` (Typer app)
- Turn orchestrator: `src/bub/framework.py`
- Hook contract: `src/bub/hookspecs.py`
- Builtin hooks/runtime: `src/bub/builtin/hook_impl.py` + `src/bub/builtin/engine.py`
- Skill discovery and validation: `src/bub/skills.py`

## Quick Start

```bash
git clone https://github.com/bubbuild/bub.git
cd bub
uv sync
uv run bub --help
```

```bash
# Runtime off: falls back to model_output=prompt
BUB_RUNTIME_ENABLED=0 uv run bub run "hello"
```

```bash
# Internal command mode (line starts with ',')
BUB_RUNTIME_ENABLED=0 uv run bub run ",help"
```

```bash
# Model runtime (hosted providers usually require a key)
BUB_API_KEY=your_key uv run bub run "Summarize this repository"
```

## CLI Commands

- `bub run MESSAGE`: execute one inbound turn and print outbound messages
- `bub hooks`: print hook-to-plugin bindings
- `bub install PLUGIN_SPEC`: install plugin from PyPI or `owner/repo` (GitHub shorthand)

## Runtime Behavior

- Regular text input: uses `run_model`; if runtime is unavailable, output falls back to the prompt text
- Comma commands: `,help`, `,tools`, `,fs.read ...`, etc.
- Unknown comma commands: executed as `bash -lc` in workspace
- Session event log: `.bub/runtime/<session-hash>.jsonl`
- `AGENTS.md`: if present in workspace, appended to runtime system prompt

## Skills

- Discovery roots with deterministic override:
  1. `<workspace>/.agent/skills`
  2. `~/.agent/skills`
  3. `src/bub_skills`
- Each skill directory must include `SKILL.md`
- Supported frontmatter fields:
  - required: `name`, `description`
  - optional: `license`, `compatibility`, `metadata`, `allowed-tools`

## Plugin Development

Plugins are loaded from Python entry points in `group="bub"`:

```toml
[project.entry-points."bub"]
my_plugin = "my_package.my_plugin"
```

Implement hooks with `@hookimpl` following `BubHookSpecs`.

## Runtime Environment Variables

- `BUB_RUNTIME_ENABLED`: `auto` (default), `1`, `0`
- `BUB_MODEL`: default `openrouter:qwen/qwen3-coder-next`
- `BUB_API_KEY`: runtime provider key
- `BUB_API_BASE`: optional provider base URL
- `BUB_RUNTIME_MAX_STEPS`: default `8`
- `BUB_RUNTIME_MAX_TOKENS`: default `1024`
- `BUB_RUNTIME_MODEL_TIMEOUT_SECONDS`: default `90`

## Documentation

- `docs/index.md`: overview
- `docs/architecture.md`: lifecycle, precedence, and failure isolation
- `docs/skills.md`: skill discovery and frontmatter constraints
- `docs/cli.md`: CLI usage and comma command mode
- `docs/features.md`: implemented capabilities and limits

## Development Checks

```bash
uv run ruff check .
uv run mypy src
uv run pytest -q
```
