fix: improve README.md (#673)

* fix: improve README.md Fixes #480 Signed-off-by: Jeff MAURY <jmaury@redhat.com> * fix: apply suggestions from @vrothberg code review Co-authored-by: Valentin Rothberg <vrothberg@redhat.com> Signed-off-by: Jeff MAURY <jmaury@redhat.com> * fix: reword the memory and CPU requiments paragraph Signed-off-by: Jeff MAURY <jmaury@redhat.com> * fix: reword model format sentence Signed-off-by: Jeff MAURY <jmaury@redhat.com> * fix: add animations Signed-off-by: Jeff MAURY <jmaury@redhat.com> --------- Signed-off-by: Jeff MAURY <jmaury@redhat.com> Co-authored-by: Valentin Rothberg <vrothberg@redhat.com>
containers · Mar 26, 2024 · 8709faf · 8709faf
1 parent 2409db5
commit 8709faf
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,69 @@
 
 The Podman Desktop AI Studio extension simplifies getting started and developing with AI in a local environment.  It provides key open-source technologies to start building on AI.  A curated catalog of so-called recipes helps navigate the jungle of AI use cases and AI models.  AI Studio further ships playgrounds: environments to experiment with and test AI models, for instance, a chat bot.
 
+
+
+## Topics
+- [Technology](#technology)
+- [Extension features](#extension-features)
+- [Requirements](#requiremements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [Feedback](#feedback)
+
+
+
+## Technology
+
+The AI Studio extensions uses [Podman](https://podman.io) machines to run inference servers for LLM models and AI applications.
+The AI models can be downloaded, and common formats like [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md), [Pytorch](https://pytorch.org) or [Tensorflow](https://www.tensorflow.org) are supported.
+
+## Extension features
+
+### AI Models
+
+AI Studio provides a curated list of open source AI models and LLMs. Once downloaded, the models are available to be used for AI applications, model services and playgrounds.
+
+#### Model services
+
+Once a model is downloaded, a model service can be started. A model service is an inference server that is running in a container and exposing the model through the well-known chat API common to many providers.
+
+#### Playgrounds
+
+The integrated Playground environments allow for experimenting with available models in a local environment. An intuitive user prompt helps in exploring the capabilities and accuracy of various models and aids in finding the best model for the use case at hand. The Playground interface further allows for parameterizing models to further optimize the settings and attributes of each model.
+
+### AI applications
+
+Once an AI model is available through a well known endpoint, it's easy to imagine a new world of applications that will connect and use the AI model. AI Studio support AI applications as a set of containers that are connected together. 
+
+AI Studio ships with a so-called Recipes Catalog that helps you navigate a number of core AI use cases and problem domains such as Chat Bots, Code Generators and Text Summarizers. Each recipe comes with detailed explanations and sample applications that can be run with various large language models (LLMs). Experimenting with multiple models allows finding the optimal one for your use case.
+
+## Requirements
+
+Disclaimer: This is **EXPERIMENTAL** and all features are subject to change as we develop the extension.
+
+### Requirement 1. Software and hardware requirements
+
+**OS:**
+
+Compatible on Windows, macOS & Linux
+
+**Software:**
+
+- [Podman Desktop 1.8.0+](https://github.com/containers/podman-desktop)
+- [Podman 4.9.0+](https://github.com/containers/podman)
+
+**Hardware**
+
+LLMs AI models are heavy resource consumers both in terms of memory and CPU. Each of the provided models consumes about 4GiB of memory and requires at least 4 CPUs to run.
+
+So we recommend that a minimum of 12GB of memory and at least 4 CPUs for the Podman machine.
+
+As an additional recommended practice, do nor run more than 3 simultaneous models concurrently.
+
+Please note that this is not relevant for WSL on Windows as the WSL technology the memory and CPU with the host desktop. 
+
 ## Installation
 
 To install the extension, go to the Podman Desktop UI > ⚙ Settings > Extensions > Install a new extension from OCI Image.
@@ -12,27 +75,51 @@ To install a development version, use the `:nightly` tag as shown in the recordi
 
 ![](https://github.com/containers/podman-desktop-media/raw/ai-lab/gifs/installation.gif)
 
-## Running in development mode
+## Usage
 
-From the AI Studio packages/frontend folder:
+1. **Download a model**
 
-```
-$ yarn watch
-```
+Let's select a model from the catalog and download it locally to our workstation.
 
-If you are not live editing the frontend package, you can just run (from the AI Studio sources folder):
+[![](/docs/img/download-model.gif)](https://github.com/containers/podman-desktop-media/raw/ai-lab/videos/download-model.mp4)
 
-```
-$ yarn build
+2. **Start an inference server**
+
+Once a model is available locally, let's start an inference server
+
+[![](/docs/img/start-inference-server.gif)](https://github.com/containers/podman-desktop-media/raw/ai-lab/videos/start-inference-server.mp4)
+
+3. **Start a playground to have a chat conversation with model**
+
+[![](/docs/img/playground.gif)](https://github.com/containers/podman-desktop-media/raw/ai-lab/videos/playground.mp4)
+
+4. **Start a AI application and use it from the browser**
+
+[![](/docs/img/start-ai-app.gif)](https://github.com/containers/podman-desktop-media/raw/ai-lab/videos/start-ai-app.mp4)
+
+## Contributing
+
+Want to help develop and contribute to the AI Studio extension?
+
+You can use `yarn watch --extension-folder` from the Podman Desktop directory to automatically rebuild and test the AI Studio extension:
+
+```sh
+git clone https://github.com/containers/podman-desktop
+git clone https://github.com/projectatomic/ai-studio
+cd ai-studio
+yarn install
+yarn build
+cd ../podman-desktop
+yarn watch --extension-folder ../ai-studio/packages/backend
 ```
 
-From the Podman Desktop sources folder:
+If you are live editing the frontend package, from packages/frontend folder:
 
 ```
-$ yarn watch --extension-folder path-to-extension-sources-folder/packages/backend
+$ yarn watch
 ```
 
-## Cleaning up resources 
+### Cleaning up resources 
 
 We'll be adding a way in AI Lab to let a user cleanup the environment: see issue https://github.com/projectatomic/ai-studio/issues/469.
 For the time being, please consider the following actions:
@@ -42,17 +129,17 @@ For the time being, please consider the following actions:
 4. Remove the containers related to AI
 5. Cleanup your local clone of the recipes: `$HOME/podman-desktop/ai-studio`
 
-## Providing a custom catalog
+### Providing a custom catalog
 
 The extension provides a default catalog, but you can build your own catalog by creating a file `$HOME/podman-desktop/ai-studio/catalog.json`.
- 
+
 The catalog provides lists of categories, recipes, and models.
 
 Each recipe can belong to one or several categories. Each model can be used by one or several recipes.
 
 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
+### Packaging sample applications
 
 Sample applications may be added to the catalog. See [packaging guide](PACKAGING-GUIDE.md) for detailed information.
 

diff --git a/docs/img/download-model.gif b/docs/img/download-model.gif
diff --git a/docs/img/playground.gif b/docs/img/playground.gif
diff --git a/docs/img/start-ai-app.gif b/docs/img/start-ai-app.gif
diff --git a/docs/img/start-inference-server.gif b/docs/img/start-inference-server.gif