jaz
New to JAZ? This is generated API reference. Start with the docs and the concepts overview.
The top-level API. Import these directly from jaz.
An agent runs as a conversation with a Python REPL: the LLM writes code, sees what it
evaluated to, and iterates until it finishes with a native return (or raise):
from jaz import invokefrom jaz.hooks import ReturnType
total = invoke(instruction="Return the sum of the numbers", numbers=[1, 2, 3])num_people: int = invoke(ReturnType(int), question="How many people are there on Earth?")The v1 public API is exactly __all__ below, in two parts.
Core symbols — reached flat as jaz.<name>:
invoke/ainvoke— run an agent on the given inputs and return its result.configure/ConfigOverride/get_config— set the global defaults, override them for a scope or a single call, and read the effective config.scope— bind variables that propagate into sub-invokes.
Public submodules — reached as jaz.<mod>.<name>, not re-exported flat:
jaz.hooks— theHookprimitive and the built-in hooks (ReturnType,PrintLogger,BudgetPool,IterationLimit, …), plus thejaz.hooks.eventsandjaz.hooks.effectsvocabularies a handler receives and returns.jaz.repl— the REPL component: the baseBaseREPLand defaultPythonREPL, plus the execution-result taxonomy (ExecResultand its members).jaz.llm— the LLM-backend component: the baseBaseLLM, theLLMResponseit returns, the three shipped backends (LiteLLMby default, plusGitHubCopilotLLMandSGLangLLM), and the chat-format seam.jaz.protocol— the interaction-protocol component: the baseBaseProtocoland defaultCodeOnlyProtocol.jaz.exceptions— the exception taxonomy every JAZ failure belongs to.
Everything outside __all__ lives in a _-prefixed module and is not part of the
official public API. It is reachable — Python has no enforcement — but it is internal, and
may change or be removed without notice.
invoke
Section titled “invoke”invoke(*local_config_hooks: Hook | ConfigOverride, **inputs: object) -> objectRun a REPL-based agent on the given inputs.
A call invoke(name1=input1, name2=input2, ...) (with arbitrary names) shows the agent
the description of each input_i along with its name_i, and binds each input_i
to a variable name_i in the REPL. Inputs typically include the prompt (e.g. instructions="..."
or task="..."), input data (e.g. df=pd.DataFrame(...)), and tools (e.g.
def web_search(...): ...; invoke(..., web_search=web_search)).
An input’s description is its str(), with these exceptions. A function is described by
its signature and docstring; an object with __call__ by those and its public members; a
class by its constructor signature, docstring and public members; a module by its docstring
and public names; and an object that defines neither __str__ nor __repr__, or a
SimpleNamespace, by its class docstring and public attributes. A value inside a list, a
dict or a dataclass shows as its repr(). So to change what the agent sees, write the
docstring of a function, class, module or callable object (whose __str__ is not used),
define __str__ on any other object, and define __repr__ on one that goes inside a
container.
Pass a ReturnType hook as the first positional arg (e.g.
invoke(ReturnType(int), ...)) to narrow the static return type and enforce it at
runtime.
To allow the agent to write async code with top-level await in its REPL, use
ainvoke instead.
Parameters
**inputs(object) (default:{}) — The inputs passed to the agent. Note thatinputsdo not propagate to sub-invokes — use thescopecontext manager to pass in variables that propagate to sub-invokes.*local_config_hooks(Hook | ConfigOverride) (default:()) — Optional hooks and config override as leading positional arguments. If aConfigOverrideis present, there can be at most one. Any hooks and config override passed as arguments toinvokeare local: they apply only to thatinvokeand do not propagate to sub-invokes. Use a hook or config override as a context manager aroundinvokefor it to propagate to sub-invokes.
Returns
object— The value the agent returned from the REPL session.
ainvoke
Section titled “ainvoke”async ainvoke(*local_config_hooks: Hook | ConfigOverride, **inputs: object) -> objectAsync version of invoke. Runs the agent loop without blocking the event loop,
enabling concurrent execution via asyncio.gather or similar patterns. It also lets the
agent write async code with top-level await in its REPL, which invoke does not.
Arguments are identical to invoke — see it for full documentation.
configure
Section titled “configure”configure(*, llm: BaseLLM | UnsetType = UNSET, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> NoneConfigure the global default JAZ framework settings.
This modifies the global default configuration that is used when no context-local override is active.
Settings are grouped by component. Each group takes the configured component itself, whose constructor is the schema for that group’s settings.
Setting a group replaces it. A group names the whole component, so you restate it completely rather than adjusting one of its settings in place.
Parameters
llm(BaseLLM | UnsetType) (default:UNSET) — How JAZ talks to the model — aBaseLLMsuch asLiteLLM(model="openai/gpt-5-mini", temperature=0.7).LiteLLMis the default;GitHubCopilotLLMandSGLangLLMalso ship (seejaz.llm), and subclassingBaseLLMadds your own. The constructor is the whole surface: themodelid, the backend’s own settings (base_url,api_key), the retry policy (retry_policy=RetryPolicy(...)), and any per-request default (temperature,max_tokens,reasoning_effort, …) it passes through to the provider API. Anything the constructor does not name becomes a per-request default, so a backend gains a setting simply by declaring it.repl(BaseREPL[Any] | UnsetType) (default:UNSET) — The REPL execution layer — aBaseREPLsuch asPythonREPL(exec_timeout=60). Its constructor takesexec_timeout,exec_memory_limit(process-RSS ceiling in bytes, enforced independently ofexec_timeout), the sandbox allow-lists, and the rest of the REPL’s settings (seePythonREPL).protocol(BaseProtocol | UnsetType) (default:UNSET) — The LLM↔REPL codec — aBaseProtocolsuch asCodeOnlyProtocol(max_invoke_input_length=20000). Its constructor takes the*_templateprompt-template names,max_invoke_input_length,max_repl_output_lengthandsubinvoke_description.
Examples
jaz.configure(repl=PythonREPL(exec_timeout=60))jaz.configure(llm=LiteLLM(model="openai/gpt-5-mini", temperature=0.7))ConfigOverride
Section titled “ConfigOverride”Temporary Config overrides, usable two ways — exactly mirroring how a hook is
used either as a with block or a positional hook argument.
- As a context manager (
with ConfigOverride(...):) it is dynamically scoped: the overrides apply for the duration of the block and propagate to every nestedjaz.invoke()in it. - Passed positionally to
jaz.invoke()it is local (a “shallow” override): it applies to that one invoke only and is not propagated to sub-invokes spawned inside it — those see the un-overridden ambient config.
Also like a hook, a single instance is active in at most one with scope at a time:
re-entering it while already active — nested (with co: with co:) or concurrently from
another thread — raises ConfigOverrideActivationError. The usual with ConfigOverride(...): constructs a fresh instance and is unaffected; sequential reuse of
one instance is fine.
Contrast with jaz.configure(...), which sets the process-wide global default.
Takes the same explicit keyword-only fields as configure (llm / repl /
protocol); an unknown field is a TypeError at construction. Field values are
validated when the override is applied and the resulting config is built.
Examples
# Dynamically scoped — propagates to nested invokes:with ConfigOverride(protocol=CodeOnlyProtocol(max_repl_output_length=20000)): invoke(...)
# Local to one invoke — passed POSITIONALLY. A nested invoke the agent makes uses the# ambient config, not the override:invoke( ConfigOverride(protocol=CodeOnlyProtocol(max_repl_output_length=5000)), task="task",)ConfigOverride.__init__
Section titled “ConfigOverride.__init__”__init__(*, llm: BaseLLM | UnsetType = UNSET, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> NoneConfigOverride.apply_to
Section titled “ConfigOverride.apply_to”apply_to(config: Config) -> ConfigReturn config with these overrides applied.
The input config is never mutated. Its unoverridden component objects
(llm/repl/protocol) stay shared by identity with config rather than being
duplicated. An override with no fields set returns config itself, there being nothing
to apply and nothing a caller could write to the result.
get_config
Section titled “get_config”get_config() -> ConfigGet the current effective configuration.
Returns
Config— The current Config instance
Raises
ValueError— if no LLM is configured. A config is complete by construction, so there is none to return untilconfigurenames a backend; the message carries the call that does it.
Config
Section titled “Config”JAZ framework configuration, grouped by architectural component.
llm(BaseLLM) — how JAZ talks to the LLM. There is no default model, so this one has no default and must be named.repl(BaseREPL) — how agent code executes.protocol(BaseProtocol) — the LLM↔REPL codec (prompts + parsing).
Those three are the whole surface; there is no fourth, top-level group, and naming an unknown keyword raises.
The surface is nested-only — there are no flat config.<option> aliases. Set via the
grouped configure/ConfigOverride shape, passing the configured component:
configure(repl=PythonREPL(exec_timeout=30)). Configuration written as data — a
settings file, an eval YAML — is compiled into components before it reaches here, so config
itself only ever holds the built object.
Setting a group replaces it. A group names the whole component, so there is no partial update of one component’s settings.
Config.__init__
Section titled “Config.__init__”__init__(*, llm: BaseLLM, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> NoneConstruct a Config from the grouped shape, passing the configured component.
llm must be named: there is no default model, so there is no config without one.
repl and protocol fall back to their defaults when omitted.
Explicit arguments are the only source of configuration: there is no ambient layer underneath them, so a Config built here is fully determined by its call site.
UnsetType
Section titled “UnsetType”Bases: enum.Enum
The “no value supplied” sentinel’s type — a marker distinct from None.
A named type rather than a bare object() so it can be written in annotations
(T | UnsetType), and so x is UNSET narrows the type for a type checker.
scope(**values: object) -> Iterator[None]Bind values as ambient inputs for all enclosed jaz.invoke calls.
Equivalent to passing each value as a kwarg to every invoke (and every nested
invoke) within the with block — but without manual threading:
from jaz import invoke, scope
with scope(fs=fs_tools, web=web_client): invoke(task="analyze logs", target_date="2026-05-30") # fs and web are bound in the REPL of this invoke and all recursive # sub-invokes. On the other hand, task and target_date are local to this # top-level invoke and do not propagate to sub-invokes.jaz.scope is user/host-facing. It is not bound in the agent’s REPL (which sees only
the invoke tool); a host that wants an agent to open scopes from its own REPL passes
scope in as an ordinary input.
Semantics:
- Kwargs-only. Names must be valid Python identifiers (they land as REPL
globals); splat a dynamic mapping with
scope(**d). - Inner shadows outer on the same name. Nesting
with scope(fs=A): with scope(fs=B): ...rebindsfstoBinside the inner block and restoresAon exit (standardwithsemantics). - An explicit kwarg colliding with a scoped name raises. Passing a scoped
name again as an invoke kwarg raises a conflict
ValueErrorat invoke time. To give one invoke a different value for a scoped name, nest anotherscopeblock around it rather than re-passing the kwarg. - No partial unbinding. There is no way to remove a name for a block; an inner scope can only shadow it with a new value.
- Process boundaries. A scope is a ContextVar binding, so whether a child process
sees one follows the start method (https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods):
forkinherits it — the names survive, the objects in them may not — whilespawnandforkserverstart clean, so an invoke there runs unscoped. Nothing serializes a scope across; bind one inside the worker.
add_template_loader
Section titled “add_template_loader”add_template_loader(loader: BaseLoader) -> NoneMake a Jinja loader’s templates addressable by name in JAZ’s prompt templates.
This is how you supply your own prompt: add a loader, then name one of its templates
in the setting you want to replace — CodeOnlyProtocol(system_prompt_template=...),
PythonREPL(repl_description_template=...), and their siblings all resolve names through
the environment this adds to.
Any loader works, so templates may live wherever suits you:
jaz.add_template_loader(FileSystemLoader("/home/me/prompts"))jaz.add_template_loader(PackageLoader("myapp", "prompts"))jaz.add_template_loader(DictLoader({"mine.jinja2": source})) # no files at allYour templates are rendered by JAZ’s environment, so they inherit its settings — notably
StrictUndefined, under which referencing a variable JAZ does not pass raises rather than
rendering empty. A shipped template is always addressable under the reserved jaz/ prefix
({% include "jaz/user_prompt.jinja2" %}), whatever a loader of yours is called.
Parameters
loader(BaseLoader) — Anyjinja2.BaseLoader.
Your names are yours: JAZ answers only jaz/<name>, so a template of your own called
system_prompt.jinja2 collides with nothing and is what that name resolves to.
Every template the loader can enumerate is compiled here, so a syntax error is reported at
this call rather than at the first render that needs it — including in a template of this
loader’s that another one {% extends %}, which compiling the child alone would not
catch. A loader that cannot enumerate (FunctionLoader) is added unchecked, and a
file it lists that cannot be read as text is skipped. Note a FileSystemLoader lists
every file in its directory, so keep non-templates out of one you add.
Adding a loader that is already in the chain does nothing, so a caller holding one loader may add it defensively without disturbing precedence. The check runs when it is added, so templates a mutable loader gains afterwards are never checked — validate those yourself.
Raises
ValueError— if the loader offers names under the reservedjaz/prefix, which JAZ answers first — those entries could never resolve.jinja2.TemplateSyntaxError— if one of the loader’s templates fails to parse or to compile. Failures the compiler reports rather than the parser raise theTemplateAssertionErrorsubclass, among them a duplicate{% block %}name and an unknown filter. Two more raise it that Jinja would not catch until render: more than one top-level{% extends %}, and templates that inherit from each other in a loop — the latter otherwise a bareRecursionErrornaming no template. Loop detection covers this loader’s own templates and only{% extends %}written as a literal: a loop closed through another loader, through a conditional or computed parent, or through{% include %}/{% import %}is not found.
The chain is process-wide, so two configurations cannot hold different templates under one
name — give them distinct names instead — and it does not cross a process boundary: a worker
started by multiprocessing or ProcessPoolExecutor must add it again.
The prompt-template guide lists the variables each template is passed and the blocks each shipped template exposes.