Added the last use case, added some variables notes.

Author: martacarbone

docs/models/models.md

@@ -1,4 +1,4 @@
-Ths is a possible implementation of AI model support in AppLab.
+This is a possible implementation of AI model support in AppLab.
 
 # Models
 In AI, a model is a trained system able to recognize patterns and/or make predictions.
@@ -22,14 +22,15 @@ models/
 		  build#2
 ```
 
-*NOTE:* We need to discuss how to handle different builds of the same model. In this case, we must ensure we reference the specific build to be run and manage the models' and model definitions' state and deletion accordingly.
+*NOTE:* We need to eventually discuss how to handle different builds of the same model. In this case, we must ensure we reference the specific build to be run and manage the model state, model definition state, and deletion accordingly.
 
 *NOTE:* To be discussed how to map Edge Impulse in an AppLab model. See Edge Impulse section below.
 
-The ```conf.yaml``` file contains generic model information. The application expects this data to be available for all models.
+The ```conf.yaml``` file contains generic model information. The application expects this data to be available for all models. The ```model_categories``` is a list of the categories of the model.
 ```
    runner: brick
    name : "Glass breaking classifier"
+   model_categories: [audio, video]
    model_labels:
      - "Background"
      - "Glass_Breaking"
@@ -50,8 +51,8 @@ In AI, a category is a common way to classify AI models, indicating the type of
 
 In AppLab, a category is defined as a keyword used to connect models to bricks. It defines which models can be attached to which bricks. Both a model and a brick have a list of categories.
 
-### Use Case (Linking Models to Bricks)
-Use Case (link the Figma here): In the brick configuration, we can choose the model to be used with the brick. The provided list is a filtered list of all models where the intersection of the model's category list and the brick's category list is not empty.
+### Linking Models to Bricks
+In the brick configuration, we can choose the model to be used with the brick. The provided list is a filtered list of all models where the intersection of the model's category list and the brick's category list is not empty.
 
 **We assume here that every model with a given category is able to work with any provider.** If there is a special model that is only able to work with a specific brick, we can always add a custom category to associate the model with the working brick.
 
@@ -62,12 +63,11 @@ A brick is defined in the brick-list.yaml
 ```
 - id: arduino:audio_classification
   name: Audio Classification
-  category: audio, other_cat
-  default_model_name: arduino:glass-breaking
+  categories: audio, other_cat
 ```
-The ```default_model_name``` field was added to specify a default model.
 
-*NOTE:* What should be done if this is a custom model? The concept of a default custom model does not exist.
+*NOTE:* categories is a model specific variable, what to do for a brick that does not involve a model?
+Somewhere is null, somewhere is "storage"
 
 ## App.yaml
 This file contains the app's information and configuration.
@@ -221,7 +221,6 @@ source-model-url: "https://aihub.qualcomm.com/models/hey_ardino_spotting_lite"
   - microphone
 ```
 *Note:* The following variables are defined in the current implementation but should be removed because they must be hidden from the final user.
-We need to discuss whether these variables should be defined here, or if we should leave them hardcoded instead (is this the correct alternative approach?).
 ```
   variables:
   - name: CUSTOM_MODEL_PATH
@@ -309,7 +308,7 @@ bricks:
 - arduino:fast_object_detection: {}
     variables:
       CUSTOM_MODEL_PATH: /home/arduino/.arduino-bricks/ei-models
-      OTHER_ENGINE_VARIABLE: /models/yolo_x_nano/builds/yolo-x-nano.eim
+      QLC_OBJ_DET_ENGINE_MODEL: /models/yolo_x_nano/builds/yolo-x-nano.eim
       SET_CUSTOM_PARAMETER: 5
 icon: 🏞️
 ```
@@ -372,10 +371,12 @@ bricks:
 - arduino:keyword_spotting: 
 EI_KEYWORD_SPOTTING_MODEL: "/models/hei_arduino_qlc/builds/qualcomm_impulse_hey_arduino.model"
 ```
+## Case #5 Two distinct bricks using the same custom model
+This case is the same as Case #3, where the variables used to customize the model are configurable by the user, with an optional default value.
 
 The following section explores whether this model is suitable for specific use cases.
 
-## The user chooses a model for a brick (link Figma here)
+## Case #6 The user chooses a model for a brick (link Figma here)
 In the brick configuration, there is a list of compatible models and the user selects the ```dog-detector``` model.
 In this case, the model will be stored in ```App.yaml```. The brick section will look like:
 ```
@@ -385,7 +386,7 @@ bricks:
 	model: dog-detector
 - arduino:mood_detector: {}
 ```
-## We need to know if a model build or a model definition can be deleted (link the Figma here):
+## Case #7 We need to know if a model build or a model definition can be deleted (link the Figma here):
 To delete a build oir a model we need to know the state of the model in the system:
 * **Downloaded** (present on the board and available for a brick to be used)
 * **Installed** At least one brick is referencing the model.
@@ -399,7 +400,7 @@ The Installed state can be inferred by checking all application ```App.yaml``` f
 We can provide a list of models, their states, and all the builds on the File System (FS) (if we implement different versions/builds).
 We can allow the deletion of only specific builds or the entire model structure.
 
-## We want to support a different model/executor
+## Case #8 We want to support a different model/executor
 We aim to support a learning model, where the model is defined by a set of weights and generated by a framework like TensorFlow. We intend to deploy and run this model within a web browser using JavaScript (TensorFlow.js).
 
 In this scenario, we can declare the model using its folder structure (API requests can be developed if required) and the necessary YAML files.
@@ -414,7 +415,7 @@ The question here is how to make the model variables available to the container.
 
 2. Environment Variables: Alternatively, we can make the entire model configuration available to the container as environment variables.
 
-# Questions:
+# Questions to be discussed:
 1. Should we keep "audio" as a generic category instead of using something more specific, such as ```ei-audio``` or ```qualcomm-audio```?
 At this level, this has no relevance.
 
@@ -428,12 +429,63 @@ If this becomes technically impossible in the future, we can then add a more spe
 3. Why there is the
 ```require model``` in the brick definition?
 
-4. Check the use case of the Figma where we go to EI and come back with a model
+4. Variable Configuration: Should variables related to a model be placed in the model or in the brick?
 
-# Proposed Changes to Bricks and Models Configuration
-This section details the proposed changes to the current implementation.
+Since different bricks may use different variables to enable the container engine to start the AI engine, it is better to do not declare these variables in the model definition.
 
+When the user provides custom values, the variable definitions will be placed in the App.yaml file. See Use Case #3 App.yaml below, where one brick requires:
+```EI_OBJ_DETECTION_MODEL: /models/yolo_x_nano/builds/yolo-x-nano.eim```
+and the other one requires:
+```QLC_OBJ_DET_ENGINE_MODEL: /models/yolo_x_nano/builds/yolo-x-nano.eim
+SET_CUSTOM_PARAMETER: 5
+```
+**App.yaml definition**
+```
+name: Detect objects on images using two webcam, compare slow and fast engine over the same model
+ports: []
+bricks:
+- arduino:object_detection: {}
+    variables:
+      CUSTOM_MODEL_PATH: /home/arduino/.arduino-bricks/ei-models
+      EI_OBJ_DETECTION_MODEL: /models/yolo_x_nano/builds/yolo-x-nano.eim
+- arduino:fast_object_detection: {}
+    variables:
+      CUSTOM_MODEL_PATH: /home/arduino/.arduino-bricks/ei-models
+      QLC_OBJ_DET_ENGINE_MODEL: /models/yolo_x_nano/builds/yolo-x-nano.eim
+      SET_CUSTOM_PARAMETER: 5
+icon: 🏞️
+```
+
+5. Check the use case of the Figma where we go to EI and come back with a model
+
+# Proposed Changes to Bricks and Models Configuration
 A Model definition contains a list of categories.
 
-A Brick definition containes a list of supported categories supported and a default_mode_name.
- 
+A Brick definition containes a list of supported categories and a default_model_name.
+ 
+ # Variables
+ This is a cross-cutting issue, not strictly related to models, but it's worth spending a moment here because it affects how models and bricks are managed.
+
+In the current implementation, all variables originating from the following sources are collected into a single map:
+- Variables declared in the brick with a default model.
+- Variables defined in the model.
+- Variables defined or overridden by the user in the App.yaml file.
+This map is then passed directly to the ```environment:``` section of the Compose file.
+
+If a variable can be overridden by the user, it must be declared in the brick definition, it is not required or mandatory to declare 
+the other variables that can not be visible/overrided by the user.
+
+*NOTE:* Due to a recent issue where using an empty string as a default value is possible, the proposal is to add the is_required flag to the brick definition file, as follows:
+```
+- name: MY_VARIABLE
+  description: Variable with empty string value as default
+  default: ""
+  required: true
+```
+
+*NOTE:* Another proposal is to add all required brick variables to the brick definition file. The drawback is that the brick file could potentially become large. The advantage is that all variables are visible, which reduces the risk of conflicts when adding new variables to existing projects.
+```
+- name: MY_VARIABLE
+  description: Variable is not user-overridable
+  private: true
+```