From 0f072f1b0cba56ecb6dd47882baf8e82c6bfd860 Mon Sep 17 00:00:00 2001 From: MFA-X-AI Date: Thu, 8 Feb 2024 17:01:05 +0800 Subject: [PATCH] update to 1.9.5 changes --- docs/component-library/installation.md | 4 +- docs/main/Installation.md | 32 +++---- docs/main/developer-guide/_category_.json | 2 +- docs/main/examples/_category_.json | 4 +- docs/main/examples/computer-vision/keras.md | 8 +- docs/main/examples/computer-vision/pytorch.md | 7 +- docs/main/index.md | 2 +- docs/main/technical-concepts/_category_.json | 2 +- docs/main/tutorials/_category_.json | 2 +- .../tutorials/running-a-xircuits-workflow.md | 92 ++++++++++++------- docs/main/xircuits-interface/_category_.json | 2 +- docs/main/xircuits-interface/cli-commands.md | 9 +- docusaurus.config.js | 4 +- yarn.lock | 8 +- 14 files changed, 100 insertions(+), 78 deletions(-) diff --git a/docs/component-library/installation.md b/docs/component-library/installation.md index e56d23f..d402fee 100644 --- a/docs/component-library/installation.md +++ b/docs/component-library/installation.md @@ -6,10 +6,10 @@ sidebar_position: 2 To get started with the Xircuits Component Libraries, you need to complete two main steps: fetching the libraries and installing them. There are two ways to accomplish this, either using the Xircuits CLI command for a quick installation or manually cloning the libraries and installing the requirements. Let's explore both methods in detail. ## Quick Installation using Xircuits CLI -The quickest and most convenient way to fetch and install the Xircuits Component Libraries is by using the provided Xircuits CLI command. If a library is included as a submodule in the main Xircuits repository, you can install it by running the following command in your terminal: +The quickest and most convenient way to fetch and install the Xircuits Component Libraries is by using the provided Xircuits CLI command. If a library is included in the [component library list](https://github.com/XpressAI/xircuits/tree/master/xai_components#external-library), you can install it by running the following command in your terminal: ``` -xircuits-submodules component-lib-name +xircuits install component-lib-name ``` Replace component-lib-name with the name of the component library you want to install. This command will fetch the library and install it for you, allowing you to start using the components right away. Repeat this process for each library you want to include in your project. diff --git a/docs/main/Installation.md b/docs/main/Installation.md index 60faab4..317d0ed 100644 --- a/docs/main/Installation.md +++ b/docs/main/Installation.md @@ -5,15 +5,13 @@ sidebar_position: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - - # Installation You will need Python 3.8+ to install Xircuits. :::tip We recommend installing in a virtual environment such as Python [venv](https://docs.python.org/3/library/venv.html). - + ```bash @@ -34,15 +32,15 @@ source venv/bin/activate ::: -To install Xircuits run: +To install Xircuits, run: -``` +```bash pip install xircuits ``` ## Canary Installation -If you'd like the latest goodies (but might be unstable features) of Xircuits, you may grab the wheel from our Github Actions. Select the Python Package Builder run from a master branch, and download the wheel artifact. +If you're interested in the cutting-edge features of Xircuits (which might include unstable features), you can get the latest version directly from our Github Actions. Look for a Python Package Builder run on the master branch, and download the wheel artifact.
Video @@ -50,28 +48,30 @@ If you'd like the latest goodies (but might be unstable features) of Xircuits, y

-After downloading the artifact, extract the wheel to your working directory then install it using +After downloading, extract the wheel to your working directory and install it with: -``` +```bash pip install xircuits-version-py3.none-any.whl ``` - ## Installing Xircuits Component Libraries -While Xircuits have preinstalled component libraries, you may want to use one of our many component libraries. Installing them is simple, simply run `xircuits install libraryName`. For example, to be able to use the Pytorch components from the [Pytorch component library](https://github.com/XpressAI/xai-pytorch): +Xircuits is designed to be extensible, featuring a variety of component libraries to enhance its functionality. While it comes with a set of pre-installed components, you might find yourself in need of more specialized functionalities that are offered by external component libraries. -``` +Installing these libraries is straightforward. For example, to use the Pytorch components from our [Pytorch component library](https://github.com/XpressAI/xai-pytorch), simply run: + +```bash xircuits install pytorch ``` -For the full list of supported libraries, you can visit the [component libraries page](https://github.com/XpressAI/xircuits/blob/master/xai_components/readme.md). - +To explore and install other component libraries, check out the full list on the [component libraries page](https://github.com/XpressAI/xircuits/blob/master/xai_components#external-library). ## Launch -Finally to launch it, run: -``` +To start using Xircuits, execute: + +```bash xircuits ``` -You will be prompted to load the `xai_components` in the current path. We recommend doing so to be able to edit them. + +Upon launch, `xai_components` will be loaded in your current working directory. \ No newline at end of file diff --git a/docs/main/developer-guide/_category_.json b/docs/main/developer-guide/_category_.json index 8ccc1eb..c44f181 100644 --- a/docs/main/developer-guide/_category_.json +++ b/docs/main/developer-guide/_category_.json @@ -1,6 +1,6 @@ { "label": "Developer Guide", - "position": 7, + "position": 8, "link": { "type": "generated-index", "description": "Are you a developer? Here are a few guides to help you create things in Xircuits." diff --git a/docs/main/examples/_category_.json b/docs/main/examples/_category_.json index 86906c9..1469f0d 100644 --- a/docs/main/examples/_category_.json +++ b/docs/main/examples/_category_.json @@ -1,6 +1,6 @@ { - "label": "Examples", - "position": 6, + "label": "Use Case Examples", + "position": 5, "link": { "type": "generated-index", "description": "Workflow examples for different use cases from our developers." diff --git a/docs/main/examples/computer-vision/keras.md b/docs/main/examples/computer-vision/keras.md index 003ffdc..93537ea 100644 --- a/docs/main/examples/computer-vision/keras.md +++ b/docs/main/examples/computer-vision/keras.md @@ -5,13 +5,13 @@ description: "Learn how to make a Xircuits workflow to load prebuilt Keras model # Keras -Before running this example, ensure that you have already installed the Keras related packages. You can do this by: +Before running this example, ensure that you have already installed the Tensorflow Keras component library. You can do this by: -``` -pip install xircuits[tensorflow_keras] +```bash +xircuits install tensorflow_keras ``` -or alternatively use the `requirements.txt` in the `xai_components/xai_tensorflow_keras` directory. +or alternatively after cloning the [library repository](https://github.com/XpressAI/xai-tensorflow-keras) use the `requirements.txt` in the `xai_components/xai_tensorflow_keras` directory. ## Loading a Keras Model and Performing Inference diff --git a/docs/main/examples/computer-vision/pytorch.md b/docs/main/examples/computer-vision/pytorch.md index 44e5be1..a2a5869 100644 --- a/docs/main/examples/computer-vision/pytorch.md +++ b/docs/main/examples/computer-vision/pytorch.md @@ -5,11 +5,12 @@ description: Learn how to make a Xircuits workflow to train a mnist model in Pyt # Pytorch -Before running this example, ensure that you have already installed the torch packages. You can do this by: +Before running this example, ensure that you have already installed the Pytorch component library. You can do this by: +```bash +xircuits install pytorch ``` -pip install xircuits[pytorch] -``` + ## Training a Torch ML Model The following example showcases how to load a Torch dataset, specify a Torch model, train and evaluate, then save the state in Xircuits. diff --git a/docs/main/index.md b/docs/main/index.md index eff0383..ec26af8 100644 --- a/docs/main/index.md +++ b/docs/main/index.md @@ -19,7 +19,7 @@ Are you new to Xircuits? Here's some quick links to start! Here's high-level overview of how the documentation is organized will help you know where to look for certain things: - [**Tutorials**](../category/tutorials) take you by the hand and get you started on your first Xircuits workflows. Start here if you’re new to Xircuits. -- [**Examples**](../category/examples) guide you through the steps involved in possible Xircuits use-cases. They are more advanced than tutorials and assume some foundation knowledge of how that particular use-case works and instead focus on how it can be implemented in Xircuits. +- [**Examples**](../category/use-case-examples) guide you through the steps involved in possible Xircuits use-cases. They are more advanced than tutorials and assume some foundation knowledge of how that particular use-case works and instead focus on how it can be implemented in Xircuits. - [**Developer Guide**](../category/developer-guide) are guides so that you can create components and workflows for Xircuits users. - [**Technical Concepts**](../category/technical-concepts) discuss key topics and concepts at a fairly high level and provide useful background information and explanation. - [**The Xircuits Interface**](xircuits-interface) contains references for Xircuits’ machinery. diff --git a/docs/main/technical-concepts/_category_.json b/docs/main/technical-concepts/_category_.json index 6818330..3ce032c 100644 --- a/docs/main/technical-concepts/_category_.json +++ b/docs/main/technical-concepts/_category_.json @@ -1,6 +1,6 @@ { "label": "Technical Concepts", - "position": 8, + "position": 7, "link": { "type": "generated-index", "description": "Here are discussions on topics and concepts at a fairly high level and provide useful background information and explanation." diff --git a/docs/main/tutorials/_category_.json b/docs/main/tutorials/_category_.json index ed6db2e..db350e8 100644 --- a/docs/main/tutorials/_category_.json +++ b/docs/main/tutorials/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorials", - "position": 5, + "position": 4, "link": { "type": "generated-index", "description": "Tutorials to guide you for your first Xircuits steps." diff --git a/docs/main/tutorials/running-a-xircuits-workflow.md b/docs/main/tutorials/running-a-xircuits-workflow.md index 953c772..2832aad 100644 --- a/docs/main/tutorials/running-a-xircuits-workflow.md +++ b/docs/main/tutorials/running-a-xircuits-workflow.md @@ -2,34 +2,53 @@ sidebar_position: 1 --- -# Your First Xircuits Workflow +# Running a Xircuits Workflow -The following tutorial will walk you through a basic Xircuits run. You will open an existing Xircuits workflow that trains a model, learn how to modify the parameters for your use case, and then run it. +This quick start tutorial will guide you through common steps when running a Xircuits workflow, which includes installing a component library, opening an existing workflow example, modifying its parameters to fit your needs, and executing the workflow. -## Prerequisites -For this tutorial, ensure that: -1. You have a Python version that is compatible with Xircuits (Python 3.8+). -2. You already have the `xai_learning` related libraries installed. You can do this by `pip install xircuits[learning]` or by `pip install -r xai_components/xai_learning/requirements.txt`. -3. Ensure that you have the `examples` folder in your working directory. After Xircuits is installed, you can download it by running `xircuits-examples` in the command line. +Before starting, ensure that: +1. Your Python version is compatible (Python 3.8+ is required). +2. You have already installed Xircuits. -## Opening an existing Xircuits File -New Xircuits users are recommended to start with premade Xircuits workflows created by developers. The task would be to change the parameters for their use case. In Xircuits, we have created a handful of workflows for you to try in the `examples` directory. +If you're interested in just running basic examples, we'd recommend trying out the workflows in the `examples` directory which covers core topics and does not require additional installations. -**For this tutorial, open `KerasTrainImageClassifier.xircuits` in the example directory.** +## Installing Component Libraries + +Often when working with advanced workflows, installing their component libraries is necessary. You have two main options: + +- Clone the component library repository and install its requirements. +- Use the `xircuits install` command for a straightforward installation: + + ``` + xircuits install tensorflow_keras + ``` + +This command lets you seamlessly integrate additional TensorFlow Keras components into Xircuits. + +:::note +The `xircuits install` command works with supported submodules listed in the [library list](https://github.com/XpressAI/xircuits/tree/master/xai_components#external-library). You can also provide it a Github URL. +::: + +## Opening an Existing Xircuits File + +For those new to Xircuits, exploring pre-made workflows is an excellent way to start. Each component library, including `xai_tensorflow_keras`, should come with its own set of example workflows located in its `examples` directory. These workflow examples are tailored to demonstrate the capabilities of the specific library and help users familiarize themselves with its components. + +**For this tutorial, navigate to the `xai_components/xai_tensorflow_keras/examples/` directory and open a `.xircuits` file of your choice.** + +Alternatively, once you've installed a component library, you can access these examples directly within Xircuits. Simply right-click on the library in the component tray and select 'Show Examples' from the context menu to explore available workflows. -## Viewing and Interpreting the Xircuits Canvas -Once the Xircuits canvas is open, you will see the [Xircuits Interface](../xircuits-interface). +## Viewing and Interpreting the Xircuits Canvas -A Xircuits workflow starts from the `Start` node to the `Finish` node. The flow sequence is indicated by the flowing blue links connecting the ▶ ports. A component node may also have data ports, which indicates how a component can receive data and parameters to configure their behavior, as well as pass data to the next nodes. +Upon opening a Xircuits canvas, you will see the [Xircuits Interface](../xircuits-interface). The workflow progresses from the `Start` node to the `Finish` node, with the sequence indicated by blue links connecting the nodes. Nodes may also have parameter ports for input and output, allowing you to pass data. -If you are unsure what a component does, you can click on the component information tooltip to display component information. For Python savvy users, you may open the component code via context menu (`right-click` > `Open Script`). +If you need more information about what a component does, click on its tooltip. For those comfortable with Python, the component code can be accessed and edited via the context menu (right-click > Open Script). -**Explore the KerasTrainImageClassifier workflow. Note the component sequence.** +**Explore the components and their sequence in the KerasTrainImageClassifier workflow.** ## Modifying the Xircuits Workflow -As previously mentioned, a Xircuits User will usually work on a premade workflow and adjust the parameter components for their use case. To modify `Literal Components` such as `Literal Int` or `Literal String`, simply double click on the component, and you will be prompted to change the value. +Typically, you'll begin with a provided workflow and adjust its parameters. To change `Literal Components` like `Literal Int` or `Literal String`, double-click on the component to edit its value.
Video @@ -37,21 +56,21 @@ As previously mentioned, a Xircuits User will usually work on a premade workflow

-For more advanced users, you may add more component nodes from the Xircuits component tray, or by dropping a link from a port. +You can also add more components from the component tray or by dragging a link from an existing port. -**Refer to the TrainImageClassifier component. Modify the number of training_epochs to 3.** +**Try changing the `training_epochs` parameter in the TrainImageClassifier component to 3.** ## Saving and Compiling a Xircuits Canvas Workflow -Once you are satisfied with your workflow, you can save and compile the Xircuits workflow. A Python script with the same filename as the .xircuits canvas will be generated. +After modifying your workflow, save and compile it. This action generates a Python script with the same name as your .xircuits file. -**Press Save then Compile, then verify that the Python script has been generated.** +**Click 'Save' followed by 'Compile', and verify that the Python script has been created.** ## Running the Workflow -To run the workflow, press the `Save & Compile` button. It will prompt you to save the workflow if you haven't. Select the Python kernel to run it. +To run the workflow, press the `Save & Compile` button. If unsaved changes exist, you'll be prompted to save. Choose the Python kernel to execute the workflow. -**Press Save then Compile button. You should get the following output:** +**After saving and compiling, the following output should appear:**
@@ -66,7 +85,6 @@ To run the workflow, press the `Save & Compile` button. It will prompt you to sa Xircuits is running... - Executing: ReadDataSet Executing: TrainTestSplit @@ -94,31 +112,35 @@ To run the workflow, press the `Save & Compile` button. It will prompt you to sa


-:::info +Congratulations on successfully running your first Xircuits workflow! This foundational knowledge will enable you to explore other example workflows created by our engineers and the open-source community. Check out the [Examples](docs/category/use-case-examples/) section for more. -You can also execute the compiled script directly from the command line. To achieve this, first, add the base directory to the Python path by running the following command: -``` + +### Additional Notes + +You can also run the compiled script directly from the command line by adding your working directory to the Python path: + +```bash export PYTHONPATH="$PWD:$PYTHONPATH" ``` -Afterward, proceed to run the Python script using the following command: -``` + +Then execute the script with: + +```bash python KerasTrainImageClassifier.py ``` -This ensures that the Python interpreter recognizes the modules in the base directory when executing the script. -::: -Congratulations you have successfully ran your first Xircuits workflow! From here, you should be able to run any Xircuits workflow examples. Jump to the [Examples](docs/category/examples/) section if you want to see the various workflows made by our engineers and open source contributors. +This ensures the Python interpreter recognizes the modules in your base directory. +### Commonly Faced Errors -### Commonly Faced Errors:
ModuleNotFoundError - You have not installed the needed libraries for that specific component library! For this tutorial, ensure that you have run the prerequisites. + This indicates that the required libraries for the component library in use are missing. Ensure all prerequisites are met before starting. Please connect all the nodes before running. - The Xircuits workflow is not complete! Please ensure the blue links from the `Start` node to the `Finish` node is completely connected. -


\ No newline at end of file + A complete Xircuits workflow is essential for a successful run. Make sure all nodes are connected from `Start` to `Finish`. +

diff --git a/docs/main/xircuits-interface/_category_.json b/docs/main/xircuits-interface/_category_.json index 0c949e0..1f79ec6 100644 --- a/docs/main/xircuits-interface/_category_.json +++ b/docs/main/xircuits-interface/_category_.json @@ -1,3 +1,3 @@ { - "position": 3 + "position": 6 } diff --git a/docs/main/xircuits-interface/cli-commands.md b/docs/main/xircuits-interface/cli-commands.md index 67483e0..853d5b5 100644 --- a/docs/main/xircuits-interface/cli-commands.md +++ b/docs/main/xircuits-interface/cli-commands.md @@ -33,7 +33,7 @@ or ```bash xircuits start ``` -- Starts Xircuits, typically launching JupyterLab and initializing the `.xircuits` config file in the current directory. It also offers to load the `xai_components` into the current working directory. +- Starts Xircuits, typically launching JupyterLab and initializing the `.xircuits` config file in the current directory. It also loads the `xai_components` into the current working directory. - You can append any JupyterLab-specific launch commands, for example: ```bash xircuits start --no-browser @@ -47,7 +47,7 @@ xircuits install ``` - Fetches and uses `pip` to install a component library for Xircuits based on its `requirements.txt`. - The component library will be saved at `./xai_components/`. -- You can provide a component library name from the [component library list](https://github.com/XpressAI/xircuits/tree/master/xai_components) or a GitHub repository URL. +- You can provide a component library name from the supported [component library list](https://github.com/XpressAI/xircuits/tree/master/xai_components) or a GitHub repository URL. --- @@ -57,7 +57,7 @@ xircuits fetch-only ``` - Fetches but does not install a component library for Xircuits. - The component library will be saved at `./xai_components/`. -- You can provide a component library name from the [component library list](https://github.com/XpressAI/xircuits/tree/master/xai_components) or a GitHub repository URL. +- You can provide a component library name from the supported [component library list](https://github.com/XpressAI/xircuits/tree/master/xai_components) or a GitHub repository URL. - If the directory already exists, it will return an error. --- @@ -66,7 +66,7 @@ xircuits fetch-only ```bash xircuits examples ``` -- Downloads the `examples` and `datasets` directories from the main branch of the Xircuits repository to your current directory. +- Loads the `examples` directory from the Xircuits wheel to your current directory. --- @@ -87,5 +87,4 @@ xircuits list --- - Each command also supports the `-h` option for help, which provides additional information and usage examples for the command. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 0e92418..f0e04d1 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -106,8 +106,8 @@ const config = { to: 'docs/category/developer-guide', }, { - label: 'Examples', - to: 'docs/category/examples', + label: 'Use Case Examples', + to: 'docs/category/use-case-examples', }, ], }, diff --git a/yarn.lock b/yarn.lock index 31184a6..98c5b93 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2580,10 +2580,10 @@ "@webassemblyjs/ast" "1.11.6" "@xtuc/long" "4.2.2" -"@xpressai/docusaurus-vecto-search@^0.0.4": - version "0.0.4" - resolved "https://registry.yarnpkg.com/@xpressai/docusaurus-vecto-search/-/docusaurus-vecto-search-0.0.4.tgz#7437117615fd2519f9beacc6c32a0e87651ecb53" - integrity sha512-pD8I6gEfscZs/eIYKCZzAmUziZNhHbQo/OeF4mEliLVAhIyKGSJPOED4UY6IndFTXrOQOIezTDVP50AydZWLFA== +"@xpressai/docusaurus-vecto-search@^0.0.5": + version "0.0.5" + resolved "https://registry.yarnpkg.com/@xpressai/docusaurus-vecto-search/-/docusaurus-vecto-search-0.0.5.tgz#b74ac944211ab8b212639c149fdd32f09c5edf1d" + integrity sha512-Ghzct4YCiMcZfz87XI/S7ZovX9LsuOfeydIASbiK69rfXQFUqureoL4JEewWenJhXu9wFkkOL6T/R6Yo0CtarQ== dependencies: "@docusaurus/plugin-content-docs" "^2.0.0-rc.1" "@docusaurus/theme-translations" "^2.0.0-rc.1"