Runs Bub's code-mode run_code in Monty, a sandboxed Python interpreter written in Rust, instead of a Python subprocess. Its provide_environment hook wraps whatever environment the other plugins provide (Docker, local sandbox, or Bub's host environment), so only run_code changes. A mixin and a wrapper function are also available for your own environments.
Monty suspends the code at every call that leaves the sandbox and hands it to Bub, which runs it and resumes the code. So:
tools.<name>(...)calls still go through Bub's tool executor and hooks, as with the default runner;asyncio.gatherruns them concurrently.- File access (
pathlib.Path.read_text/write_text) goes through the environment'sread_text/write_text, so the code sees the same files asfs.*. - The
republicmodule is available, as with the default runner: its models call back into Bub, which runs them with its own credentials and settings. See Therepublicmodule. - The code cannot start processes, open sockets, read the host's environment variables or import third-party packages.
- Starting a run takes microseconds instead of a Python process start.
Requires Bub 0.5 or later. Only run_code changes: bash and fs.* keep running wherever the underlying environment runs them.
Chinese documentation: README.zh-CN.md
Monty runs a subset of Python. Code that model-written glue usually needs works: functions, closures, comprehensions, f-strings, try/except, simple classes and @dataclass, async/await with asyncio.gather, and much of json, re, datetime, collections, itertools, math, pathlib. It rejects class inheritance, match, generators (yield), async with, async for, del, method decorators (@property) and every third-party package. When code fails on unsupported syntax, the error tells the model it runs in Monty so it can rewrite the code. See Monty's limitations.
Use it when code-mode code is glue between tools; keep the default runner when the model needs pandas, numpy or other packages.
Bub's default runner gives code-mode code a republic module for media and model calls; this plugin provides the same module in Monty. Its model calls reach Bub as republic.<operation> calls on run_code's call_tool, with Republic values as {"$republic": ...} JSON objects, the same protocol as the default runner, so Bub serves them unchanged and the code never sees provider credentials.
from republic import Image, get_model, user
model = get_model() # the model running this session; or get_model("provider:model")
chart = Image("image/png", url="https://example.com/chart.png")
reply = await model.chat([user("Describe this chart.", chart)])
print(reply.text, reply.token_usage.total_tokens)Available: Image / Audio / Video, Message, system / user / assistant, get_model(spec=None).chat(...), get_embedding_model(spec).embed(...) / embed_many(...), get_decision_model(spec).decide(...) with republic.decisions.Noul / Choice / Score. Media in tools.* arguments and results crosses as Republic values too.
Differences from the default runner, which come from Monty:
republicis a preset global. Monty cannot import modules it does not ship, so before running the code the plugin rewritesimport republicandfrom republic[.decisions] import ...into assignments from that global, keeping line numbers.- No streaming:
model.stream(...)needsasync withandasync for, which Monty does not support. Useawait model.chat(...)for the whole response, and use models withoutasync with.
In the monty_env: section of ~/.bub/config.yml, or as environment variables BUB_MONTY_ENV_<KEY> (lists are JSON: BUB_MONTY_ENV_SESSIONS='["qq:*"]'). Restart Bub after a change.
monty_env:
sessions: ["qq:*"]
filesystem: read-only
max_memory_mb: 256| Key | Default | What it does |
|---|---|---|
sessions |
["*"] |
Globs over session ids (<channel>:<chat id>); others keep the environment other plugins provide, unwrapped |
filesystem |
read-write |
File access from the code: read-write, read-only or none |
max_memory_mb |
256 |
Heap limit per run; null for none |
max_recursion_depth |
1000 |
Maximum call stack depth |
max_suspensions |
10000 |
Maximum tool calls, file accesses and other host round trips per run |
max_processes |
CPU count | Monty worker processes per session |
The run time limit is run_code's own timeout_seconds.
The plugin's hook runs first (tryfirst), asks the other plugins for the session's environment (pluggy's subset_hook_caller), and wraps it with create_monty_environment. With bub-docker-env or bub-sandbox-env installed, bash and fs.* keep running in Docker or the sandbox, and run_code runs in Monty with file access through that environment. When no other plugin provides one, it wraps Bub's host environment. Sessions outside sessions get the other plugins' environment unchanged.
For your own environments:
from bub_monty_env import MontyCodeMixin, MontyOptions, create_monty_environment
# Wrap an instance: everything but run_code is delegated to it, and closing the
# wrapper closes it.
environment = create_monty_environment(MyEnvironment(...), MontyOptions(filesystem="read-only"))
# Or mix into a class: the mixin goes first.
class MyMontyEnvironment(MontyCodeMixin, MyEnvironment):
monty_options = MontyOptions(filesystem="read-only")MontyEnvironment is Bub's host environment with Monty run_code.
Lower-level pieces: run_code_in_monty(pool, code, ...) implements Environment.run_code on a pydantic_monty.AsyncMonty pool, and MontyCodeMixin.monty_os_handler() can be overridden to change what file access the code gets.
open()is not supported; the code reads and writes files withpathlib.Path.Path.exists,iterdir,mkdirand other file operations are not available.- Monty is young; behavior may differ from CPython in places the limitations page lists.
- Tool results cross into the sandbox as JSON-compatible data, as with the default runner.
Path.read_bytesis not available, so media from files needsdata=from elsewhere, ortools.attach_image(image="<path>")to let Bub load it.