Skip to content

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 invoke
from 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:

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(*local_config_hooks: Hook | ConfigOverride, **inputs: object) -> object

Run 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 that inputs do not propagate to sub-invokes — use the scope context 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 a ConfigOverride is present, there can be at most one. Any hooks and config override passed as arguments to invoke are local: they apply only to that invoke and do not propagate to sub-invokes. Use a hook or config override as a context manager around invoke for it to propagate to sub-invokes.

Returns

  • object — The value the agent returned from the REPL session.
async ainvoke(*local_config_hooks: Hook | ConfigOverride, **inputs: object) -> object

Async 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(*, llm: BaseLLM | UnsetType = UNSET, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> None

Configure 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 — a BaseLLM such as LiteLLM(model="openai/gpt-5-mini", temperature=0.7). LiteLLM is the default; GitHubCopilotLLM and SGLangLLM also ship (see jaz.llm), and subclassing BaseLLM adds your own. The constructor is the whole surface: the model id, 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 — a BaseREPL such as PythonREPL(exec_timeout=60). Its constructor takes exec_timeout, exec_memory_limit (process-RSS ceiling in bytes, enforced independently of exec_timeout), the sandbox allow-lists, and the rest of the REPL’s settings (see PythonREPL).
  • protocol (BaseProtocol | UnsetType) (default: UNSET) — The LLM↔REPL codec — a BaseProtocol such as CodeOnlyProtocol(max_invoke_input_length=20000). Its constructor takes the *_template prompt-template names, max_invoke_input_length, max_repl_output_length and subinvoke_description.

Examples

jaz.configure(repl=PythonREPL(exec_timeout=60))
jaz.configure(llm=LiteLLM(model="openai/gpt-5-mini", temperature=0.7))

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 nested jaz.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",
)
__init__(*, llm: BaseLLM | UnsetType = UNSET, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> None
apply_to(config: Config) -> Config

Return 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() -> Config

Get 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 until configure names a backend; the message carries the call that does it.

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.

__init__(*, llm: BaseLLM, repl: BaseREPL[Any] | UnsetType = UNSET, protocol: BaseProtocol | UnsetType = UNSET) -> None

Construct 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.

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): ... rebinds fs to B inside the inner block and restores A on exit (standard with semantics).
  • An explicit kwarg colliding with a scoped name raises. Passing a scoped name again as an invoke kwarg raises a conflict ValueError at invoke time. To give one invoke a different value for a scoped name, nest another scope block 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): fork inherits it — the names survive, the objects in them may not — while spawn and forkserver start clean, so an invoke there runs unscoped. Nothing serializes a scope across; bind one inside the worker.
add_template_loader(loader: BaseLoader) -> None

Make 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 all

Your 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) — Any jinja2.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 reserved jaz/ 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 the TemplateAssertionError subclass, 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 bare RecursionError naming 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.