bub 0.3.3__tar.gz → 0.3.4__tar.gz

bub-0.3.4/.gitignore

@@ -0,0 +1,147 @@
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.pdm-python
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Vscode config files
+.vscode/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Reference directory - ignore all reference projects
+reference/
+
+# Local legacy backups created during framework migrations
+backup/

{bub-0.3.3 → bub-0.3.4}/PKG-INFO

@@ -1,8 +1,12 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bub
-Version: 0.3.3
+Version: 0.3.4
 Summary: A common shape for agents that live alongside people.
-Author-Email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>, Yihong <zouzou0208@gmail.com>
+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
@@ -10,25 +14,22 @@ 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.4
+Requires-Dist: aiohttp>=3.13.3
 Requires-Dist: any-llm-sdk[anthropic]
-Requires-Dist: rich>=13.0.0
+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: loguru>=0.7.2
+Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rapidfuzz>=3.14.3
-Requires-Dist: aiohttp>=3.13.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"
+Requires-Dist: logfire>=4.31.0; extra == 'logfire'
 Description-Content-Type: text/markdown
 
 # Bub

{bub-0.3.3 → bub-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bub"
-version = "0.3.3"
+version = "0.3.4"
 description = "A common shape for agents that live alongside people."
 authors = [
     { name = "Chojan Shang", email = "psiace@apache.org" },
@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
+
 dependencies = [
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
@@ -63,30 +64,22 @@ dev = [
 ]
 
 [build-system]
-requires = [
-    "pdm-backend",
-]
-build-backend = "pdm.backend"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
 
-[tool.pdm.build]
-includes = [
-    "src/bub",
-    "src/skills",
-]
+[tool.hatch.build.targets.sdist]
+only-include = ["src/bub", "src/skills", "tests"]
+
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/bub", "src/skills"]
 
 [tool.vulture]
-ignore_names = [
-    "test_*",
-    "Test*",
-]
-paths = [
-    "src",
-]
+ignore_names = ["test_*", "Test*"]
+paths = ["src"]
 
 [tool.mypy]
-files = [
-    "src",
-]
+files = ["src"]
 disallow_untyped_defs = false
 disallow_any_unimported = false
 no_implicit_optional = true
@@ -100,48 +93,62 @@ exclude = [
 ]
 
 [tool.pytest.ini_options]
-testpaths = [
-    "tests",
-]
+testpaths = ["tests"]
 
 [tool.ruff]
 target-version = "py312"
 line-length = 120
 fix = true
 extend-exclude = [
-    "src/skills/**/scripts/*",
+    "src/skills/**/scripts/*"
 ]
 
 [tool.ruff.lint]
 select = [
+    # flake8-2020
     "YTT",
+    # flake8-bandit
     "S",
+    # flake8-bugbear
     "B",
+    # flake8-builtins
     "A",
+    # flake8-comprehensions
     "C4",
+    # flake8-debugger
     "T10",
+    # flake8-simplify
     "SIM",
+    # isort
     "I",
+    # mccabe
     "C90",
+    # pycodestyle
     "E",
     "W",
+    # pyflakes
     "F",
+    # pygrep-hooks
     "PGH",
+    # pyupgrade
     "UP",
+    # ruff
     "RUF",
+    # tryceratops
     "TRY",
 ]
 ignore = [
+    # LineTooLong
     "E501",
+    # DoNotAssignLambda
     "E731",
+    # Avoid noisy exception-message rule for CLI/tool errors
     "TRY003",
     "S603",
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = [
-    "S101",
-]
+"tests/*" = ["S101"]
 
 [tool.ruff.format]
 preview = true

{bub-0.3.3 → bub-0.3.4}/src/bub/__init__.py

@@ -5,4 +5,4 @@ from bub.hookspecs import hookimpl
 from bub.tools import tool
 
 __all__ = ["BubFramework", "hookimpl", "tool"]
-__version__ = "0.3.3"
+__version__ = "0.3.4"

{bub-0.3.3 → bub-0.3.4}/src/bub/builtin/agent.py

@@ -7,7 +7,8 @@ import inspect
 import re
 import shlex
 import time
-from collections.abc import Collection
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Collection, Coroutine, Iterable
+from contextlib import AsyncExitStack
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime
 from functools import cached_property
@@ -15,7 +16,15 @@ from pathlib import Path
 from typing import Any
 
 from loguru import logger
-from republic import LLM, AsyncTapeStore, TapeContext, ToolAutoResult, ToolContext
+from republic import (
+    LLM,
+    AsyncStreamEvents,
+    AsyncTapeStore,
+    StreamEvent,
+    StreamState,
+    TapeContext,
+    ToolContext,
+)
 from republic.tape import InMemoryTapeStore, Tape
 
 from bub.builtin.settings import AgentSettings, load_settings
@@ -29,6 +38,11 @@ from bub.utils import workspace_from_state
 
 CONTINUE_PROMPT = "Continue the task."
 HINT_RE = re.compile(r"\$([A-Za-z0-9_.-]+)")
+_CONTEXT_LENGTH_PATTERNS = re.compile(
+    r"context.{0,20}length|maximum.{0,20}context|token.{0,10}limit|prompt.{0,10}too long|tokens? > \d+ maximum",
+    re.IGNORECASE,
+)
+MAX_AUTO_HANDOFF_RETRIES = 1
 
 
 class Agent:
@@ -47,6 +61,25 @@ class Agent:
         llm = _build_llm(self.settings, tape_store, self.framework.build_tape_context())
         return TapeService(llm, self.settings.home / "tapes", tape_store)
 
+    @staticmethod
+    def _events_from_iterable(iterable: Iterable) -> AsyncStreamEvents:
+        async def generator() -> AsyncIterator:
+            for item in iterable:
+                yield item
+
+        return AsyncStreamEvents(generator())
+
+    @staticmethod
+    def _events_with_callback(
+        events: AsyncStreamEvents, callback: Callable[[], Coroutine[Any, Any, Any]]
+    ) -> AsyncStreamEvents:
+        async def generator() -> AsyncIterator[StreamEvent]:
+            async for event in events:
+                yield event
+            await callback()
+
+        return AsyncStreamEvents(generator(), state=events._state)
+
     async def run(
         self,
         *,
@@ -56,19 +89,33 @@ class Agent:
         model: str | None = None,
         allowed_skills: Collection[str] | None = None,
         allowed_tools: Collection[str] | None = None,
-    ) -> str:
+    ) -> AsyncStreamEvents:
         if not prompt:
-            return "error: empty prompt"
+            events = [
+                StreamEvent("text", {"delta": "error: empty prompt"}),
+                StreamEvent("final", {"text": "error: empty prompt", "ok": False}),
+            ]
+            return self._events_from_iterable(events)
+
         tape = self.tapes.session_tape(session_id, workspace_from_state(state))
         tape.context = replace(tape.context, state=state)
         merge_back = not session_id.startswith("temp/")
-        async with self.tapes.fork_tape(tape.name, merge_back=merge_back):
-            await self.tapes.ensure_bootstrap_anchor(tape.name)
-            if isinstance(prompt, str) and prompt.strip().startswith(","):
-                return await self._run_command(tape=tape, line=prompt.strip())
-            return await self._agent_loop(
+        stack = AsyncExitStack()
+        # the fork_tape context manager must not be exited until the last chunk of the stream is consumed.
+        # So we use an AsyncExitStack and inject a callback to the iterator.
+        await stack.enter_async_context(self.tapes.fork_tape(tape.name, merge_back=merge_back))
+        await self.tapes.ensure_bootstrap_anchor(tape.name)
+        if isinstance(prompt, str) and prompt.strip().startswith(","):
+            result = await self._run_command(tape=tape, line=prompt.strip())
+            events = self._events_from_iterable([
+                StreamEvent("text", {"delta": result}),
+                StreamEvent("final", {"text": result, "ok": True}),
+            ])
+        else:
+            events = await self._agent_loop(
                 tape=tape, prompt=prompt, model=model, allowed_skills=allowed_skills, allowed_tools=allowed_tools
             )
+        return self._events_with_callback(events, callback=stack.aclose)
 
     async def _run_command(self, tape: Tape, *, line: str) -> str:
         line = line[1:].strip()
@@ -118,7 +165,7 @@ class Agent:
         model: str | None = None,
         allowed_skills: Collection[str] | None = None,
         allowed_tools: Collection[str] | None = None,
-    ) -> str:
+    ) -> AsyncStreamEvents:
         next_prompt: str | list[dict] = prompt
         display_model = model or self.settings.model
         await self.tapes.append_event(
@@ -131,34 +178,61 @@ class Agent:
                 "allowed_tools": list(allowed_tools) if allowed_tools else None,
             },
         )
+        state = StreamState()
+        iterator = self._stream_events_with_auto_handoff(
+            tape=tape,
+            prompt=next_prompt,
+            state=state,
+            model=model,
+            allowed_skills=allowed_skills,
+            allowed_tools=allowed_tools,
+        )
+        return AsyncStreamEvents(iterator, state=state)
+
+    async def _stream_events_with_auto_handoff(
+        self,
+        tape: Tape,
+        prompt: str | list[dict],
+        state: StreamState,
+        model: str | None = None,
+        allowed_skills: Collection[str] | None = None,
+        allowed_tools: Collection[str] | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        auto_handoff_remaining = MAX_AUTO_HANDOFF_RETRIES
+        display_model = model or self.settings.model
+        next_prompt = prompt
         for step in range(1, self.settings.max_steps + 1):
             start = time.monotonic()
+            outcome = _ToolAutoOutcome(kind="text", text="", error="")
             logger.info("loop.step step={} tape={} model={}", step, tape.name, display_model)
             await self.tapes.append_event(tape.name, "loop.step.start", {"step": step, "prompt": next_prompt})
-            try:
-                output = await self._run_tools_once(
-                    tape=tape,
-                    prompt=next_prompt,
-                    model=model,
-                    allowed_skills=allowed_skills,
-                    allowed_tools=allowed_tools,
-                )
-            except Exception as exc:
-                elapsed_ms = int((time.monotonic() - start) * 1000)
-                await self.tapes.append_event(
-                    tape.name,
-                    "loop.step",
-                    {
-                        "step": step,
-                        "elapsed_ms": elapsed_ms,
-                        "status": "error",
-                        "error": f"{exc!s}",
-                        "date": datetime.now(UTC).isoformat(),
-                    },
-                )
-                raise
-
-            outcome = _resolve_tool_auto_result(output)
+            output = await self._run_once(
+                tape=tape,
+                prompt=next_prompt,
+                model=model,
+                allowed_skills=allowed_skills,
+                allowed_tools=allowed_tools,
+            )
+            async for event in output:
+                yield event
+                if event.kind == "error":
+                    elapsed_ms = int((time.monotonic() - start) * 1000)
+                    await self.tapes.append_event(
+                        tape.name,
+                        "loop.step",
+                        {
+                            "step": step,
+                            "elapsed_ms": elapsed_ms,
+                            "status": "error",
+                            "error": event.data.get("message", ""),
+                            "date": datetime.now(UTC).isoformat(),
+                        },
+                    )
+                elif event.kind == "final":
+                    outcome = _resolve_tool_auto_result(event.data)
+
+            state.error = output.error
+            state.usage = output.usage
             elapsed_ms = int((time.monotonic() - start) * 1000)
             if outcome.kind == "text":
                 await self.tapes.append_event(
@@ -171,7 +245,7 @@ class Agent:
                         "date": datetime.now(UTC).isoformat(),
                     },
                 )
-                return outcome.text
+                return
             if outcome.kind == "continue":
                 if "context" in tape.context.state:
                     next_prompt = f"{CONTINUE_PROMPT} [context: {tape.context.state['context']}]"
@@ -188,6 +262,35 @@ class Agent:
                     },
                 )
                 continue
+
+            # Check if this is a context-length error that can be recovered via auto-handoff
+            if auto_handoff_remaining > 0 and _is_context_length_error(outcome.error):
+                auto_handoff_remaining -= 1
+                logger.warning(
+                    "auto_handoff: context length exceeded, performing automatic handoff. tape={} step={}",
+                    tape.name,
+                    step,
+                )
+                await self.tapes.handoff(
+                    tape.name,
+                    name="auto_handoff/context_overflow",
+                    state={"reason": "context_length_exceeded", "error": outcome.error},
+                )
+                await self.tapes.append_event(
+                    tape.name,
+                    "loop.step",
+                    {
+                        "step": step,
+                        "elapsed_ms": elapsed_ms,
+                        "status": "auto_handoff",
+                        "error": outcome.error,
+                        "date": datetime.now(UTC).isoformat(),
+                    },
+                )
+                # Retry with original prompt — the handoff anchor will truncate history
+                next_prompt = prompt
+                continue
+
             await self.tapes.append_event(
                 tape.name,
                 "loop.step",
@@ -212,7 +315,7 @@ class Agent:
         expanded_skills = set(HINT_RE.findall(prompt)) & set(skill_index.keys())
         return render_skills_prompt(list(skill_index.values()), expanded_skills=expanded_skills)
 
-    async def _run_tools_once(
+    async def _run_once(
         self,
         *,
         tape: Tape,
@@ -220,7 +323,7 @@ class Agent:
         model: str | None = None,
         allowed_tools: Collection[str] | None = None,
         allowed_skills: Collection[str] | None = None,
-    ) -> ToolAutoResult:
+    ) -> AsyncStreamEvents:
         prompt_text = prompt if isinstance(prompt, str) else _extract_text_from_parts(prompt)
         if allowed_tools is not None:
             allowed_tools = {name.casefold() for name in allowed_tools}
@@ -232,8 +335,8 @@ class Agent:
         else:
             tools = list(REGISTRY.values())
         async with asyncio.timeout(self.settings.model_timeout_seconds):
-            return await tape.run_tools_async(
-                prompt=prompt,  # republic accepts list content parts at runtime
+            return await tape.stream_events_async(
+                prompt=prompt,
                 system_prompt=self._system_prompt(prompt_text, state=tape.context.state, allowed_skills=allowed_skills),
                 max_tokens=self.settings.max_tokens,
                 tools=model_tools(tools),
@@ -260,15 +363,12 @@ class _ToolAutoOutcome:
     error: str = ""
 
 
-def _resolve_tool_auto_result(output: ToolAutoResult) -> _ToolAutoOutcome:
-    if output.kind == "text":
-        return _ToolAutoOutcome(kind="text", text=output.text or "")
-    if output.kind == "tools" or output.tool_calls or output.tool_results:
+def _resolve_tool_auto_result(final_data: dict[str, Any]) -> _ToolAutoOutcome:
+    if (text := final_data.get("text")) is not None:
+        return _ToolAutoOutcome(kind="text", text=text)
+    if final_data.get("tool_calls") or final_data.get("tool_results"):
         return _ToolAutoOutcome(kind="continue")
-    if output.error is None:
-        return _ToolAutoOutcome(kind="error", error="tool_auto_error: unknown")
-    error_kind = getattr(output.error.kind, "value", str(output.error.kind))
-    return _ToolAutoOutcome(kind="error", error=f"{error_kind}: {output.error.message}")
+    return _ToolAutoOutcome(kind="error", error="unknown error")
 
 
 def _build_llm(settings: AgentSettings, tape_store: AsyncTapeStore, tape_context: TapeContext) -> LLM:
@@ -318,6 +418,11 @@ def _parse_args(args_tokens: list[str]) -> Args:
     return Args(positional=positional, kwargs=kwargs)
 
 
+def _is_context_length_error(error_msg: str) -> bool:
+    """Check whether an error message indicates a context-length / prompt-too-long failure."""
+    return bool(_CONTEXT_LENGTH_PATTERNS.search(error_msg))
+
+
 def _extract_text_from_parts(parts: list[dict]) -> str:
     """Extract text content from multimodal content parts."""
     return "\n".join(p.get("text", "") for p in parts if p.get("type") == "text")