.TOOLS Mode Breaking with Enums in response_model — Any insights?

[ashoknimiwal]

Hi everyone,

I'm running into a problem with the instructor library when using .TOOLS mode, and I’m hoping the community can help me figure this out.

🚨 Issue Summary

I recently noticed that .TOOLS mode is throwing an error when using Enum types in the response_model. Interestingly, this setup was working perfectly fine about 4-5 days ago.

Here’s the error I’m getting:
InstructorRetryException: Error code: 400 - {'object': 'error', 'message': 'The provided JSON schema contains features not supported by xgrammar.', 'type': 'BadRequestError', 'param': None, 'code': 400}

After testing different variations, I found that the error only occurs when using Enum in the response model.
If I switch to .JSON mode instead of .TOOLS, it works without any errors — but:

• The outputs are less consistent
• The inference is noticeably slower
• For my use case (large-scale classification using batch inference over millions of records), the slowdown is significant - as I noticed that token usage (input + output tokens) increases significantly when using the .JSON mode.

---

🔍 Minimal Example to Reproduce

Here’s a simple dummy example that replicates the issue:

from pydantic import BaseModel
from typing import List
from enum import Enum
import os
from openai import OpenAI
import instructor

# API and Model Configuration
OPENSOURCE_MODEL = os.getenv('MODEL')  # an open-source model deployed on the cloud
CUSTOM_API_ENDPOINT = f"{os.getenv('API_ENDPOINT')}/v1"  # API endpoint for the deployed model
OPENAI_API_KEY = os.getenv('API_KEY', "EMPTY")  # OpenAI API key (included for reference, but not currently in use)

client = OpenAI(base_url=CUSTOM_API_ENDPOINT)
client = instructor.from_openai(client, mode=instructor.Mode.TOOLS)

class Categories(str, Enum):
    BILLING = "BILLING"
    SHIPPING = "SHIPPING"

class Reply(BaseModel):
    category: Categories

resp = client.chat.completions.create(
    model=OPENSOURCE_MODEL,
    response_model=Reply,
    messages=[
        {
            "role": "user",
            "content": "Classify the following message: I am having trouble with my billing",
        },
    ],
)
# assert resp == Label.BILLING
print(resp)

Error Output:

InstructorRetryException: Error code: 400 - {'object': 'error', 'message': 'The provided JSON schema contains features not supported by xgrammar.', 'type': 'BadRequestError', 'param': None, 'code': 400}