Instructor
AI & LLMsstructured outputs for llms
Release History
View all versions →v1.15.47 fixesInstructor 1.15.4 is a patch release consolidating fixes for runtime model preparation, streamed JSON extraction, image handling, and CLI fine-tuning operations.
v1.15.38 fixesThis release focuses on numerous bug fixes across templating, streaming, logging, and Anthropic tool usage, alongside general runtime consolidation for v2.
v1.15.19 fixes2 featuresThis release significantly enhances security by blocking remote URL fetching in Bedrock and PDF processing, alongside numerous bug fixes across Anthropic, OpenRouter, and Bedrock integrations. New keyword arguments were added to completion error hooks.
v1.15.02 fixes3 featuresThis release introduces new CLI functionality, updates handling for Gemini streaming, and makes the xai-sdk an optional runtime dependency.
v1.14.51 fixThis release fixes an issue where the Author metadata field was not being populated correctly for PyPI statistics by ensuring author names are properly separated from emails.
v1.14.44 fixesThis release focuses on stability and correctness, including fixes for validation errors, configuration label loss, and crashes related to list object processing.
v1.14.32 fixes2 featuresThis release introduces completeness-based validation for partial streaming and fixes bugs related to stream handling and field constraints during streaming.
v1.14.22 fixes1 featureThis release addresses critical bugs related to model validation during partial streaming and fixes infinite recursion issues with self-referential models.
v1.14.11 fix1 featureThis patch release introduces support for Google GenAI context caching via the cached_content parameter.
v1.14.06 fixes4 featuresThis release focuses on standardizing provider factory methods and exception handling, while adding Bedrock document support and fixing critical bugs in GenAI, OpenAI, and Cohere integrations.
v1.13.05 fixes2 featuresThis release introduces image support for Bedrock, improves type safety with a py.typed marker, and includes critical fixes for Gemini streaming and Anthropic tool blocks.
v1.12.09 fixes6 featuresThis release introduces enhanced retry tracking, per-call hooks, and xAI streaming support while fixing critical bugs in OpenAI JSON mode and Gemini response handling. It also marks the transition from validation_context to a unified context parameter.
v1.11.31 fix3 featuresThis release introduces enhanced retry tracking, per-call hook support, and llms.txt documentation support, while fixing multimodal import issues.
1.11.22 fixes2 featuresThis release enhances Google Cloud Storage support for multimodal data types and restores backwards compatibility for exception imports.
v1.11.0Breaking3 fixes5 featuresThis release introduces a major modular reorganization of the codebase, adds support for xAI, OpenRouter, and Truefoundry providers, and implements in-memory batching.
v1.11.1This release bumps the version to 1.11.1. It is a minor update with no significant changes mentioned.
1.10.0Breaking5 fixes7 featuresThis release introduces native caching (Redis/AutoCache), expands provider support to include DeepSeek and Anthropic parallel tools, and migrates Google integrations to the new google-genai SDK.
1.9.24 fixes1 featureThis release introduces support for the xAI provider and includes several bug fixes for Gemini API safety settings and GenAI image harm categories.
1.9.14 fixes2 featuresThis release introduces Azure OpenAI support and simplifies Gemini safety configurations while fixing public API visibility for exceptions and JSON schema issues.
1.9.0Breaking6 fixes7 featuresThis release introduces Ollama and Writer provider support, improves Gemini and Anthropic integrations, and standardizes VertexAI async parameters. It also enhances error handling with a new exception hierarchy and resolves several dependency conflicts.
1.8.34 fixes4 featuresRelease 1.8.3 introduces support for asynchronous Bedrock clients and response handling, alongside various bug fixes for the Bedrock converse endpoint and documentation improvements.
1.8.21 fixThis patch release removes a stray print statement to clean up console output.
1.8.12 fixes2 featuresRelease 1.8.1 introduces a unified provider interface and enables streaming support directly within the create method, alongside fixes for Anthropic web search.
1.8.06 fixes1 featureThis release introduces a unified provider interface with string-based initialization and includes several bug fixes for Google GenAI and Python 3.10 type compatibility.
1.7.91 fix3 featuresThis release introduces async partial streaming for Gemini, adds Mistral PDF support, and improves type hinting for LiteLLM integrations.
Common Errors
InstructorRetryException23 reportsInstructorRetryException usually arises from rate limiting or transient errors in the underlying API being called. Implement retry logic with exponential backoff and jitter around the API call within your instructor client. This will handle temporary service unavailability or exceeding API usage limits, ultimately preventing the exception.
ModuleNotFoundError4 reportsThe "ModuleNotFoundError" in instructor typically arises when required dependencies are not installed or are inaccessible in the Python environment. To resolve this, ensure all necessary packages, especially optional dependencies like google libraries, are installed using `pip install instructor[extra]` (or specific extras like `pip install instructor[google]`) and that your Python environment is correctly activated. Verify the package name isn't misspelled in your code as well.
ValidationError3 reportsValidationError in instructor often arises from mismatches between the expected data structure defined in your instructor model and the actual data returned by the language model. Carefully inspect your model's fields, types, and validation constraints. Ensure the LLM response aligns precisely, and use validation hooks (pre/post) to catch and correct discrepancies or provide better guidance to the LLM.
IncompleteOutputException3 reportsIncompleteOutputException usually means the LLM response was cut off prematurely, often due to insufficient `max_tokens` or a restrictive stopping condition causing truncation. Increase `max_tokens` in your `OpenAISchema` or adjust your prompt to encourage more concise responses, or relax any custom stopping criteria to allow the model to fully express its output. Ensure retry mechanisms are in place to handle potential truncation and attempt re-generation.
InternalServerError2 reportsInternalServerError in instructor often stems from issues with the language model, like timeouts, unexpected schema mismatches, or model incompatibilities. To fix it, first ensure your model adheres to the expected schema and reduce complexity; then, implement robust error handling, including custom timeouts and retry mechanisms, tailored to the specific model you're using (e.g., increase timeout for Ollama or avoid incompatible models like 'kimi-k2-thinking' for tool calling).
InstructorValidationError2 reportsThe "InstructorValidationError" arises when the response from the LLM fails to conform to the pydantic model defined by instructor. To fix this, carefully validate your pydantic model's structure, types, and constraints to ensure they align with the LLM's output, and implement robust error handling to catch validation errors and guide the LLM to correct its response, potentially using `instructor.patch` with `mode="retry"` .
Related AI & LLMs Packages
AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
Get up and running with OpenAI gpt-oss, DeepSeek-R1, Gemma 3 and other models.
🦜🔗 The platform for reliable agents.
The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.
LLM inference in C/C++
GPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.
Subscribe to Updates
Get notified when new versions are released