Skip to content

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

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.

parse(llm_response: LLMResponse) -> str

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

response_format_description: str

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

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.

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, or None when this invoke may not spawn sub-invokes. Its presence is the single signal for both the invoke description and the delegation guidance.
  • repl_history_withheld (bool) — Whether a hook withheld __history__ from this invoke with WithholdREPLHistory. The history section renders when it is False and the REPL describes a record (repl_history_description is not None), 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.

get_subinvoke_description(subinvoke: Callable[..., object]) -> str

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

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 (see render_observation).
  • subinvoke_description: an authored description of the recursive invoke tool in place of the one derived from its closure (see get_subinvoke_description).
__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) -> None
parse(llm_response: LLMResponse) -> str

Take 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: str

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

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]) -> str

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