graph LR
Instructor_Core_Client["Instructor Core Client"]
Response_Processing_Schema_Engine["Response Processing & Schema Engine"]
Robustness_Error_Handling_System["Robustness & Error Handling System"]
Provider_Integration_Layer["Provider Integration Layer"]
Lifecycle_Configuration_Management["Lifecycle & Configuration Management"]
Utility_Functions["Utility Functions"]
Instructor_Core_Client -- "initiates calls to" --> Response_Processing_Schema_Engine
Instructor_Core_Client -- "delegates its API calls to" --> Robustness_Error_Handling_System
Instructor_Core_Client -- "is configured and instantiated by" --> Provider_Integration_Layer
Instructor_Core_Client -- "interacts with" --> Lifecycle_Configuration_Management
Response_Processing_Schema_Engine -- "receives raw AI responses from" --> Instructor_Core_Client
Response_Processing_Schema_Engine -- "can raise exceptions that are caught and handled by" --> Robustness_Error_Handling_System
Response_Processing_Schema_Engine -- "utilizes" --> Utility_Functions
Robustness_Error_Handling_System -- "wraps and manages API calls initiated by" --> Instructor_Core_Client
Robustness_Error_Handling_System -- "processes and reacts to errors originating from" --> Response_Processing_Schema_Engine
Robustness_Error_Handling_System -- "interacts with" --> Lifecycle_Configuration_Management
Provider_Integration_Layer -- "provides configured and patched AI client instances to" --> Instructor_Core_Client
Provider_Integration_Layer -- "consults" --> Lifecycle_Configuration_Management
Lifecycle_Configuration_Management -- "configures the behavior and flow for" --> Instructor_Core_Client
Lifecycle_Configuration_Management -- "informs" --> Response_Processing_Schema_Engine
Lifecycle_Configuration_Management -- "receives event triggers from" --> Robustness_Error_Handling_System
Utility_Functions -- "are utilized by" --> Response_Processing_Schema_Engine
Utility_Functions -- "are used by" --> Instructor_Core_Client
click Instructor_Core_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Instructor_Core_Client.md" "Details"
click Response_Processing_Schema_Engine href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Response_Processing_Schema_Engine.md" "Details"
click Robustness_Error_Handling_System href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Robustness_Error_Handling_System.md" "Details"
click Provider_Integration_Layer href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Provider_Integration_Layer.md" "Details"
click Lifecycle_Configuration_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Lifecycle_Configuration_Management.md" "Details"
click Utility_Functions href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main//instructor/Utility_Functions.md" "Details"
The instructor library's architecture is designed to provide a robust and intuitive way to interact with Large Language Models (LLMs), primarily focusing on enabling structured output (Pydantic models) and enhancing reliability. The analysis of its Control Flow Graph (CFG) and source code reveals a modular design centered around patching existing AI clients, processing responses, and ensuring resilience.
This is the central user-facing interface, encompassing the Instructor and AsyncInstructor classes. It acts as the orchestrator, wrapping and patching the underlying AI client's create method to inject instructor's core capabilities, such as response_model for structured output, max_retries, and hooks. It manages the overall request lifecycle from initiation to receiving the final processed output.
Related Classes/Methods:
This component is responsible for the core value proposition of instructor: transforming raw AI model responses into validated, structured Pydantic models. It handles the generation of AI-compatible schemas from Pydantic models, parses function/tool calls, manages different response modes (e.g., JSON, tool calls), and integrates advanced Domain Specific Language (DSL) features like parallel, iterable, and partial models, as well as multimodal data handling.
Related Classes/Methods:
instructor.process_response(120:193)instructor.function_calls(1:1)instructor.multimodal(1:1)instructor.dsl.parallel(1:1)instructor.dsl.iterable(1:1)instructor.dsl.partial(1:1)
This critical component implements the robust retry and "reasking" mechanisms that ensure reliable structured output from AI models. It defines and handles custom instructor-specific exceptions (e.g., ValidationError, IncompleteOutputException). When an AI response fails validation, this system intelligently retries the request, potentially re-prompting the AI with specific error details to guide it towards a correct and valid structured response.
Related Classes/Methods:
This layer acts as a factory for initializing and configuring instructor-enhanced AI clients across various providers (e.g., OpenAI, Anthropic, Google Gemini, Cohere). It abstracts away provider-specific client setup complexities and ensures that instructor's patching and capabilities are correctly applied to the respective client's API methods, often determining the appropriate instructor.Mode for the integration.
Related Classes/Methods:
instructor.auto_client(1:1)instructor.client_anthropic(1:1)instructor.client_bedrock(1:1)instructor.client_gemini(1:1)instructor.client_cohere(1:1)
This component manages the various operational modes (instructor.Mode) that dictate how instructor interacts with different AI models (e.g., using tools, functions, or json_mode). It also provides a flexible and extensible event hooks system, allowing users to register custom callback functions at various predefined points within the AI interaction lifecycle for purposes like logging, monitoring, debugging, or modifying behavior.
Related Classes/Methods:
This component comprises a collection of general-purpose helper functions that are used across the instructor codebase. These utilities support various core components by performing common tasks such as extracting JSON from different text formats, determining the LLM provider from a base URL, converting messages, and managing usage statistics. While not a primary flow component, it provides essential foundational support.
Related Classes/Methods: