[brettelliot]

Context

We hit a real production OOM backfilling liquid_universe_prices for RW's own full ~2,136-ticker equities universe (2015–present) — a Celery worker died at both a 2GB and then a 4GB memory limit.

Root cause: liquid_universe_prices (unlike ib_shortstock) isn't Template.YEAR-partitioned, so Session._read_object re-reads and re-filters the entire on-disk export via formats.read_frame on every get() call, no matter how narrow start/end are. Our own workaround was to slice our own ingestion loop by calendar year to bound our memory — but that just multiplied the number of full-export reads within one long-running process (~36 of them), and since CPython/pandas don't reliably return freed memory to the OS between them, RSS ratcheted upward across the run rather than staying flat, eventually crossing any fixed ceiling we gave it.

We flagged this in Discord and were invited to open a PR, so here it is.

What this PR does

Adds a small per-AsyncSession LRU cache of _read_object's own parsed-and-filtered results (ClientConfig.frame_cache_max_entries / RWPYTOOLS_FRAME_CACHE_MAX_ENTRIES, default 8, 0 disables). A caller that repeats an identical request — retrying after a partial failure, or iterating windows itself to bound its own memory, both very real patterns against a large non-templated bulk dataset — gets the identical result back instead of re-reading and re-filtering the export from disk.

Keyed by the export's own on-disk identity (path, size — the same pair BulkClient.fetch_one already re-validates a cache entry against) plus the request shape (date_column, start, end, symbol_column, symbols), so a refreshed export or a genuinely different request always misses. Returns a shallow copy on a hit so no caller can mutate the shared cached object.

What this does not fix, to be upfront about scope: a first-time read of a large non-templated export, or two calls for genuinely different windows within one sweep (exactly our own year-by-year loop's shape), still each pay the full-export cost once. The fix that would actually help every caller and every window — not just exact repeats — is Template.YEAR-partitioning liquid_universe_prices itself, the same way ib_shortstock already is. That's a data-publishing decision on your side, not something a client-side PR can do, so it's a separate ask, not part of this PR.

Testing

• 3 new tests in test_session.py: cache hit (spies on formats.read_frame, asserts it's called once across two identical get() calls, and that results match), correct discrimination by request shape (different symbols still reads fresh), and frame_cache_max_entries=0 fully disabling the cache.
• Full existing suite: 232 passed (229 existing + 3 new).
• ruff check, ruff format --check, mypy all clean on the changed files. (Two pre-existing lint findings elsewhere in the repo, unrelated to this change, confirmed present on main before this branch — left untouched.)
• Also added a README Configuration table row and a short Cache section note distinguishing this from the existing on-disk FilesystemCache.

Happy to adjust the default LRU size, the cache-key shape, or split this into a smaller PR if that's easier to review — and equally happy to hear if Template.YEAR for liquid_universe_prices is already on your radar, in which case this PR might not be worth carrying long-term.