Skip to content
Docs Pydantic Docs

Host Functions

Host functions are one of three ways sandboxed code reaches anything outside the sandbox. The others, host objects and filesystem mounts, are specialised forms of the same idea.

When sandboxed code reads a name it never defined, execution suspends. The host resolves the name — usually by running a real function — and execution resumes with the result. The interpreter never calls out; it stops and waits to be told what happened.

The basics

from pydantic_monty import Monty


def get_temperature(city: str) -> float:
    return 21.5


with Monty() as pool:
    with pool.checkout() as session:
        result = session.feed_run(
            "f'{get_temperature(\"London\")} degrees'",
            external_lookup={'get_temperature': get_temperature},
        )
        print(result)
        #> 21.5 degrees

external_lookup maps names to host values. A callable entry becomes a function the sandbox can call. Any other value is converted and returned when the name is read:

from pydantic_monty import Monty

with Monty() as pool:
    with pool.checkout() as session:
        cfg = {'retries': 3}
        print(session.feed_run('cfg["retries"]', external_lookup={'cfg': cfg}))
        #> 3

A name that is not in external_lookup raises NameError inside the sandbox:

from pydantic_monty import Monty, MontyRuntimeError

with Monty() as pool:
    with pool.checkout() as session:
        try:
            session.feed_run('missing()')
        except MontyRuntimeError as exc:
            print(exc.display(format='type-msg'))
            #> NameError: name 'missing' is not defined

inputs versus external_lookup

Both put host values in front of the sandbox, but they differ in when:

inputsexternal_lookup
Boundeagerly, before the snippet runslazily, when the name is read
Convertedevery entry, used or notonly what the code touches
Callablesa reference, not a host functionbecome host functions
Missing namenot applicableNameError in the sandbox

A name present in both is served by the eager inputs binding. Lookup only runs for undefined names; it does not override builtins. See host-function proxies for caching and rebinding rules.

Pass host functions through external_lookup. A callable in inputs binds only a reference carrying the callable’s __name__, and calling it resolves that name through external_lookup — so inputs={'f': double} alone raises NameError: name 'double' is not defined on f(2).

Prefer inputs for the small, always-needed values the code was written around, and external_lookup for the tool surface — a model that writes code calling ten of your tools only pays for the ones it actually calls.

Arguments and return values

Positional and keyword arguments pass through as written:

from pydantic_monty import Monty


def report(name, *, level='info', **extra):
    return f'{name} {level} {extra}'


with Monty() as pool:
    with pool.checkout() as session:
        code = "report('x', level='warn', code=7)"
        print(session.feed_run(code, external_lookup={'report': report}))
        #> x warn {'code': 7}

Return values must be types Monty can represent — the same set inputs and external_lookup accept, listed under which values cross the boundary. Arguments come the other way, out of the sandbox. A sandbox-defined class instance arrives as a read-only MontyClassProxy; see host objects. A builtin function or a non-data type object arrives as a MontyStdTypeProxy naming it, never the host’s own open or exec; type is the one builtin function that arrives as the host class. Not every value crosses unchanged: unsupported sandbox values become strings, and cycles and deeply nested values are truncated. See host-value limitations for conversion failures, identity rules and size caps.

Raising into the sandbox

An exception raised by a host function crosses the boundary and behaves like an ordinary Python exception inside the sandbox, so sandboxed code can catch it:

from pydantic_monty import Monty


def fetch(url: str) -> str:
    raise ValueError('bad url')


code = """
try:
    fetch('nope')
except ValueError as e:
    result = f'caught: {e}'
result
"""

with Monty() as pool:
    with pool.checkout() as session:
        print(session.feed_run(code, external_lookup={'fetch': fetch}))
        #> caught: bad url

If the sandbox does not catch it, feed_run raises MontyRuntimeError with the sandbox traceback. Only the exception types Monty implements can cross; the type name is what carries over, not your exception class. JavaScript uses error.name; an unrecognised name becomes RuntimeError. Host tracebacks are not preserved.

Async host functions

With AsyncMonty, callables in external_lookup may be coroutine functions. They are awaited on your event loop, so blocking work inside one blocks it exactly as it would anywhere else in your async code — what AsyncMonty moves off the loop is worker I/O, not your callbacks. In JavaScript every host function may be async, and there is no separate pool class. asyncio.gather inside the sandbox lets several run concurrently:

import asyncio

from pydantic_monty import AsyncMonty


async def fetch(url: str) -> str:
    await asyncio.sleep(0.01)
    return f'contents of {url}'


code = """
import asyncio

results = await asyncio.gather(fetch('a'), fetch('b'))
len(results)
"""


async def main():
    async with AsyncMonty() as pool:
        async with pool.checkout() as session:
            print(await session.feed_run(code, external_lookup={'fetch': fetch}))
            #> 2


asyncio.run(main())

The sync Monty cannot drive coroutine host functions — use AsyncMonty, or resolve the pending futures by hand with feed_start.

Importing host modules

Imports of unknown modules ask the host for them. Pass external_modules to checkout() (externalModules in JavaScript): an imported module stays bound for the session, and the mapping is read live, so a module added to it later is importable by later feeds. It maps import names to ExternalModule values holding the module’s attributes and its optional .pyi type stub:

from pydantic_monty import ExternalModule, Monty


def add(a: int, b: int) -> int:
    return a + b


code = """
import tools
from tools import add

tools.add(1, 2) + add(3, 4)
"""

tools = ExternalModule({'add': add})

with Monty() as pool:
    with pool.checkout(external_modules={'tools': tools}) as session:
        print(session.feed_run(code))
        #> 10

An entry’s attrs dict (a plain object in JavaScript) is copied when the ExternalModule is made, and the module imports as a module object whose attributes are its public items, those whose keys do not start with _. Python module objects are rejected because they would also expose their imports; a dict explicitly selects attributes. In JavaScript a plain object is one whose prototype is Object.prototype or null, so a module namespace (import * as tools) qualifies while an instance of another class does not. A callable attribute becomes a host function named <module>.<attr>, dispatched like an external_lookup entry: a JavaScript promise is awaited, and a Python coroutine needs AsyncMonty (the sync Monty raises RuntimeError). Any other attribute is converted when the module is imported, so a ClassInstance among them routes its methods back to the wrapped object. The constructor checks attrs (a dict with identifier keys, nested modules under valid module names) and raises TypeError or ValueError there. A mapping entry is checked when a snippet first imports it: a value that is neither an ExternalModule nor a factory is refused with TypeError, a bad name with ValueError, and an entry under a sandbox module’s name is never reached. A zero-argument factory returning an ExternalModule runs when a feed first needs the module: for an import, a stub request, or a function call through a restored binding. Its result stands for the module for the rest of the session, so a module no feed imports costs nothing to offer. Under AsyncMonty it may return an awaitable, and in JavaScript a promise; the sync Monty raises RuntimeError for an awaitable. Factory exceptions and invalid return values raise at the requesting import, stub request or call, and the next use runs the factory again. from tools import add reads the attribute of that object and raises ImportError for a name it does not have. An import of a module absent from external_modules raises ModuleNotFoundError; the sandbox’s own modules, json or math, are never looked up here. Every import statement asks again: the sandbox has no module cache, and a module bound by an earlier feed is a plain global. Each import sends the entry the mapping holds at that moment, so replacing an entry changes what the next import binds, while a module’s own attrs never change after construction. The bound value is a module object: type(tools) is module, a missing attribute raises AttributeError: module 'tools' has no attribute 'x', and a module returned to the host arrives as an ExternalModule with the id it imported with and the values the sandbox holds, a host function among them as its dotted name. See modules for the remaining differences.

Module names are identifiers. An ExternalModule attribute defines a submodule: ExternalModule({'sub': ExternalModule(...)}) in Python or new ExternalModule({ sub: new ExternalModule(...) }) in JavaScript. It supports import pkg.sub, import pkg.sub as s, from pkg import sub and from pkg.sub import add. Its host functions use dotted names such as pkg.sub.add. Missing submodules raise ModuleNotFoundError: No module named 'pkg.nope'. Submodules must be values, not factories, because they cross with their parent. import pkg.x requires x to be a submodule: any other attribute raises ModuleNotFoundError, as in CPython.

The bindings answer two OS calls from external_modules, before mounts or os:

  • import requests the top-level module name and returns its value; not_found raises ModuleNotFoundError. Dotted imports read subsequent components as attributes.
  • import_stubs requests stubs for imported host modules the session has not asked about, once before type checking. Return a dict of dotted paths to .pyi sources, including submodules, with None for missing stubs.

A host driving suspensions itself answers both like any other OS call. To type-check code that imports a host module, give the entry its stubs; see type checking.

Driving suspensions yourself

feed_run answers every suspension for you and returns only the final value. feed_start hands each suspension back as a snapshot so you can log it, rate-limit it, require approval for it, or serialize it and continue tomorrow:

from pydantic_monty import FunctionSnapshot, Monty, MontyComplete

with Monty() as pool:
    with pool.checkout() as session:
        snapshot = session.feed_start('greet(name) + "!"', inputs={'name': 'Ada'})
        assert isinstance(snapshot, FunctionSnapshot)
        print(snapshot.function_name, snapshot.args)
        #> greet ('Ada',)
        result = snapshot.resume({'return_value': 'hello Ada'})
        assert isinstance(result, MontyComplete)
        print(result.output)
        #> hello Ada!

resume also takes {'exception': SomeError('...')} to raise into the sandbox, or {'exc_type': 'ValueError', 'message': '...'} when you only have the type by name. In JavaScript resume(value) takes the return value directly and resumeError(err) raises. Each snapshot’s position locates the suspending expression in the source; see where execution stopped. See snapshots for the full set of snapshot kinds.

Designing a safe tool surface

Monty guarantees the sandbox reaches nothing you did not hand it. It cannot guarantee that what you handed it is safe, because a host function runs in your process with your process’s authority.

  • Validate arguments as untrusted input. A host function taking a path, a URL, a SQL fragment or a shell string is a filesystem, network, database or shell primitive that you built. The model writing the code is not adversarial by assumption, but the code it writes is not reviewed.
  • Keep the surface narrow. read_customer(id) is a tool; read_file(path) is a filesystem.
  • Prefer mounts for file access. Mounts already enforce canonicalization, boundary checks and symlink rejection. A hand-rolled read_file host function does not.
  • Make callbacks idempotent if you plan to restore snapshots across a restart. When a suspended session is dumped while the host is answering a call, restoring it re-announces that call and it runs again.