openai as an optional extra#

  • Status: Accepted

  • Date: 2026-05-29

  • Deciders: saia-python maintainers

Context and Problem Statement#

saia-python ships an OpenAI-compatibility layer (create_openai_client() and the SAIAClient.openai / .openai_async properties) built on the openai SDK. Everything else — chat, voice, ARCANA, documents, models, rate limits — speaks the SAIA REST API directly through requests. Should openai be a mandatory dependency of the whole package?

Originally it was: openai sat in the core dependencies and was imported at package-import time (__init__ → openai_compat → import openai). That contradicted the documentation, which described openai as optional and promised a friendly ImportError — impossible when a missing openai breaks import saia_python itself.

Decision Drivers#

  • The OpenAI layer is a single function; the native client never needs openai.

  • openai is heavy (pulls httpx, pydantic, anyio, …).

  • The documentation already promised an [openai] extra and a graceful failure.

  • Consistency with the existing tqdm pattern (already imported lazily).

Considered Options#

  • Optional extra + lazy import — move openai to [project.optional-dependencies] and import it inside create_openai_client().

  • Keep it mandatory — leave openai in core deps and delete the “optional” wording from the docs.

Decision Outcome#

Chosen option: optional extra + lazy import. openai moved to an [openai] extra (pip install saia-python[openai]); the import openai now lives inside create_openai_client(), guarded by a try/except that raises a clear ImportError with install instructions. The core package installs and imports with just requests + tomlkit (+ tqdm).

Consequences#

  • Good — lean base install; the heavy SDK is opt-in.

  • Good — the documented behavior is now true, and the property-level lazy import finally has an effect.

  • Good — internally consistent with the tqdm optional-import pattern.

  • Trade-off — a plain pip install saia-python no longer provides client.openai; users must add the extra. Mitigated by the explicit ImportError, and the test extra depends on [openai] so CI is unaffected.

Confirmation#

import saia_python no longer pulls openai into sys.modules (verified); tests/test_openai_compat.py uses pytest.importorskip("openai") so the suite is correct whether or not the extra is installed.

More Information#

If the OpenAI-compatibility layer ever becomes a headline, always-available feature, the only change required is moving openai>=1.0 back to core dependencies — the lazy import remains harmless. Relates to ADR-0003.