Carry an image state through the socket.io upload

[HannesDeittert]

Motivation

The Learning Loop organises images as a kanban board and its upload endpoint already accepts a state per image, filing it into that state instead of the default inbox — trash included. A robot that wants to archive an image without pushing it into the annotation queue therefore only needs a way to say so.

ImageMetadata declared no such field, and it was lost twice over: dacite.from_dict is called non-strict, so an unknown state key in the metadata was discarded silently, and Outbox._save_files_to_disk writes asdict(image_metadata), which can only emit declared fields. A client could send the key and see no error, no log line, and no effect.

Implementation

• ImageMetadata gains state: str | None = None.
• Nothing else in the node needed touching: the socket.io handler parses into the dataclass and the outbox serialises out of it, so both are already generic over its fields.
• Docstring of the socket.io upload event and the README's upload section document the field.
• test_sio_upload_with_state asserts the state reaches the json file the outbox uploads.

Deliberately a plain str rather than an enum: the state vocabulary belongs to the loop backend, which this library does not depend on, and its own exchange type accepts a bare string here. Written as str | None rather than Optional[str] to match CONTRIBUTING and keep ruff quiet, which does read slightly against the neighbouring fields in that dataclass — say the word if you would rather have local consistency.

Compatibility

Additive and optional. Existing clients send no state and get the loop default; older nodes receiving a state from a newer client keep ignoring it exactly as before.

Testing

• learning_loop_node/tests/detector → 28 passed, plus the new test.
• test_outbox.py::test_set_outbox_mode errors, on this branch and on main alike: it wants LOOP_HOST from a local .env that is not present here.
• uvx ruff check . → 717 findings before and after; the whole diff is shifted line numbers.

Follow-up

RoSys needs a matching state= parameter on Detector.upload() before a robot can actually use this, and the detector images have to be rebuilt against a release that contains this change.

※

[Copilot]

🟡 Changes recommended

The updated README section still documents an incorrect Socket.IO upload return value and should be corrected while this area is being modified.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the library’s Socket.IO image upload pipeline to preserve an image “state” (e.g. trash) through ImageMetadata so the Learning Loop can file uploaded images into a non-default kanban column.

Changes:

• Add an optional state field to ImageMetadata so it survives dacite.from_dict(...) parsing and asdict(...) serialization.
• Document the new state metadata key in the Socket.IO upload docs (README + detector node docstring).
• Add a detector Socket.IO test asserting state is written into the outbox metadata JSON file.

File summaries

File	Description
README.md	Documents state as an accepted Socket.IO upload metadata key.
learning_loop_node/tests/detector/test_client_communication.py	Adds a test ensuring state reaches the outbox JSON metadata file.
learning_loop_node/detector/detector_node.py	Updates the Socket.IO upload event docstring to mention state.
learning_loop_node/data_classes/image_metadata.py	Adds state to the ImageMetadata wire type.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.