{"owner":"567-labs","repo":"instructor","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n# Instructor Development Guide\n\n## Commands\n- Install deps: `uv pip install -e \".[dev,anthropic]\"` or `poetry install --with dev,anthropic`\n- Run tests: `uv run pytest tests/ -n auto`\n- Run specific test: `uv run pytest tests/path_to_test.py::test_name`\n- Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`\n- Type check: `uv run ty check`\n- Lint: `uv run ruff check instructor examples tests`\n- Format: `uv run ruff format instructor examples tests`\n- Generate coverage: `uv run coverage run -m pytest tests/ -k \"not docs\"` then `uv run coverage report`\n- Build documentation: `uv run mkdocs serve` (for local preview) or `./build_mkdocs.sh` (for production)\n- Waiting: use `sleep <seconds>` for explicit pauses (e.g., CI waits) or to let external processes finish\n\n## Installation & Setup\n- Fork the repository and clone your fork\n- Install UV: `pip install uv`\n- Create virtual environment: `uv venv`\n- Install dependencies: `uv pip install -e \".[dev]\"`\n- Install pre-commit: `uv run pre-commit install`\n- Run tests to verify: `uv run pytest tests/ -k \"not openai\"`\n\n## Code Style Guidelines\n- **Typing**: Use strict typing with annotations for all functions and variables\n- **Imports**: Standard lib → third-party → local imports\n- **Formatting**: Follow Black's formatting conventions (enforced by Ruff)\n- **Models**: Define structured outputs as Pydantic BaseModel subclasses\n- **Naming**: snake_case for functions/variables, PascalCase for classes\n- **Error Handling**: Use custom exceptions from exceptions.py, validate with Pydantic\n- **Comments**: Docstrings for public functions, inline comments for complex logic\n\n## Conventional Commits\n- **Format**: `type(scope): description`\n- **Types**: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert\n- **Examples**:\n  - `feat(anthropic): add support for Claude 3.5`\n  - `fix(openai): correct response parsing for streaming`\n  - `docs(README): update installation instructions`\n  - `test(gemini): add validation tests for JSON mode`\n\n## Core Architecture\n- **Base Classes**: `Instructor` and `AsyncInstructor` in client.py are the foundation\n- **Factory Pattern**: Provider-specific factory functions (`from_openai`, `from_anthropic`, etc.)\n- **Unified Access**: `from_provider()` function in auto_client.py for automatic provider detection\n- **Mode System**: `Mode` enum categorizes different provider capabilities (tools vs JSON output)\n- **Patching Mechanism**: Uses Python's dynamic nature to patch provider clients for structured outputs\n- **Response Processing**: Transforms raw API responses into validated Pydantic models\n- **DSL Components**: Special types like Partial, Iterable, Maybe extend the core functionality\n\n## Provider Architecture\n- **Supported Providers**: OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, VertexAI, Fireworks, Cerebras, Writer, Databricks, Anyscale, Together, LiteLLM, Bedrock, Perplexity\n- **Provider Implementation**: Each provider has a dedicated client file (e.g., `client_anthropic.py`) with factory functions\n- **Modes**: Different providers support specific modes (`Mode` enum): `ANTHROPIC_TOOLS`, `GEMINI_JSON`, etc.\n- **Common Pattern**: Factory functions (e.g., `from_anthropic`) take a native client and return patched `Instructor` instances\n- **Provider Testing**: Tests in `tests/llm/` directory, define Pydantic models, make API calls, verify structured outputs\n- **Provider Detection**: `get_provider` function analyzes base URL to detect which provider is being used\n\n## Key Components\n- **process_response.py**: Handles parsing and converting LLM outputs to Pydantic models\n- **patch.py**: Contains the core patching logic for modifying provider clients\n- **function_calls.py**: Handles generating function/tool schemas from Pydantic models\n- **hooks.py**: Provides event hooks for intercepting various stages of the LLM request/response cycle\n- **dsl/**: Domain-specific language extensions for specialized model types\n- **retry.py**: Implements retry logic for handling validation failures\n- **validators.py**: Custom validation mechanisms for structured outputs\n\n## Testing Guidelines\n- Tests are organized by provider under `tests/llm/`\n- Each provider has its own conftest.py with fixtures\n- Standard tests cover: basic extraction, streaming, validation, retries\n- Evaluation tests in `tests/llm/test_provider/evals/` assess model capabilities\n- Use parametrized tests when testing similar functionality across variants\n- **IMPORTANT**: No mocking in tests - tests make real API calls\n\n## Documentation Guidelines\n- Every provider needs documentation in `docs/integrations/` following standard format\n- Provider docs should include: installation, basic example, modes supported, special features\n- When adding a new provider, update `mkdocs.yml` navigation and redirects\n- Example code should include complete imports and environment setup\n- Tutorials should progress from simple to complex concepts\n- New features should include conceptual explanation in `docs/concepts/`\n- **Writing Style**: Grade 10 reading level, all examples must be working code\n\n## Branch and Development Workflow\n1. Fork and clone the repository\n2. Create feature branch: `git checkout -b feat/your-feature`\n3. Make changes and add tests\n4. Run tests and linting\n5. Commit with conventional commit message\n6. Push to your fork and create PR\n7. Use stacked PRs for complex features\n\n## Adding New Providers\n\n### Step-by-Step Guide\n1. **Update Provider Enum** in `instructor/utils.py`:\n   ```python\n   class Provider(Enum):\n       YOUR_PROVIDER = \"your_provider\"\n   ```\n\n2. **Add Provider Modes** in `instructor/mode.py`:\n   ```python\n   class Mode(enum.Enum):\n       YOUR_PROVIDER_TOOLS = \"your_provider_tools\"\n       YOUR_PROVIDER_JSON = \"your_provider_json\"\n   ```\n\n3. **Create Client Implementation** `instructor/client_your_provider.py`:\n   - Use overloads for sync/async variants\n   - Validate mode compatibility\n   - Return appropriate Instructor/AsyncInstructor instance\n   - Handle provider-specific edge cases\n\n4. **Add Conditional Import** in `instructor/__init__.py`:\n   ```python\n   if importlib.util.find_spec(\"your_provider_sdk\") is not None:\n       from .client_your_provider import from_your_provider\n       __all__ += [\"from_your_provider\"]\n   ```\n\n5. **Update Auto Client** in `instructor/auto_client.py`:\n   - Add to `supported_providers` list\n   - Implement provider handling in `from_provider()`\n   - Update `get_provider()` function if URL-detectable\n\n6. **Create Tests** in `tests/llm/test_your_provider/`:\n   - `conftest.py` with client fixtures\n   - Basic extraction tests\n   - Streaming tests\n   - Validation/retry tests\n   - No mocking - use real API calls\n\n7. **Add Documentation** in `docs/integrations/your_provider.md`:\n   - Installation instructions\n   - Basic usage examples\n   - Supported modes\n   - Provider-specific features\n\n8. **Update Navigation** in `mkdocs.yml`:\n   - Add to integrations section\n   - Include redirects if needed\n\n## Contributing to Evals\n- Standard evals for each provider test model capabilities\n- Create new evals following existing patterns\n- Run evals as part of integration test suite\n- Performance tracking and comparison\n\n## Pull Request Guidelines\n- Keep PRs small and focused\n- Include tests for all changes\n- Update documentation as needed\n- Follow PR template\n- Link to relevant issues\n- **Update CHANGELOG.md**: Every PR that changes behavior (fix, feat, security, deprecation) must add an entry under the current `[Unreleased]` section in `CHANGELOG.md`. Format: `- **Area**: Description ([#PR](url))`\n\n## Type System and Best Practices\n\n### Type Checking with ty\n- **Type Checker**: Using `ty` for fast, incremental type checking\n- **Python Version**: 3.9+ for compatibility\n- **Configuration**: Uses `pyproject.toml` settings for type checking\n- Run `uv run ty check` before committing - aim for zero errors\n\n### Code Quality Checks Before Committing\nAlways run these checks before committing code:\n1. **Ruff linting**: `uv run ruff check .` - Fix all errors\n2. **Ruff formatting**: `uv run ruff format .` - Apply consistent formatting\n3. **Type checking**: `uv run ty check` - Aim for zero type errors\n4. **Tests**: Run relevant tests to ensure changes don't break functionality\n\n### Type Patterns\n- **Bounded TypeVars**: Use `T = TypeVar(\"T\", bound=Union[BaseModel, ...])` for constraints\n- **Version Compatibility**: Handle Python 3.9 vs 3.10+ typing differences explicitly\n- **Union Type Syntax**: Use `from __future__ import annotations` to enable Python 3.10+ union syntax (`|`) in Python 3.9\n- **Simple Type Detection**: Special handling for `list[Union[int, str]]` patterns\n- **Runtime Type Handling**: Graceful fallbacks for compatibility\n\n### Pydantic Integration\n- Heavy use of `BaseModel` for structured outputs\n- `TypeAdapter` used internally for JSON schema generation\n- Field validators and custom types\n- Models serve dual purpose: validation and documentation\n\n## Building Documentation\n\n### Setup\n```bash\n# Install documentation dependencies\npip install -r requirements-doc.txt\n```\n\n### Local Development\n```bash\n# Serve documentation locally with hot reload\nuv run mkdocs serve\n\n# Build documentation for production\n./build_mkdocs.sh\n```\n\n### Documentation Features\n- **Material Theme**: Modern UI with extensive customization\n- **Plugins**:\n  - `mkdocstrings` - API documentation from docstrings\n  - `mkdocs-jupyter` - Notebook integration\n  - `mkdocs-redirects` - URL management\n  - Custom hooks for code processing\n- **Custom Processing**: `hide_lines.py` removes code marked with `# <%hide%>`\n- **Redirect Management**: Comprehensive redirect maps for moved content\n\n### Writing Documentation\n- Follow templates in `docs/templates/` for consistency\n- Grade 10 reading level for accessibility\n- All code examples must be runnable\n- Include complete imports and environment setup\n- Progressive complexity: simple → advanced\n\n## Project Structure\n- `instructor/` - Core library code\n  - Base classes (`client.py`): `Instructor` and `AsyncInstructor`\n  - Provider clients (`client_*.py`): Factory functions for each provider\n  - DSL components (`dsl/`): Partial, Iterable, Maybe, Citation extensions\n  - Core logic: `patch.py`, `process_response.py`, `function_calls.py`\n  - CLI tools (`cli/`): Batch processing, file management, usage tracking\n- `tests/` - Test suite organized by provider\n  - Provider-specific tests in `tests/llm/test_<provider>/`\n  - Evaluation tests for model capabilities\n  - No mocking - all tests use real API calls\n- `docs/` - MkDocs documentation\n  - `concepts/` - Core concepts and features\n  - `integrations/` - Provider-specific guides\n  - `examples/` - Practical examples and cookbooks\n  - `learning/` - Progressive tutorial path\n  - `blog/posts/` - Technical articles and announcements\n  - `templates/` - Templates for new docs (provider, concept, cookbook)\n- `examples/` - Runnable code examples\n  - Feature demos: caching, streaming, validation, parallel processing\n  - Use cases: classification, extraction, knowledge graphs\n  - Provider examples: anthropic, openai, groq, mistral\n  - Each example has `run.py` as the main entry point\n- `typings/` - Type stubs for untyped dependencies\n\n## Documentation Structure\n- **Getting Started Path**: Installation → First Extraction → Response Models → Structured Outputs\n- **Learning Patterns**: Simple Objects → Lists → Nested Structures → Validation → Streaming\n- **Example Organization**: Self-contained directories with runnable code demonstrating specific features\n- **Blog Posts**: Technical deep-dives with code examples in `docs/blog/posts/`\n\n## Example Patterns\nWhen creating examples:\n- Use `run.py` as the main file name\n- Include clear imports: stdlib → third-party → instructor\n- Define Pydantic models with descriptive fields\n- Show expected output in comments\n- Handle errors appropriately\n- Make examples self-contained and runnable\n\n## Dependency Management\n\n### Core Dependencies\n- **Minimal core**: `openai`, `pydantic`, `docstring-parser`, `typer`, `rich`\n- **Python requirement**: `<4.0,>=3.9`\n- **Pydantic version**: `<3.0.0,>=2.8.0` (constrained for stability)\n\n### Optional Dependencies\nProvider-specific packages as extras:\n```bash\n# Install with specific provider\npip install \"instructor[anthropic]\"\npip install \"instructor[google-generativeai]\"\npip install \"instructor[groq]\"\n```\n\n### Development Dependencies\n```bash\n# Install all development dependencies\nuv pip install -e \".[dev]\"\n```\nIncludes:\n- ty \n- `pytest` and `pytest-asyncio` - Testing\n- `ruff` - Linting and formatting\n- `coverage` - Test coverage\n- `mkdocs` and plugins - Documentation\n\n### Version Constraints\n- **Upper bounds on all dependencies** for stability\n- **Provider SDK versions** pinned to tested versions\n- **Test dependencies** include evaluation frameworks\n\n### Managing Dependencies\n- Update `pyproject.toml` for new dependencies\n- Test with multiple Python versions (3.9-3.12)\n- Run full test suite after dependency updates\n- Document any provider-specific version requirements\n\nThe library enables structured LLM outputs using Pydantic models across multiple providers with type safety.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n# Instructor Development Guide\n\n## Commands\n- Install deps: `uv pip install -e \".[dev,anthropic]\"` or `poetry install --with dev,anthropic`\n- Run tests: `uv run pytest tests/ -n auto`\n- Run specific test: `uv run pytest tests/path_to_test.py::test_name`\n- Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`\n- Type check: `uv run ty check`\n- Lint: `uv run ruff check instructor examples tests`\n- Format: `uv run ruff format instructor examples tests`\n- Generate coverage: `uv run coverage run -m pytest tests/ -k \"not docs\"` then `uv run coverage report`\n- Build documentation: `uv run mkdocs serve` (for local preview) or `./build_mkdocs.sh` (for production)\n- Waiting: use `sleep <seconds>` for explicit pauses (e.g., CI waits) or to let external processes finish\n\n## Installation & Setup\n- Fork the repository and clone your fork\n- Install UV: `pip install uv`\n- Create virtual environment: `uv venv`\n- Install dependencies: `uv pip install -e \".[dev]\"`\n- Install pre-commit: `uv run pre-commit install`\n- Run tests to verify: `uv run pytest tests/ -k \"not openai\"`\n\n## Code Style Guidelines\n- **Typing**: Use strict typing with annotations for all functions and variables\n- **Imports**: Standard lib → third-party → local imports\n- **Formatting**: Follow Black's formatting conventions (enforced by Ruff)\n- **Models**: Define structured outputs as Pydantic BaseModel subclasses\n- **Naming**: snake_case for functions/variables, PascalCase for classes\n- **Error Handling**: Use custom exceptions from exceptions.py, validate with Pydantic\n- **Comments**: Docstrings for public functions, inline comments for complex logic\n\n## Conventional Commits\n- **Format**: `type(scope): description`\n- **Types**: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert\n- **Examples**:\n  - `feat(anthropic): add support for Claude 3.5`\n  - `fix(openai): correct response parsing for streaming`\n  - `docs(README): update installation instructions`\n  - `test(gemini): add validation tests for JSON mode`\n\n## Core Architecture\n- **Base Classes**: `Instructor` and `AsyncInstructor` in client.py are the foundation\n- **Factory Pattern**: Provider-specific factory functions (`from_openai`, `from_anthropic`, etc.)\n- **Unified Access**: `from_provider()` function in auto_client.py for automatic provider detection\n- **Mode System**: `Mode` enum categorizes different provider capabilities (tools vs JSON output)\n- **Patching Mechanism**: Uses Python's dynamic nature to patch provider clients for structured outputs\n- **Response Processing**: Transforms raw API responses into validated Pydantic models\n- **DSL Components**: Special types like Partial, Iterable, Maybe extend the core functionality\n\n## Provider Architecture\n- **Supported Providers**: OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, VertexAI, Fireworks, Cerebras, Writer, Databricks, Anyscale, Together, LiteLLM, Bedrock, Perplexity\n- **Provider Implementation**: Each provider has a dedicated client file (e.g., `client_anthropic.py`) with factory functions\n- **Modes**: Different providers support specific modes (`Mode` enum): `ANTHROPIC_TOOLS`, `GEMINI_JSON`, etc.\n- **Common Pattern**: Factory functions (e.g., `from_anthropic`) take a native client and return patched `Instructor` instances\n- **Provider Testing**: Tests in `tests/llm/` directory, define Pydantic models, make API calls, verify structured outputs\n- **Provider Detection**: `get_provider` function analyzes base URL to detect which provider is being used\n\n## Key Components\n- **process_response.py**: Handles parsing and converting LLM outputs to Pydantic models\n- **patch.py**: Contains the core patching logic for modifying provider clients\n- **function_calls.py**: Handles generating function/tool schemas from Pydantic models\n- **hooks.py**: Provides event hooks for intercepting various stages of the LLM request/response cycle\n- **dsl/**: Domain-specific language extensions for specialized model types\n- **retry.py**: Implements retry logic for handling validation failures\n- **validators.py**: Custom validation mechanisms for structured outputs\n\n## Testing Guidelines\n- Tests are organized by provider under `tests/llm/`\n- Each provider has its own conftest.py with fixtures\n- Standard tests cover: basic extraction, streaming, validation, retries\n- Evaluation tests in `tests/llm/test_provider/evals/` assess model capabilities\n- Use parametrized tests when testing similar functionality across variants\n- **IMPORTANT**: No mocking in tests - tests make real API calls\n\n## Documentation Guidelines\n- Every provider needs documentation in `docs/integrations/` following standard format\n- Provider docs should include: installation, basic example, modes supported, special features\n- When adding a new provider, update `mkdocs.yml` navigation and redirects\n- Example code should include complete imports and environment setup\n- Tutorials should progress from simple to complex concepts\n- New features should include conceptual explanation in `docs/concepts/`\n- **Writing Style**: Grade 10 reading level, all examples must be working code\n\n## Branch and Development Workflow\n1. Fork and clone the repository\n2. Create feature branch: `git checkout -b feat/your-feature`\n3. Make changes and add tests\n4. Run tests and linting\n5. Commit with conventional commit message\n6. Push to your fork and create PR\n7. Use stacked PRs for complex features\n\n## Adding New Providers\n\n### Step-by-Step Guide\n1. **Update Provider Enum** in `instructor/utils.py`:\n   ```python\n   class Provider(Enum):\n       YOUR_PROVIDER = \"your_provider\"\n   ```\n\n2. **Add Provider Modes** in `instructor/mode.py`:\n   ```python\n   class Mode(enum.Enum):\n       YOUR_PROVIDER_TOOLS = \"your_provider_tools\"\n       YOUR_PROVIDER_JSON = \"your_provider_json\"\n   ```\n\n3. **Create Client Implementation** `instructor/client_your_provider.py`:\n   - Use overloads for sync/async variants\n   - Validate mode compatibility\n   - Return appropriate Instructor/AsyncInstructor instance\n   - Handle provider-specific edge cases\n\n4. **Add Conditional Import** in `instructor/__init__.py`:\n   ```python\n   if importlib.util.find_spec(\"your_provider_sdk\") is not None:\n       from .client_your_provider import from_your_provider\n       __all__ += [\"from_your_provider\"]\n   ```\n\n5. **Update Auto Client** in `instructor/auto_client.py`:\n   - Add to `supported_providers` list\n   - Implement provider handling in `from_provider()`\n   - Update `get_provider()` function if URL-detectable\n\n6. **Create Tests** in `tests/llm/test_your_provider/`:\n   - `conftest.py` with client fixtures\n   - Basic extraction tests\n   - Streaming tests\n   - Validation/retry tests\n   - No mocking - use real API calls\n\n7. **Add Documentation** in `docs/integrations/your_provider.md`:\n   - Installation instructions\n   - Basic usage examples\n   - Supported modes\n   - Provider-specific features\n\n8. **Update Navigation** in `mkdocs.yml`:\n   - Add to integrations section\n   - Include redirects if needed\n\n## Contributing to Evals\n- Standard evals for each provider test model capabilities\n- Create new evals following existing patterns\n- Run evals as part of integration test suite\n- Performance tracking and comparison\n\n## Pull Request Guidelines\n- Keep PRs small and focused\n- Include tests for all changes\n- Update documentation as needed\n- Follow PR template\n- Link to relevant issues\n- **Update CHANGELOG.md**: Every PR that changes behavior (fix, feat, security, deprecation) must add an entry under the current `[Unreleased]` section in `CHANGELOG.md`. Format: `- **Area**: Description ([#PR](url))`\n\n## Type System and Best Practices\n\n### Type Checking with ty\n- **Type Checker**: Using `ty` for fast, incremental type checking\n- **Python Version**: 3.9+ for compatibility\n- **Configuration**: Uses `pyproject.toml` settings for type checking\n- Run `uv run ty check` before committing - aim for zero errors\n\n### Code Quality Checks Before Committing\nAlways run these checks before committing code:\n1. **Ruff linting**: `uv run ruff check .` - Fix all errors\n2. **Ruff formatting**: `uv run ruff format .` - Apply consistent formatting\n3. **Type checking**: `uv run ty check` - Aim for zero type errors\n4. **Tests**: Run relevant tests to ensure changes don't break functionality\n\n### Type Patterns\n- **Bounded TypeVars**: Use `T = TypeVar(\"T\", bound=Union[BaseModel, ...])` for constraints\n- **Version Compatibility**: Handle Python 3.9 vs 3.10+ typing differences explicitly\n- **Union Type Syntax**: Use `from __future__ import annotations` to enable Python 3.10+ union syntax (`|`) in Python 3.9\n- **Simple Type Detection**: Special handling for `list[Union[int, str]]` patterns\n- **Runtime Type Handling**: Graceful fallbacks for compatibility\n\n### Pydantic Integration\n- Heavy use of `BaseModel` for structured outputs\n- `TypeAdapter` used internally for JSON schema generation\n- Field validators and custom types\n- Models serve dual purpose: validation and documentation\n\n## Building Documentation\n\n### Setup\n```bash\n# Install documentation dependencies\npip install -r requirements-doc.txt\n```\n\n### Local Development\n```bash\n# Serve documentation locally with hot reload\nuv run mkdocs serve\n\n# Build documentation for production\n./build_mkdocs.sh\n```\n\n### Documentation Features\n- **Material Theme**: Modern UI with extensive customization\n- **Plugins**:\n  - `mkdocstrings` - API documentation from docstrings\n  - `mkdocs-jupyter` - Notebook integration\n  - `mkdocs-redirects` - URL management\n  - Custom hooks for code processing\n- **Custom Processing**: `hide_lines.py` removes code marked with `# <%hide%>`\n- **Redirect Management**: Comprehensive redirect maps for moved content\n\n### Writing Documentation\n- Follow templates in `docs/templates/` for consistency\n- Grade 10 reading level for accessibility\n- All code examples must be runnable\n- Include complete imports and environment setup\n- Progressive complexity: simple → advanced\n\n## Project Structure\n- `instructor/` - Core library code\n  - Base classes (`client.py`): `Instructor` and `AsyncInstructor`\n  - Provider clients (`client_*.py`): Factory functions for each provider\n  - DSL components (`dsl/`): Partial, Iterable, Maybe, Citation extensions\n  - Core logic: `patch.py`, `process_response.py`, `function_calls.py`\n  - CLI tools (`cli/`): Batch processing, file management, usage tracking\n- `tests/` - Test suite organized by provider\n  - Provider-specific tests in `tests/llm/test_<provider>/`\n  - Evaluation tests for model capabilities\n  - No mocking - all tests use real API calls\n- `docs/` - MkDocs documentation\n  - `concepts/` - Core concepts and features\n  - `integrations/` - Provider-specific guides\n  - `examples/` - Practical examples and cookbooks\n  - `learning/` - Progressive tutorial path\n  - `blog/posts/` - Technical articles and announcements\n  - `templates/` - Templates for new docs (provider, concept, cookbook)\n- `examples/` - Runnable code examples\n  - Feature demos: caching, streaming, validation, parallel processing\n  - Use cases: classification, extraction, knowledge graphs\n  - Provider examples: anthropic, openai, groq, mistral\n  - Each example has `run.py` as the main entry point\n- `typings/` - Type stubs for untyped dependencies\n\n## Documentation Structure\n- **Getting Started Path**: Installation → First Extraction → Response Models → Structured Outputs\n- **Learning Patterns**: Simple Objects → Lists → Nested Structures → Validation → Streaming\n- **Example Organization**: Self-contained directories with runnable code demonstrating specific features\n- **Blog Posts**: Technical deep-dives with code examples in `docs/blog/posts/`\n\n## Example Patterns\nWhen creating examples:\n- Use `run.py` as the main file name\n- Include clear imports: stdlib → third-party → instructor\n- Define Pydantic models with descriptive fields\n- Show expected output in comments\n- Handle errors appropriately\n- Make examples self-contained and runnable\n\n## Dependency Management\n\n### Core Dependencies\n- **Minimal core**: `openai`, `pydantic`, `docstring-parser`, `typer`, `rich`\n- **Python requirement**: `<4.0,>=3.9`\n- **Pydantic version**: `<3.0.0,>=2.8.0` (constrained for stability)\n\n### Optional Dependencies\nProvider-specific packages as extras:\n```bash\n# Install with specific provider\npip install \"instructor[anthropic]\"\npip install \"instructor[google-generativeai]\"\npip install \"instructor[groq]\"\n```\n\n### Development Dependencies\n```bash\n# Install all development dependencies\nuv pip install -e \".[dev]\"\n```\nIncludes:\n- ty \n- `pytest` and `pytest-asyncio` - Testing\n- `ruff` - Linting and formatting\n- `coverage` - Test coverage\n- `mkdocs` and plugins - Documentation\n\n### Version Constraints\n- **Upper bounds on all dependencies** for stability\n- **Provider SDK versions** pinned to tested versions\n- **Test dependencies** include evaluation frameworks\n\n### Managing Dependencies\n- Update `pyproject.toml` for new dependencies\n- Test with multiple Python versions (3.9-3.12)\n- Run full test suite after dependency updates\n- Document any provider-specific version requirements\n\nThe library enables structured LLM outputs using Pydantic models across multiple providers with type safety.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n# Instructor Development Guide\n\n## Commands\n- Install deps: `uv pip install -e \".[dev,anthropic]\"` or `poetry install --with dev,anthropic`\n- Run tests: `uv run pytest tests/ -n auto`\n- Run specific test: `uv run pytest tests/path_to_test.py::test_name`\n- Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`\n- Type check: `uv run ty check`\n- Lint: `uv run ruff check instructor examples tests`\n- Format: `uv run ruff format instructor examples tests`\n- Generate coverage: `uv run coverage run -m pytest tests/ -k \"not docs\"` then `uv run coverage report`\n- Build documentation: `uv run mkdocs serve` (for local preview) or `./build_mkdocs.sh` (for production)\n- Waiting: use `sleep <seconds>` for explicit pauses (e.g., CI waits) or to let external processes finish\n\n## Installation & Setup\n- Fork the repository and clone your fork\n- Install UV: `pip install uv`\n- Create virtual environment: `uv venv`\n- Install dependencies: `uv pip install -e \".[dev]\"`\n- Install pre-commit: `uv run pre-commit install`\n- Run tests to verify: `uv run pytest tests/ -k \"not openai\"`\n\n## Code Style Guidelines\n- **Typing**: Use strict typing with annotations for all functions and variables\n- **Imports**: Standard lib → third-party → local imports\n- **Formatting**: Follow Black's formatting conventions (enforced by Ruff)\n- **Models**: Define structured outputs as Pydantic BaseModel subclasses\n- **Naming**: snake_case for functions/variables, PascalCase for classes\n- **Error Handling**: Use custom exceptions from exceptions.py, validate with Pydantic\n- **Comments**: Docstrings for public functions, inline comments for complex logic\n\n## Conventional Commits\n- **Format**: `type(scope): description`\n- **Types**: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert\n- **Examples**:\n  - `feat(anthropic): add support for Claude 3.5`\n  - `fix(openai): correct response parsing for streaming`\n  - `docs(README): update installation instructions`\n  - `test(gemini): add validation tests for JSON mode`\n\n## Core Architecture\n- **Base Classes**: `Instructor` and `AsyncInstructor` in client.py are the foundation\n- **Factory Pattern**: Provider-specific factory functions (`from_openai`, `from_anthropic`, etc.)\n- **Unified Access**: `from_provider()` function in auto_client.py for automatic provider detection\n- **Mode System**: `Mode` enum categorizes different provider capabilities (tools vs JSON output)\n- **Patching Mechanism**: Uses Python's dynamic nature to patch provider clients for structured outputs\n- **Response Processing**: Transforms raw API responses into validated Pydantic models\n- **DSL Components**: Special types like Partial, Iterable, Maybe extend the core functionality\n\n## Provider Architecture\n- **Supported Providers**: OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, VertexAI, Fireworks, Cerebras, Writer, Databricks, Anyscale, Together, LiteLLM, Bedrock, Perplexity\n- **Provider Implementation**: Each provider has a dedicated client file (e.g., `client_anthropic.py`) with factory functions\n- **Modes**: Different providers support specific modes (`Mode` enum): `ANTHROPIC_TOOLS`, `GEMINI_JSON`, etc.\n- **Common Pattern**: Factory functions (e.g., `from_anthropic`) take a native client and return patched `Instructor` instances\n- **Provider Testing**: Tests in `tests/llm/` directory, define Pydantic models, make API calls, verify structured outputs\n- **Provider Detection**: `get_provider` function analyzes base URL to detect which provider is being used\n\n## Key Components\n- **process_response.py**: Handles parsing and converting LLM outputs to Pydantic models\n- **patch.py**: Contains the core patching logic for modifying provider clients\n- **function_calls.py**: Handles generating function/tool schemas from Pydantic models\n- **hooks.py**: Provides event hooks for intercepting various stages of the LLM request/response cycle\n- **dsl/**: Domain-specific language extensions for specialized model types\n- **retry.py**: Implements retry logic for handling validation failures\n- **validators.py**: Custom validation mechanisms for structured outputs\n\n## Testing Guidelines\n- Tests are organized by provider under `tests/llm/`\n- Each provider has its own conftest.py with fixtures\n- Standard tests cover: basic extraction, streaming, validation, retries\n- Evaluation tests in `tests/llm/test_provider/evals/` assess model capabilities\n- Use parametrized tests when testing similar functionality across variants\n- **IMPORTANT**: No mocking in tests - tests make real API calls\n\n## Documentation Guidelines\n- Every provider needs documentation in `docs/integrations/` following standard format\n- Provider docs should include: installation, basic example, modes supported, special features\n- When adding a new provider, update `mkdocs.yml` navigation and redirects\n- Example code should include complete imports and environment setup\n- Tutorials should progress from simple to complex concepts\n- New features should include conceptual explanation in `docs/concepts/`\n- **Writing Style**: Grade 10 reading level, all examples must be working code\n\n## Branch and Development Workflow\n1. Fork and clone the repository\n2. Create feature branch: `git checkout -b feat/your-feature`\n3. Make changes and add tests\n4. Run tests and linting\n5. Commit with conventional commit message\n6. Push to your fork and create PR\n7. Use stacked PRs for complex features\n\n## Adding New Providers\n\n### Step-by-Step Guide\n1. **Update Provider Enum** in `instructor/utils.py`:\n   ```python\n   class Provider(Enum):\n       YOUR_PROVIDER = \"your_provider\"\n   ```\n\n2. **Add Provider Modes** in `instructor/mode.py`:\n   ```python\n   class Mode(enum.Enum):\n       YOUR_PROVIDER_TOOLS = \"your_provider_tools\"\n       YOUR_PROVIDER_JSON = \"your_provider_json\"\n   ```\n\n3. **Create Client Implementation** `instructor/client_your_provider.py`:\n   - Use overloads for sync/async variants\n   - Validate mode compatibility\n   - Return appropriate Instructor/AsyncInstructor instance\n   - Handle provider-specific edge cases\n\n4. **Add Conditional Import** in `instructor/__init__.py`:\n   ```python\n   if importlib.util.find_spec(\"your_provider_sdk\") is not None:\n       from .client_your_provider import from_your_provider\n       __all__ += [\"from_your_provider\"]\n   ```\n\n5. **Update Auto Client** in `instructor/auto_client.py`:\n   - Add to `supported_providers` list\n   - Implement provider handling in `from_provider()`\n   - Update `get_provider()` function if URL-detectable\n\n6. **Create Tests** in `tests/llm/test_your_provider/`:\n   - `conftest.py` with client fixtures\n   - Basic extraction tests\n   - Streaming tests\n   - Validation/retry tests\n   - No mocking - use real API calls\n\n7. **Add Documentation** in `docs/integrations/your_provider.md`:\n   - Installation instructions\n   - Basic usage examples\n   - Supported modes\n   - Provider-specific features\n\n8. **Update Navigation** in `mkdocs.yml`:\n   - Add to integrations section\n   - Include redirects if needed\n\n## Contributing to Evals\n- Standard evals for each provider test model capabilities\n- Create new evals following existing patterns\n- Run evals as part of integration test suite\n- Performance tracking and comparison\n\n## Pull Request Guidelines\n- Keep PRs small and focused\n- Include tests for all changes\n- Update documentation as needed\n- Follow PR template\n- Link to relevant issues\n- **Update CHANGELOG.md**: Every PR that changes behavior (fix, feat, security, deprecation) must add an entry under the current `[Unreleased]` section in `CHANGELOG.md`. Format: `- **Area**: Description ([#PR](url))`\n\n## Type System and Best Practices\n\n### Type Checking with ty\n- **Type Checker**: Using `ty` for fast, incremental type checking\n- **Python Version**: 3.9+ for compatibility\n- **Configuration**: Uses `pyproject.toml` settings for type checking\n- Run `uv run ty check` before committing - aim for zero errors\n\n### Code Quality Checks Before Committing\nAlways run these checks before committing code:\n1. **Ruff linting**: `uv run ruff check .` - Fix all errors\n2. **Ruff formatting**: `uv run ruff format .` - Apply consistent formatting\n3. **Type checking**: `uv run ty check` - Aim for zero type errors\n4. **Tests**: Run relevant tests to ensure changes don't break functionality\n\n### Type Patterns\n- **Bounded TypeVars**: Use `T = TypeVar(\"T\", bound=Union[BaseModel, ...])` for constraints\n- **Version Compatibility**: Handle Python 3.9 vs 3.10+ typing differences explicitly\n- **Union Type Syntax**: Use `from __future__ import annotations` to enable Python 3.10+ union syntax (`|`) in Python 3.9\n- **Simple Type Detection**: Special handling for `list[Union[int, str]]` patterns\n- **Runtime Type Handling**: Graceful fallbacks for compatibility\n\n### Pydantic Integration\n- Heavy use of `BaseModel` for structured outputs\n- `TypeAdapter` used internally for JSON schema generation\n- Field validators and custom types\n- Models serve dual purpose: validation and documentation\n\n## Building Documentation\n\n### Setup\n```bash\n# Install documentation dependencies\npip install -r requirements-doc.txt\n```\n\n### Local Development\n```bash\n# Serve documentation locally with hot reload\nuv run mkdocs serve\n\n# Build documentation for production\n./build_mkdocs.sh\n```\n\n### Documentation Features\n- **Material Theme**: Modern UI with extensive customization\n- **Plugins**:\n  - `mkdocstrings` - API documentation from docstrings\n  - `mkdocs-jupyter` - Notebook integration\n  - `mkdocs-redirects` - URL management\n  - Custom hooks for code processing\n- **Custom Processing**: `hide_lines.py` removes code marked with `# <%hide%>`\n- **Redirect Management**: Comprehensive redirect maps for moved content\n\n### Writing Documentation\n- Follow templates in `docs/templates/` for consistency\n- Grade 10 reading level for accessibility\n- All code examples must be runnable\n- Include complete imports and environment setup\n- Progressive complexity: simple → advanced\n\n## Project Structure\n- `instructor/` - Core library code\n  - Base classes (`client.py`): `Instructor` and `AsyncInstructor`\n  - Provider clients (`client_*.py`): Factory functions for each provider\n  - DSL components (`dsl/`): Partial, Iterable, Maybe, Citation extensions\n  - Core logic: `patch.py`, `process_response.py`, `function_calls.py`\n  - CLI tools (`cli/`): Batch processing, file management, usage tracking\n- `tests/` - Test suite organized by provider\n  - Provider-specific tests in `tests/llm/test_<provider>/`\n  - Evaluation tests for model capabilities\n  - No mocking - all tests use real API calls\n- `docs/` - MkDocs documentation\n  - `concepts/` - Core concepts and features\n  - `integrations/` - Provider-specific guides\n  - `examples/` - Practical examples and cookbooks\n  - `learning/` - Progressive tutorial path\n  - `blog/posts/` - Technical articles and announcements\n  - `templates/` - Templates for new docs (provider, concept, cookbook)\n- `examples/` - Runnable code examples\n  - Feature demos: caching, streaming, validation, parallel processing\n  - Use cases: classification, extraction, knowledge graphs\n  - Provider examples: anthropic, openai, groq, mistral\n  - Each example has `run.py` as the main entry point\n- `typings/` - Type stubs for untyped dependencies\n\n## Documentation Structure\n- **Getting Started Path**: Installation → First Extraction → Response Models → Structured Outputs\n- **Learning Patterns**: Simple Objects → Lists → Nested Structures → Validation → Streaming\n- **Example Organization**: Self-contained directories with runnable code demonstrating specific features\n- **Blog Posts**: Technical deep-dives with code examples in `docs/blog/posts/`\n\n## Example Patterns\nWhen creating examples:\n- Use `run.py` as the main file name\n- Include clear imports: stdlib → third-party → instructor\n- Define Pydantic models with descriptive fields\n- Show expected output in comments\n- Handle errors appropriately\n- Make examples self-contained and runnable\n\n## Dependency Management\n\n### Core Dependencies\n- **Minimal core**: `openai`, `pydantic`, `docstring-parser`, `typer`, `rich`\n- **Python requirement**: `<4.0,>=3.9`\n- **Pydantic version**: `<3.0.0,>=2.8.0` (constrained for stability)\n\n### Optional Dependencies\nProvider-specific packages as extras:\n```bash\n# Install with specific provider\npip install \"instructor[anthropic]\"\npip install \"instructor[google-generativeai]\"\npip install \"instructor[groq]\"\n```\n\n### Development Dependencies\n```bash\n# Install all development dependencies\nuv pip install -e \".[dev]\"\n```\nIncludes:\n- ty \n- `pytest` and `pytest-asyncio` - Testing\n- `ruff` - Linting and formatting\n- `coverage` - Test coverage\n- `mkdocs` and plugins - Documentation\n\n### Version Constraints\n- **Upper bounds on all dependencies** for stability\n- **Provider SDK versions** pinned to tested versions\n- **Test dependencies** include evaluation frameworks\n\n### Managing Dependencies\n- Update `pyproject.toml` for new dependencies\n- Test with multiple Python versions (3.9-3.12)\n- Run full test suite after dependency updates\n- Document any provider-specific version requirements\n\nThe library enables structured LLM outputs using Pydantic models across multiple providers with type safety.\n","category":"root","tokens":3327}]}