# Learning Loop Node
This Python library helps to write Nodes that interact with the Zauberzeug Learning Loop. There are 4 types of Nodes:
| Type | Purpose |
| --------- | ---------------------------------------------------- |
| Trainer | Runs training using the latest training data |
| Detector | Loads latest models from Loop and performs inference |
| Annotator | Used for custom annotation inside the Loop |
| Converter | Converts between different model formats |
## General Usage
To start a node you have to implement the logic by inheriting from the corresponding base logic class. We provide samples in the 'mock' folders and recommend to follow that scheme. A complete trainer and detector example can be found [here](https://github.com/zauberzeug/yolov5_node).
#### Environment variables
You can configure connection to our Learning Loop by specifying the following environment variables before starting:
| Name | Alias | Purpose | Required by |
| ------------------------ | ------------ | ------------------------------------------------------------ | ------------------------- |
| LOOP_HOST | HOST | Learning Loop address (e.g. learning-loop.ai) | all |
| LOOP_USERNAME | USERNAME | Learning Loop user name | all besides Detector |
| LOOP_PASSWORD | PASSWORD | Learning Loop password | all besides Detector |
| LOOP_SSL_CERT_PATH | - | Path to the SSL certificate | all (opt.) |
| LOOP_ORGANIZATION | ORGANIZATION | Organization name | Detector |
| LOOP_PROJECT | PROJECT | Project name | Detector (opt.) |
| MIN_UNCERTAIN_THRESHOLD | - | smallest confidence (float) at which auto-upload will happen | Detector (opt.) |
| MAX_UNCERTAIN_THRESHOLD | - | largest confidence (float) at which auto-upload will happen | Detector (opt.) |
| INFERENCE_BATCH_SIZE | - | Batch size of trainer when calculating detections | Trainer (opt.) |
| RESTART_AFTER_TRAINING | - | Restart the trainer after training (set to 1) | Trainer (opt.) |
| KEEP_OLD_TRAININGS | - | Do not delete old trainings (set to 1) | Trainer (opt.) |
| TRAINER_IDLE_TIMEOUT_SEC | - | Automatically shutdown trainer after timeout (in seconds) | Trainer (opt.) |
| USE_BACKDOOR_CONTROLS | - | Always enable backdoor controls (set to 1) | Trainer / Detector (opt.) |
#### Testing
We use github actions for CI. Tests can also be executed locally by running
`LOOP_HOST=XXXXXXXX LOOP_USERNAME=XXXXXXXX LOOP_PASSWORD=XXXXXXXX python -m pytest -v`
from learning_loop_node/learning_loop_node
## Detector Node
Detector Nodes are normally deployed on edge devices like robots or machinery but can also run in the cloud to provide backend services for an app or similar. These nodes register themself at the Learning Loop. They provide REST and Socket.io APIs to run inference on images. The processed images can automatically be used for active learning: e.g. uncertain predictions will be send to the Learning Loop.
### Running Inference
Images can be send to the detector node via socketio or rest.
The later approach can be used via curl,
Example usage:
`curl --request POST -F 'file=@test.jpg' localhost:8004/detect`
Where 8804 is the specified port in this example.
You can additionally provide the following camera parameters:
- `autoupload`: configures auto-submission to the learning loop; `filtered` (default), `all`, `disabled` (example curl parameter `-H 'autoupload: all'`)
- `camera-id`: a string which groups images for submission together (example curl parameter `-H 'camera-id: front_cam'`)
The detector also has a sio **upload endpoint** that can be used to upload images and detections to the learning loop. The function receives a json dictionary, with the following entries:
- `image`: the image data in jpg format
- `tags`: a list of strings. If not provided the tag is `picked_by_system`
- `detections`: a dictionary representing the detections. UUIDs for the classes are automatically determined based on the category names. This field is optional. If not provided, no detections are uploaded.
The endpoint returns None if the upload was successful and an error message otherwise.
### Changing the model version
The detector can be configured to one of the following behaviors:
- download use a specific model version
- automatically update the model version according to the learning loop deployment target
- pause the model updates and use the version that was last loaded
The model versioning configuration can be accessed/changed via a REST endpoint. Example Usage:
- Fetch the current model versioning configuration: `curl http://localhost/model_version`
- Configure the detector to use a specific model version: `curl -X PUT -d "1.0" http://localhost/model_version`
- Configure the detector to automatically update the model version: `curl -X PUT -d "follow_loop" http://localhost/model_version`
- Pause the model updates: `curl -X PUT -d "pause" http://localhost/model_version`
Note that the configuration is not persistent, however, the default behavior on startup can be configured via the environment variable `VERSION_CONTROL_DEFAULT`.
If the environment variable is set to `VERSION_CONTROL_DEFAULT=PAUSE`, the detector will pause the model updates on startup. Otherwise, the detector will automatically follow the loop deployment target.
### Changing the outbox mode
If the autoupload is set to `all` or `filtered` (selected) images and the corresponding detections are saved on HDD (the outbox). A background thread will upload the images and detections to the Learning Loop. The outbox is located in the `outbox` folder in the root directory of the node. The outbox can be cleared by deleting the files in the folder.
The continuous upload can be stopped/started via a REST enpoint:
Example Usage:
- Enable upload: `curl -X PUT -d "continuous_upload" http://localhost/outbox_mode`
- Disable upload: `curl -X PUT -d "stopped" http://localhost/outbox_mode`
The current state can be queried via a GET request:
`curl http://localhost/outbox_mode`
### Explicit upload
The detector has a REST endpoint to upload images (and detections) to the Learning Loop. The endpoint takes a POST request with the image and optionally the detections. The image is expected to be in jpg format. The detections are expected to be a json dictionary. Example:
`curl -X POST -F 'files=@test.jpg' "http://localhost:/upload"`
## Trainer Node
Trainers fetch the images and anntoations from the Learning Loop to train new models.
- if the command line tool "jpeginfo" is installed, the downloader will drop corrupted images automatically
## Converter Node
A Conveter Node converts models from one format into another.
## Annotator Node
...
#### Test operability
Assumend there is a Converter Node which converts models of format 'format_a' into 'format_b'.
Upload a model with
`curl --request POST -F 'files=@my_model.zip' https://learning-loop.ai/api/zauberzeug/projects/demo/format_a`
The model should now be available for the format 'format_a'
`curl "https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_a"`
````
{
"models": [
{
"id": "3c20d807-f71c-40dc-a996-8a8968aa5431",
"version": "4.0",
"formats": [
"format_a"
],
"created": "2021-06-01T06:28:21.289092",
"comment": "uploaded at 2021-06-01 06:28:21.288442",
...
}
]
}
```
but not in the format_b
`curl "https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_b"`
```
{
"models": []
}
```
Connect the Node to the Learning Loop by simply starting the container.
After a short time the converted model should be available as well.
`curl https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_b`
```
{
"models": [
{
"id": "3c20d807-f71c-40dc-a996-8a8968aa5431",
"version": "4.0",
"formats": [
"format_a",
"format_b",
],
"created": "2021-06-01T06:28:21.289092",
"comment": "uploaded at 2021-06-01 06:28:21.288442",
...
}
]
}
```
## About Models (the currency between Nodes)
- Models are packed in zips and saved on the Learning Loop (one for each format)
- Nodes and users can upload and download models with which they want to work
- In each zip there is a file called `model.json` which contains the metadata to interpret the other files in the package
- for base models (pretrained models from external sources) no `model.json` has to be sent, ie. these models should simply be zipped in such a way that the respective trainer can work with them.
- the loop adds or corrects the following properties in the `model.json` after receiving; it also creates the file if it is missing:
- `host`: uri to the loop
- `organization`: the ID of the organization
- `project`: the id of the project
- `version`: the version number that the loop assigned for this model (e.g. 1.3)
- `id`: the model UUID (currently not needed by anyone, since host, org, project, version clearly identify the model)
- `format`: the format e.g. yolo, tkdnn, yolor etc.
- Nodes add properties to `model.json`, which contains all the information which are needed by subsequent nodes. These are typically the properties:
- `resolution`: resolution in which the model expects images (as `int`, since the resolution is mostly square - later, ` resolution_x`` resolution_y ` would also be conceivable or `resolutions` to give a list of possible resolutions)
- `categories`: list of categories with name, id, (later also type), in the order in which they are used by the model -- this is neccessary to be robust about renamings
```
````
Raw data
{
"_id": null,
"home_page": "https://github.com/zauberzeug/learning_loop_node",
"name": "learning-loop-node",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Zauberzeug GmbH",
"author_email": "info@zauberzeug.com",
"download_url": "https://files.pythonhosted.org/packages/12/f2/517dc450aaa21fa39f9640a9afc57a99bddd1bbd402795451cdb78c5f92f/learning_loop_node-0.12.0.tar.gz",
"platform": null,
"description": "# Learning Loop Node\n\nThis Python library helps to write Nodes that interact with the Zauberzeug Learning Loop. There are 4 types of Nodes:\n\n| Type | Purpose |\n| --------- | ---------------------------------------------------- |\n| Trainer | Runs training using the latest training data |\n| Detector | Loads latest models from Loop and performs inference |\n| Annotator | Used for custom annotation inside the Loop |\n| Converter | Converts between different model formats |\n\n## General Usage\n\nTo start a node you have to implement the logic by inheriting from the corresponding base logic class. We provide samples in the 'mock' folders and recommend to follow that scheme. A complete trainer and detector example can be found [here](https://github.com/zauberzeug/yolov5_node).\n\n#### Environment variables\n\nYou can configure connection to our Learning Loop by specifying the following environment variables before starting:\n\n| Name | Alias | Purpose | Required by |\n| ------------------------ | ------------ | ------------------------------------------------------------ | ------------------------- |\n| LOOP_HOST | HOST | Learning Loop address (e.g. learning-loop.ai) | all |\n| LOOP_USERNAME | USERNAME | Learning Loop user name | all besides Detector |\n| LOOP_PASSWORD | PASSWORD | Learning Loop password | all besides Detector |\n| LOOP_SSL_CERT_PATH | - | Path to the SSL certificate | all (opt.) |\n| LOOP_ORGANIZATION | ORGANIZATION | Organization name | Detector |\n| LOOP_PROJECT | PROJECT | Project name | Detector (opt.) |\n| MIN_UNCERTAIN_THRESHOLD | - | smallest confidence (float) at which auto-upload will happen | Detector (opt.) |\n| MAX_UNCERTAIN_THRESHOLD | - | largest confidence (float) at which auto-upload will happen | Detector (opt.) |\n| INFERENCE_BATCH_SIZE | - | Batch size of trainer when calculating detections | Trainer (opt.) |\n| RESTART_AFTER_TRAINING | - | Restart the trainer after training (set to 1) | Trainer (opt.) |\n| KEEP_OLD_TRAININGS | - | Do not delete old trainings (set to 1) | Trainer (opt.) |\n| TRAINER_IDLE_TIMEOUT_SEC | - | Automatically shutdown trainer after timeout (in seconds) | Trainer (opt.) |\n| USE_BACKDOOR_CONTROLS | - | Always enable backdoor controls (set to 1) | Trainer / Detector (opt.) |\n\n#### Testing\n\nWe use github actions for CI. Tests can also be executed locally by running\n`LOOP_HOST=XXXXXXXX LOOP_USERNAME=XXXXXXXX LOOP_PASSWORD=XXXXXXXX python -m pytest -v` \nfrom learning_loop_node/learning_loop_node\n\n## Detector Node\n\nDetector Nodes are normally deployed on edge devices like robots or machinery but can also run in the cloud to provide backend services for an app or similar. These nodes register themself at the Learning Loop. They provide REST and Socket.io APIs to run inference on images. The processed images can automatically be used for active learning: e.g. uncertain predictions will be send to the Learning Loop.\n\n### Running Inference\n\nImages can be send to the detector node via socketio or rest.\nThe later approach can be used via curl,\n\nExample usage:\n\n`curl --request POST -F 'file=@test.jpg' localhost:8004/detect`\n\nWhere 8804 is the specified port in this example.\nYou can additionally provide the following camera parameters:\n\n- `autoupload`: configures auto-submission to the learning loop; `filtered` (default), `all`, `disabled` (example curl parameter `-H 'autoupload: all'`)\n- `camera-id`: a string which groups images for submission together (example curl parameter `-H 'camera-id: front_cam'`)\n\nThe detector also has a sio **upload endpoint** that can be used to upload images and detections to the learning loop. The function receives a json dictionary, with the following entries:\n\n- `image`: the image data in jpg format\n- `tags`: a list of strings. If not provided the tag is `picked_by_system`\n- `detections`: a dictionary representing the detections. UUIDs for the classes are automatically determined based on the category names. This field is optional. If not provided, no detections are uploaded.\n\nThe endpoint returns None if the upload was successful and an error message otherwise.\n\n### Changing the model version\n\nThe detector can be configured to one of the following behaviors:\n\n- download use a specific model version\n- automatically update the model version according to the learning loop deployment target\n- pause the model updates and use the version that was last loaded\n\nThe model versioning configuration can be accessed/changed via a REST endpoint. Example Usage:\n\n- Fetch the current model versioning configuration: `curl http://localhost/model_version`\n- Configure the detector to use a specific model version: `curl -X PUT -d \"1.0\" http://localhost/model_version`\n- Configure the detector to automatically update the model version: `curl -X PUT -d \"follow_loop\" http://localhost/model_version`\n- Pause the model updates: `curl -X PUT -d \"pause\" http://localhost/model_version`\n\nNote that the configuration is not persistent, however, the default behavior on startup can be configured via the environment variable `VERSION_CONTROL_DEFAULT`.\nIf the environment variable is set to `VERSION_CONTROL_DEFAULT=PAUSE`, the detector will pause the model updates on startup. Otherwise, the detector will automatically follow the loop deployment target.\n\n### Changing the outbox mode\n\nIf the autoupload is set to `all` or `filtered` (selected) images and the corresponding detections are saved on HDD (the outbox). A background thread will upload the images and detections to the Learning Loop. The outbox is located in the `outbox` folder in the root directory of the node. The outbox can be cleared by deleting the files in the folder.\n\nThe continuous upload can be stopped/started via a REST enpoint:\n\nExample Usage:\n\n- Enable upload: `curl -X PUT -d \"continuous_upload\" http://localhost/outbox_mode`\n- Disable upload: `curl -X PUT -d \"stopped\" http://localhost/outbox_mode`\n\nThe current state can be queried via a GET request:\n`curl http://localhost/outbox_mode`\n\n### Explicit upload\n\nThe detector has a REST endpoint to upload images (and detections) to the Learning Loop. The endpoint takes a POST request with the image and optionally the detections. The image is expected to be in jpg format. The detections are expected to be a json dictionary. Example:\n\n`curl -X POST -F 'files=@test.jpg' \"http://localhost:/upload\"`\n\n## Trainer Node\n\nTrainers fetch the images and anntoations from the Learning Loop to train new models.\n\n- if the command line tool \"jpeginfo\" is installed, the downloader will drop corrupted images automatically\n\n## Converter Node\n\nA Conveter Node converts models from one format into another.\n\n## Annotator Node\n\n...\n\n#### Test operability\n\nAssumend there is a Converter Node which converts models of format 'format_a' into 'format_b'.\nUpload a model with\n`curl --request POST -F 'files=@my_model.zip' https://learning-loop.ai/api/zauberzeug/projects/demo/format_a`\nThe model should now be available for the format 'format_a'\n`curl \"https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_a\"`\n\n````\n\n{\n\"models\": [\n{\n\"id\": \"3c20d807-f71c-40dc-a996-8a8968aa5431\",\n\"version\": \"4.0\",\n\"formats\": [\n\"format_a\"\n],\n\"created\": \"2021-06-01T06:28:21.289092\",\n\"comment\": \"uploaded at 2021-06-01 06:28:21.288442\",\n...\n}\n]\n}\n\n```\n\nbut not in the format_b\n`curl \"https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_b\"`\n\n```\n\n{\n\"models\": []\n}\n\n```\n\nConnect the Node to the Learning Loop by simply starting the container.\nAfter a short time the converted model should be available as well.\n`curl https://learning-loop.ai/api/zauberzeug/projects/demo/models?format=format_b`\n\n```\n\n{\n\"models\": [\n{\n\"id\": \"3c20d807-f71c-40dc-a996-8a8968aa5431\",\n\"version\": \"4.0\",\n\"formats\": [\n\"format_a\",\n\"format_b\",\n],\n\"created\": \"2021-06-01T06:28:21.289092\",\n\"comment\": \"uploaded at 2021-06-01 06:28:21.288442\",\n...\n}\n]\n}\n\n```\n\n## About Models (the currency between Nodes)\n\n- Models are packed in zips and saved on the Learning Loop (one for each format)\n- Nodes and users can upload and download models with which they want to work\n- In each zip there is a file called `model.json` which contains the metadata to interpret the other files in the package\n- for base models (pretrained models from external sources) no `model.json` has to be sent, ie. these models should simply be zipped in such a way that the respective trainer can work with them.\n- the loop adds or corrects the following properties in the `model.json` after receiving; it also creates the file if it is missing:\n - `host`: uri to the loop\n - `organization`: the ID of the organization\n - `project`: the id of the project\n - `version`: the version number that the loop assigned for this model (e.g. 1.3)\n - `id`: the model UUID (currently not needed by anyone, since host, org, project, version clearly identify the model)\n - `format`: the format e.g. yolo, tkdnn, yolor etc.\n- Nodes add properties to `model.json`, which contains all the information which are needed by subsequent nodes. These are typically the properties:\n - `resolution`: resolution in which the model expects images (as `int`, since the resolution is mostly square - later, ` resolution_x`` resolution_y ` would also be conceivable or `resolutions` to give a list of possible resolutions)\n - `categories`: list of categories with name, id, (later also type), in the order in which they are used by the model -- this is neccessary to be robust about renamings\n```\n````\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Library for Nodes which connect to the Zauberzeug Learning Loop",
"version": "0.12.0",
"project_urls": {
"Homepage": "https://github.com/zauberzeug/learning_loop_node",
"Repository": "https://github.com/zauberzeug/learning_loop_node"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3342b1b545f0739319e2409361bb5c9534cad132331897eb439b6ba2310581ab",
"md5": "bb5e7dbd3c42fc5bd13cc6d542d1446f",
"sha256": "69aabf35937144ededcae2a3af48094df2127e929dc98b0c7db3e64ef6be75ca"
},
"downloads": -1,
"filename": "learning_loop_node-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb5e7dbd3c42fc5bd13cc6d542d1446f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 263688,
"upload_time": "2024-11-25T15:53:23",
"upload_time_iso_8601": "2024-11-25T15:53:23.643431Z",
"url": "https://files.pythonhosted.org/packages/33/42/b1b545f0739319e2409361bb5c9534cad132331897eb439b6ba2310581ab/learning_loop_node-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "12f2517dc450aaa21fa39f9640a9afc57a99bddd1bbd402795451cdb78c5f92f",
"md5": "61c51a5629178b790ea95c58f5dec946",
"sha256": "f81aa81b575fc9e9edbd28a44a2aa969189d28e83f585f01e1b30a4976989761"
},
"downloads": -1,
"filename": "learning_loop_node-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "61c51a5629178b790ea95c58f5dec946",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 233574,
"upload_time": "2024-11-25T15:53:25",
"upload_time_iso_8601": "2024-11-25T15:53:25.970641Z",
"url": "https://files.pythonhosted.org/packages/12/f2/517dc450aaa21fa39f9640a9afc57a99bddd1bbd402795451cdb78c5f92f/learning_loop_node-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 15:53:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zauberzeug",
"github_project": "learning_loop_node",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "learning-loop-node"
}
JSON
