bub 0.3.6__tar.gz → 0.3.7__tar.gz

{bub-0.3.6 → bub-0.3.7}/.gitignore

@@ -146,3 +146,4 @@ reference/
 # Local legacy backups created during framework migrations
 backup/
 _version.py
+!website/src/lib/

bub-0.3.7/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: bub
+Version: 0.3.7
+Summary: A common shape for agents that live alongside people.
+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-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.13.3
+Requires-Dist: any-llm-sdk[anthropic]
+Requires-Dist: httpx[socks]>=0.28.1
+Requires-Dist: inquirer-textual>=0.5.1
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: pluggy>=1.6.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rapidfuzz>=3.14.3
+Requires-Dist: republic>=0.5.4
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: logfire
+Requires-Dist: logfire>=4.31.0; extra == 'logfire'
+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 hook-first runtime for agents that live alongside people.</strong></p>
+
+</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 included but replaceable. The same runtime drives CLI, Telegram, and any channel you add.
+
+[Website](https://bub.build) · [GitHub](https://github.com/bubbuild/bub)
+
+## Quick Start
+
+```bash
+pip install bub
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/bubbuild/bub.git
+cd bub
+uv sync  # enough to run Bub from source
+```
+
+For local development, use `make install` instead so the website toolchain and `prek` hooks are installed too.
+
+```bash
+uv run bub chat                         # interactive session
+uv run bub run "summarize this repo"    # one-shot task
+uv run bub gateway                      # channel listener mode
+```
+
+## Why Bub
+
+- **Hook-first runtime.** Every turn stage is a 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. No hidden operator class.
+
+## 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. External plugins load after them. At runtime, later plugins take precedence. There are no framework-only shortcuts.
+
+Key source files:
+
+- Turn orchestrator: [`src/bub/framework.py`](https://github.com/bubbuild/bub/blob/main/src/bub/framework.py)
+- Hook contract: [`src/bub/hookspecs.py`](https://github.com/bubbuild/bub/blob/main/src/bub/hookspecs.py)
+- Builtin hooks: [`src/bub/builtin/hook_impl.py`](https://github.com/bubbuild/bub/blob/main/src/bub/builtin/hook_impl.py)
+- Skill discovery: [`src/bub/skills.py`](https://github.com/bubbuild/bub/blob/main/src/bub/skills.py)
+
+## Extend It
+
+```python
+from bub import hookimpl
+
+
+class EchoPlugin:
+    @hookimpl
+    def build_prompt(self, message, session_id, state):
+        return f"[echo] {message['content']}"
+
+    @hookimpl
+    async def run_model(self, prompt, session_id, state):
+        return prompt
+```
+
+```toml
+[project.entry-points."bub"]
+echo = "my_package.plugin:EchoPlugin"
+```
+
+See the [Extending docs](https://bub.build/docs/extending/) for hook guides, packaging, and plugin structure.
+
+## CLI
+
+| Command            | Description                       |
+| ------------------ | --------------------------------- |
+| `bub chat`         | Interactive REPL                  |
+| `bub run MESSAGE`  | One-shot turn                     |
+| `bub gateway`      | Channel listener (Telegram, etc.) |
+| `bub install`      | Install or sync Bub plugin deps   |
+| `bub update`       | Upgrade Bub plugin deps           |
+| `bub login openai` | OpenAI Codex OAuth                |
+
+Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-skill`, `,fs.read path=README.md`).
+
+`bub hooks` still exists for diagnostics, but it is hidden from top-level help. `bub install` and `bub update` manage a separate uv project for Bub plugins, defaulting to `~/.bub/bub-project` or `BUB_PROJECT`.
+
+## Configuration
+
+| Variable                    | Default                      | Description                                          |
+| --------------------------- | ---------------------------- | ---------------------------------------------------- |
+| `BUB_MODEL`                 | `openrouter:openrouter/free` | Model identifier                                     |
+| `BUB_API_KEY`               | —                            | Provider key (optional with `bub login openai`)      |
+| `BUB_API_BASE`              | —                            | Custom provider endpoint                             |
+| `BUB_API_FORMAT`            | `completion`                 | `completion`, `responses`, or `messages`             |
+| `BUB_CLIENT_ARGS`           | —                            | JSON object forwarded to the underlying model client |
+| `BUB_MAX_STEPS`             | `50`                         | Max tool-use loop iterations                         |
+| `BUB_MAX_TOKENS`            | `1024`                       | Max tokens per model call                            |
+| `BUB_MODEL_TIMEOUT_SECONDS` | —                            | Model call timeout (seconds)                         |
+
+## Background
+
+Bub is shaped by one constraint: real collaboration is messier than a solo demo. In shared environments, operators need visible boundaries, auditable history, and extension points that do not collapse into framework sprawl.
+
+Read more:
+
+- [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)
+
+## Docs
+
+- [Getting Started](https://bub.build/docs/getting-started/) — install Bub and run the first turn
+- [Architecture](https://bub.build/docs/concepts/architecture/) — the mental model behind the runtime
+- [Channels](https://bub.build/docs/guides/channels/) — run Bub in CLI, Telegram, or your own channel
+- [Skills](https://bub.build/docs/guides/skills/) — discover, inspect, and author Agent Skills in Bub
+- [Extending](https://bub.build/docs/extending/) — write plugins, override hooks, ship tools and skills
+- [Deployment](https://bub.build/docs/guides/deployment/) — Docker, environment, upgrades
+
+## Development
+
+```bash
+make install
+make check
+make test
+make docs
+make docs-test
+```
+
+See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)

bub-0.3.7/README.md

@@ -0,0 +1,153 @@
+# 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 hook-first runtime for agents that live alongside people.</strong></p>
+
+</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 included but replaceable. The same runtime drives CLI, Telegram, and any channel you add.
+
+[Website](https://bub.build) · [GitHub](https://github.com/bubbuild/bub)
+
+## Quick Start
+
+```bash
+pip install bub
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/bubbuild/bub.git
+cd bub
+uv sync  # enough to run Bub from source
+```
+
+For local development, use `make install` instead so the website toolchain and `prek` hooks are installed too.
+
+```bash
+uv run bub chat                         # interactive session
+uv run bub run "summarize this repo"    # one-shot task
+uv run bub gateway                      # channel listener mode
+```
+
+## Why Bub
+
+- **Hook-first runtime.** Every turn stage is a 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. No hidden operator class.
+
+## 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. External plugins load after them. At runtime, later plugins take precedence. There are no framework-only shortcuts.
+
+Key source files:
+
+- Turn orchestrator: [`src/bub/framework.py`](https://github.com/bubbuild/bub/blob/main/src/bub/framework.py)
+- Hook contract: [`src/bub/hookspecs.py`](https://github.com/bubbuild/bub/blob/main/src/bub/hookspecs.py)
+- Builtin hooks: [`src/bub/builtin/hook_impl.py`](https://github.com/bubbuild/bub/blob/main/src/bub/builtin/hook_impl.py)
+- Skill discovery: [`src/bub/skills.py`](https://github.com/bubbuild/bub/blob/main/src/bub/skills.py)
+
+## Extend It
+
+```python
+from bub import hookimpl
+
+
+class EchoPlugin:
+    @hookimpl
+    def build_prompt(self, message, session_id, state):
+        return f"[echo] {message['content']}"
+
+    @hookimpl
+    async def run_model(self, prompt, session_id, state):
+        return prompt
+```
+
+```toml
+[project.entry-points."bub"]
+echo = "my_package.plugin:EchoPlugin"
+```
+
+See the [Extending docs](https://bub.build/docs/extending/) for hook guides, packaging, and plugin structure.
+
+## CLI
+
+| Command            | Description                       |
+| ------------------ | --------------------------------- |
+| `bub chat`         | Interactive REPL                  |
+| `bub run MESSAGE`  | One-shot turn                     |
+| `bub gateway`      | Channel listener (Telegram, etc.) |
+| `bub install`      | Install or sync Bub plugin deps   |
+| `bub update`       | Upgrade Bub plugin deps           |
+| `bub login openai` | OpenAI Codex OAuth                |
+
+Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-skill`, `,fs.read path=README.md`).
+
+`bub hooks` still exists for diagnostics, but it is hidden from top-level help. `bub install` and `bub update` manage a separate uv project for Bub plugins, defaulting to `~/.bub/bub-project` or `BUB_PROJECT`.
+
+## Configuration
+
+| Variable                    | Default                      | Description                                          |
+| --------------------------- | ---------------------------- | ---------------------------------------------------- |
+| `BUB_MODEL`                 | `openrouter:openrouter/free` | Model identifier                                     |
+| `BUB_API_KEY`               | —                            | Provider key (optional with `bub login openai`)      |
+| `BUB_API_BASE`              | —                            | Custom provider endpoint                             |
+| `BUB_API_FORMAT`            | `completion`                 | `completion`, `responses`, or `messages`             |
+| `BUB_CLIENT_ARGS`           | —                            | JSON object forwarded to the underlying model client |
+| `BUB_MAX_STEPS`             | `50`                         | Max tool-use loop iterations                         |
+| `BUB_MAX_TOKENS`            | `1024`                       | Max tokens per model call                            |
+| `BUB_MODEL_TIMEOUT_SECONDS` | —                            | Model call timeout (seconds)                         |
+
+## Background
+
+Bub is shaped by one constraint: real collaboration is messier than a solo demo. In shared environments, operators need visible boundaries, auditable history, and extension points that do not collapse into framework sprawl.
+
+Read more:
+
+- [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)
+
+## Docs
+
+- [Getting Started](https://bub.build/docs/getting-started/) — install Bub and run the first turn
+- [Architecture](https://bub.build/docs/concepts/architecture/) — the mental model behind the runtime
+- [Channels](https://bub.build/docs/guides/channels/) — run Bub in CLI, Telegram, or your own channel
+- [Skills](https://bub.build/docs/guides/skills/) — discover, inspect, and author Agent Skills in Bub
+- [Extending](https://bub.build/docs/extending/) — write plugins, override hooks, ship tools and skills
+- [Deployment](https://bub.build/docs/guides/deployment/) — Docker, environment, upgrades
+
+## Development
+
+```bash
+make install
+make check
+make test
+make docs
+make docs-test
+```
+
+See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)

{bub-0.3.6 → bub-0.3.7}/pyproject.toml

@@ -24,6 +24,7 @@ dependencies = [
     "pydantic-settings>=2.0.0",
     "pyyaml>=6.0.0",
     "pluggy>=1.6.0",
+    "inquirer-textual>=0.5.1",
     "typer>=0.9.0",
     "republic>=0.5.4",
     "any-llm-sdk[anthropic]",
@@ -33,6 +34,7 @@ dependencies = [
     "loguru>=0.7.2",
     "rapidfuzz>=3.14.3",
     "aiohttp>=3.13.3",
+    "httpx[socks]>=0.28.1",
 ]
 
 [project.urls]
@@ -55,10 +57,6 @@ dev = [
     "types-PyYAML>=6.0.12",
     "mypy>=0.991",
     "ruff>=0.11.5",
-    "mkdocs>=1.4.2",
-    "mkdocs-terminal>=4.7.0",
-    "mkdocstrings[python]>=0.26.1",
-    "rust-just>=1.42.0",
     "prek>=0.3.1",
     "pytest-asyncio>=1.3.0",
 ]

bub-0.3.7/src/bub/__init__.py

@@ -0,0 +1,37 @@
+"""Bub framework package."""
+
+from __future__ import annotations
+
+import os
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as metadata_version
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from bub.configure import Settings, config, ensure_config
+from bub.framework import DEFAULT_HOME, BubFramework
+from bub.hookspecs import hookimpl
+from bub.tools import tool
+
+__all__ = ["BubFramework", "Settings", "config", "ensure_config", "home", "hookimpl", "tool"]
+
+try:
+    __version__ = import_module("bub._version").version
+except ModuleNotFoundError:
+    try:
+        __version__ = metadata_version("bub")
+    except PackageNotFoundError:
+        __version__ = "0.0.0"
+
+
+if TYPE_CHECKING:
+    home: Path
+
+
+def __getattr__(name: str):
+    if name == "home":
+        if "BUB_HOME" in os.environ:
+            return Path(os.environ["BUB_HOME"])
+        return DEFAULT_HOME
+    raise AttributeError(f"module {__name__} has no attribute {name}")

{bub-0.3.6 → bub-0.3.7}/src/bub/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.6'
-__version_tuple__ = version_tuple = (0, 3, 6)
+__version__ = version = '0.3.7'
+__version_tuple__ = version_tuple = (0, 3, 7)
 
 __commit_id__ = commit_id = None

{bub-0.3.6 → bub-0.3.7}/src/bub/builtin/agent.py

@@ -56,12 +56,14 @@ class Agent:
 
     @cached_property
     def tapes(self) -> TapeService:
+        import bub
+
         tape_store = self.framework.get_tape_store()
         if tape_store is None:
             tape_store = InMemoryTapeStore()
         tape_store = ForkTapeStore(tape_store)
         llm = _build_llm(self.settings, tape_store, self.framework.build_tape_context())
-        return TapeService(llm, self.settings.home / "tapes", tape_store)
+        return TapeService(llm, bub.home / "tapes", tape_store)
 
     @staticmethod
     def _events_from_iterable(iterable: Iterable) -> AsyncStreamEvents:

{bub-0.3.6 → bub-0.3.7}/src/bub/builtin/cli.py

@@ -16,11 +16,23 @@ from urllib.request import url2pathname
 
 import typer
 
+from bub import __version__, configure
 from bub.builtin.auth import app as login_app  # noqa: F401
 from bub.channels.message import ChannelMessage
 from bub.envelope import field_of
 from bub.framework import BubFramework
 
+ONBOARD_BANNER = r"""
+ ███████████             █████
+▒▒███▒▒▒▒▒███           ▒▒███
+ ▒███    ▒███ █████ ████ ▒███████
+ ▒██████████ ▒▒███ ▒███  ▒███▒▒███
+ ▒███▒▒▒▒▒███ ▒███ ▒███  ▒███ ▒███
+ ▒███    ▒███ ▒███ ▒███  ▒███ ▒███
+ ███████████  ▒▒████████ ████████
+▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒  v{version}
+""".strip("\n")
+
 
 def run(
     ctx: typer.Context,
@@ -92,6 +104,25 @@ def chat(
     asyncio.run(manager.listen_and_run())
 
 
+def onboard(ctx: typer.Context) -> None:
+    """Interactively collect plugin configuration and write it to Bub's config file."""
+
+    framework = ctx.ensure_object(BubFramework)
+    typer.echo(ONBOARD_BANNER.format(version=__version__))
+    typer.echo("\nWelcome to Bub! Let's get you set up.\n")
+
+    try:
+        config_data = framework.collect_onboard_config()
+        configure.save(framework.config_file, config_data)
+    except (typer.Abort, typer.Exit):
+        raise
+    except Exception as exc:
+        typer.secho(f"Onboarding failed: {exc}", err=True, fg="red")
+        raise typer.Exit(1) from exc
+
+    typer.echo(f"Saved config to {framework.config_file}")
+
+
 @lru_cache(maxsize=1)
 def _find_uv() -> str:
     import shutil
@@ -106,10 +137,9 @@ def _find_uv() -> str:
 
 @lru_cache(maxsize=1)
 def _default_project() -> Path:
-    from .settings import load_settings
+    import bub
 
-    settings = load_settings()
-    project = settings.home / "bub-project"
+    project = bub.home / "bub-project"
     project.mkdir(exist_ok=True, parents=True)
     return project