docs: add packaging guide

Fixes #123

Signed-off-by: Jeff MAURY <[email protected]>

PACKAGING-GUIDE.md

@@ -0,0 +1,101 @@
+# Packaging guide
+
+## Catalog
+
+AI Studio uses an internal catalog that is embedded into AI Studio. This catalog is loaded
+by AI Studio and displayed when you access the catalog page.
+
+The format of the catalog is JSON. It is possible for users to have a custom version of
+the catalog. In order to do so, copy the file located at https://github.com/projectatomic/ai-studio/blob/main/packages/backend/src/ai.json
+to $HOME/podman-desktop/ai-studio/catalog.json and AI Studio will use it instead of the embedded one.
+Any change done to this file will also be automatically be loaded by AI Studio.
+
+### Format of the catalog file
+
+The catalog file has three main elements: categories, models and recipes. Each of these elements is
+represented in the JSON file as an array.
+
+#### Categories
+
+This is the top level construct of the catalog UI. Recipes are grouped into categories. A category
+represents the kind of AI application. Although the list of categories provided by default by
+AI Studio represents the AI landscape, it is possible to add new categories.
+
+A category has three main attributes: an id (which should be unique among categories), a description
+and a name. The category id attribute will then be used to attach a recipe to one or several categories.
+
+#### Models
+
+The catalog also list the models that may be associated to recipes. A model is also a first class
+citizen in AI Studio as they will be listed in the Models page and can be tested through the playground.
+
+A model has the following attributes:
+- ```id```: a unique identifier for the model
+- ```name```: the model name
+- ```description```: a detailed description about the model
+- ```hw```: the hardware where the model is compatible. Possible values are CPU and GPU
+- ```registry```: the model registry where the model is stored
+- ```popularity```: an integer field giving the rating of the model. Can be thought as the number of stars
+- ```license```: the license under which the model is available
+- ```url```: the URL used to download the model
+
+#### Recipes
+
+A recipe is a sample AI application that is packaged as one or several containers. It is build by
+AI Studio when the user chooses to download it on his workstation and run it. It is provided as
+source code and AI Studio will make sure the container images are built prior to laucnhing the containers.
+
+A recipe has the following attributes:
+- ```id```: a unique identifier to the recipe
+- ```name```: the recipe name
+- ```description```: a detailed description about the recipe
+- ```repository```: the URL where the recipe code can be retrieved
+- ```categories```: an array of category id to be associated by this recipe
+- ```config```: an optional path of the configuration file within the repository. If not provided, the file is assumed to be located at the root the repository and called ai-studio.yaml
+- ```readme```: a markdown description of the recipe
+- ```models```: an array of model id to be associated with this recipe
+
+#### Recipe configuration file
+
+The configuration file is called ```ai-studio.yaml``` and follows the following syntax.
+
+The root element is called ```application```. This element contains an attribute called ```containers```
+whose syntax is an array of objects containing the following attribute:
+- ```name```: the name of the container
+- ```contextdir```: the context directory used to build the container.
+- ```containerfile```: the containerfile used to build the image
+- ```model-service```: a boolean flag used to indicate if the container is running the model or not
+- ```arch```: an optional array of architecture for which this image is compatible with. The values follows the
+[GOARCH specification](https://go.dev/src/go/build/syslist.go)
+- ```gpu-env```: an optional array of GPU environment for which this image is compatible with. The only accepted value here is cuda.
+
+The container that is running the service (having the ```model-service``` flag equal to ```true```) can use at runtime
+the model managed by AI Studio through an environment variable ```MODEL_PATH``` whose value is the full path name of the
+model file
+
+Below is given an example of such a configuration file:
+```yaml
+application:
+  containers:
+    - name: chatbot-inference-app
+      contextdir: ai_applications
+      containerfile: builds/Containerfile
+    - name: chatbot-model-service
+      contextdir: model_services
+      containerfile: base/Containerfile
+      model-service: true
+      arch:
+        - arm64
+        - amd64
+    - name: chatbot-model-servicecuda
+      contextdir: model_services
+      containerfile: cuda/Containerfile
+      model-service: true 
+      gpu-env:
+        - cuda
+      arch: 
+        - amd64
+```
+
+
+

README.md

@@ -28,6 +28,10 @@ Each recipe can belong to one or several categories. Each model can be used by o
 
 The format of the catalog is not stable nor versioned yet, you can see the current catalog's format [in the sources of the extension](https://github.com/projectatomic/studio-extension/blob/main/packages/backend/src/ai.json).
 
+## Packaging sample applications
+
+Sample applications may be added to the catalog. See [packaging guide](PACKAGING-GUIDE.md) for detailed information.
+
 ## Feedback
 
 You can provide your feedback on the extension with [this form](https://forms.gle/tctQ4RtZSiMyQr3R8) or create [an issue on this repository](https://github.com/projectatomic/studio-extension/issues).