Xai-sdk optional dependency

[jxnl]

feat: make xai-sdk an optional dependency

Describe your changes

This PR makes xai-sdk an optional dependency, addressing user feedback to reduce unnecessary installations for users not requiring xAI functionality.

Key changes include:

• Optional Dependency: xai-sdk is now installed via the instructor[xai] extra.
• Improved Error Handling: Attempting to use xAI functionality without xai-sdk installed now raises a ConfigurationError with clear instructions on how to install the optional extra.
• Documentation Updates: docs/getting-started.md and docs/integrations/index.md have been updated to reflect the new optional installation method.
• New Tests: Added tests/test_xai_optional_dependency.py to verify the correct behavior of the optional dependency and error handling.

Issue ticket number and link

567-316 (Make xai-sdk an optional dependency for instructor library)

Checklist before requesting a review

• I have performed a self-review of my code
• If it is a core feature, I have added thorough tests.
• If it is a core feature, I have added documentation.

---

Linear Issue: 567-316

 

---

Note

Low Risk
Low risk: changes are limited to xAI provider dependency gating, error messaging, and docs/tests; no core request/response logic is altered.

Overview
Makes the xAI integration truly optional by standardizing the missing-xai-sdk behavior: xAI entrypoints (from_provider, from_xai, and _convert_messages) now raise a ConfigurationError with explicit install instructions for instructor[xai] (and note the Python 3.10+ requirement).

Updates docs to advertise pip install "instructor[xai]" and adds tests/test_xai_optional_dependency.py to ensure the new error messaging is raised when the SDK is not installed.

^{Written by Cursor Bugbot for commit 0bf0937. Configure here.}

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	instructor	0bf0937	Commit Preview URL Branch Preview URL	Jan 29 2026, 04:15 PM

[jxnl]

@cursor can you fix tests and ruff. Update agents Md to make sure you run ruff before pushing.

[cursor]

Fixes for tests + Ruff (and agent guidance)

• Ruff CI failure: Fixed ruff format --check by formatting tests/test_xai_optional_dependency.py (CI was only complaining this file would be reformatted).
• Unit test fixes (tests/test_auto_client.py):
  • Updated the GenAI mode tests to not require the google package by injecting a lightweight google.genai module via sys.modules and patching instructor.from_genai with create=True.
  • Reworked test_additional_kwargs_passed to be a true unit test (no Anthropic auth/network). It now asserts max_tokens is passed through to from_anthropic using mocks.
• Agent docs: Updated AGENT.md with a short “Before you push” checklist that explicitly says to run Ruff check/format and tests.

I’ve committed and pushed these updates to the same PR branch (cursor/567-316-xai-sdk-optional-dependency-8da2).

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issue.}

[cursor]

Tests fail when xai-sdk is installed

Medium Severity

The tests assume xai-sdk is not installed but lack a skip condition for when it is. If xai-sdk is present, test_direct_from_xai_has_clear_error_when_sdk_missing will raise ClientError (from the isinstance check) instead of ConfigurationError, causing the test to fail. Similar issue affects test_from_provider_xai_requires_optional_extra. Tests need to skip when xai-sdk is installed, similar to patterns used elsewhere (e.g., pytest.skip("xai-sdk is installed") in an import try/except block).

 

[cursor]

Bugbot Autofix resolved the bug found in the latest run.

• ✅ Fixed: Tests fail when xai-sdk is installed
  • Added a module-level pytest skip when xai_sdk is importable so missing-SDK error tests only run when the SDK is absent.