Skip to content

Fix nlp cache release key - #831

Merged
milton-minervino merged 3 commits into
MAIF:developfrom
milton-minervino:fix/nlp-cache-release-key
Nov 10, 2026
Merged

milton-minervino merged 3 commits into
MAIF:developfrom
milton-minervino:fix/nlp-cache-release-key

Conversation

@milton-minervino

Copy link
Copy Markdown
Collaborator

Summary

NlpExplainer.explain(cache_dir=...) included the full shapash version string in its cache key. Under setuptools-scm that string looks like 2.10.1.dev13+gd9f9d23.d20261103, which causes two problems:

  • Too strict on development installs. The commit hash and the dirty-tree date stamp change the key on every commit and every day, so the cache was effectively disabled while developing.
  • Too loose on editable installs. The version is frozen when the package is installed, so after code changes the key could stay the same and serve results computed by older code.

This PR keys the cache on the release (major.minor.patch) and adds an explicit way to force a refresh.

Changes

  • Cache key uses the release, not the full version. _cache_release() keeps only the leading major.minor.patch:
    • 2.10.0 and 2.10.1 → different keys. A patch release may fix how a backend computes, and a stale entry looks exactly like a correct one.
    • 2.10.1.dev13+g<hash>.d<date> → 2.10.1, stable across commits and days.
    • 2.11.0rc1 → shares a key with 2.11.0.
    • 0+unknown (source tree that was never installed) → falls back to the raw string.
  • explain(..., recompute=False). recompute=True skips both the in-memory and the on-disk cache, runs the backend again and stores the fresh result. The previous entry is only overwritten after the new one is computed, so a failed recompute (OOM, interrupted run) keeps it, whereas clear_cache() followed by explain() loses it. This matches the existing recompute argument of compute_embeddings/compute_projection. clear_cache() stays, for dropping an entry without recomputing.
  • demo/serve_nlp.py --recompute now uses explain(recompute=...) instead of clear_cache().
  • Corrected the _compute_key and _load_cached docstrings. _load_cached claimed the key "changes with every release, not with every commit", which wasn't true.

Impact

  • Existing cache entries are invalidated once, because the key format changed. They are recomputed on the next explain(). After that, users recompute once per shapash upgrade, per corpus.
  • On a development build the key doesn't change between commits. After changing backend code, use explain(recompute=True) or --recompute in the demo.

Tests

  • Key tests: different releases give different keys, a dev build stays stable across commits/dates and shares its target release's key, an rc shares its final release's key, the uninstalled fallback works.
  • recompute tests: it bypasses the in-memory guard, it bypasses and overwrites the disk entry, and a failed recompute keeps both the disk entry and the in-memory entry.
  • pytest tests/unit_tests passes, and ruff and mypy are clean.

@codecov

codecov Bot commented Nov 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.19%. Comparing base (58f4562) to head (347bd20).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop     #831   +/-   ##
========================================
  Coverage    86.18%   86.19%           
========================================
  Files          115      115           
  Lines        11859    11864    +5     
  Branches      2161     2161           
========================================
+ Hits         10221    10226    +5     
  Misses         997      997           
  Partials       641      641           
Files with missing lines Coverage Δ
shapash/explainer/nlp_explainer.py 89.13% <100.00%> (+0.20%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@milton-minervino
milton-minervino merged commit 6f10e31 into MAIF:develop Nov 10, 2026
11 checks passed
@milton-minervino
milton-minervino deleted the fix/nlp-cache-release-key branch November 10, 2026 16:46
@milton-minervino
milton-minervino restored the fix/nlp-cache-release-key branch November 10, 2026 16:47
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.

2 participants