Add Azure AI Foundry as a first-class v2 provider

[azrirefik]

Motivation

Azure OpenAI is currently usable via instructor.from_openai(AzureOpenAI(...)), but there is no dedicated from_azure() factory, no from_provider("azure/...") routing, and no AZURE_OPENAI_* environment variable auto-detection — all of which exist for other OpenAI-compatible providers like groq, perplexity, fireworks, cerebras, and xai.

Beyond ergonomics, Azure AI Foundry now hosts non-OpenAI models (Mistral, Llama, Phi, etc.) through a single endpoint. A dedicated provider would add routing value that from_openai(AzureOpenAI(...)) cannot provide — the same justification that motivated first-class providers for other OpenAI-compatible platforms.

Proposed scope

Mirror the v2 provider pattern (following PR #2306 MiniMax as the template):

• instructor/v2/core/mode.py — AZURE_TOOLS, AZURE_JSON in Mode enum
• instructor/v2/core/providers.py — Provider.AZURE, URL detection
• instructor/v2/core/provider_specs.py — PROVIDER_SPECS entry
• instructor/v2/providers/azure/handlers.py — AzureToolsHandler (extends OpenAIToolsHandler)
• instructor/v2/providers/azure/client.py — from_azure() factory
• instructor/v2/auto_client.py — _build_azure() reading AZURE_OPENAI_* env
• instructor/providers/azure/client.py — legacy compat shim
• instructor/__init__.py — lazy import + export
• docs/integrations/azure.md, tests/llm/test_azure/ (auto-skip without key)
• mkdocs.yml, CHANGELOG.md, pyproject.toml (optional azure-identity dep for Entra ID)

Most files are 1-10 line shims/registry entries. Real substance = handler + client + tests + docs.

Context

• Support for Microsoft Entra ID with Azure OpenAI interface #1692 (Entra ID support) was completed — Azure IS maintained, not rejected
• refactor(providers): add missing providers, centralize URL detection, add tests #2039 (URL detection centralization) by @jxnl was merged — the plumbing a new provider needs is in place
• NEW_PROVIDER_AGENT_INSTRUCTIONS.md is outdated (pre-v2); PR feat(minimax): add MiniMax provider support #2306 is the authoritative v2 template

Ask

Would a PR for this be welcome? Happy to mirror the MiniMax v2 pattern. If there's a preference for scope (e.g., Azure OpenAI only vs. full Foundry routing), I can adjust.

[Bhavyashah20]

Taking this on, will follow the same v2 pattern. Planning full Foundry routing with separate handling for Azure OpenAI vs non-OpenAI models. Will post a draft PR once the core is ready.

[azrirefik]

Hi @Bhavyashah20 — thanks for the interest in picking this up. I'm also planning to work on this (I opened the issue) and have been studying PR #2306's v2 layout as the template.

A few things I've already mapped out from the MiniMax PR:

• instructor/v2/core/mode.py — AZURE_TOOLS, AZURE_JSON enum entries
• instructor/v2/core/providers.py — Provider.AZURE + URL detection for .openai.azure.com
• instructor/v2/core/provider_specs.py — spec entry with supported/unsupported modes
• instructor/v2/providers/azure/{handlers,client,__init__}.py — AzureToolsHandler extending OpenAIToolsHandler + from_azure() factory via _from_openai_compat()
• instructor/v2/auto_client.py — _build_azure() reading AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_API_KEY
• Legacy shim in instructor/providers/azure/ re-exporting v2
• Tests in tests/llm/test_azure/ (auto-skip without key)

I also have Azure AI Foundry endpoints available for integration testing (Azure OpenAI + Foundry-hosted non-OpenAI models like Mistral/Llama).

Rather than duplicate effort, happy to collaborate — I can take the v2 core wiring (mode/provider/specs/auto_client) + handler + client, and you could take docs + tests, or vice versa. Or if you'd prefer to drive it solo, I'll hold off and review your PR when it's ready. Let me know what works.

[Bhavyashah20]

I'm happy to collaborate and since this is your feature i would be happy to work on the docs and th testing work

[azrirefik]

thanks man, appreciate it

PR #2384 has the core + basics. diff is your map. no need to wait for it to merge; if you spot gaps, just open a follow-up PR right away.

high-leverage spots if you want a head start:

• streaming across the 5 modes (i only did sync/async TOOLS + JSON for the basic tests)
• foundry-hosted non-OpenAI models (mistral/llama/phi), separate test file would be 🔥
• worked end-to-end example in the docs (e.g. structured extraction pipeline)
• "azure openai vs foundry vs github models" decision guide

no blockers from my side, take whatever interests you. ping me on the PR if you want a review.