feat(v2): implement core infrastructure (registry, handlers, protocols)

Author: jxnl

instructor/v2/__init__.py

@@ -0,0 +1,46 @@
+"""Instructor v2 - Mode registry system.
+
+v2 uses a registry system that maps Mode enum values directly to handlers.
+This replaces the hardcoded dictionaries in v1 with a dynamic, extensible system.
+
+Usage:
+    from instructor import Mode
+    from instructor.v2 import from_anthropic
+
+    client = from_anthropic(anthropic_client, mode=Mode.ANTHROPIC_TOOLS)
+
+Benefits:
+- Dynamic registration: Modes register themselves via decorators
+- Lazy loading: Handlers loaded only when used
+- Extensible: Easy to add new modes without modifying core
+- Type-safe: Protocols ensure handler compatibility
+"""
+
+from instructor import Mode, Provider
+from instructor.v2.core.handler import ModeHandler
+from instructor.v2.core.protocols import ReaskHandler, RequestHandler, ResponseParser
+from instructor.v2.core.registry import ModeHandlers, ModeRegistry, mode_registry
+
+# Import providers (will auto-register modes)
+try:
+    from instructor.v2.providers.anthropic import from_anthropic
+except ImportError:
+    from_anthropic = None  # type: ignore
+
+__all__ = [
+    # Core types
+    "Provider",
+    "Mode",
+    # Registry
+    "mode_registry",
+    "ModeRegistry",
+    "ModeHandlers",
+    # Handler base class
+    "ModeHandler",
+    # Protocols
+    "RequestHandler",
+    "ReaskHandler",
+    "ResponseParser",
+    # Providers
+    "from_anthropic",
+]

instructor/v2/core/__init__.py

@@ -0,0 +1,16 @@
+"""Core v2 infrastructure - registry, protocols, and mode types."""
+
+from instructor import Mode, Provider
+from instructor.v2.core.protocols import ReaskHandler, RequestHandler, ResponseParser
+from instructor.v2.core.registry import ModeHandlers, ModeRegistry, mode_registry
+
+__all__ = [
+    "Provider",
+    "Mode",
+    "mode_registry",
+    "ModeRegistry",
+    "ModeHandlers",
+    "RequestHandler",
+    "ReaskHandler",
+    "ResponseParser",
+]

instructor/v2/core/decorators.py

@@ -0,0 +1,52 @@
+"""Decorator utilities for v2 mode registration."""
+
+from instructor import Mode, Provider
+from instructor.v2.core.registry import mode_registry
+
+
+def register_mode_handler(
+    provider: Provider,
+    mode: Mode,
+):
+    """Decorator to register a mode handler class.
+
+    The decorated class must implement RequestHandler, ReaskHandler,
+    and ResponseParser protocols via prepare_request, handle_reask,
+    and parse_response methods.
+
+    Args:
+        provider: Provider enum value (for tracking)
+        mode: Mode enum value
+
+    Returns:
+        Decorator function
+
+    Example:
+        >>> from instructor import Mode
+        >>> @register_mode_handler(Provider.ANTHROPIC, Mode.ANTHROPIC_TOOLS)
+        ... class AnthropicToolsHandler:
+        ...     def prepare_request(self, response_model, kwargs):
+        ...         return response_model, kwargs
+        ...     def handle_reask(self, kwargs, response, exception):
+        ...         return kwargs
+        ...     def parse_response(self, response, response_model, **kwargs):
+        ...         return response_model.model_validate(response)
+    """
+
+    def decorator(handler_class: type) -> type:
+        """Register the handler class."""
+        # Instantiate the handler
+        handler = handler_class()
+
+        # Register with the registry
+        mode_registry.register(
+            mode=mode,
+            provider=provider,
+            request_handler=handler.prepare_request,
+            reask_handler=handler.handle_reask,
+            response_parser=handler.parse_response,
+        )
+
+        return handler_class
+
+    return decorator

instructor/v2/core/handler.py

@@ -0,0 +1,94 @@
+"""Base handler class for v2 mode handlers.
+
+Provides the common interface and default implementations for mode handlers.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ModeHandler(ABC):
+    """Base class for mode handlers.
+
+    Subclasses must implement prepare_request, handle_reask, and parse_response.
+    These methods define how requests are prepared, errors are handled, and
+    responses are parsed for a specific mode.
+    """
+
+    @abstractmethod
+    def prepare_request(
+        self,
+        response_model: type[BaseModel] | None,
+        kwargs: dict[str, Any],
+    ) -> tuple[type[BaseModel] | None, dict[str, Any]]:
+        """Prepare request kwargs for this mode.
+
+        Args:
+            response_model: Pydantic model to extract (or None for unstructured)
+            kwargs: Original request kwargs from user
+
+        Returns:
+            Tuple of (possibly modified response_model, modified kwargs)
+
+        Example:
+            For TOOLS mode, this adds "tools" and "tool_choice" to kwargs.
+            For JSON mode, this adds JSON schema to system message.
+        """
+        ...
+
+    @abstractmethod
+    def handle_reask(
+        self,
+        kwargs: dict[str, Any],
+        response: Any,
+        exception: Exception,
+    ) -> dict[str, Any]:
+        """Handle validation failure and prepare retry request.
+
+        Args:
+            kwargs: Original request kwargs
+            response: Failed API response
+            exception: Validation exception that occurred
+
+        Returns:
+            Modified kwargs for retry attempt
+
+        Example:
+            For TOOLS mode, appends tool_result with error message.
+            For JSON mode, appends user message with validation error.
+        """
+        ...
+
+    @abstractmethod
+    def parse_response(
+        self,
+        response: Any,
+        response_model: type[BaseModel],
+        validation_context: dict[str, Any] | None = None,
+        strict: bool | None = None,
+    ) -> BaseModel:
+        """Parse API response into validated Pydantic model.
+
+        Args:
+            response: Raw API response
+            response_model: Pydantic model to validate against
+            validation_context: Optional context for Pydantic validation
+            strict: Optional strict validation mode
+
+        Returns:
+            Validated Pydantic model instance
+
+        Raises:
+            ValidationError: If response doesn't match model schema
+
+        Example:
+            For TOOLS mode, extracts tool_use blocks and validates.
+            For JSON mode, extracts JSON from text blocks and validates.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """String representation of handler."""
+        return f"<{self.__class__.__name__}>"