Share the generic parts of a node

[klangenk]

Motivation

Three node repositories build on this library, and a surprising amount of what they contain is not about their models at all. It had been copied between them and had drifted:

• clip_point was byte-identical in five places. clip_box existed in those five plus a sixth that used a centre-based convention under the same name, so the function meant two different things depending on the file.
• Confidence filtering, per-class NMS, and building the loop's detection dataclasses existed three to four times over.
• Every main.py repeated the same twenty lines of parser-and-uvicorn scaffolding — eight copies.
• The confusion-matrix F1 score was implemented three times, over two different data shapes.
• Batch-size selection was implemented three times, three different ways: a real probe, an estimate parsed out of torchinfo's summary text, and a doubling loop catching bare RuntimeError.
• _get_executor_error_from_log was byte-identical in two repositories.

A fourth node would have copied all of it again. This adds the shared home for it, in three commits that are worth reading in order.

What is added

detector/postprocess.py, detector/geometry.py, detector/categories.py — Detection, bbox_iou, non_max_suppression, post_process, detections_from_xyxy; one clipping implementation per convention (clip_box, clip_box_centered, clip_point); and category_by_index/category_by_name, which resolve a model's metadata rather than post-processing anything and so live apart from it.

The two containers for the same detections are unified: to_image_metadata (what a detector reports) and to_detections (what a trainer's auto-detection pass reports) share one routine, so the two paths can no longer clip and filter differently — which they did.

helpers/entrypoint.py — node_parser and run_node. A setting is named after its flag: --conf-threshold reads CONF_THRESHOLD, and --help lists it. legacy_env_prefix lets a node that once required a prefix keep reading the old names with a deprecation warning.

--host/--port are the deliberate exception, reading NODE_HOST/NODE_PORT. The bare HOST already means the loop's address — every deployment sets it — so a node deriving it would hand that to uvicorn and fail to bind. There is a test for exactly this.

trainer/cuda.py — usable_memory_bytes, limit_cuda_memory and free_cuda_memory, the two halves of a --vram-limit-gb setting: the budget a batch-size probe measures against, and the cap that holds the process to it. This is the one module that imports torch, and the package deliberately does not declare it — only a trainer imports it, and a trainer brings torch already. Its test installs a stand-in under that name, which covers the arithmetic and the guards; that the cap holds can only be seen on a card.

trainer/subprocess.py, trainer/batch_size.py, trainer/metrics.py — iterator_cpu_bound, the power-of-two batch-size search, and macro_f1. The batch-size search imports no framework: it is pure arithmetic around a fits predicate the trainer supplies, which is what lets any node use it. is_out_of_memory is part of that: allocation failures do not all arrive as a dedicated error type — cuDNN and cuBLAS raise plain RuntimeError — and one repository was catching bare RuntimeError, so every crash looked like a full card.

TrainerLogic._get_executor_error_from_log gains a default implementation and stops being abstract; existing overrides keep working.

Testing

Adds learning_loop_node/tests/unit/, the first suite that runs without a Learning Loop — no credentials, no network, 214 tests in about 1.5 seconds, on every Python version requires-python promises. CI gates the credential-dependent jobs on it.

Those jobs are restructured while here. They used to split the suites between versions — general, detector and mock_detector on 3.10, annotator, trainer and mock_trainer on 3.13 — so neither version was tested, only half of each. One matrix job now runs all six on 3.10 and 3.13, serialised: they share one Learning Loop, and test_general creates and deletes zauberzeug/pytest_nodelib_general by a fixed name.

That gap is why the node repositories have so few tests: learning_loop_node/tests/ is excluded from the wheel, so nothing in it is importable downstream. Making the helpers shippable is a follow-up phase; this establishes the suite.

A disagreeing environment variable no longer points at production

read_from_env takes an ordered list of names — ['LOOP_HOST', 'HOST'] and so on — and returned None when two were set to different values. The caller then fell back to its default, and host()'s default is 'learning-loop.ai'. So a .env carrying both spellings with different values pointed the node at production, with only a log warning.

Since values is built in possible_names order and then filtered, the first surviving value is already the preferred one — so the fix is to warn and fall through to the existing return values[0]. ignore_errors=False still raises.

This is the right layer for it: the node repositories' docker.sh scripts had been working around it by forwarding exactly one spelling, which forced every sub-project to agree on which. Now that the container receives the whole .env, only the library can decide. Six tests added in tests/unit/test_environment_reader.py.

Notes for the reviewer

• Box corners are rounded once, in clip_box. The first version of this branch kept post_process's int() so detector output stayed bit-identical; review pointed out that truncating and then rounding again is strictly worse than rounding once. A box moves by at most a pixel, confidences are no longer clipped to two decimals, and point detections gain real precision — their centre used to come from truncated ints. No node consumes this yet.
• The PEP 695 type parameters (def f[T]) in the moved generator were rewritten as TypeVar/ParamSpec: this library supports Python 3.10 while the node repository they came from targets 3.12. The unit suite runs on 3.10 through 3.13 in CI, and every suite now runs on both ends of that range.
• The logging.basicConfig(...) every trainer carries is not reproduced. helpers/log_conf.py configures the root logger at import, so basicConfig has been a no-op — checked, not assumed.
• The batch-size search ships with one consumer. It came out of one node's trainer and that node is still the only caller, so it becomes public API with a single user the moment this is released. That is deliberate rather than an oversight: yolov5_node picks its batch size by string-parsing torchinfo.summary() instead of probing, and replacing that changes which batch size a training gets — it needs a GPU box and has its own card. is_out_of_memory from the same module already has two consumers.
• No node consumes this yet; the node PRs are separate and stay pinned to 0.21.0 until this is released.

Deliberately not included

• SubprocessTrainerLogic, a third trainer base class. With a single node as its only consumer, its progress protocol would be invented from one example, and yolov5_node's executor-and-log-scraping shape may not fit it.

---

⬛ claude-opus-5[1m] · 700k tokens · $16.90

[jfrieli]

Nice PR in general, really looking forward to merge this :)
I still found some points that could be worth to discuss/implement from my side.