fix(weave): gql 4.0+ compatibility and improve client/server dependency separation

[andrewmonostate]

This PR fixes two critical issues that prevent Weave from working properly with modern dependencies and clean architecture patterns. Fixes #5288.

Changes

1. Added gql 3.x/4.x Compatibility

• File: weave/wandb_interface/wandb_api.py

  • Added runtime version detection for gql library
  • Implemented conditional execution based on gql version:
    • gql 3.x: Uses execute(query, kwargs)
    • gql 4.x: Uses execute(query, variable_values=kwargs)
  • Added comprehensive documentation explaining the compatibility layer

• File: pyproject.toml

  • Updated gql dependency from "gql[aiohttp,requests]" to "gql[aiohttp,requests]>=3.4.0"
  • Allows both gql 3.x and 4.x to be used

2. Improved Dependency Separation

• New File: weave/trace/exceptions.py

  • Created common exceptions module for shared exceptions
  • Moved ObjectDeletedError here to avoid circular dependencies

• Updated Files:

  • weave/trace/refs.py - Now imports from trace.exceptions
  • weave/trace/vals.py - Now imports from trace.exceptions
  • weave/trace_server/errors.py - Imports ObjectDeletedError from common location

Testing

• New Test: tests/wandb_api/test_wandb_api_gql_compatibility.py

  • Tests gql version detection
  • Validates compatibility code structure
  • Ensures both execution patterns are present

• New Test: tests/architecture/test_dependency_separation.py

  • Verifies client code can be imported without server dependencies
  • Validates exception is accessible from both client and server
  • Ensures proper separation of concerns

Impact

• ✅ Backward Compatible: No breaking changes for existing users
• ✅ Forward Compatible: Works with gql 4.0+
• ✅ Cleaner Architecture: Client code no longer requires server dependencies
• ✅ Better Testing: Tests can run without heavy dependencies like clickhouse_connect

Before/After

Before:

# With gql 4.0 installed
>>> from weave.wandb_interface.wandb_api import WandbApi
TypeError: SyncClientSession.execute() takes 2 positional arguments but 3 were given

# Without clickhouse_connect
>>> from weave.trace import refs
ModuleNotFoundError: No module named 'clickhouse_connect'

After:

# Works with both gql 3.x and 4.x ✅
>>> from weave.wandb_interface.wandb_api import WandbApi
>>> # No errors!

# Works without server dependencies ✅
>>> from weave.trace import refs
>>> # No errors!

Verification

Tested with:

• ✅ gql 3.4.1
• ✅ gql 4.0.0
• ✅ Python 3.9, 3.11, 3.13
• ✅ With and without clickhouse_connect

Related Issues

Fixes #5288 - Multiple architectural issues preventing clean imports and gql 4.0 compatibility

Checklist

• [x] Tests added for all changes
• [x] Documentation updated where necessary
• [x] No breaking changes
• [x] Follows existing code patterns
• [x] All tests pass

[circle-job-mirror[bot]]

This PR requires manual approval from a wandb user to run all CI checks.

To see the current diff, click here.

To approve CI for this PR as of this commit, comment:

/approve d04dab1463f879575048a34f4b77226356454e3c

[github-actions[bot]]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[andrewmonostate]

I have read the CLA Document and I hereby sign the CLA

[andrewmonostate]

I have read the CLA Document and I hereby sign the CLA

[circle-job-mirror[bot]]

Preview this PR with FeatureBee: https://beta.wandb.ai/?betaVersion=49a5c80b656d1a0c28b985c3bca58867493a51ba

[andrewmonostate]

@tssweeney @andrewtruong can anyone review this to close it?

[andrewmonostate]

@andrewtruong continuing from the comment at #5288

Your #5290 unblocks users on gql==4.x today via gql’s compatibility layer. For completeness, here’s what #5289 contributes beyond #5290 and why I’m asking for reconsideration here:

What #5289 adds that is not covered by #5290 (had to pull extensive work to be honest): 1. Future-proof gql 3.x/4.x handling (sync + async) • Uses the stable 4.x API: session.execute(query, variable_values=kwargs) (and async variant). • Runtime version detection preserves 3.x behavior; 4.x uses keyword-only arg. • Avoids relying on gql’s temporary compat shim that can be dropped later. 2. Client/server dependency separation • Creates weave/trace/exceptions.py for shared exceptions. • Updates trace/refs.py, trace/vals.py, and trace_server/errors.py so client imports don’t require clickhouse_connect. • Makes lightweight client usage and testing possible without server deps. 3. Tests that guard both areas • tests/wandb_api/test_wandb_api_gql_compatibility.py ensures the correct code path is present for 3.x vs 4.x (sync/async). • tests/architecture/test_dependency_separation.py verifies client importability without server deps and shared exception availability. 4. Docs + version stance • Keeps pyproject.toml permissive (gql[aiohttp,requests]>=3.4.0) and documents behaviour.

TLDR: #5290 is about upstream compatibility; #5289 removes that fragility and fixes the ClickHouse import coupling.