docs: add packaging guide (#185)

* docs: add packaging guide Fixes #123 Signed-off-by: Jeff MAURY <[email protected]> * fix: typo Co-authored-by: Luca Stocchi <[email protected]> * fix: wording Co-authored-by: Luca Stocchi <[email protected]> * fix: typo Co-authored-by: Luca Stocchi <[email protected]> * fix: typo Co-authored-by: Luca Stocchi <[email protected]> * fix: apply suggestions from @feloy code review Co-authored-by: Philippe Martin <[email protected]> --------- Signed-off-by: Jeff MAURY <[email protected]> Co-authored-by: Luca Stocchi <[email protected]> Co-authored-by: Philippe Martin <[email protected]>
containers · Feb 8, 2024 · 495fd51 · 495fd51
1 parent 613bd00
commit 495fd51
Show file tree

Hide file tree

Showing 2 changed files with 104 additions and 0 deletions.
diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md
@@ -0,0 +1,100 @@
+# Packaging guide
+
+## Catalog
+
+AI Studio uses an internal catalog embedded within the application. 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 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 lists 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 built by AI Studio when the user chooses to download and run it on their workstation. It is provided as
+source code and AI Studio will make sure the container images are built prior to launching 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 attributes:
+- ```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 follow 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
+```
+
+
+
diff --git a/README.md b/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).