# instructor

> structured outputs for llms 

- **URL**: https://www.freshcrate.ai/projects/instructor
- **Author**: jxnl
- **Category**: Uncategorized
- **Latest version**: `v1.15.1` (2026-04-03)
- **License**: MIT
- **Source**: https://github.com/567-labs/instructor
- **Homepage**: https://python.useinstructor.com/
- **Language**: Python
- **GitHub**: 12,803 stars, 1,024 forks
- **Registry**: github
- **Tags**: `openai`, `openai-function-calli`, `openai-functions`, `pydantic-v2`, `python`, `validation`

## Description

structured outputs for llms

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v1.15.1` | 2026-04-03 | High | ## Security - **Bedrock**: Block remote HTTP(S) image URL fetching in `_openai_image_part_to_bedrock` — only `data:` URLs accepted, preventing SSRF via user-controlled image URLs - **Bedrock/PDF**: Block remote URL and local file fetching in `PDF.to_bedrock` — only base64 data or `s3://` sources supported, preventing SSRF and local file disclosure  ## Added - **Hooks**: `completion:error` and `completion:last_attempt` handlers now receive `attempt_number`, `max_attempts`, and `is_last_attempt` a |
| `v1.15.0` | 2026-04-02 | Medium | ## What's Changed  - **Validation**: Fix `Validator` to require `is_valid` field (#2230) - **Gemini**: Handle `GEMINI_TOOLS` in async streaming paths (#2135) - **CLI**: Add `--full-id` flag to show complete batch IDs (#2068) - **Providers**: Remove opinionated system prompt from JSON mode (#2069) - **Mode**: Add missing `GENAI` and `Responses` modes to `tool_modes()` (#2072) - **xAI**: Make xai-sdk optional at runtime (#2043, #2094) - **Docs**: Add canonical OpenAI starter example (#2117) - **De |
| `v1.14.5` | 2026-01-29 | Low | ## Changes  - fix(metadata): populate author field for PyPI stats  Separate author names from emails so hatchling populates the Author metadata field correctly. pypistats.org reads this field and was showing "None" because the names were only in author_email. |
| `v1.14.4` | 2026-01-16 | Low | ## What's Changed * refactor(json_tracker): simplify using sibling heuristic by @thomasnormal in https://github.com/567-labs/instructor/pull/2000 * Responses API validation error by @jxnl in https://github.com/567-labs/instructor/pull/2002 * GenAI config labels loss by @jxnl in https://github.com/567-labs/instructor/pull/2005 * GenAI SafetySettings image content by @jxnl in https://github.com/567-labs/instructor/pull/2007 * List object crashes fix by @jxnl in https://github.com/567-labs/ins |
| `v1.14.3` | 2026-01-13 | Low | ## Added - Completeness-based validation for Partial streaming - only validates JSON structures that are structurally complete (#1999) - New `JsonCompleteness` class in `instructor/dsl/json_tracker.py` for tracking JSON completeness during streaming (#1999)  ## Fixed - Fixed Stream objects crashing reask handlers when using streaming with `max_retries > 1` (#1992) - Field constraints (`min_length`, `max_length`, `ge`, `le`, etc.) now work correctly during streaming (#1999)  ## Deprecated - `Part |
| `v1.14.2` | 2026-01-13 | Low | ## Fixed - Fixed model validators crashing during partial streaming by skipping them until streaming completes (#1994) - Fixed infinite recursion with self-referential models in Partial (e.g., TreeNode with children: List["TreeNode"]) (#1997)  ## Added - Added `PartialLiteralMixin` documentation for handling Literal/Enum types during streaming (#1994) - Added final validation against original model after streaming completes to enforce required fields (#1994) - Added tests for recursive Partial m |
| `v1.14.1` | 2026-01-08 | Low | ## What's Changed * fix(genai): Support cached_content for Google context caching by @b-antosik-marcura in https://github.com/567-labs/instructor/pull/1987  ## New Contributors * @b-antosik-marcura made their first contribution in https://github.com/567-labs/instructor/pull/1987  **Full Changelog**: https://github.com/567-labs/instructor/compare/v1.14.0...v1.14.1 |
| `v1.14.0` | 2026-01-08 | Low | ## What's Changed * Audit and standardize exception handling in instructor library by @jxnl in https://github.com/567-labs/instructor/pull/1897 * Standardize provider imports in documentation by @jxnl in https://github.com/567-labs/instructor/pull/1896 * Fix the issue by @jxnl in https://github.com/567-labs/instructor/pull/1914 * Standardize provider factory methods in codebase by @jxnl in https://github.com/567-labs/instructor/pull/1898 * Update image base URL in ipnb tutorials by @jxnl in |
| `v1.13.0` | 2025-11-06 | Low | ## What's Changed * fix: Gemini HARM_CATEGORY_JAILBREAK and Anthropic tool_result blocks by @jxnl in https://github.com/567-labs/instructor/pull/1867 * fix(genai): fix Gemini streaming by @DaveOkpare in https://github.com/567-labs/instructor/pull/1864 * fix(processing): ensure JSON decode errors are caught by retry; add regression tests for JSON mode (#1856) by @devin-ai-integration[bot] in https://github.com/567-labs/instructor/pull/1857 * fix: resolve type checking diagnostics by @jxnl in |
| `v1.12.0` | 2025-10-27 | Low | ## What's Changed * feat: add mkdocs-llmstxt plugin and llms.txt support by @jxnl in https://github.com/567-labs/instructor/pull/1795 * Restore multimodal import compatibility by @jxnl in https://github.com/567-labs/instructor/pull/1797 * feat(retry): add comprehensive tracking of all failed attempts and exceptions by @jxnl in https://github.com/567-labs/instructor/pull/1802 * feat(hooks): add hook combination and per-call hooks support by @jxnl in https://github.com/567-labs/instructor/pull |

## Citation

- HTML: https://www.freshcrate.ai/projects/instructor
- Markdown: https://www.freshcrate.ai/projects/instructor.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/instructor/deps

_Generated by freshcrate.ai. Indexes github releases for AI-agent ecosystem packages._