General

Mode Comparison Guide

Compare different modes available in Instructor and understand when to use each

promptBeginner5 min to valuemarkdown

0 views

Feb 1, 2026

Additional Files (17)

View Original Source

Related Skills

General

PromptBeginner5 minmarkdown

<h1 align="center">

Jan 12, 2026

General

PromptBeginner5 minmarkdown

2. Apply Deepthink Protocol (reason about dependencies

risks

Jan 15, 2026

General

PromptBeginner5 minmarkdown

- Identify gaps

ambiguities

Jan 15, 2026

Additional Files (17)

title: Mode Comparison Guide description: Compare different modes available in Instructor and understand when to use each

Instructor Mode Comparison Guide

Instructor uses core modes that work across providers. Provider-specific modes still work, but they are deprecated and will show warnings.

Mode handling now lives in provider handlers. The DSL no longer stores mode-specific streaming logic.

Core Modes

```
TOOLS
```
: Tool or function calling for structured extraction.
```
JSON_SCHEMA
```
: Native schema support when a provider has it.
```
MD_JSON
```
: JSON from text or code blocks for simple or fallback cases.
```
PARALLEL_TOOLS
```
: Multiple tool calls in one response.
```
RESPONSES_TOOLS
```
: OpenAI Responses API tools.

Legacy Modes (Deprecated)

These legacy modes map to core modes:

```
FUNCTIONS
```
->
```
TOOLS
```
```
TOOLS_STRICT
```
->
```
TOOLS
```
```
ANTHROPIC_TOOLS
```
->
```
TOOLS
```
```
ANTHROPIC_JSON
```
->
```
MD_JSON
```
```
GENAI_TOOLS
```
->
```
TOOLS
```
```
GENAI_JSON
```
->
```
JSON
```
```
MISTRAL_TOOLS
```
->
```
TOOLS
```
```
MISTRAL_STRUCTURED_OUTPUTS
```
->
```
JSON_SCHEMA
```
```
BEDROCK_TOOLS
```
->
```
TOOLS
```
```
BEDROCK_JSON
```
->
```
MD_JSON
```
```
FIREWORKS_TOOLS
```
->
```
TOOLS
```
```
FIREWORKS_JSON
```
->
```
MD_JSON
```
```
CEREBRAS_TOOLS
```
->
```
TOOLS
```
```
CEREBRAS_JSON
```
->
```
MD_JSON
```
```
WRITER_TOOLS
```
->
```
TOOLS
```
```
WRITER_JSON
```
->
```
MD_JSON
```
```
PERPLEXITY_JSON
```
->
```
MD_JSON
```
```
VERTEXAI_TOOLS
```
->
```
TOOLS
```
```
VERTEXAI_JSON
```
->
```
MD_JSON
```
```
VERTEXAI_PARALLEL_TOOLS
```
->
```
PARALLEL_TOOLS
```

Mode Selection Tips

Use
```
TOOLS
```
for most structured output cases.
Use
```
JSON_SCHEMA
```
when the provider supports native schema enforcement.
Use
```
MD_JSON
```
if tools are not supported or outputs are simple.
Use
```
PARALLEL_TOOLS
```
for multiple tasks in one response.

Examples

TOOLS Mode (Recommended)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.TOOLS,
)

MD_JSON Mode (Fallback)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    mode=Mode.MD_JSON,
)

JSON_SCHEMA Mode (Native Schema)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.JSON_SCHEMA,
)

See the Mode Migration Guide for more details.

Google/Gemini

For complex structures:

import instructor

client = instructor.from_provider(
    "google/gemini-2.5-flash",
    mode=instructor.Mode.TOOLS,
)

For structured outputs with JSON:

import instructor

client = instructor.from_provider(
    "google/gemini-2.5-flash",
    mode=instructor.Mode.JSON,
)

Mode Compatibility List

Legacy modes are shown for compatibility only. Prefer core modes in new code.

OpenAI: TOOLS, TOOLS_STRICT, PARALLEL_TOOLS, FUNCTIONS; JSON, MD_JSON, JSON_O1.
Anthropic: ANTHROPIC_TOOLS, ANTHROPIC_PARALLEL_TOOLS; ANTHROPIC_JSON.
Gemini: TOOLS; JSON.
Vertex AI: VERTEXAI_TOOLS; VERTEXAI_JSON.
Cohere: COHERE_TOOLS; JSON, MD_JSON.
Mistral: MISTRAL_TOOLS; MISTRAL_STRUCTURED_OUTPUTS.
Anyscale: (none); JSON, MD_JSON, JSON_SCHEMA.
Databricks: TOOLS; JSON, MD_JSON.
Together: (none); JSON, MD_JSON.
Fireworks: FIREWORKS_TOOLS; FIREWORKS_JSON.
Cerebras: (none); CEREBRAS_JSON.
Writer: WRITER_TOOLS; JSON.
Perplexity: (none); PERPLEXITY_JSON.
GenAI: TOOLS; JSON.
LiteLLM: depends on provider for both tool-based and JSON-based modes.

Best Practices

Start with the recommended mode for your provider
- For OpenAI:
```
TOOLS
```
- For Anthropic:
```
ANTHROPIC_TOOLS
```
  (Claude 3+) or
```
ANTHROPIC_JSON
```
- For Gemini:
```
TOOLS
```
  or
```
JSON
```
Try JSON modes for simple structures or if you encounter issues
- JSON modes often work with simpler schemas
- They may be more token-efficient
- They work with more models
Use provider-specific modes when available
- Provider-specific modes are optimized for that provider
- They handle special cases and requirements
Test and validate
- Different modes may perform differently for your specific use case
- Always test with your actual data and models

title: Mode Comparison Guide description: Compare different modes available in Instructor and understand when to use each

Instructor Mode Comparison Guide

Instructor uses core modes that work across providers. Provider-specific modes still work, but they are deprecated and will show warnings.

Mode handling now lives in provider handlers. The DSL no longer stores mode-specific streaming logic.

Core Modes

```
TOOLS
```
: Tool or function calling for structured extraction.
```
JSON_SCHEMA
```
: Native schema support when a provider has it.
```
MD_JSON
```
: JSON from text or code blocks for simple or fallback cases.
```
PARALLEL_TOOLS
```
: Multiple tool calls in one response.
```
RESPONSES_TOOLS
```
: OpenAI Responses API tools.

Legacy Modes (Deprecated)

These legacy modes map to core modes:

```
FUNCTIONS
```
->
```
TOOLS
```
```
TOOLS_STRICT
```
->
```
TOOLS
```
```
ANTHROPIC_TOOLS
```
->
```
TOOLS
```
```
ANTHROPIC_JSON
```
->
```
MD_JSON
```
```
GENAI_TOOLS
```
->
```
TOOLS
```
```
GENAI_JSON
```
->
```
JSON
```
```
MISTRAL_TOOLS
```
->
```
TOOLS
```
```
MISTRAL_STRUCTURED_OUTPUTS
```
->
```
JSON_SCHEMA
```
```
BEDROCK_TOOLS
```
->
```
TOOLS
```
```
BEDROCK_JSON
```
->
```
MD_JSON
```
```
FIREWORKS_TOOLS
```
->
```
TOOLS
```
```
FIREWORKS_JSON
```
->
```
MD_JSON
```
```
CEREBRAS_TOOLS
```
->
```
TOOLS
```
```
CEREBRAS_JSON
```
->
```
MD_JSON
```
```
WRITER_TOOLS
```
->
```
TOOLS
```
```
WRITER_JSON
```
->
```
MD_JSON
```
```
PERPLEXITY_JSON
```
->
```
MD_JSON
```
```
VERTEXAI_TOOLS
```
->
```
TOOLS
```
```
VERTEXAI_JSON
```
->
```
MD_JSON
```
```
VERTEXAI_PARALLEL_TOOLS
```
->
```
PARALLEL_TOOLS
```

Mode Selection Tips

Use
```
TOOLS
```
for most structured output cases.
Use
```
JSON_SCHEMA
```
when the provider supports native schema enforcement.
Use
```
MD_JSON
```
if tools are not supported or outputs are simple.
Use
```
PARALLEL_TOOLS
```
for multiple tasks in one response.

Examples

TOOLS Mode (Recommended)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.TOOLS,
)

MD_JSON Mode (Fallback)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    mode=Mode.MD_JSON,
)

JSON_SCHEMA Mode (Native Schema)

import instructor
from instructor import Mode

client = instructor.from_provider(
    "openai/gpt-4o-mini",
    mode=Mode.JSON_SCHEMA,
)

See the Mode Migration Guide for more details.

Google/Gemini

For complex structures:

import instructor

client = instructor.from_provider(
    "google/gemini-2.5-flash",
    mode=instructor.Mode.TOOLS,
)

For structured outputs with JSON:

import instructor

client = instructor.from_provider(
    "google/gemini-2.5-flash",
    mode=instructor.Mode.JSON,
)

Mode Compatibility List

Legacy modes are shown for compatibility only. Prefer core modes in new code.

OpenAI: TOOLS, TOOLS_STRICT, PARALLEL_TOOLS, FUNCTIONS; JSON, MD_JSON, JSON_O1.
Anthropic: ANTHROPIC_TOOLS, ANTHROPIC_PARALLEL_TOOLS; ANTHROPIC_JSON.
Gemini: TOOLS; JSON.
Vertex AI: VERTEXAI_TOOLS; VERTEXAI_JSON.
Cohere: COHERE_TOOLS; JSON, MD_JSON.
Mistral: MISTRAL_TOOLS; MISTRAL_STRUCTURED_OUTPUTS.
Anyscale: (none); JSON, MD_JSON, JSON_SCHEMA.
Databricks: TOOLS; JSON, MD_JSON.
Together: (none); JSON, MD_JSON.
Fireworks: FIREWORKS_TOOLS; FIREWORKS_JSON.
Cerebras: (none); CEREBRAS_JSON.
Writer: WRITER_TOOLS; JSON.
Perplexity: (none); PERPLEXITY_JSON.
GenAI: TOOLS; JSON.
LiteLLM: depends on provider for both tool-based and JSON-based modes.

Best Practices

Start with the recommended mode for your provider
- For OpenAI:
```
TOOLS
```
- For Anthropic:
```
ANTHROPIC_TOOLS
```
  (Claude 3+) or
```
ANTHROPIC_JSON
```
- For Gemini:
```
TOOLS
```
  or
```
JSON
```
Try JSON modes for simple structures or if you encounter issues
- JSON modes often work with simpler schemas
- They may be more token-efficient
- They work with more models
Use provider-specific modes when available
- Provider-specific modes are optimized for that provider
- They handle special cases and requirements
Test and validate
- Different modes may perform differently for your specific use case
- Always test with your actual data and models