The guidance.py module

Summary

Functions

error_guidance	Classify an error code.
error_code_of	Return the error code of a result payload, or None for a success.
enrich_error_payload	Add retryable and next_action to an error payload in place.
enrich_result	Return a tool result with error guidance added; successes are returned unchanged.

Description

Uniform retryable / next_action guidance on tool error results.

Leaf tools report failures as {"status": "error", "error_code", "message"} (or {"ok": False, "error": ""}, or a typed error model). A host LLM still has to guess whether to retry and what to do next. enrich_result() adds:

• retryable: True only when the same call can succeed after waiting or after the named recovery step.

• next_action: one concrete recovery step, when the error class has one.

Values a tool already set are never overwritten, and successful results are returned unchanged. Error codes are classified by ordered name patterns, so new codes that follow the existing naming are covered automatically.

Module detail

guidance.error_guidance(error_code: str, message: str = '') → tuple[bool, str | None]

Classify an error code.

Parameters:

error_codestr

Machine-readable error code reported by the tool.

messagestr, default: “”

Human-readable error message; authentication failures are detected here.

Returns:

tuple[bool, str | None]

(retryable, next_action). next_action is None for unknown codes.

guidance.error_code_of(payload: Any) → str | None

Return the error code of a result payload, or None for a success.

Parameters:

payloadAny

Tool result as a mapping.

Returns:

str | None

The error_code (or error when ok is False), else None.

guidance.enrich_error_payload(payload: dict[str, Any]) → bool

Add retryable and next_action to an error payload in place.

A payload carrying input_request (a missing user decision with an argument name and optional options) is told to ask the user and call again.

Parameters:

payloaddict[str, Any]

Structured tool result.

Returns:

bool

Whether the payload was changed.

guidance.enrich_result(result: Any, *, trace_id: str | None = None) → Any

Return a tool result with error guidance added; successes are returned unchanged.

Mappings are copied before they are changed. Pydantic error models (for example TypedError) are converted to a mapping so the guidance fields can be added.

Parameters:

resultAny

Value returned by a tool function.

trace_idstr | None, default: None

Trace id of the call, added to error results as trace_id.

Returns:

Any

The original result, or an enriched mapping.