Skip to content

fix(tracing): make OpenTelemetry an optional runtime dependency#30

Merged
Yash1hi merged 1 commit into
mainfrom
fix/otel-optional-import
Jun 15, 2026
Merged

fix(tracing): make OpenTelemetry an optional runtime dependency#30
Yash1hi merged 1 commit into
mainfrom
fix/otel-optional-import

Conversation

@Yash1hi

@Yash1hi Yash1hi commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Problem

otel is declared as an optional extra in pyproject.toml, but import scorecard_ai failed entirely unless [otel] was installed:

ModuleNotFoundError: No module named 'opentelemetry'

The top-level package (src/scorecard_ai/__init__.py) eagerly imports lib/wrap_llms.py, which imported opentelemetry at module load time. So the documented pip install scorecard-ai produced a broken SDK — the otel extra was effectively mandatory just to use the core API client.

Reproduced (with opentelemetry absent):

>>> import scorecard_ai
ModuleNotFoundError: No module named 'opentelemetry'

Fix

Make OpenTelemetry genuinely optional by deferring its import to first use of the tracing wrappers:

  • lib/_wrap_llms_otel.py (new) — the existing OpenTelemetry-backed implementation, moved verbatim. Still imports opentelemetry at the top.
  • lib/wrap_llms.py — now a thin shim with no top-level otel import. wrap / wrap_openai / wrap_anthropic lazily import the implementation on first call. If opentelemetry is missing, they raise a clear ImportError pointing to pip install 'scorecard-ai[otel]' instead of breaking import of the whole SDK. The type-only WrapConfig stays under TYPE_CHECKING.

All three public import paths are preserved: scorecard_ai.wrap, scorecard_ai.lib.wrap, and scorecard_ai.lib.wrap_llms.wrap.

Verification

  • import scorecard_ai succeeds with opentelemetry blocked; core Scorecard client constructs and works.
  • wrap() without otel raises a helpful ImportError (not an opaque ModuleNotFoundError).
  • ✅ With otel present, wrap() end-to-end still returns the _LLMClientWrapper; aliases preserved (wrap_openai is wrap).
  • ruff check and ruff format pass on both files.

Notes

  • Node SDK intentionally unchanged — @opentelemetry/* stay required dependencies there, so it already imports fine.
  • The [otel] install for tracing is already documented in examples/README.md, and the new error message points there too.

`import scorecard_ai` previously failed with `ModuleNotFoundError: No
module named 'opentelemetry'` unless the optional `[otel]` extra was
installed, because the top-level package eagerly imported
`lib/wrap_llms.py`, which imported opentelemetry at module load time.
This made the documented `pip install scorecard-ai` broken.

Move the OpenTelemetry-backed implementation into a private
`_wrap_llms_otel` module and turn `wrap_llms` into a thin shim whose
`wrap`/`wrap_openai`/`wrap_anthropic` lazily import the implementation on
first use. When opentelemetry is missing, calling a wrapper now raises a
clear ImportError pointing to `pip install 'scorecard-ai[otel]'` instead
of breaking import of the whole SDK.
@Yash1hi Yash1hi merged commit 59e3de8 into main Jun 15, 2026
7 checks passed
@Yash1hi Yash1hi deleted the fix/otel-optional-import branch June 15, 2026 23:31
@stainless-app stainless-app Bot mentioned this pull request Jun 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant