Skip to content

Record that the browser runtime is its own package - #1458

Merged
neuromechanist merged 3 commits into
devfrom
docs/adr-lean-runtime-package
Sep 20, 2026
Merged

neuromechanist merged 3 commits into
devfrom
docs/adr-lean-runtime-package

Conversation

@neuromechanist

@neuromechanist neuromechanist commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Adds ADR 0069, and closes a path this epic had been walking down.

What was decided

eegprep stays whole. Its default install keeps every dependency it has today, so pip install eegprep is unchanged and no existing user gets less than they had.

The browser runtime becomes a separate distribution, eegprep-lean, published from the eegprep repository rather than a new one: same source tree, same tests, same maintainers. eegprep depends on it and re-exports it, so the default install is a superset of what it is today and the science code is not forked into two copies that drift. This project owns the seam: a declared contract, with any divergence in behavior written into that contract rather than discovered by a user who hit it.

Why not eegprep[lean]

It is the name everyone reaches for first, including in the discussion that produced this ADR, and it cannot work. A Python extra adds to a distribution's requirements and never replaces them, so pip install eegprep[lean] resolves eegprep's whole 62.6 MB base and then adds more. micropip resolves the same way, so the browser gets no relief either. A genuinely small install needs a distribution whose base is small: either a lean eegprep, which changes what every existing user gets from an unchanged command, or a second name. The ADR records this in full, because it is the proposal that will come back.

Extras are still the right mechanism one level down, where they are additive by nature:

install packages download what it buys
eegprep-lean 12 4.2 MB read a window of data
eegprep-lean[plot] 22 14.0 MB and draw it, adding matplotlib
eegprep-lean[preprocess] 23 30.4 MB and filter and resample it, adding scipy
eegprep-lean[ica] 27 36.3 MB and decompose it, adding python-picard

Plotting is out of the base deliberately. It costs 9.8 MB and it is the first thing a person asks for after looking at data, so it arrives when a plot is actually asked for rather than being paid for by a session that only reads.

Why it is an ADR rather than a comment

It closes off the alternative, which had measurements behind it and was nearly executed. The plan was to move mne, pybids, h5py and neo into eegprep extras, taking the base install from 61 packages and 62.6 MB down toward 36.3 MB.

Two findings stopped it:

  • Lazy imports do not reduce the download. micropip installs the declared closure whether or not a module is imported, so only moving a package to an extra changes the number. Trimming eegprep therefore means changing what pip install eegprep gives people, not merely when it loads things.
  • An import-site audit cannot tell which packages are safe to move. eeglabio has no import site anywhere in src/ and is still load-bearing: mne imports it when asked to write an EEGLAB file, and eeg_mne2eeg exports through mne. Removing it failed 12 tests on every supported platform. Every other candidate would need the same proof, run against an environment that genuinely lacks the package.

The honest cost is written into the ADR: a seam, and seams drift. Two implementations of one operation can disagree, and that disagreement shows up as a result that differs between a browser and a workstation. The contract is the deliverable for exactly that reason. Divergence is allowed; undeclared divergence is not.

Related work

Numbered 0069 rather than 0068: 0068 was taken on dev while this was being written.

The measurements that drove this are in sccn/eegprep#395 and the
decision was argued more than once, most recently against the plan to
move mne, pybids, h5py and neo into eegprep extras. It closes that path,
so it belongs in an ADR rather than in a comment thread.

The finding that settled it: an import-site audit cannot tell which
dependencies are safe to move. eeglabio has no import site anywhere in
eegprep and is not removable, because mne imports it when asked to write
an EEGLAB file, which 12 tests proved on every supported platform after
it was removed.
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1458

Version: 0.10.5-PR1458.3f2aa91
Commit: 3f2aa91


🤖 Updated on each push.

eegprep[lean] is the name everyone reaches for first, and it cannot
work: a Python extra adds to a distribution's requirements and never
replaces them, so pip and micropip both resolve eegprep's whole base
install before the extra is considered. A small install needs a
distribution whose base is small. Recording the reason in the ADR
because it is the proposal that will come back.

The lean distribution is published from the eegprep repository rather
than a new one, and eegprep depends on it, so the science code is not
forked and the default install stays a superset of what it is today.

Its tiers are extras, which is what extras are for, since each one
genuinely adds to the tier beneath it: 4.2 MB to read a window, plot
adding matplotlib at 14.0 MB, preprocess adding scipy at 30.4 MB, ica
adding python-picard at 36.3 MB. Plotting is out of the base
deliberately; it is 9.8 MB and it arrives when a plot is asked for.
matplotlib is 62 percent bundled fonts and its working library is about
2 MB, so a rebuilt wheel is technically available. Costed out it saves
2.47 MB without changing behavior, which does not pay for a wheel to
maintain against every matplotlib release and a font-fallback
divergence to declare.

Recorded with the threshold that would change the answer, around 8 MB
or half the tier, so the next person finds the measurement instead of
repeating it.
@neuromechanist
neuromechanist merged commit 29af4a8 into dev Sep 20, 2026
12 checks passed
@neuromechanist
neuromechanist deleted the docs/adr-lean-runtime-package branch September 20, 2026 22:52

This branch was previously deployed

1 inactive deployment
npm — 3f2aa910 Deployed Sep 20, 2026 by neuromechanist via publish #2746
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