Skip to content

Commit b44fa73

Browse files
jxnljxnl
committed
feat(v2): add Anthropic and OpenAI providers
- Add instructor/v2/providers/anthropic/ with handlers for TOOLS, JSON_SCHEMA, PARALLEL_TOOLS, ANTHROPIC_REASONING_TOOLS modes - Add instructor/v2/providers/openai/ with handlers for TOOLS, JSON_SCHEMA, MD_JSON, PARALLEL_TOOLS, RESPONSES_TOOLS modes - Update instructor/v2/__init__.py with from_anthropic and from_openai exports - Update instructor/auto_client.py with v2 routing integration - Add tests/v2/test_provider_modes.py for integration tests - Add tests/v2/test_handlers_parametrized.py for unit tests - Add tests/v2/test_openai_streaming.py for streaming tests This PR was written by [Cursor](https://cursor.com)
1 parent 26e1795 commit b44fa73

File tree

11 files changed

+2574
-82
lines changed

11 files changed

+2574
-82
lines changed

‎instructor/auto_client.py‎

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
from instructor.cache import BaseCache
77
import warnings
88
import logging
9+
import json
10+
import time
911

1012
# Type alias for the return type
1113
InstructorType = Union[Instructor, AsyncInstructor]
@@ -411,19 +413,21 @@ def from_provider(
411413
elif provider == "anthropic":
412414
try:
413415
import anthropic
414-
from instructor import from_anthropic # type: ignore[attr-defined] # type: ignore[attr-defined]
416+
from instructor.v2 import from_anthropic
415417

416418
client = (
417419
anthropic.AsyncAnthropic(api_key=api_key)
418420
if async_client
419421
else anthropic.Anthropic(api_key=api_key)
420422
)
421-
max_tokens = kwargs.pop("max_tokens", 4096)
423+
# Set default max_tokens if not provided (like v1)
424+
if "max_tokens" not in kwargs:
425+
kwargs["max_tokens"] = 4096
426+
# Use Mode.TOOLS instead of Mode.ANTHROPIC_TOOLS
422427
result = from_anthropic(
423428
client,
424429
model=model_name,
425-
mode=mode if mode else instructor.Mode.ANTHROPIC_TOOLS,
426-
max_tokens=max_tokens,
430+
mode=mode if mode else instructor.Mode.TOOLS,
427431
**kwargs,
428432
)
429433
logger.info(
@@ -452,7 +456,7 @@ def from_provider(
452456
# Import google-genai package - catch ImportError only for actual imports
453457
try:
454458
import google.genai as genai
455-
from instructor import from_genai # type: ignore[attr-defined]
459+
from instructor.v2 import from_genai
456460
except ImportError as e:
457461
from .core.exceptions import ConfigurationError
458462

@@ -487,21 +491,16 @@ def from_provider(
487491
api_key=api_key,
488492
**client_kwargs,
489493
) # type: ignore
490-
if async_client:
491-
result = from_genai(
492-
client,
493-
use_async=True,
494-
model=model_name,
495-
mode=mode if mode else instructor.Mode.GENAI_TOOLS,
496-
**kwargs,
497-
) # type: ignore
498-
else:
499-
result = from_genai(
500-
client,
501-
model=model_name,
502-
mode=mode if mode else instructor.Mode.GENAI_TOOLS,
503-
**kwargs,
504-
) # type: ignore
494+
# Use v2 from_genai with generic Mode.TOOLS as default
495+
# Extract model from kwargs if present, otherwise use model_name
496+
model_param = kwargs.pop("model", model_name)
497+
result = from_genai(
498+
client,
499+
mode=mode if mode else instructor.Mode.TOOLS,
500+
use_async=async_client,
501+
model=model_param,
502+
**kwargs,
503+
)
505504
logger.info(
506505
"Client initialized",
507506
extra={**provider_info, "status": "success"},
@@ -564,14 +563,41 @@ def from_provider(
564563
elif provider == "cohere":
565564
try:
566565
import cohere
567-
from instructor import from_cohere # type: ignore[attr-defined]
568-
566+
from instructor.v2 import from_cohere
567+
568+
# region agent log
569+
with open("/Users/jasonliu/dev/instructor/.cursor/debug.log", "a") as _log:
570+
_log.write(
571+
json.dumps(
572+
{
573+
"sessionId": "debug-session",
574+
"runId": "streaming-pre",
575+
"hypothesisId": "H5",
576+
"location": "instructor/auto_client.py:from_provider",
577+
"message": "cohere_client_construction",
578+
"data": {
579+
"async_client": bool(async_client),
580+
"has_async_client_v2": hasattr(cohere, "AsyncClientV2"),
581+
"has_client_v2": hasattr(cohere, "ClientV2"),
582+
},
583+
"timestamp": int(time.time() * 1000),
584+
}
585+
)
586+
+ "\n"
587+
)
588+
# endregion agent log
569589
client = (
570590
cohere.AsyncClientV2(api_key=api_key)
571591
if async_client
572592
else cohere.ClientV2(api_key=api_key)
573593
)
574-
result = from_cohere(client, model=model_name, **kwargs)
594+
# Use Mode.TOOLS as default for Cohere
595+
result = from_cohere(
596+
client,
597+
mode=mode if mode else instructor.Mode.TOOLS,
598+
model=model_name,
599+
**kwargs,
600+
)
575601
logger.info(
576602
"Client initialized",
577603
extra={**provider_info, "status": "success"},
@@ -1099,16 +1125,17 @@ def from_provider(
10991125
try:
11001126
from xai_sdk.sync.client import Client as SyncClient
11011127
from xai_sdk.aio.client import Client as AsyncClient
1102-
from instructor import from_xai # type: ignore[attr-defined]
1128+
from instructor.v2 import from_xai
11031129

11041130
client = (
11051131
AsyncClient(api_key=api_key)
11061132
if async_client
11071133
else SyncClient(api_key=api_key)
11081134
)
1135+
# Use Mode.TOOLS instead of Mode.XAI_TOOLS (v2 uses generic modes)
11091136
result = from_xai(
11101137
client,
1111-
mode=mode if mode else instructor.Mode.XAI_JSON,
1138+
mode=mode if mode else instructor.Mode.TOOLS,
11121139
model=model_name,
11131140
**kwargs,
11141141
)

‎instructor/v2/__init__.py‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
"""Instructor V2: Registry-based architecture.
22
33
This module provides the v2 implementation with a registry-based handler system.
4-
Provider-specific functions will be added in subsequent PRs.
54
65
Usage:
76
from instructor import Mode
8-
from instructor.v2 import mode_registry
7+
from instructor.v2 import from_anthropic, from_openai
98
10-
# Check if a mode is registered
11-
if mode_registry.is_registered(Provider.ANTHROPIC, Mode.TOOLS):
12-
handlers = mode_registry.get_handlers(Provider.ANTHROPIC, Mode.TOOLS)
9+
client = from_anthropic(anthropic_client, mode=Mode.TOOLS)
10+
client = from_openai(openai_client, mode=Mode.TOOLS)
1311
"""
1412

1513
from instructor import Mode, Provider
@@ -24,6 +22,17 @@
2422
normalize_mode,
2523
)
2624

25+
# Import providers (will auto-register modes)
26+
try:
27+
from instructor.v2.providers.anthropic import from_anthropic
28+
except ImportError:
29+
from_anthropic = None # type: ignore
30+
31+
try:
32+
from instructor.v2.providers.openai import from_openai
33+
except ImportError:
34+
from_openai = None # type: ignore
35+
2736
__all__ = [
2837
# Re-exports from instructor
2938
"Mode",
@@ -40,4 +49,7 @@
4049
"ReaskHandler",
4150
"RequestHandler",
4251
"ResponseParser",
52+
# Providers
53+
"from_anthropic",
54+
"from_openai",
4355
]

‎instructor/v2/providers/anthropic/__init__.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
"""v2 Anthropic provider."""
2+
3+
try:
4+
from instructor.v2.providers.anthropic.client import from_anthropic
5+
except ImportError:
6+
from_anthropic = None # type: ignore
7+
8+
__all__ = ["from_anthropic"]

‎instructor/v2/providers/anthropic/client.py‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
"""v2 Anthropic client factory.
2+
3+
Creates Instructor instances using v2 hierarchical registry system.
4+
"""
5+
6+
from __future__ import annotations
7+
8+
from typing import Any, overload
9+
10+
import anthropic
11+
12+
from instructor import AsyncInstructor, Instructor, Mode, Provider
13+
from instructor.v2.core.patch import patch_v2
14+
15+
# Ensure handlers are registered (decorators auto-register on import)
16+
from instructor.v2.providers.anthropic import handlers # noqa: F401
17+
18+
19+
@overload
20+
def from_anthropic(
21+
client: (
22+
anthropic.Anthropic | anthropic.AnthropicBedrock | anthropic.AnthropicVertex
23+
),
24+
mode: Mode = Mode.TOOLS,
25+
beta: bool = False,
26+
model: str | None = None,
27+
**kwargs: Any,
28+
) -> Instructor: ...
29+
30+
31+
@overload
32+
def from_anthropic(
33+
client: (
34+
anthropic.AsyncAnthropic
35+
| anthropic.AsyncAnthropicBedrock
36+
| anthropic.AsyncAnthropicVertex
37+
),
38+
mode: Mode = Mode.TOOLS,
39+
beta: bool = False,
40+
model: str | None = None,
41+
**kwargs: Any,
42+
) -> AsyncInstructor: ...
43+
44+
45+
def from_anthropic(
46+
client: (
47+
anthropic.Anthropic
48+
| anthropic.AsyncAnthropic
49+
| anthropic.AnthropicBedrock
50+
| anthropic.AsyncAnthropicBedrock
51+
| anthropic.AsyncAnthropicVertex
52+
| anthropic.AnthropicVertex
53+
),
54+
mode: Mode = Mode.TOOLS,
55+
beta: bool = False,
56+
model: str | None = None,
57+
**kwargs: Any,
58+
) -> Instructor | AsyncInstructor:
59+
"""Create an Instructor instance from an Anthropic client using v2 registry.
60+
61+
Args:
62+
client: An instance of Anthropic client (sync or async)
63+
mode: The mode to use (defaults to Mode.TOOLS)
64+
beta: Whether to use beta API features (uses client.beta.messages.create)
65+
model: Optional model to inject if not provided in requests
66+
**kwargs: Additional keyword arguments to pass to the Instructor constructor
67+
68+
Returns:
69+
An Instructor instance (sync or async depending on the client type)
70+
71+
Raises:
72+
ValueError: If mode is not registered
73+
TypeError: If client is not a valid Anthropic client instance
74+
75+
Examples:
76+
>>> import anthropic
77+
>>> from instructor import Mode
78+
>>> from instructor.v2.providers.anthropic import from_anthropic
79+
>>>
80+
>>> client = anthropic.Anthropic()
81+
>>> instructor_client = from_anthropic(client, mode=Mode.TOOLS)
82+
>>>
83+
>>> # Or use JSON mode
84+
>>> instructor_client = from_anthropic(client, mode=Mode.JSON)
85+
"""
86+
from instructor.v2.core.registry import mode_registry, normalize_mode
87+
88+
# Normalize provider-specific modes to generic modes
89+
# ANTHROPIC_TOOLS -> TOOLS, ANTHROPIC_JSON -> JSON, ANTHROPIC_PARALLEL_TOOLS -> PARALLEL_TOOLS
90+
normalized_mode = normalize_mode(Provider.ANTHROPIC, mode)
91+
92+
# Validate mode is registered (use normalized mode for check)
93+
if not mode_registry.is_registered(Provider.ANTHROPIC, normalized_mode):
94+
from instructor.core.exceptions import ModeError
95+
96+
available_modes = mode_registry.get_modes_for_provider(Provider.ANTHROPIC)
97+
raise ModeError(
98+
mode=mode.value,
99+
provider=Provider.ANTHROPIC.value,
100+
valid_modes=[m.value for m in available_modes],
101+
)
102+
103+
# Use normalized mode for patching
104+
mode = normalized_mode
105+
106+
# Validate client type
107+
valid_client_types = (
108+
anthropic.Anthropic,
109+
anthropic.AsyncAnthropic,
110+
anthropic.AnthropicBedrock,
111+
anthropic.AnthropicVertex,
112+
anthropic.AsyncAnthropicBedrock,
113+
anthropic.AsyncAnthropicVertex,
114+
)
115+
116+
if not isinstance(client, valid_client_types):
117+
from instructor.core.exceptions import ClientError
118+
119+
raise ClientError(
120+
f"Client must be an instance of one of: {', '.join(t.__name__ for t in valid_client_types)}. "
121+
f"Got: {type(client).__name__}"
122+
)
123+
124+
# Get create function (beta or regular)
125+
if beta:
126+
create = client.beta.messages.create
127+
else:
128+
create = client.messages.create
129+
130+
# Patch using v2 registry, passing the model for injection
131+
patched_create = patch_v2(
132+
func=create,
133+
provider=Provider.ANTHROPIC,
134+
mode=mode,
135+
default_model=model,
136+
)
137+
138+
# Return sync or async instructor
139+
if isinstance(
140+
client,
141+
(anthropic.Anthropic, anthropic.AnthropicBedrock, anthropic.AnthropicVertex),
142+
):
143+
return Instructor(
144+
client=client,
145+
create=patched_create,
146+
provider=Provider.ANTHROPIC,
147+
mode=mode,
148+
**kwargs,
149+
)
150+
else:
151+
return AsyncInstructor(
152+
client=client,
153+
create=patched_create,
154+
provider=Provider.ANTHROPIC,
155+
mode=mode,
156+
**kwargs,
157+
)

0 commit comments

Comments
 (0)