Cortex Fabric Developer Extension

The Fabric Developer Extension is a plugin for VS Code that is used with CognitiveScale's Cortex Fabric Enterprise Platform. It provides Fabric specific support for creating, developing, publishing, invoking, and debugging resources, especially Skills.

The Fabric Developer Extension utilizes and shares a configuration file with the Fabric Console and CLI. Work done in the Extension, CLI, and/or Console is shared by all of the Cortex Fabric interfaces.

NOTE: You must set a folder context in VS Code before you begin working with the Fabric Developer Extension.

Features

The Cortex VS Code Extension allows users to:

• Use the VS Code interface to navigate, create, and modify resources within a Fabric instance.
• Bootstrap Skill development using Skill templates.
• Run and debug Skills locally on your system without publishing to your enterprise instance.

Configuration

Authentication

When you authenticate to the Fabric Developer Extension your instances are automatically added to the Extension.

Fabric authentication for the Fabric Developer Extension is implemented using the "Personal Access Token" (PAT) that is provided in the Fabric Console.

After you have downloaded the PAT file, use it to authenticate to the Fabric Developer Extension:

1. In the Fabric Developer Extension, activate the Fabric Activity panel by clicking the Cortex logo in the VS Code Activity bar.
2. Click the plus icon in the Configuration panel, and select the PAT file you downloaded from the Fabric Console.
3. When prompted, enter a name for your Cortex Fabric instance.
4. When prompted, select a Project context. You can change the active Project at any time.

The Configuration Panel

The Configuration panel serves as the main configuration point for your interaction with the Fabric Developer Extension. In the Configuration panel you select:

• The URL of the Fabric instance you want to activate
• The registry to publish Skills and other resources to
• The Project context

This panel also displays the Fabric version running in the currently active instance, and it shows the current statuses of all of the running services.

Active Instance

The Fabric Developer Extension supports having multiple instances configured with different PAT's at the same time. The extension can only show the state of one instance at a time, and the "Active Instance" line shows which instance is currently active.

To change the instance:

1. Click the gear icon to open a list of configured instances.
2. Select an instance from the list.

Image Repositories

Fabric pulls container images from a repository. Skill images are stored in those containers. By default, most Fabric instances are configured with an internal image repository where Skill images are stored.

If your instance stores images in an external repository, the Fabric Developer Extension must be configured with the location of that repository, so your Skill images may be published there.

1. Click the plus icon next to the "Active Registry" line in the Instances panel.
2. Enter a descriptive name for the registry.
3. Provide the registry's URL.
4. Provide the namespace from the instance where the URL is configured.

The URL and namespace work together to identify the registry that images are published to.

For example, if your instance was configured to pull images from a registry on DockerHub, the URL would be from docker.io and the namespace would be your DockerHub username.

Active Project

To change the active Fabric Project:

1. Click the gear icon next to the "Active Project" line in the Instances panel to display a list of Projects that you have access to.
2. Select a Project from the list.

NOTE: You can filter the Project list by typing in the filter box at the top of the list.

Workspace Folder Layout

Skills (and other Cortex resources) are generated inside your VSCode workspace using a specific file/folder layout and naming convention. This folder layout is how the Cortex-Code extension is able to identify and automatically handle certain resource operations for you.

The layout defines several top-level folders that are containers for specific kinds of Cortex resources. Note that not all Skills will use or require all of these folders.

• docs
• experiments
• models
• skills
• types
• agents
• content

Each top-level folder contains sub-folders named for each Skill in the workspace. For example, if two Skills have been saved and are named skill1 and skill2, both of which define some Cortex types, then the types folder would contain two subfolders, named skill1 and skill2.

All of the Fabric top-level resources are arranged this way, with Skill names as subfolders.

The Skills Panel

The Skills panel shows the current state of the Skills in your active Project and instance. When a local Skill is "published" to a Fabric instance, it appears in the Skills panel.

At the top of the Skills panel is a toolbar exposing several functions available to you:

Use View filters

Because many Skills may be published in an instance, the extension provides "View Filters" that allow you to show or hide Skills based on selected attributes. These attributes include:

• "Shared" Skills: Skill that are available across projects
• "Deployed" Skills: Skills that are in a deployed state, ready to be invoked
• "Undeployed" Skills: Skills that are in an undeployed state

Create Skills

In order to easily create a sample Skill or to bootstrap a new Skill project:

1. Click the plus icon on the Skills panel.
2. Select a Skill template from the list.
3. Enter a name for the Skill you are building.
4. The Extension generates the base-files for the Skill.

The templates provide you with a fully functional Skill that can be built and deployed into your Fabric instance as is.

To generate custom Skills edit the template files, then build and deploy the Skills.

Delete Skills

To delete Skills that are saved to your workspace:

1. Click the Delete Skills button in the Skills panel.
2. Check the Skills to delete.
3. Select whether you want the Skills to be deleted from your local system only, or from your local system AND the Fabric instance.

Build Skill Images

After you have configured the Skill files and before you deploy a Skill to the Fabric instance, you must build it into a Docker image. Building the image does NOT deploy the Skill to the instance.

To build a Skill image:

1. Click the Build Skills button in the Skills panel.
2. Check the Skills you want to build.

OR

1. Right-click on the skill.yaml file in the file explorer.
2. Select Build Skill from the menu.

The extension displays the progress of the build in the status bar at the bottom of the VSCode window.

Publish Skills

After building the Skill image, it must published or deployed to the Fabric instance to make it available to be invoked/run.

After you build the image, it must be pushed to the registry, and the Skill definition must be uploaded to the Fabric instance in order to actually run the Skill in the Kubernetes cluster.

To publish Skills:

1. Click the Publish Skills button in the Skills panel.
2. Check the Skills you want to publish.

OR

1. Right-click on the skill.yaml file in the file explorer.
2. Select Publish Skill from the menu.

The extension displays the progress of the build in the status bar at the bottom of the VSCode window.

Deployment may take some time depending on several factors, including the type of Skill you are deploying.

Your Skill is listed as "Deployed" when the process is complete.

Invoke Skills

Invoking the Skill involves the Skill image acting upon a specific collection of data to produce insights. To invoke a Skill, you need to specify:

• The Skill name
• The Input Service Message name
• The Payload parameters

Payloads

The data that is passed to a Skill is contained in a payload file, which provides the request to the Input Service Message for a specific Skill.

EXAMPLE PAYLOAD:

{
    "payload": {
        "message":  "This is a test payload message"
    }
}

In the extension each Skill folder has a subfolder named invoke. That folder contains a folder with the Input Service Message name, which holds the Payload json file.

To invoke a Skill:

1. Find the Skill folder of the Skill you want to invoke.
2. Right click the payload file (e.g. skills/skill1/invoke/request/message.json).
3. Select the option Cortex -> Invoke Skill in cluster from the actions menu.

OR

1. In the Skills panel hover over the desired input line.
2. Click the invoke icon.

If more than one payload file has been saved to the Skill's invoke folder, the extension requests that you make a selection. If only one file has been saved, the extension automatically uses it.

Payload Template Parameters

The Extension automatically inserts certain information into your payload files when it invokes the Skill. For example, in the following payload file:

{
    "payload": {
        "message":  "This is a test payload message for {{ skill.name }}",
        "moredata": "For input named {{ inputName }}",
        "yetmoredata": "The cortex token is {{ token }}",
        "someinstancedata": "The instance url is {{ instance.url }}"
    }
}

When this payload is invoked, the template parameters enclosed in {{ }} are replaced with data from the following data/objects provided by the extension:

• inputName: String containing the name of the Input Message Service
• skill: Object containing the Skill definition. See the Skill reference here.
• token: String containing an authentication token
• instance: Object defining the various attributes of the currently active Cortex instance:
  • url: string - The API URL for the instance
  • username: string - The user name
  • project: string - The project name
  • name: string - The name of the active instance
  • currentRegistry: string - The name of the image registry

Activations

Once a Skill is invoked, Fabric generates an activation ID, so you can identify and track the invocation within the cluster.

In the Skills panel, pending and completed activations can be viewed. To view activation results:

1. Double-click the activation ID.
2. The activation results are retrieved from Fabric and viewable in the VS Code window.

Viewing Skill Logs

The Skill type daemons are long running processes that perform on demand until terminated. Jobs, on the other hand, run, process data, and then terminate when completed.

For the longer-running daemons, the log output is viewable in the Extension during runtime.

To view the log:

1. In the Skills panel, under Actions, select the desired action name and expand it.
2. Logs available for that action are listed.
3. Double-click on a log to display the details.

Debugging Skills

After a Skill has been saved, and the image has been built, the Skill can be invoked locally for the purpose of debugging.

To debug a job:

1. Set some breakpoints in the Skill code.

EXAMPLE: Simple job Skill main.py file with a breakpoint set:

2. Verify that you have configured a payload for the Skill.
3. Navigate to the invoke folder and input you want to invoke.
4. Select Debug Skill Locally in the menu.

A container is created and the Skill image with the appropriate payload is launched in the extension. The Skill stops on the breakpoints.

Debugging Daemon Skills

Debugging a daemon is different from debugging a job.

To debug a daemon:

1. Set the breakpoints.
2. Verify that you have configured a payload for the Skill.
3. Navigate to the invoke folder and input you want to invoke.
4. Select Debug Skill Locally in the Cortex context menu.
5. The daemon Skill container remains running as it listens for incoming REST requests.

When the daemon is running, you can trigger the Skill using curl command, postman collection, or another method. The debugger will stop at breakpoints when requests are received.

The Experiments Panel

Experiments are instances of ML models (algorithms) that are stored in Fabric. A model may have multiple experiments.

This panel displays the model experiments defined in Fabric. In the extension experiments are stored in the top-level Workspace folder named experiments. As with other top-level folders, the experiments folder contains sub-folders for each Skill that has defined model experiments.

Inside each Skill subfolder is an experiment.yaml file that defines the model experiment.

Experiment Runs

Each experiment can have multiple "runs" with varying parameters that are stored in the sub-folder named runs. Each run is contained in a sub-folder in the main runs folder.

Each run may have artifacts that are uploaded automatically. Those artifacts are contained in the artifacts folder for the specific run.

EXAMPLE: An experiment named op1-gc_dtree_exp for the Skill named op1 has runs named run_01 and run_02.

The Types Panel

Custom data types that are used by Skills and Service Messages may be configured in Fabric. In the extension these custom types are stored in the top-level types folder, within the sub-folders for the Skills they have been defined for.

To retrieve the type resource definition:

1. Double-click the type found in the Skill sub-folder.
2. The resource definition is displayed in the editor.
3. View or delete the resource by right-clicking on the entry in the panel and selecting View Resource or Delete Resource.

The Managed Content Panel

Managed Content is internal storage that is configured for your Fabric instance. You can uploaded data files into Managed Content using the extension.

To load data to Managed Content:

1. Add a top-level content folder.
2. Add a sub-folders for the Skill that will be using the file you are loading to Managed Content.
3. Drag the data file into the content/skill-name/ folder.
4. When you build the Skill, that data file is automatically uploaded to Fabric Managed Content.

The name of the file will be used as the artifact name.

To download or delete a Skill resource:

1. Right-click on the resource.
2. Select Download Resource or Delete Resource.

Other Fabric Resources

There are other types of Fabric resources displayed in the Fabric Developer Extension that are not currently supported. Additional functionality is being developed.

You can remove the unused resources in the Cortex extension by right-clicking the resource and selecting Delete.