6iLktdZddlmZddlZddlZddlmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZdd lmZmZd d lmZd d lmZd d lmZd dlmZd dlmZerddlm Z d dl!m"Z"ddl#m$Z$d dl%m&Z&d dl'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-d dl.m/Z/m0Z0m1Z1m2Z2d dl3m4Z4m5Z5m6Z6d dl7m8Z8m9Z9m:Z:d dl;mZ>m?Z?d dl@mAZAmBZBmCZCmDZDmEZEmFZFmGZGmHZHmIZImJZJmKZKmLZLmMZMd dlNmOZOmPZPmQZQmRZRd dlSmTZTmUZUmVZVmWZWmXZXmYZYmZZZm[Z[m\Z\m]Z]m^Z^m_Z_m`Z`d dlambZbmcZcd dldmeZemfZfmgZgmhZhd dlimjZjmkZkmlZlmmZmejd Zoed!e"Zped#Zqed$Zred%Zsd&dde"jd' d.d(Zuddde"jd) d/d*Zvd0d+Zwe"jf d1d,Zx d2 d3d-Zyy)4a This module serves as the central dispatcher for processing responses from various LLM providers (OpenAI, Anthropic, Google, Cohere, etc.) and transforming them into structured Pydantic models. It handles different response formats, streaming responses, validation, and error recovery. The module supports 40+ different modes across providers, each with specific handling logic for request formatting and response parsing. It also provides retry mechanisms (reask) for handling validation errors gracefully. Key Components: - Response processing functions for sync/async operations - Mode-based response model handlers for different providers - Error recovery and retry logic for validation failures - Support for streaming, partial, parallel, and iterable response models Example: ```python from instructor.process_response import process_response from ..mode import Mode from pydantic import BaseModel class User(BaseModel): name: str age: int # Process an OpenAI response processed = process_response( response=openai_response, response_model=User, mode=Mode.TOOLS, stream=False ) ``` ) annotationsN)AnyTypeVar TYPE_CHECKINGcast)AsyncGenerator)ChatCompletion) BaseModel) ParamSpec)InstructorErrorConfigurationError) IterableBase) ParallelBase) PartialBase) ListResponse) AdapterBase) OpenAISchema)Mode)convert_messages)prepare_response_model)handle_anthropic_jsonhandle_anthropic_parallel_tools handle_anthropic_reasoning_toolshandle_anthropic_toolsreask_anthropic_jsonreask_anthropic_tools)handle_bedrock_jsonhandle_bedrock_toolsreask_bedrock_jsonreask_bedrock_tools)handle_cerebras_jsonhandle_cerebras_toolsreask_cerebras_tools)handle_cohere_json_schemahandle_cohere_toolsreask_cohere_tools)handle_fireworks_jsonhandle_fireworks_toolsreask_fireworks_jsonreask_fireworks_tools) handle_gemini_jsonhandle_gemini_toolshandle_genai_structured_outputshandle_genai_toolshandle_vertexai_jsonhandle_vertexai_parallel_toolshandle_vertexai_toolsreask_gemini_jsonreask_gemini_toolsreask_genai_structured_outputsreask_genai_toolsreask_vertexai_jsonreask_vertexai_tools)!handle_mistral_structured_outputshandle_mistral_tools reask_mistral_structured_outputsreask_mistral_tools) handle_functionshandle_json_modeshandle_json_o1$handle_openrouter_structured_outputshandle_parallel_toolshandle_responses_tools)handle_responses_tools_with_inbuilt_tools handle_toolshandle_tools_strict reask_default reask_md_jsonreask_responses_tools reask_tools)handle_perplexity_jsonreask_perplexity_json)handle_writer_jsonhandle_writer_toolsreask_writer_jsonreask_writer_tools)handle_xai_jsonhandle_xai_toolsreask_xai_jsonreask_xai_tools instructorT_Model)boundT_Retval T_ParamSpecTF)streamvalidation_contextstrictmodec2Ktjd|||Stj|rt@tjBtDtjFtHtjJtLtjNtPtjRtTtjVtXtjZfd itj\fd tj^t`tjbtdtjfthtjjtltjntptjrtttjvtxtjzt|tj~ttjttjttjttjttjttjttjt}||vr||||\}}n5td|ddjd|jDd|vrt|d||d<tjd|jd|d||j|t|dr |jn t||d||fS)a Handles the response model based on the specified mode and prepares the kwargs for the API call. This really should be named 'prepare_create_kwargs' as its job is to map the openai create kwargs to the correct format for the API call based on the mode. Args: response_model (type[T] | None): The response model to be used for parsing the API response. mode (Mode): The mode to use for handling the response model. Defaults to Mode.TOOLS. **kwargs: Additional keyword arguments to be passed to the API call. Returns: tuple[type[T] | None, dict[str, Any]]: A tuple containing the processed response model and the updated kwargs. This function prepares the response model and modifies the kwargs based on the specified mode. It handles various modes like TOOLS, JSON, FUNCTIONS, etc., and applies the appropriate transformations to the response model and kwargs. autodetect_imagesFzInstructor Request: mode.value=z, response_model=z , new_kwargs=__name__)r^rv new_kwargs)extrac8t||tjSN)r?rJSONrmnks ryz'handle_response_model..s"3BDII"Frc8t||tjSr)r?rMD_JSONrs ryrz'handle_response_model..s%6r2t||%Lrc8t||tjSr)r?r JSON_SCHEMArs ryrz'handle_response_model..s):2r4CSCS)Trct||Sr)r0rrrs ryrz'handle_response_model..s);BDU)Vrct||Sr)r/rs ryrz'handle_response_model..s6U %7 rzInvalid or unsupported mode: z5. This mode may not be implemented. Available modes: z, c32K|]}t|ywr)str).0ms ry z(handle_response_model..s)OQ#a&)Osmessages)r)ScopypoprPARALLEL_TOOLSrBVERTEXAI_PARALLEL_TOOLSr2ANTHROPIC_PARALLEL_TOOLSrrhrivaluerrrr FUNCTIONSr> TOOLS_STRICTrFTOOLSrE MISTRAL_TOOLSr;MISTRAL_STRUCTURED_OUTPUTSr:JSON_O1r@rrrANTHROPIC_TOOLSrANTHROPIC_REASONING_TOOLSrANTHROPIC_JSONrCOHERE_JSON_SCHEMAr& COHERE_TOOLSr' GEMINI_JSONr- GEMINI_TOOLSr. GENAI_TOOLSGENAI_STRUCTURED_OUTPUTSVERTEXAI_TOOLSr3 VERTEXAI_JSONr1 CEREBRAS_JSONr#CEREBRAS_TOOLSr$FIREWORKS_JSONr)FIREWORKS_TOOLSr* WRITER_TOOLSrN WRITER_JSONrM BEDROCK_JSONr BEDROCK_TOOLSr PERPLEXITY_JSONrKOPENROUTER_STRUCTURED_OUTPUTSrARESPONSES_TOOLSrC"RESPONSES_TOOLS_WITH_INBUILT_TOOLSrDXAI_JSONrQ XAI_TOOLSrRr joinkeysr)rvr^kwargsrPARALLEL_MODES mode_handlersrs @ryhandle_response_modelrsm*J"':EB 2 $$&D %%'FN  ~%9^D%9.*%U"  .4::-/A.1B.ZM R &1 ;#++^,(   z))!/?% (% .% L% 0 % '')J % n % F% L% T% 4% &&(H% 2% !:% .% ,% .!%" V#%$ %%( %%* 2+%, 0-%. 0/%0 21%2 23%4 45%6 .7%8 ,9%: .;%< 0=%> 4?%@ **,PA%B 4C%D //1ZE%F G%H (I%MN }%8]4%8%T"  +D62 $ )O-:L:L:N)O OP R  Z!1 z " /" :  LL *tzzm+=n->n NJJ"-'.*2U''($   : %%rc|j}tj||}itjt tj ttjttjt tjttjttjttjttjt tj"t tj$t&tj(t*tj,t.tj0t.tj2t4tj6t.tj8t:itj<t:tj>t@tjBtDtjFtHtjJtLtjNtPtjRtTtjVtPtjXtZtj\t tj^t`tjbtdtjfthtjjtltjntptjrtttjvtxtjzt tj|t~tjti}||vr |||||St |||S)alHandle validation errors by reformatting the request for retry (reask). This function serves as the central dispatcher for handling validation failures across all supported LLM providers. When a response fails validation, it prepares a new request that includes detailed error information and retry context, allowing the LLM to understand what went wrong and generate a corrected response. The reask process involves: 1. Analyzing the validation error and failed response 2. Selecting the appropriate provider-specific reask handler 3. Enriching the exception with retry history (failed_attempts) 4. Formatting error feedback in the provider's expected message format 5. Preserving original request parameters while adding retry context Args: kwargs (dict[str, Any]): The original request parameters that resulted in a validation error. Contains all parameters passed to the LLM API: - messages: conversation history - tools/functions: available function definitions - temperature, max_tokens: generation parameters - model, provider-specific settings mode (Mode): The provider/format mode that determines which reask handler to use. Each mode implements a specific strategy for formatting error feedback and retry messages. Examples: - Mode.TOOLS: OpenAI function calling - Mode.ANTHROPIC_TOOLS: Anthropic tool use - Mode.JSON: JSON-only responses response (Any): The raw response from the LLM that failed validation. Type and structure varies by provider: - OpenAI: ChatCompletion with tool_calls or content - Anthropic: Message with tool_use blocks or text content - Google: GenerateContentResponse with function calls - Cohere: NonStreamedChatResponse with tool calls exception (Exception): The validation error that occurred, typically: - Pydantic ValidationError: field validation failures - JSONDecodeError: malformed JSON responses - Custom validation errors from response processors The exception will be enriched with failed_attempts data. failed_attempts (list[FailedAttempt] | None): Historical record of previous retry attempts for this request. Each FailedAttempt contains: - attempt_number: sequential attempt counter - exception: the validation error for that attempt - completion: the raw LLM response that failed Used to provide retry context and prevent repeated mistakes. Returns: dict[str, Any]: Modified kwargs for the retry request with: - Updated messages including error feedback - Original tool/function definitions preserved - Generation parameters maintained (temperature, etc.) - Provider-specific error formatting applied - Retry context embedded in appropriate message format Provider-Specific Reask Strategies: **OpenAI Modes:** - TOOLS/FUNCTIONS: Adds tool response messages with validation errors - JSON modes: Appends user message with correction instructions - Preserves function schemas and conversation context **Anthropic Modes:** - TOOLS: Creates tool_result blocks with error details - JSON: Adds user message with structured error feedback - Maintains conversation flow with proper message roles **Google/Gemini Modes:** - TOOLS: Formats as function response with error content - JSON: Appends user message with validation feedback **Other Providers (Cohere, Mistral, etc.):** - Provider-specific message formatting - Consistent error reporting patterns - Maintained conversation context Error Enrichment: The exception parameter is enriched with retry metadata: - exception.failed_attempts: list of previous failures - exception.retry_attempt_number: current attempt number This allows downstream handlers to access full retry context. Example: ```python # After a ValidationError occurs during retry attempt #2 new_kwargs = handle_reask_kwargs( kwargs=original_request, mode=Mode.TOOLS, response=failed_completion, exception=validation_error, # Will be enriched with failed_attempts failed_attempts=[attempt1, attempt2] # Previous failures ) # new_kwargs now contains retry messages with error context ``` Note: This function is called internally by retry_sync() and retry_async() when max_retries > 1. It ensures each retry includes progressively more context about previous failures, helping the LLM learn from mistakes and avoid repeating the same errors. )failed_attempts)Brr from_exceptionrrrGrrJrrrrHrrrrrIrrr=rr<rrrrrrrr(rrr5rr4rr7rr6rr9rr8rrr%rrr,rr+rrPrrOrr"rr!rrLrrrSrrT)rr^ru exceptionr kwargs_copyREASK_HANDLERSs ryhandle_reask_kwargsrsT++-K..?I 3  3 ;3 K 3 m 3 = 3 m3 -3 [3 33 //1F3 /3 '')I3 3!3" &&(=#3$ 1%3& %%'<'3* -+3, !3-30 -132 +334 +536 %%'E73: 1;3< /=3> $$&:?3B 1C3D ME3H 3I3J 1K3N -O3P +Q3T /U3V -W3Z 3[3^ **M ~ e3Nj ~#~d#K9EE[(I>>r)rur rvz/type[T_Model | OpenAISchema | BaseModel] | Noner[boolr\dict[str, Any] | Noner]z bool | Noner^rreturnr) rurVrvz%type[OpenAISchema | BaseModel] | Noner[rr\rr^rrr)rr)rvztype[T] | Noner^rrrrz%tuple[type[T] | None, dict[str, Any]]r) rdict[str, Any]r^rrurr Exceptionrzlist[Any] | Nonerr)z__doc__ __future__rrjloggingtypingrrrrcollections.abcropenai.types.chatr pydanticr typing_extensionsr instructor.core.exceptionsr r dsl.iterabler dsl.parallelr dsl.partialrdsl.response_listrdsl.simple_typerfunction_callsrr^r multimodalr utils.corerproviders.anthropic.utilsrrrrrrproviders.bedrock.utilsrr r!r"providers.cerebras.utilsr#r$r%providers.cohere.utilsr&r'r(providers.fireworks.utilsr)r*r+r,providers.gemini.utilsr-r.r/r0r1r2r3r4r5r6r7r8r9providers.mistral.utilsr:r;r<r=providers.openai.utilsr>r?r@rArBrCrDrErFrGrHrIrJproviders.perplexity.utilsrKrLproviders.writer.utilsrMrNrOrPproviders.xai.utilsrQrRrSrT getLoggerrhrVrXrYrZrrzr~rrrrryrsD!F#44*,'J''%,),(/""    < ( )9 - :  &  CL04ggDg  g . g  g g gZ=A04 ss:s  s . s s sl26x&"x&*.x&GJx&*x&@)- i? i? i?i? i? & i?  i?r