This system is designed to ensure reliable structured output from AI models by implementing robust retry and "reasking" mechanisms, along with custom exception handling. It intelligently retries requests and re-prompts the AI with error details when validation fails.

Components

Retry Mechanism

This component is the central orchestrator of the robustness system. It executes API calls to Language Model Models (LLMs) and intelligently retries them upon specific failures, such as `ValidationError` or `JSONDecodeError`. It manages retry attempts, integrates with the `Re-ask Logic` to guide the LLM, and emits events through the `Hooks System`. It provides both synchronous (`retry_sync`) and asynchronous (`retry_async`) capabilities.

Re-ask Logic

This component acts as a central dispatcher for various re-asking strategies. When a parsing or validation error occurs in an LLM response, it determines the appropriate re-asking function based on the LLM's `mode`. It then intelligently modifies the original request parameters (`kwargs`) to provide specific error details and guidance to the LLM, helping it generate a correct and valid structured response in subsequent retry attempts.

Response Processing

This component is responsible for transforming raw responses received from LLM APIs into structured Python objects, typically Pydantic models. It handles diverse response formats (streaming, iterable, parallel) and performs crucial validation to ensure the output conforms to the expected schema. Errors detected during this process can trigger the `Retry Mechanism` and `Re-ask Logic`.

Hooks System

This component provides a flexible, event-driven mechanism that allows developers to register and emit custom events at various stages of the LLM interaction lifecycle (e.g., before/after completion, on parse error, on retry). It enables the injection of custom logic, logging, or monitoring without modifying the core `instructor` codebase, enhancing extensibility and observability.

Utility Functions

This component encapsulates a collection of general-purpose helper functions that support various aspects of the `Robustness & Error Handling System` and other parts of the `instructor` library. Key functions include `update_total_usage` for aggregating token usage and `extract_json_from_codeblock` for robust JSON parsing.

Custom Exception Handling

This component defines specialized exceptions tailored for `instructor`'s robust interaction patterns. The primary exception, `InstructorRetryException`, is raised when all configured retry attempts have been exhausted. It provides comprehensive details about the failure, facilitating debugging and error analysis. Other exceptions like `ValidationError` are also defined here.