Graphify-Labs/graphify · error · ImportError

the '{pkg}' package is required for this backend but is not

Error message

the '{pkg}' package is required for this backend but is not installed. Install it with:  uv tool install "graphifyy[{extra}]" --force  (uv tool), or  pip install {pkg}  (pip/venv install).

What it means

Raised when the OpenAI-compatible call path (`_call_openai_compat`) cannot import the `openai` SDK. graphify routes many backends (openai, kimi, gemini-via-openai, ollama, deepseek, moonshot) through the `openai` Python package, so a missing package aborts the call before any request is made. The message is generated by `_backend_pkg_hint("openai", extra)` and includes the correct uv/pip install command for the selected backend.

Source

Thrown at graphify/llm.py:1184

    base_url: str,
    api_key: str,
    model: str,
    user_message: str,
    temperature: float | None = 0,
    reasoning_effort: str | None = None,
    max_completion_tokens: int = 8192,
    *,
    backend: str = "",
    deep_mode: bool = False,
    images: list[_ImageRef] | None = None,
    extra_body: dict | None = None,
) -> dict:
    """Call any OpenAI-compatible API (Kimi, OpenAI, etc.) and return parsed JSON."""
    try:
        from openai import OpenAI
    except ImportError as exc:
        extra = backend if backend in ("kimi", "gemini", "openai", "ollama") else "openai"
        raise ImportError(_backend_pkg_hint("openai", extra)) from exc

    # Local backends (ollama, llama.cpp, vLLM) routinely take >60s for a
    # single chunk on a large model — far longer than the openai SDK's
    # default. Honour GRAPHIFY_API_TIMEOUT (seconds) for explicit override;
    # default to 600s, which is long enough for a 31B model on a 16k chunk
    # but still bounds runaway connections (issue #792 addendum).
    # The SDK's transient-error retries (default 6) exist for cloud rate limits
    # (429). A local Ollama server does not rate-limit, and if it wedges it will
    # not recover by retrying, so 6 retries turn a 180s --api-timeout into a
    # ~21min block (7 attempts x 180s) with no progress (#1686). Default ollama
    # to 0 SDK retries so --api-timeout is the hard wall-clock bound and a hung
    # request fails fast into the chunk-level retry/skip. An explicit
    # GRAPHIFY_MAX_RETRIES still wins for users who want it.
    _retries = _resolve_max_retries()
    if backend == "ollama" and not os.environ.get("GRAPHIFY_MAX_RETRIES", "").strip():
        _retries = 0
    client = OpenAI(api_key=api_key, base_url=base_url, timeout=_resolve_api_timeout(),
                    max_retries=_retries)

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. Install the matching extra: `uv tool install "graphifyy[openai]" --force` (or the backend-specific extra shown in the message, e.g. `[kimi]`), or `pip install openai` inside the active venv.
2. Verify with `python -c "import openai"` in the exact interpreter/venv graphify runs under.
3. If installed as a uv tool, remember tools live in an isolated venv — install the extra there, not in your project venv.

Example fix

# before
uv tool install graphifyy --force

# after
uv tool install "graphifyy[openai]" --force   # or [kimi], [gemini], ... for that backend

import importlib.util
from graphify.llm import BACKENDS

def can_use_openai_compat(backend: str) -> bool:
    return importlib.util.find_spec("openai") is not None and backend in BACKENDS

# before extraction:
if not can_use_openai_compat("kimi"):
    raise SystemExit("install graphifyy[openai] (or the backend extra) first")

try:
    extract_files_direct(files, root, backend="kimi")
except ImportError as e:
    if "openai" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "openai"], check=True)
    else:
        raise

When it happens

Trigger: Calling `extract_files_direct(..., backend="kimi"|"openai"|"ollama"|...)` (or letting `detect_backend()` pick one) when `import openai` fails — i.e. graphify was installed without the `openai` extra and no openai SDK exists in the environment.

Common situations: Installing graphify via `pip install graphifyy` (no extras) and then selecting a cloud/local backend that rides the OpenAI compat layer; using `uv tool install graphifyy` without `[openai]` or `[kimi]` etc.; a venv where openai was uninstalled or pinned-away by another dependency conflict.

Related errors

• the 'anthropic' package is required for this backend but is
• Azure OpenAI requires the openai package. Run: pip install o
• AWS Bedrock extraction requires boto3. Run: pip install grap
• matplotlib not installed. Run: pip install matplotlib
• neo4j driver not installed. Run: pip install neo4j

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/ad0386cd6e8e068d. Report an issue: GitHub.