bird_song cannot co-install with fs_watch, lan_discovery, dashboard, memory_explorer or spatial_viz — birdnetlib hard-pins watchdog==2.1.9

[LetsGetToWorkBro]

What happened

#609 (closing #605) declared birds and infra as conflicting extras, because without that declaration uv lock could not resolve at all and the lock had been rotting for two weeks — the SBOM and pip-audit workflows were describing a dependency set the project no longer had.

That unblocked the lock, but it is worth being plain that it cost something real, and this issue is the cost.

$ curl -s https://pypi.org/pypi/birdnetlib/json | jq '.info.requires_dist[] | select(contains("watchdog"))'
"watchdog==2.1.9"

birdnetlib pins watchdog to an exact version. The infra extra needs watchdog>=6,<7 for the filesystem watcher. The two cannot be satisfied together.

Unlike the pillow conflicts declared above it in [tool.uv] conflicts, this is not a per-machine split. Those are honest: the profiles say "pick ONE per machine" and the two sides live on different hardware. This one is not — both would run on the same Mac. Five capabilities are now mutually exclusive with one other capability for no reason a wearer would recognise:

extra	capability	impact
birds	bird_song	2
infra	lan_discovery	3
infra	doc_read via dashboard	2
infra	fs_watch	2
infra	memory_explorer	2
infra	spatial_viz	2

Somebody who wants their Brain to name the birds outside and watch a folder for new files currently cannot have both, and nothing in the product explains why.

Ask

Any of these is a good answer; they are listed roughly easiest-first, not best-first.

1. Upstream it. watchdog==2.1.9 is almost certainly incidental — birdnetlib uses watchdog for directory-watching analysis, and the API it needs is stable across 2.x→6.x. A PR to joeweiss/birdnetlib relaxing it to a range would fix this for everyone, not just us, and would let the conflict declaration be deleted outright. This is the outcome I would most like.

2. Find out whether birdnetlib actually needs watchdog at all for our use. We call it to identify a bird from an audio buffer. If the directory-watcher is a separate entry point we never touch, the pin may be avoidable with a narrower install or by depending on the analyzer package directly.

3. Replace the dependency. birdnetlib is a wrapper around BirdNET-Analyzer. If the model can be driven through onnxruntime/tflite directly — which the project already ships for other lenses — bird_song stops needing the wrapper and its pin.

4. Argue it does not matter and close this. A defensible position: birds ships in no profile, it is opt-in, and someone who wants bird ID probably is not also running a Datasette dashboard. If you think that is right, say so here and I will fold the reasoning into decisions/ so nobody re-litigates it in six months.

Verifying a fix

cd host-python
# remove the [{ extra = "birds" }, { extra = "infra" }] pair from [tool.uv] conflicts
uv lock          # must resolve
uv lock --check
python -m pytest src/dreamlayer/tests/test_lockfile.py -q

test_lockfile.py was added in #609 and asserts, among other things, that no shipped profile contains a conflicting pair — so it will keep you honest if you shuffle extras between profiles to dodge the problem rather than solve it.

Related

Two more conflicts were declared in the same change and are the same shape, if this one interests you:

• math-ocr / vision — pix2tex pins timm==0.5.4, open-clip-torch wants timm>=1.0.17. Costs math_ocr (impact 2) alongside the whole vision tier.
• doc-ocr / dream — the pillow<11 vs >=11 split. This one is a genuine per-machine split (glasses-bridge host vs Mac Brain) and was simply never named; it is the least objectionable of the three.

Where

host-python

[Nitjsefnie]

Opened joeweiss/birdnetlib#135 for option 1.

One correction, because the premise turned out not to hold: watchdog==2.1.9 is not incidental in the way "the API it needs is stable across 2.x→6.x" suggests. watchdog 5.0.0 made PatternMatchingEventHandler.__init__ keyword-only (their PR #1057), and birdnetlib constructs it with four positional arguments — so relaxing the dependency line on its own would have shipped a TypeError straight into DirectoryWatcher.watch(). The PR is two edits, not one: convert that call to keyword arguments, then widen to >=2.1.9,<7.

Measured rather than read: the positional form works on 2.1.9, 3.0.0 and 4.0.2 and raises on 5.0.0, 6.0.0 and 7.0.0-dev; the keyword form works on all of them under identical parameter names, so no version-conditional code is needed. Observer.schedule was already passing recursive by keyword, so the handler construction was the only affected call. birdnetlib's own CI passes on 3.9/3.10/3.11 with watchdog 6.0.0 resolved under the widened requirement.

Two things to know before counting on it:

• The <7 ceiling is a choice I made, not a necessity. watchdog 7 switches pattern matching from path.match() to path.full_match(), under which their existing ["*.mp3", "*.wav"] silently stop matching. Adding "**/*.mp3", "**/*.wav" alongside the existing patterns matches on every version from 2.1.9 through 7.0.0-dev and would need no ceiling — I offered that in the PR rather than deciding it for him. (Swapping *.mp3 for **/*.mp3, which is what watchdog's own changelog advises, regresses on ≤6 for a bare relative path. Only the union is safe.)
• birdnetlib's last commit is 2026-04-28, with 13 open issues and one unrelated open PR. Landing the PR and getting a release are separate events, and it's the release that unblocks your lock — I have no read on his response latency, so treat the timing as unknown rather than soon.

Your option 2 also appears to be true: nothing DreamLayer calls reaches the watchdog surface, since bird_lens only touches Analyzer and Recording and neither pulls in birdnetlib.watcher. I don't think it's actionable though — there's no way to express "install birdnetlib without its watchdog dependency" — so it doesn't give you a resolver fix even though it's a correct observation. Flagging that one as a single-pass finding I haven't independently re-verified, unlike the watchdog behaviour above.

Happy to do the conflicts-table cleanup here once a release actually ships, if you want it.

[LetsGetToWorkBro]

Thank you — and thank you particularly for correcting the premise instead of working around it. "Almost certainly incidental" was my assumption, stated confidently, and it was wrong in a way that would have shipped a crash.

Verified both ends independently before writing it down:

$ python -c "import inspect; from watchdog.events import PatternMatchingEventHandler as P; print(inspect.signature(P.__init__))"
(self, *, patterns=None, ignore_patterns=None, ignore_directories=False, case_sensitive=False)   # 6.0.0

$ python -c "P(['*.mp3'], None, False, True)"
TypeError: PatternMatchingEventHandler.__init__() takes 1 positional argument but 5 were given

…and 4.0.2, unpacked from its wheel, still takes them positionally. birdnetlib 0.18.1's watcher.py passes all four that way with Requires-Dist: watchdog==2.1.9. So the two-edit shape of your PR is necessary, not defensive.

I've written it up as decisions/0012 (#630), because the version of this issue that lives in my head — "just relax the pin" — is the one someone will act on in six months otherwise. Your <7 finding is in there too, including the part that's easy to get backwards: the union with **/*.mp3 is safe on every version, swapping regresses on ≤6. I'd have made that mistake by following watchdog's own changelog advice.

Keeping this open, since the constraint is real and unresolved. Not option 4 — the cost is genuine and a wearer who wants birdsong and a folder watcher still can't have both.

Yes to the conflicts-table cleanup when a release ships, and thank you for offering. decisions/0012 records the check that says the moment has arrived:

$ curl -s https://pypi.org/pypi/birdnetlib/json | jq -r '.info.requires_dist[] | select(contains("watchdog"))'

Anything other than watchdog==2.1.9 and the pair can come out of [tool.uv] conflicts. No pressure on timing — you've already read upstream's activity better than I would have, and a merged PR isn't a release.

On option 2: agreed it's correct and agreed it isn't actionable. bird_lens only touches Analyzer and Recording, so the broken call site is one this project would never reach — which is a nice thing to know and still leaves the resolver stuck. Recorded as such rather than as a lead.

---

Generated by Claude Code