jaz.protocol
New to JAZ? This is generated API reference. Start with the docs and the concepts overview.
Public API of the jaz.protocol submodule (import from jaz.protocol, e.g. from jaz.protocol import ...).
One of the three pluggable components of an agent loop (BaseREPL × BaseProtocol ×
BaseLLM). Selected by configuring an instance: jaz.configure(protocol=...).
A protocol both decodes an LLM turn (parse) and encodes the messages sent back to
it (render_observation / render_initial_message_list).
BaseProtocol
Section titled “BaseProtocol”Bases: ABC
Codec between the LLM and the REPL — encode the session, decode the response.
Pluggable like the LLM backend: a protocol is selected by configuring an instance
(jaz.configure(protocol=...)). See CodeOnlyProtocol for the built-in
raw-code protocol.
Defines the decoder (parse), the encode primitives
(render_observation, render_initial_message_list), and the
prompt-text seam for the wire format (response_format_description).
All four are abstract. The __history__ record is the REPL’s, not the protocol’s: see
update_repl_history.
BaseProtocol.parse
Section titled “BaseProtocol.parse”parse(llm_response: LLMResponse) -> strDecode an LLM response into the code to execute.
Returns the extracted code.
llm_response is the whole LLMResponse, not a pre-extracted
content string: a protocol reads .content itself (str | None — None on a
content-less completion) and can also reach .raw_response for refusal /
finish_reason / tool_calls — what a tool-calling or refusal-aware protocol needs
to decode a turn the content string alone cannot express.
Write this method so that it never raises. There is no recoverable parse failure: the
loop catches nothing here, so any exception is terminal and ends the invoke — an agent
that emitted one bad message loses the whole run. Return your best reading instead,
including the message verbatim when you have none, and let the REPL judge it; that is
where malformed code surfaces anyway, as a SyntaxError inside a recoverable
Continue the model can react to. An empty message is empty code, i.e. a no-op turn.
BaseProtocol.response_format_description
Section titled “BaseProtocol.response_format_description”response_format_description: strThe description of the response format — the request half of the codec.
Returns the model-facing text that tells the LLM how to shape its response so that
parse can decode it (for the default: “respond with ONLY code, no fences”).
The system-prompt template splices this in verbatim as an opaque
{{ response_format_description }} block, so the accept half (parse) and the
request half (this) are owned by the same protocol and move together — a protocol
cannot instruct one wire format while parsing another. The template still owns the
surrounding wording and placement; only the format block itself belongs to the codec.
Must return a non-empty string: CodeOnlyProtocol refuses an empty or non-string
return with ValueError, as it does for every description seam, since the template
renders this block unconditionally.
BaseProtocol.render_observation
Section titled “BaseProtocol.render_observation”render_observation(exec_result: Continue) -> list[dict[str, Any]]Render a (continuing) REPL execution result into the next turn’s message(s).
Returns the observation as one or more ready messages — the seam speaks the LLM’s
own message shape directly rather than a bare str body. A message is an
OpenAI-shaped mapping, {"role": ..., "content": ...}, plus whatever extra keys
the configured provider accepts; JAZ neither validates nor closes the shape. The
common case is a single user message carrying the text body, which is the CodeOnlyProtocol
single-REPL path and the only shape any in-tree protocol returns. The list is
load-bearing for protocols whose observation is inherently multiple messages or a
multi-block message: one tool message per parallel tool call (OpenAI requires one
result per tool_call_id), or a single message carrying several tool_result /
image content blocks (Anthropic returns all parallel results together in one user
message). A str return could express neither.
The driver appends the returned messages verbatim — persisted history is pure protocol output, with no per-turn footer folded in. Hook prompt additions, when present, are the driver’s concern, not the protocol’s.
BaseProtocol.render_initial_message_list
Section titled “BaseProtocol.render_initial_message_list”render_initial_message_list(inputs: Mapping[str, object], scope: Mapping[str, object], repl: BaseREPL[Any], *, subinvoke: Callable[..., object] | None, repl_history_withheld: bool) -> list[dict[str, Any]]Encode the session opening into the initial message list (system + user).
Rendered once per session: the REPL self-description, safety guidance, and the
input blocks. There is no distinguished task argument — the task prompt is an
ordinary entry in inputs (conventionally named task), rendered as one
<name type="..."> block like any other input.
The response-format description (the “respond with ONLY code” block that is the
request half of what parse accepts) is owned by the protocol via
response_format_description and spliced into the system-prompt template as an opaque
{{ response_format_description }} block. The template still owns the surrounding wording and
layout, but the codec’s accept half (parse) and request half live in the same
protocol and cannot silently desync.
Hook prompt additions do not flow through this seam — the driver owns them, the same
symmetry render_observation has. The arguments are the genuine
rendering context the opener needs to render (not hook-effect outputs).
Parameters
inputs(Mapping[str, object]) — The invoke’s inputs, each rendered as an input block.scope(Mapping[str, object]) — Ambient scoped values (jaz.scope) in effect for this session.repl(BaseREPL[Any]) — The configured REPL, for its self-description.subinvoke(Callable[..., object] | None) — The bound sub-invoke function, orNonewhen this invoke may not spawn sub-invokes. Its presence is the single signal for both theinvokedescription and the delegation guidance.repl_history_withheld(bool) — Whether a hook withheld__history__from this invoke withWithholdREPLHistory. The history section renders when it isFalseand the REPL describes a record (repl_history_descriptionis notNone), and is omitted otherwise.
As with render_observation, the driver folds any hook AddInputs /
DropInputs into the REPL and prompt — not the protocol’s job.
BaseProtocol.get_subinvoke_description
Section titled “BaseProtocol.get_subinvoke_description”get_subinvoke_description(subinvoke: Callable[..., object]) -> strThe agent-facing description of the recursive sub-invoke tool (bound as invoke).
Rendered into the system prompt as the invoke catalog entry. Must return a non-empty
string; CodeOnlyProtocol refuses an empty or non-string return with ValueError,
since a bound tool described as nothing would render an empty block. The default introspects
the bound closure — its signature and docstring ARE the description, so the two cannot
drift. Not abstract, unlike response_format_description: this default is derived
from the tool itself rather than chosen, so there is no decision for an author to make
and forcing one would buy nothing.
A protocol overrides this to author the description explicitly — typically to advertise a
NARROWER surface than the closure actually supports. The motivating case is a
restrict_invoke_args-style guard that vetoes non-literal / positional-hook invoke
calls at runtime: the prompt should then describe an inputs-only signature even though the
closure still accepts hooks. Owning the words here — rather than swapping the executable
closure — keeps “what the tool can do” separable from “what the agent is told it can do”;
an overriding author owns keeping the two in step with the guard that motivates the
override.
CodeOnlyProtocol
Section titled “CodeOnlyProtocol”Bases: BaseProtocol
The protocol: the assistant message is the code (see the module docstring).
Its rendering settings are constructor parameters — the constructor is the only declaration of them, and of their defaults:
*_template: which Jinja template renders the system prompt and the user prompt.max_invoke_input_length/max_repl_output_length: truncation ceilings for rendered inputs and for REPL output. A truncated value keeps an even split of head and tail. The REPL appends a recoverable error’s traceback at the end of the turn’s output, so the retained tail carries the exception line; what a long turn can lose is the top of that traceback, and any error message the agent’s own code printed early (seerender_observation).subinvoke_description: an authored description of the recursiveinvoketool in place of the one derived from its closure (seeget_subinvoke_description).
CodeOnlyProtocol.__init__
Section titled “CodeOnlyProtocol.__init__”__init__(*, system_prompt_template: str = 'jaz/system_prompt.jinja2', user_prompt_template: str = 'jaz/user_prompt.jinja2', max_invoke_input_length: int = 50000, max_repl_output_length: int = 50000, subinvoke_description: str | None = None) -> NoneCodeOnlyProtocol.parse
Section titled “CodeOnlyProtocol.parse”parse(llm_response: LLMResponse) -> strTake the response as code, verbatim.
The message is the code — what the format instructions ask for and what the REPL receives. Nothing is unwrapped, extracted or repaired.
parse never fails. A truncated response, one with a prose preamble, or one carrying no
content at all reaches the REPL and surfaces there — a SyntaxError inside a
recoverable Continue for the first two, and a no-op turn for an empty one. Failing
here instead would move the failure from exec-time to parse-time and change which history
fields record it, for no gain to the agent.
An empty or whitespace-only message is therefore empty code, not an error. The agent is not told its turn produced nothing; it sees a blank observation and continues, and the turn still costs an iteration. That is the accepted trade for a protocol with no failure mode; a content-less completion is rare in practice.
CodeOnlyProtocol.response_format_description
Section titled “CodeOnlyProtocol.response_format_description”response_format_description: strReturn the response-format description (see BaseProtocol.response_format_description).
A constant: this protocol’s request format does not vary with its rendering settings. It
is the request half of the codec whose accept half is parse — the two are edited
together here so an instruction to “respond with ONLY code” can never drift from what
parse actually accepts.
CodeOnlyProtocol.render_observation
Section titled “CodeOnlyProtocol.render_observation”render_observation(exec_result: Continue) -> list[dict[str, Any]]Render a continuing REPL result into the next turn’s user message(s).
Returns a single user message whose content is the (abbreviated) output and nothing
else: no <repl_output> wrapper, no separate <error> block, no **REPL output (iteration #N):** header, no error-flag line, and no truncation advice.
The framing is gone entirely rather than merely simplified because output already holds
the whole agent-facing text (stdout on success; stdout + traceback, or the rendered
parse error, on a recoverable error). Every wrapper around it was restating in markup what
the text says on its own — including the success/error split, which the traceback in
output already announces, so exception stays pure metadata with no rendered surface
at all. The iteration number went with the header: the turn’s position is implicit in the
conversation, and __history__ is the addressable form for an agent that needs it.
CodeOnlyProtocol.get_subinvoke_description
Section titled “CodeOnlyProtocol.get_subinvoke_description”get_subinvoke_description(subinvoke: Callable[..., object]) -> strCodeOnlyProtocol.render_initial_message_list
Section titled “CodeOnlyProtocol.render_initial_message_list”render_initial_message_list(inputs: Mapping[str, object], scope: Mapping[str, object], repl: BaseREPL[Any], *, subinvoke: Callable[..., object] | None, repl_history_withheld: bool) -> list[dict[str, Any]]Build the [system, user] opener.
inputs (explicit **inputs kwargs) and scope (resolved jaz.scope)
arrive as SEPARATE mappings, so the two sections render directly from their own
dict — no merged namespace, no scoped_keys re-split. There is no separate
task argument anymore: the prompt is an ordinary input.