Expose attempt metadata on completion:error and completion:last_attempt hooks

[aress31]

Summary

completion:error and completion:last_attempt currently only receive the raised exception, but not retry metadata such as attempt_number.

This makes it hard to build clean logging around retries. In particular, a client cannot distinguish:

• an intermediate retryable API error
• the final failed attempt

without keeping extra local state or reconstructing retry behavior externally.

Current behavior

Hook signatures appear to be:

• completion:kwargs -> handler(*args, **kwargs)
• completion:response -> handler(response)
• completion:error -> handler(error)
• completion:last_attempt -> handler(error)

Internally, retry logic already has access to attempt.retry_state.attempt_number, but that metadata is not forwarded to the error hooks.

Desired behavior

Please expose retry metadata to completion:error and completion:last_attempt, for example one of:

1. Add keyword metadata to those hooks:

   • handler(error, *, attempt_number: int, max_attempts: int | None, is_last_attempt: bool)

2. Or pass _instructor_meta consistently, similar to completion:kwargs

3. Or add a structured event object instead of a bare exception

Use case

I’m integrating Instructor into a CLI and want to:

• log retryable API errors at lower severity for intermediate attempts
• suppress duplicate "API error" logs when the final completion:last_attempt hook will fire immediately after
• render better retry UX without maintaining my own shadow retry counter

Right now, the only clean workaround is local state or waiting for the final InstructorRetryException, which loses hook-time context.

Notes

The retry implementation already tracks:

• attempt.retry_state.attempt_number
• failed_attempts
• n_attempts on InstructorRetryException

So this seems like the metadata already exists internally and would mainly need to be surfaced through the hook API.

[majiayu000]

Hi, I've been looking into this and traced the root cause.

Proposed approach: Find hook emission points for completion:error and completion:last_attempt in the retry logic. Pass attempt metadata (attempt_number, max_attempts, is_last_attempt) as keyword arguments to those hooks. Add tests verifying the metadata is correctly forwarded. Option 1 from the issue (keyword metadata) is likely cleanest and most backward-compatible.

I'll open a draft PR shortly. Happy to adjust based on your preference.

[yuquan2088]

This is a well-scoped request. The missing retry metadata is actually a symptom of a broader observability gap in structured-output pipelines: by the time an error surfaces, you've lost the behavioral context of which agent triggered it, under what identity, and with what intent.

We ran into exactly this when building ClawSocial — a layer that gives AI agents persistent identity and behavioral reputation across tool calls. When instructor's hooks only expose the bare exception, any upstream agent identity (model, session, caller role) gets stripped, making it impossible to attribute retry patterns to specific agents in a multi-agent pipeline.

Your option 1 (keyword metadata: attempt_number, max_attempts, is_last_attempt) is cleanest for backward compatibility. I'd add one more field worth considering:

handler(
    error,
    *,
    attempt_number: int,
    max_attempts: int | None,
    is_last_attempt: bool,
    caller_context: dict | None = None,  # propagated from client.chat.completions.create call site
)

caller_context would let the invoking agent inject its identity metadata (agent_id, session_id, task_id) at call time and have it bubble through all hooks — without instructor needing to know anything about the identity scheme.

This pairs naturally with the structured event object approach (option 3): emit a RetryEvent that carries both retry state and caller context, and let hooks pattern-match on it. Similar to how OpenTelemetry spans carry baggage through the call stack.

Happy to draft a PR for option 1 + caller_context if there's appetite for it.