apache/seatunnel · error · ImportError

openai package required for AI_PROVIDER=orcarouter. Install…

Error message

openai package required for AI_PROVIDER=orcarouter. Install it: pip install openai

What it means

The OrcaRouter provider class requires the third-party openai Python package (used as its client SDK). If importing openai fails at construction time, an ImportError with install instructions is raised so the user knows exactly which optional dependency is missing.

Solutions

Run `pip install openai` in the active environment
Install the CLI with its LLM extras (e.g. pip install seatunnel-cli[llm] if provided)
Verify with `python -c "import openai"` that the package resolves in the same interpreter running seatunnel

Example fix

// before
$ seatunnel --provider orcarouter
ImportError: openai package required...
// after
$ pip install openai
$ seatunnel --provider orcarouter

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("openai") is None:
    raise SystemExit("Install the openai package: pip install openai")

Try / catch

try:
    provider = create_provider("orcarouter")
except ImportError as e:
    print(f"Missing dependency: {e}; run pip install openai")
    sys.exit(1)

Prevention

Pin the openai package in requirements.txt or the CLI's llm extra
Run a startup dependency check before invoking LLM commands
Use one dedicated virtualenv for the CLI so installed extras are not lost

When it happens

Trigger: Instantiating the orcarouter provider (via create_provider("orcarouter") or AI_PROVIDER=orcarouter) in an environment where the openai package is not installed; the `import openai` inside __init__ raises ImportError.

Common situations: Fresh virtualenvs or minimal installs where only seatunnel-cli's core dependencies are present; CI containers built without extras; users switching AI_PROVIDER to orcarouter without installing the extra.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/69fc971dd3268107. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-cli/seatunnel_cli/llm_provider.py:1279

    addressed as ``provider/model``, e.g. ``orcarouter/auto`` routes and
    grades automatically. Defaults to the ``orcarouter/auto`` model, which
    automatically selects the best model for each request.

    Since OrcaRouter speaks the OpenAI Chat Completions protocol, this
    provider mirrors :class:`OpenAIProvider` and only customizes the base
    URL, the API key environment variable, and the default model.
    """

    #: OrcaRouter's OpenAI-compatible base URL.
    DEFAULT_BASE_URL = "https://api.orcarouter.ai/v1"
    #: Default model: auto-routes to the best model for the request.
    DEFAULT_MODEL = "orcarouter/auto"

    def __init__(self):
        try:
            import openai
        except ImportError:
            raise ImportError(
                "openai package required for AI_PROVIDER=orcarouter. "
                "Install it: pip install openai"
            )

        api_key = os.environ.get("ORCAROUTER_API_KEY")
        if not api_key:
            raise ValueError(
                "ORCAROUTER_API_KEY environment variable is required for "
                "AI_PROVIDER=orcarouter"
            )

        self._model_id = os.environ.get(
            "ORCAROUTER_MODEL",
            os.environ.get("OPENAI_MODEL", self.DEFAULT_MODEL))
        self._fast_model_id = os.environ.get(
            "ORCAROUTER_SMALL_FAST_MODEL",
            os.environ.get("OPENAI_SMALL_FAST_MODEL", self._model_id))
        self._client = openai.OpenAI(api_key=api_key, base_url=self.DEFAULT_BASE_URL)

View on GitHub (pinned to cf67b549a7)