567-labs--instructor/github_issue.md

Refactor OpenAISchema class methods to standalone functions

Summary

Currently, schema generation for different LLM providers requires models to inherit from OpenAISchema or be wrapped with the @openai_schema decorator. This creates an unnecessary inheritance requirement and couples schema generation to class-based patterns.

We should refactor the schema generation logic into standalone, provider-agnostic functions.

Current State Analysis

Current usage pattern: response_model.openai_schema (where response_model inherits from OpenAISchema)

Affected files with usage counts:

• instructor/utils/ (12 calls across cerebras.py, writer.py, fireworks.py, openai.py, mistral.py)
• instructor/process_response.py (11 calls)
• instructor/dsl/parallel.py (3 calls - handles parallel tools)
• instructor/distil.py (1 call)
• instructor/function_calls.py (13 calls - method definitions and internal usage)
• instructor/utils/core.py (1 call - decorator application)
• instructor/utils/anthropic.py (1 call - anthropic_schema)
• instructor/utils/google.py (1 call - gemini_schema)
• Examples and tests (20+ calls)

Total: ~60 usages across codebase

Proposed Solution

1. Create instructor/schema_utils.py with standalone functions:

from __future__ import annotations
import functools
from typing import Any, Type
from docstring_parser import parse
from pydantic import BaseModel

@functools.lru_cache(maxsize=256)
def generate_openai_schema(model: Type[BaseModel]) -> dict[str, Any]:
    """Generate OpenAI function schema from Pydantic model."""
    # Move logic from OpenAISchema.openai_schema here

def generate_anthropic_schema(model: Type[BaseModel]) -> dict[str, Any]:
    """Generate Anthropic tool schema from Pydantic model."""
    # Move logic from OpenAISchema.anthropic_schema here

def generate_gemini_schema(model: Type[BaseModel]) -> Any:
    """Generate Gemini function schema from Pydantic model."""
    # Move logic from OpenAISchema.gemini_schema here

2. Update OpenAISchema class to delegate to new functions:

class OpenAISchema(BaseModel):
    @classproperty
    def openai_schema(cls):
        return generate_openai_schema(cls)

    @classproperty  
    def anthropic_schema(cls):
        return generate_anthropic_schema(cls)

    @classproperty
    def gemini_schema(cls):
        return generate_gemini_schema(cls)

3. Migration path:

Phase 1: Add new functions, maintain backward compatibility

• All existing response_model.openai_schema calls continue working
• New code can use generate_openai_schema(response_model) directly

Phase 2: Internal migration

• Replace internal usage in utils/ and process_response.py
• Update parallel tools handling in dsl/parallel.py

Phase 3: Deprecation

• Mark @openai_schema decorator as deprecated
• Encourage users to migrate to standalone functions

Benefits

1. No inheritance requirement - Any Pydantic model can generate schemas
2. Provider-agnostic - Clean separation of schema generation logic
3. Better testability - Functions are easier to unit test
4. Performance - LRU cache maintains current performance characteristics
5. Backward compatibility - Zero breaking changes during transition
6. Cleaner API - More functional approach vs class-based inheritance

Implementation Checklist

• Create instructor/schema_utils.py with standalone functions
• Update OpenAISchema class to delegate to new functions
• Add comprehensive tests comparing old vs new output
• Update internal usage in utils/ (12 locations)
• Update process_response.py (11 locations)
• Update parallel tools handling in dsl/parallel.py
• Update distil.py usage
• Mark decorator as deprecated with warning
• Update documentation and examples
• Run full test suite to ensure no regressions

Special Considerations

• Parallel tools: dsl/parallel.py uses both openai_schema(model).openai_schema and openai_schema(model).anthropic_schema patterns
• Caching: Current @classproperty provides implicit memoization - maintain with @lru_cache
• Error handling: Preserve current validation and error behavior
• Provider compatibility: Ensure schema output remains identical for all providers

This refactoring will modernize the schema generation approach while maintaining full backward compatibility.