Skip to content

Refactor: Create providers package to modularize LLM client implementations #1532

Closed as not planned
@jxnl

Description

@jxnl

The current flat structure with individual client_*.py files has become difficult to maintain as we add more providers. We should reorganize into a proper provider package structure.

Current problems:

  • Flat directory with many provider-specific files cluttering the root namespace
  • Related provider code is scattered across client_*.py and process_response.py
  • No clear interface that providers must implement
  • Difficult to discover which functionality is supported by which provider

Proposed solution:

instructor/
├── providers/
│   ├── __init__.py     # Provider registry and common utilities
│   ├── base.py         # Provider interface/protocol
│   ├── oai_provider.py # OpenAI implementation (avoid name conflict)
│   ├── claude.py       # Anthropic implementation 
│   └── ...             # Other providers

Each provider module would contain:

  1. Factory functions (e.g., from_openai)
  2. Provider-specific response handlers (moved from process_response.py)
  3. Provider-specific validation logic (mode support, etc.)
  4. Provider-specific utility functions
  5. Structured comments documenting supported features

Implementation steps:

  1. Create providers/ directory with placeholder __init__.py and base.py
  2. Move each client_*.py file into corresponding provider module with non-conflicting names
  3. Move provider-specific handlers from process_response.py to provider modules
  4. Update imports throughout codebase
  5. Update type annotations to reflect new structure

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpythonPull requests that update python codesize:MThis PR changes 30-99 lines, ignoring generated files.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions