UX: `uv run --with graphifyy python -m graphify` silently loads an older system-installed version instead of the uv-managed one

[sub4biz]

Summary

When a user has an older version of graphifyy installed in their system Python alongside a newer version managed by uv tools, uv run --with graphifyy python -m graphify silently loads the older one. There is no error — everything appears to work — but OPENAI_BASE_URL and other env-var overrides are ignored, causing requests to go to api.openai.com instead of the configured endpoint.

Environment

• OS: Windows 11, Python 3.13 (system)
• graphifyy 0.9.1 (installed via uv tool install graphifyy)
• graphifyy 0.8.13 (older version installed in system Python via pip install graphifyy)

Reproduction

1. Install graphifyy via uv tools: uv tool install graphifyy
2. Have an older version of graphifyy installed in system Python (e.g. pip install graphifyy at some point in the past). Note: pip show graphify reports "not found" — pip registers it under the package name graphifyy, not the module name.
3. Set env vars: OPENAI_BASE_URL=https://api.groq.com/openai/v1 and OPENAI_API_KEY=<groq_key>
4. Run: uv run --with graphifyy python -m graphify . --backend openai --token-budget 800 --out out/

Expected: requests go to api.groq.com
Actual: requests go to api.openai.com → 401 "Incorrect API key"

Root cause

uv run uses the system Python and does not fully isolate from its site-packages. The --with graphifyy flag adds graphifyy to the ephemeral environment, but if system Python already has graphify in its site-packages, Python finds it first (earlier in sys.path).

Confirm with:

import graphify.llm as llm
print(llm.__file__)
# Wrong: C:\Users\...\AppData\Local\Programs\Python\Python313\Lib\site-packages\graphify\llm.py
# Right: C:\Users\...\AppData\Roaming\uv\tools\graphifyy\Lib\site-packages\graphify\llm.py

The loaded module is graphifyy 0.8.13 — an older version that does not honor OPENAI_BASE_URL. Confirmed: BACKENDS["openai"]["base_url"] is always https://api.openai.com/v1 regardless of the env var.

Why it's silent

• graphify runs without error — AST extraction on code files succeeds
• Semantic extraction fails with 401 (wrong endpoint + wrong key type)
• graphify warns "chunk N/N failed" but exits with code 0
• The extracted graph contains only AST nodes (code files), zero semantic nodes from docs
• The user sees no obvious error and may assume the run succeeded

There is one partial signal already present: graphify prints a version mismatch warning when the skill file and the loaded package differ:

warning: skill is from graphify 0.9.1, package is 0.8.13

This is the actual fingerprint of the problem — the skill was written for 0.9.1 but the running module is 0.8.13 from the system Python install. The warning is correct, but a user seeing it is likely to dismiss it as a stale skill rather than as evidence that a different installation was loaded.

Workaround

Use the installed executable directly instead of uv run --with graphifyy:

# Instead of:
uv run --with graphifyy python -m graphify . --backend openai ...

# Use (as documented in README) — uvx names the source package explicitly:
uvx --from graphifyy graphify extract . --backend openai ...

For DeepSeek backends (--backend deepseek), the bug was not observed in testing — DeepSeek extractions succeeded even when loaded via uv run. The exact mechanism was not confirmed.

Relationship to existing documentation

The package author has documented a related case in the README:

Running with uvx / uv tool run instead of installing? Name the package, not the command: uvx --from graphifyy graphify install. Plain uvx graphify … fails (No solution found … no versions of graphify) because uv tool run reads the first word as a package, and the package is graphifyy — the graphify command lives inside it.

The documented case (uvx graphify → package not found) fails loudly — the user gets an explicit error and can fix it.

The case in this issue is different and fails silently:

• uv run --with graphifyy python -m graphify — no error, graphify runs and produces output
• The wrong graphify module is loaded from system Python site-packages
• OPENAI_BASE_URL is ignored, requests go to api.openai.com
• The only symptom is a 401 that looks like a key problem, not a routing problem

The existing documentation does not cover this scenario.

Suggested fix

Add a path check to __main__.py or the CLI entry point:

import graphify
import os
import sys
from importlib.metadata import distribution

try:
    dist = distribution("graphifyy")
    expected = os.path.normpath(str(dist.locate_file("graphify")))
    loaded = os.path.normpath(os.path.dirname(graphify.__file__))
    if expected != loaded:
        print(
            f"error: loaded graphify from {loaded!r}, "
            f"but graphifyy {dist.version} is at {expected!r}\n"
            "Use 'uvx --from graphifyy graphify' instead of "
            "'uv run --with graphifyy python -m graphify'.",
            file=sys.stderr,
        )
        sys.exit(1)
except Exception:
    pass

• Compares where the active distribution("graphifyy") expects its files against where the loaded module actually came from — catches both stale pip installs and unrelated same-named packages
• Uses importlib.metadata (stdlib since 3.9), no magic sentinels
• The error message shows both paths, making the issue immediately diagnosable

Side note: while looking at BACKENDS in llm.py, OPENAI_BASE_URL is currently read once at module import time (os.environ.get(...) in the dict literal). For CLI use this is harmless — env vars are always set before process start. For library/programmatic usage where env vars might be set after import, reading lazily at call time would be safer.

---

[HerenderKumar]

PR up: #2085

[safishamsi]

Addressed in v0.9.24 (#2085). The README now has a troubleshooting note for an older graphifyy in system site-packages shadowing uv run --with graphifyy. Thanks for the report. https://github.com/Graphify-Labs/graphify/releases/tag/v0.9.24