567-labs · jxnl · Feb 6, 2026 · Jan 18, 2026 · Jan 18, 2026 · Jan 18, 2026
diff --git a/docs/api-docstring-assessment.md b/docs/api-docstring-assessment.md
@@ -0,0 +1,150 @@
+# API Docstring Quality Assessment
+
+This document assesses the quality and completeness of docstrings for all API items referenced in the expanded API documentation.
+
+## Summary
+
+Overall, the docstring quality is **good to excellent** for most items. Many classes and functions have comprehensive docstrings with usage examples, while some core classes could benefit from class-level docstrings.
+
+## Excellent Docstrings (Comprehensive with Examples)
+
+These have detailed docstrings with usage examples and clear descriptions:
+
+### Client Creation
+- **`from_provider`** - Comprehensive docstring with Args, Returns, Raises, and Examples sections. Includes multiple usage examples showing basic usage, caching, and async clients.
+
+### Validation
+- **`llm_validator`** - Good docstring with usage examples, parameter descriptions, and error message examples showing how validation errors are formatted.
+
+### DSL Components
+- **`CitationMixin`** - Excellent docstring with complete usage examples showing how to use it with context, and result examples showing the output structure.
+- **`IterableModel`** - Good docstring with usage examples showing before/after transformation, Parameters section, and Returns description.
+- **`Maybe`** - Good docstring with usage examples and result structure showing the generated model fields.
+
+### Batch Processing
+- **`BatchProcessor`** - Good class-level docstring explaining the unified interface. Methods like `create_batch_from_messages` and `submit_batch` have clear Args and Returns sections.
+
+### Distillation
+- **`Instructions`** - Good docstring with parameter descriptions. The `distil` method has usage examples showing decorator usage patterns.
+
+### Hooks
+- **`Hooks`** - Excellent class-level docstring explaining the purpose. Methods like `on()`, `get_hook_name()`, `emit()`, etc. have comprehensive docstrings with Args, Returns, Raises, and Examples sections.
+
+### Schema Generation
+- **`generate_openai_schema`** - Good docstring with Args, Returns, and Notes sections explaining how docstrings are used.
+- **`generate_anthropic_schema`** - Has docstring explaining the conversion process.
+
+### Multimodal
+- **`Audio`** - Good class-level docstring. Methods like `autodetect()` and `autodetect_safely()` have clear docstrings with Args and Returns.
+
+### Exceptions
+- **`InstructorError`** - Excellent docstring with Attributes section, Examples showing error handling, and See Also references.
+- **`IncompleteOutputException`** - Good docstring with Attributes, Common Solutions, and Examples.
+- **`InstructorRetryException`** - Comprehensive docstring with Attributes, Common Causes, Examples, and See Also.
+- **`ValidationError`** - Good docstring with Examples and See Also.
+- **`ProviderError`** - Good docstring with Attributes, Common Causes, and Examples.
+- **`ConfigurationError`** - Good docstring with Common Scenarios and Examples.
+- **`ModeError`** - Good docstring with Attributes, Examples, and See Also.
+- **`ClientError`** - Good docstring with Common Scenarios and Examples.
+- **`AsyncValidationError`** - Good docstring with Attributes and Examples.
+- **`ResponseParsingError`** - Good docstring with Attributes, Examples, and backwards compatibility notes.
+- **`MultimodalError`** - Good docstring with Attributes, Examples, and backwards compatibility notes.
+
+## Good Docstrings (Clear but Could Be Enhanced)
+
+These have adequate docstrings but could benefit from more examples or additional detail:
+
+### Core Clients
+- **`Instructor`** - No class-level docstring. Methods have type hints but lack comprehensive docstrings. The class is well-documented through usage in examples, but a class-level docstring would help.
+- **`AsyncInstructor`** - Similar to `Instructor`, no class-level docstring.
+- **`Response`** - No class-level docstring. Methods like `create()` and `create_with_completion()` lack docstrings.
+
+### Client Creation
+- **`from_openai`** - No docstring. Only has type overloads. The implementation exists but lacks documentation explaining usage, parameters, and return values.
+
+### Function Calls & Schema
+- **`OpenAISchema`** - Good method docstrings for `openai_schema`, `anthropic_schema`, `gemini_schema`, and `from_response()`. The class itself could use a class-level docstring explaining its purpose and usage.
+- **`openai_schema`** - Decorator function, but the docstring is on the class method, not the decorator itself.
+
+### DSL Components
+- **`Partial`** - Minimal docstring. Has Notes and Example sections but could benefit from more comprehensive usage examples showing streaming scenarios.
+
+### Multimodal
+- **`Image`** - No class-level docstring. Methods have good docstrings (`autodetect()`, `autodetect_safely()`, `from_gs_url()`, etc.), but the class itself lacks documentation.
+
+### Mode & Provider
+- **`Mode`** - Good class-level docstring explaining what modes are and how they work. Individual mode values lack docstrings but the enum docstring is comprehensive.
+- **`Provider`** - No class-level docstring. Just enum values without explanation.
+
+### Patch Functions
+- **`patch`** - Good docstring explaining what features it enables (response_model, max_retries, validation_context, strict, hooks). Could benefit from usage examples.
+- **`apatch`** - Need to check if it has similar docstring quality.
+
+## Areas Needing Improvement
+
+### Missing Class-Level Docstrings
+1. **`Instructor`** - Should have a class-level docstring explaining:
+   - What the class does
+   - How to use it
+   - Key features (modes, hooks, retries)
+   - Basic usage example
+
+2. **`AsyncInstructor`** - Should have a class-level docstring explaining:
+   - Async usage patterns
+   - How it differs from `Instructor`
+   - Async examples
+
+3. **`Response`** - Should have a class-level docstring explaining:
+   - What the Response helper does
+   - When to use it vs direct client methods
+   - Usage examples
+
+4. **`Image`** - Should have a class-level docstring explaining:
+   - What Image represents
+   - Supported formats
+   - Common usage patterns
+
+5. **`Provider`** - Should have a class-level docstring explaining:
+   - What providers are supported
+   - How to use Provider enum
+   - Provider detection
+
+### Missing Function Docstrings
+1. **`from_openai`** - Needs comprehensive docstring with:
+   - Purpose and usage
+   - Parameters explanation
+   - Return value description
+   - Examples
+
+2. **`from_litellm`** - No docstring. Only has type overloads. Similar to `from_openai`, needs comprehensive docstring.
+
+### Could Be Enhanced
+1. **`Partial`** - Could add more streaming examples
+2. **`patch`** - Could add usage examples showing before/after
+3. **`apatch`** - Has docstring but marked as deprecated ("No longer necessary, use `patch` instead"). Docstring is adequate but the deprecation should be more prominent.
+4. **`openai_schema`** - Has minimal docstring. Could expand with usage examples showing how to use the decorator.
+
+## Recommendations
+
+### High Priority
+1. Add class-level docstrings to `Instructor` and `AsyncInstructor` - These are the core classes users interact with
+2. Add docstring to `from_openai` - Important client creation function
+3. Add class-level docstring to `Response` - Helper class that needs explanation
+
+### Medium Priority
+1. Add class-level docstring to `Image` - Commonly used multimodal class
+2. Add class-level docstring to `Provider` - Enum that could use explanation
+3. Enhance `Partial` docstring with more streaming examples
+
+### Low Priority
+1. Add more examples to `patch` docstring
+2. Expand `openai_schema` docstring with examples
+3. Consider updating `apatch` deprecation message to be more prominent
+
+## Overall Assessment
+
+**Grade: B+**
+
+The documentation is generally good with many excellent examples, but the core classes (`Instructor`, `AsyncInstructor`, `Response`) would benefit significantly from class-level docstrings. The DSL components and utility functions are well-documented, and the exception classes have comprehensive docstrings.
+
+The mkdocs autodoc plugin will generate API documentation from these docstrings, so improving them will directly improve the generated API reference pages.
diff --git a/docs/api.md b/docs/api.md
@@ -5,8 +5,34 @@ description: Explore the comprehensive API reference with details on instructors
 
 # API Reference
 
+Core modes are the recommended default. Legacy provider-specific modes still
+work but are deprecated and will show warnings. See the
+[Mode Migration Guide](concepts/mode-migration.md) for details.
+
+## Core Clients
+
+The main client classes for interacting with LLM providers.
+
+::: instructor.Instructor
+
+::: instructor.AsyncInstructor
+
+::: instructor.core.client.Response
+
+## Client Creation
+
+Functions to create Instructor clients from various providers.
+
 ::: instructor.from_provider
 
+::: instructor.from_openai
+
+::: instructor.from_litellm
+
+## DSL Components
+
+Domain-specific language components for advanced patterns and data handling.
+
 ::: instructor.dsl.validators
 
 ::: instructor.dsl.iterable
@@ -17,4 +43,96 @@ description: Explore the comprehensive API reference with details on instructors
 
 ::: instructor.dsl.maybe
 
+::: instructor.dsl.citation
+
+## Function Calls & Schema
+
+Classes and functions for defining and working with function call schemas.
+
 ::: instructor.function_calls
+
+::: instructor.OpenAISchema
+
+::: instructor.openai_schema
+
+::: instructor.generate_openai_schema
+
+::: instructor.generate_anthropic_schema
+
+::: instructor.generate_gemini_schema
+
+## Validation
+
+Validation utilities for LLM outputs and async validation support.
+
+::: instructor.validation
+
+::: instructor.llm_validator
+
+::: instructor.openai_moderation
+
+## Batch Processing
+
+Batch processing utilities for handling multiple requests efficiently.
+
+::: instructor.batch
+
+::: instructor.batch.BatchProcessor
+
+::: instructor.batch.BatchRequest
+
+::: instructor.batch.BatchJob
+
+## Distillation
+
+Tools for distillation and fine-tuning workflows.
+
+::: instructor.distil
+
+::: instructor.FinetuneFormat
+
+::: instructor.Instructions
+
+## Multimodal
+
+Support for image and audio content in LLM requests.
+
+::: instructor.processing.multimodal
+
+::: instructor.Image
+
+::: instructor.Audio
+
+## Mode & Provider
+
+Enumerations for modes and providers.
+
+::: instructor.Mode
+
+::: instructor.Provider
+
+## Exceptions
+
+Exception classes for error handling.
+
+::: instructor.core.exceptions
+
+## Hooks
+
+Event hooks system for monitoring and intercepting LLM interactions.
+
+::: instructor.core.hooks
+
+::: instructor.core.hooks.Hooks
+
+::: instructor.core.hooks.HookName
+
+## Patch Functions
+
+Decorators for patching LLM client methods.
+
+::: instructor.core.patch
+
+::: instructor.patch
+
+::: instructor.apatch
diff --git a/docs/blog/posts/announcing-instructor-responses-support.md b/docs/blog/posts/announcing-instructor-responses-support.md
@@ -29,12 +29,10 @@ Getting started is now easier than ever. With our unified provider interface, yo
 
 ```python
 import instructor
-from pydantic import BaseModel
 
 # Initialize the client with Responses mode
 client = instructor.from_provider(
-    "openai/gpt-4.1-mini",
-    mode=instructor.Mode.RESPONSES_TOOLS
+    "openai/gpt-4.1-mini", mode=instructor.Mode.RESPONSES_TOOLS
 )
 ```
 
@@ -47,6 +45,7 @@ class User(BaseModel):
     name: str
     age: int
 
+
 # Create structured output
 profile = client.responses.create(
     input="Extract out Ivan is 28 years old",
@@ -70,10 +69,12 @@ class Citation(BaseModel):
     id: int
     url: str
 
+
 class Summary(BaseModel):
     citations: list[Citation]
     summary: str
 
+
 response = client.responses.create(
     input="What are some of the best places to visit in New York for Latin American food?",
     tools=[{"type": "web_search_preview"}],
@@ -88,14 +89,11 @@ For production applications, we've maintained full async support. This lets you
 ```python
 async def get_user_profile():
     async_client = instructor.from_provider(
-        "openai/gpt-4.1-mini",
-        mode=instructor.Mode.RESPONSES_TOOLS,
-        async_client=True
+        "openai/gpt-4.1-mini", mode=instructor.Mode.RESPONSES_TOOLS, async_client=True
     )
 
     profile = await async_client.responses.create(
-        input="Extract: Maria lives in Spain.",
-        response_model=UserProfile
+        input="Extract: Maria lives in Spain.", response_model=UserProfile
     )
 ```
 
@@ -138,8 +136,9 @@ response = client.create(
     response_model=Summary,
 )
 print(response)
-# > citations=[Citation(id=1,url=....)]
-# > summary = New York City offers a rich variety of ...
+"""
+citations=[Citation(id=1, url='https://www.nycgo.com/restaurants/best-latin-american-restaurants-in-nyc/'), Citation(id=2, url='https://www.timeout.com/newyork/restaurants/best-latin-american-restaurants-in-nyc'), Citation(id=3, url='https://www.thrillist.com/eat/nation/best-latin-american-restaurants-nyc')] summary="Some of the best places to visit in New York for Latin American food include neighborhoods and restaurants known for authentic and diverse offerings. In Manhattan, areas like the East Village and Lower East Side have excellent Latin American restaurants. Popular spots include Casa Enrique, known for Mexican cuisine; Tia Pol, offering Spanish and Latin flavors; and La Contenta, serving dishes from various Latin American countries. Brooklyn's Williamsburg and Bushwick have emerged as vibrant spots for Latin American eats, with restaurants such as La Esquina and Fonda not to miss. These places are celebrated for delicious food, lively atmospheres, and cultural authenticity, making them top choices for anyone looking to enjoy Latin American cuisine in New York City."
+"""
 ```
 
 This makes the path forward clear - you can enhance your existing applications with the latest OpenAI features while maintaining the type safety and validation Instructor is known for. No need to learn a new API or refactor your code. It just works.