1 of 8

Advanced

Run Recipe via REST API

This provides instructions on how to execute Omnitool recipes through the REST API, enabling seamless integration into your system.

1. Preparing a JWT Token

To generate a JWT token, use the provided script with the following syntax:

Parameters

<action>: String parameter for the intended action (use exec for running recipes).
<subject>: String parameter specifying the JWT subject, typically the recipe to execute.
<expires_in>: Integer parameter for the token's validity in milliseconds.
<recipe_id>: (Optional) Unique ID of the recipe.

Example

Generate a JWT for a recipe execution with 1-hour validity by running the command in Omnitool chat window:

Output

The script outputs a JWT for use in API request headers.

Security Considerations

Ensure JWT security to prevent unauthorized recipe access.
Use secure connections for API interactions.
Rotate tokens regularly and prefer short expiration times.

Troubleshooting

If you encounter authorization issues, verify the JWT's expiration, correct header setup, and parameter accuracy.

2. Executing a Recipe

With your JWT, make a POST request to the recipe execution API, including the JWT in the Authorization header.

Endpoint

Header

<token> is the JWT acquired from the /generateJwtToken script.

Curl Example

To make the request using curl, you would use the following command, replacing with your actual JWT:

Request Body

The args parameter acts as a input container for executing recipes, capable of passing various data types to the Chat Input as a starting block. These data types include images, text, audio, video, documents, and even structured JSON objects.

Supported Image Formats

When using images in the args parameter, our system is compatible with various formats, such as GIF, PNG, JPG, and WebP. For APIs with specific format requirements, utilize Sharp's 'Prepare Image' block within your recipe to convert and comply with these constraints.

Response

Upon success, the API will initiate the specified recipe. You will receive a JSON response containing details about the recipe's execution status, including any outputs or errors.

3. Retrieve the Recipe Results

Adding Recipe Output Block

Ensure that your recipe includes the 'Recipe Output' block for proper execution and result retrieval.

Accessing Execution Outputs

Once a job is finished, retrieve results with:

Refer to for a end-to-end sample JavaScript implementation.

Create New Blocks

Add a New Block via Composition API

Step 1: Import Necessary Components

Import the necessary components

Step 2: Create a New Component Instance

Instantiate the ComponentComposer and initialize your component by defining its namespace and operationId using the .create(displayNamespace, displayOperationId) method.

Set the namespace to const NS_OMNI

Step 3: Define Component Characteristics

Further define the characteristics of your component using provided methods. You can set the title, description, method, and category.

Instead of using the fromScratch() method, you can also utilize the fromJSON() method with a valid Partial<OmniComponentFormat> JSON. This must include both the displayNamespace/operationID and apiNamespace/operationId.

Step 4: Create and Add Inputs and Outputs

For inputs and outputs, you'll first create an IOComposer using the .createInput(name, type, customSocket) or .createOutput(name, type, customSocket) methods. You can further define their properties, including setting up controls which can be automatically selected or overridden.

Inputs always have controls associated with them, and they can be defined directly within the input creation process. Here's an example of defining an input with a control:

Note:

When using .allowMultiple() in conjunction with { array: true }, the input array is flattened into a single array:

You can define which characters are used for joining (or separating on input) an array (default is \n) via a custom setting (specific to the Text Socket):

Alternatively, you can also define inputs and outputs in an array:

You also have the option to directly write the JSON if that's your preference.

Step 5: Create and Add Controls (Optional)

Controls are created using the ControlComposer and are added similarly to inputs/outputs.

Step 6: Define Execution Macro

You can define the behavior of your component using a macro. In this case, the OmniComponentMacroTypes.EXEC macro type is used.

Step 8: Export the Component

Finally, convert the component to JSON and export it.

Step 9: Add the Component to App Blocks

Note: extensions don’t need to call addBlock. they just need to export the createComponent function.

Optional Settings:

Composing Patches

To compose a patch with a valid OmniComponentPatch, the same format applies:

Dependencies

Use .dependsOn(string[]) to specify dependencies, indicating if a block relies on other blocks (for instance, when using runblock internally). For example:

Adding New Block via Extension

Extensions provide a powerful way to augment the capabilities of the system by exporting blocks to the block manager. These blocks are loaded on startup, enabling you to create custom components and patches. In this guide, we'll outline how to use extensions to create and export components.

Creating Components with the Composition API

Follow Creating Components with the Composition API , you can use the composition API from the mercs_rete library to create components. First, make sure to import the necessary modules:

Then, you can create components and patches using methods provided by OAIBaseComponent.

Example:

Adding Inputs/Outputs

Follow , you can also define and add inputs/outpus to the component:

Configuring ESBuild to Avoid Errors

To prevent any errors from being thrown and to avoid bundling mercs_shared, which the server already has, you'll need to externalize mercs_rete. You can do this by adding --external:mercs_rete to the ESBuild in your package.json. This step ensures a smooth building process (because it already is loaded in server memory, no need to bundle it).

Export Components and Patches

Add the supports: ["blocks:v2"] property to the extension.yaml to tell the server to try to load the blocks:

An extension must export an object containing hooks and a createComponents() function. Once you have defined your components and patches, combine them into an array and return them within the createComponents() function as described. The system will automatically load these during startup, incorporating them into the available set of components.

Building the Extension

After making all the necessary updates to your extension code, run the following command to build the extension:

This command compiles your code and generates the extension.js file, which contains the entire extension ready for use. If you are using TypeScript for your extension development, make sure to update the tsconfig.json file with the appropriate configuration for your project.

By following these steps, you can create complex and customizable components and integrate them into the system via extensions. Make sure to follow the guidelines for each type of component or patch and consult the specific documentation related to each class or method for more details.

Adding new Block via OpenAPI Spec

Importing an Existing OpenAPI Specification

Locate the API Specification: Determine if the API specification exists at a known URL. For example, OpenAI's specification can be found at https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml.
Validate the Specification: Use https://editor.swagger.io/ to validate the OpenAPI spec.
Add to System:
- Navigate to packages/omni-server/extensions/omni-core-blocks/server/apis/[NAMESPACE]/[NAMESPACE].yaml.
- Replace [NAMESPACE] with your desired namespace (e.g.,

Example Configuration for OpenAI

Creating an OpenAPI Spec

Generate Draft Spec: If the specification doesn't exist, use tools like "OpenAPI Spec Generator" or request ChatGPT 4 to draft an initial spec.
Validate the Specification: Use https://editor.swagger.io/ to validate the OpenAPI spec.
Add to System:

Example Configuration for GetImg

Configure API in YAML

Patch Authentication

We support the following authentication type:

If auth is not defined globally in the original OpenAPI spec, you can patch it in the API yaml /omni-core-blocks/server/apis/[NAMESPACE].yaml

Filter APIs

Configure Blocks in YAML

Basic Metadata

Filter Inputs/Outputs

Transform

Hoist?

Control

Input

type:

customSocket:

Socket Format Options

Base64 image socket option:

Array:

Allow multiple connect

Rename

Run block to Generate Choices

Use JSONATA to Manipulate the format

Patch Security Scheme

Default Result

how to patch when response doesn't have property?

Special Cases

When properties have mutually exclusive or dependencies

Property name is Case-sensitive

When request content type is multipart/form-data, need file type to carry mimetype

Create New Extension

Extensions allow adding additional functionality to omnitool, both on client and server side. They can provide a convenient way for prototyping AI powered applications.

⚠️ Extensions run with the same permissions as the omnitool process and have full access to the omnitool server process. They should be treated like any other npm package or executable code from the internet, with extreme caution. ⚠️

Getting Started

Creating a custom extension for Omnitool is streamlined with our easy-to-use template. Here's a step-by-step guide to create, develop, and test your extension:

Access and Use the Template Repository:
- Visit the on GitHub. This template provides the basic structure needed for your extension.
- Create a new repository from this template, ensuring that it's set to public visibility.

By following these steps, you can effectively create and develop a functional and innovative extension for Omnitool. This guide is designed to assist both beginners and experienced developers in navigating the extension development process with ease.

Extension Structure

extension.yaml

For an extension to be recoginized by the server, it needs, at minimum, an extension.yaml file in the directory.

Directory Structure

The following directory structure may, optionally, exist under the extension's sub directory

public - Files in this directory are served to the client under server_url/extensions/<extension id>. By default, if client.addToWorkbench is true, the client will attempt to show public/index.html if it exists when a users selects the extension in the extension menu
scripts/client - Files in this directory, following the script format, will be exported to the client, adding to the list of known /chat commands. The chat command will be mapped to the file's name, so test.js would become /test. For more details, see Client Programming/Scripts below.

Extension Discovery

Currently the server keeps track of known extensions via the /etc/extensions/known_extensions.yaml file. An entry in this file will make extensions discoverable by the omnitool community. We plan on adding the ability to add additional extensions repositories outside the official one.

The file's format is straightforward:

An entry in this file is not required for an extension to be loaded, only for it to be discoverable by other omnitool users.

Client Extension Programming

The client, after successful login, polls the /extensions endpoint on the server to retrieve a list active extension. It then constructs the extension menu and compiles the received client scripts.

Upon being shown, client extensions are loaded into an iframe overlaying the canvas by default and has access to the omnitool client context via the window.parent object. This is done by calling (window.parent.client.)workbench.showExtension(extension-id, openArgs ), usually from automatically from within the extensions menu or from a client script.

Closing the extension will show the canvas again but not unload the iframe. However, the extensions state is not guaranteed, as showing any other extension will replace the iframe content. If it is necessary to persist client state, local or session storage can be used or data could be marshalled via server scripts.

Scripts

Scripts in the client/scripts subdirectory of the extension are automatically registered with each connecting client after successful authentication and become available as /chat commands.

Within scripts, full access to the omnitool client is accessbile via the window.client object.

To display the index.html file surfaced via the extensions public/ directory, the window.client.workbench.showExtension("extension-id", {...}); provides a convenient method that also allow marshalling 'opening args

When the workbench.showExtension command is used, the full object structure of the arguments object will be serialized (JSON. strigified) into a parameter q in the opening url.

The following example code shows how to deserialize the opening args inside the extension's index.html

Server Extensions Programming

When the server starts, it will execute the server/extension.js file for each extension, if present.

This file can:

(1) Attach hooks to server events to allow running code when these events happen (2) Export a list of blocks to be registered with the server.

A minimally viable extension.js looks like this

Event Hooks

Event hooks are events exported by the server (see server/src/core/ServerExtensionsManager.ts) that extension can hook into. by default, these hooks are executed synchronously, giving the extension the ability to modify execution parameters or, in some cases, even cancel the execution.

Currently, the following events are implemented:

The first parameter of each event is an event context, followed by a variable list of parameter depending on the event.

For example:

Block Factory

Extensions can add blocks to the omnitool. Unlike API based blocks imported from the registry, extension components have the ability to execute javascript code, allowing them to encapsulate useful nodejs libraries or custom code to provide more sophisticated experiences

To export blocks from an extensions, a createComponents factory function must be exported by the extension.js file. This function is invoked by the server on startup with the servers block factory function (currently APIOperationsComponent.fromJSON).

Use Local Models

Omnitool enables you to utilize models that run locally on your system. Follow this guide to begin integrating and using local models with Omnitool.

Supported Local APIs

For a detailed list of all the local apis supported by Omnitool, visit Omnitool Local API templates. Here is a quick list of supported software that allows to run models locally:

ollama

Steps to Activate Local APIs

Install the Local Software:
- Make sure to install the necessary local software. Follow the instructions provided on their respective websites or GitHub repositories.
Verify Service Status:

Add a New Block via Composition API

Step 1: Import Necessary Components

Import the necessary components

import { OAIBaseComponent, type OmniComponentFormat, WorkerContext, OmniComponentMacroTypes } from "./path_to_file"

Step 2: Create a New Component Instance

Instantiate the ComponentComposer and initialize your component by defining its namespace and operationId using the .create(displayNamespace, displayOperationId) method.

Set the namespace to const NS_OMNI

Step 3: Define Component Characteristics

Further define the characteristics of your component using provided methods. You can set the title, description, method, and category.

Step 4: Create and Add Inputs and Outputs

Inputs always have controls associated with them, and they can be defined directly within the input creation process. Here's an example of defining an input with a control:

Note:

When using .allowMultiple() in conjunction with { array: true }, the input array is flattened into a single array:

You can define which characters are used for joining (or separating on input) an array (default is \n) via a custom setting (specific to the Text Socket):

Alternatively, you can also define inputs and outputs in an array:

You also have the option to directly write the JSON if that's your preference.

Step 5: Create and Add Controls (Optional)

Controls are created using the ControlComposer and are added similarly to inputs/outputs.

Step 6: Define Execution Macro

You can define the behavior of your component using a macro. In this case, the OmniComponentMacroTypes.EXEC macro type is used.

Step 8: Export the Component

Finally, convert the component to JSON and export it.

Step 9: Add the Component to App Blocks

Note: extensions don’t need to call addBlock. they just need to export the createComponent function.

Optional Settings:

Composing Patches

To compose a patch with a valid OmniComponentPatch, the same format applies:

Dependencies

Use .dependsOn(string[]) to specify dependencies, indicating if a block relies on other blocks (for instance, when using runblock internally). For example:

Create New Extension

Extensions allow adding additional functionality to omnitool, both on client and server side. They can provide a convenient way for prototyping AI powered applications.

Getting Started

Creating a custom extension for Omnitool is streamlined with our easy-to-use template. Here's a step-by-step guide to create, develop, and test your extension:

Access and Use the Template Repository:
- Visit the on GitHub. This template provides the basic structure needed for your extension.
- Create a new repository from this template, ensuring that it's set to public visibility.

Extension Structure

extension.yaml

For an extension to be recoginized by the server, it needs, at minimum, an extension.yaml file in the directory.

Directory Structure

The following directory structure may, optionally, exist under the extension's sub directory

public - Files in this directory are served to the client under server_url/extensions/<extension id>. By default, if client.addToWorkbench is true, the client will attempt to show public/index.html if it exists when a users selects the extension in the extension menu
scripts/client - Files in this directory, following the script format, will be exported to the client, adding to the list of known /chat commands. The chat command will be mapped to the file's name, so test.js would become /test. For more details, see Client Programming/Scripts below.

Extension Discovery

The file's format is straightforward:

An entry in this file is not required for an extension to be loaded, only for it to be discoverable by other omnitool users.

Client Extension Programming

The client, after successful login, polls the /extensions endpoint on the server to retrieve a list active extension. It then constructs the extension menu and compiles the received client scripts.

Scripts

Scripts in the client/scripts subdirectory of the extension are automatically registered with each connecting client after successful authentication and become available as /chat commands.

Within scripts, full access to the omnitool client is accessbile via the window.client object.

When the workbench.showExtension command is used, the full object structure of the arguments object will be serialized (JSON. strigified) into a parameter q in the opening url.

The following example code shows how to deserialize the opening args inside the extension's index.html

Server Extensions Programming

When the server starts, it will execute the server/extension.js file for each extension, if present.

This file can:

(1) Attach hooks to server events to allow running code when these events happen (2) Export a list of blocks to be registered with the server.

A minimally viable extension.js looks like this

Event Hooks

Currently, the following events are implemented:

The first parameter of each event is an event context, followed by a variable list of parameter depending on the event.

For example:

Block Factory

const MyCustomBlock = { schema: // <-- OpenAPI 3 Schema { // Namespace is automatically set to the extension id "tags": ['default'], "componentKey": "my-first-block", // <-- unique id within the namespace //"apiKey": "my-first-block", // <-- optional, set to the 'parent' API if this is a normal rest component (not supported yet) "operation": { // operationId is automatically set to componentKey "schema": { "title": "My First Block", // <-- componentn title "type": "object", required:[], "properties": { "text": { "title": "Some Text Input", "type": "string", // <-- openAPI type "x-type": "text", // <-- custom omnitool socket type if wanted "default": "my default value", "description": `My block description` } }, }, "responseTypes": { "200": { "schema": { "required": [ "text" ], "type": "string", "properties": { "text": { "title": "My Output Text", "type": "string", }, }, }, "contentType": "application/json" }, }, "method": "X-CUSTOM" // <-- This is important }, patch: // <-- optional omnitool patch block { "title": "My Custom Component", /// <-- component "category": "Test", "summary": "Replaces Cars with Horses", "meta": { "source": { "summary": "Replaces cars with horses", links: { // list of string: string fields that are rendered as urls. "research papaer": "https://arxiv.org..." } } }, inputs: {...}, controls: {...} outputs: {...} } }, functions: { _exec: async (payload, ctx) => // <-- The _exec function is invoked when the component is run { if (payload.text) { payload.text = payload.text.replace("car", "horse" ) } return payload // <-- Do not forget to return the altered payload } } } let blocks = [MyCustomBlock] export default (FactoryFn: any) => { return components.map((c) => FactoryFn(c.schema, c.functions)) }

Advanced

Run Recipe via REST API

hashtag1. Preparing a JWT Token

hashtag2. Executing a Recipe

hashtagSupported Image Formats

hashtag3. Retrieve the Recipe Results

hashtagAdding Recipe Output Block

hashtagAccessing Execution Outputs

Create New Blocks

Add a New Block via Composition API

hashtagStep 1: Import Necessary Components

hashtagStep 2: Create a New Component Instance

hashtagStep 3: Define Component Characteristics

hashtagStep 4: Create and Add Inputs and Outputs

hashtagStep 5: Create and Add Controls (Optional)

hashtagStep 6: Define Execution Macro

hashtagStep 8: Export the Component

hashtagStep 9: Add the Component to App Blocks

hashtagOptional Settings:

hashtagComposing Patches

hashtagDependencies

Adding New Block via Extension

hashtagCreating Components with the Composition API

hashtagAdding Inputs/Outputs

hashtagConfiguring ESBuild to Avoid Errors

hashtagExport Components and Patches

hashtagBuilding the Extension

Adding new Block via OpenAPI Spec

hashtagImporting an Existing OpenAPI Specification

hashtagExample Configuration for OpenAI

hashtagCreating an OpenAPI Spec

hashtagExample Configuration for GetImg

hashtagConfigure API in YAML

hashtagPatch Authentication

hashtagFilter APIs

hashtagConfigure Blocks in YAML

hashtagBasic Metadata

hashtagFilter Inputs/Outputs

hashtagTransform

hashtagHoist?

hashtagControl

hashtagInput

hashtagSocket Format Options

hashtagRename

hashtagRun block to Generate Choices

hashtagUse JSONATA to Manipulate the format

hashtagPatch Security Scheme

hashtagDefault Result

hashtagSpecial Cases

Create New Extension

hashtagGetting Started

hashtagExtension Structure

hashtagextension.yaml

hashtagDirectory Structure

hashtagExtension Discovery

hashtagClient Extension Programming

hashtagScripts

hashtagServer Extensions Programming

hashtagEvent Hooks

hashtagBlock Factory

Use Local Models

hashtagSupported Local APIs

hashtagSteps to Activate Local APIs

Create New Blocks

Add a New Block via Composition API

hashtagStep 1: Import Necessary Components

hashtagStep 2: Create a New Component Instance

hashtagStep 3: Define Component Characteristics

hashtagStep 4: Create and Add Inputs and Outputs

hashtagStep 5: Create and Add Controls (Optional)

hashtagStep 6: Define Execution Macro

hashtagStep 8: Export the Component

hashtagStep 9: Add the Component to App Blocks

hashtagOptional Settings:

hashtagComposing Patches

hashtagDependencies

Adding New Block via Extension

hashtagCreating Components with the Composition API

hashtagAdding Inputs/Outputs

hashtagConfiguring ESBuild to Avoid Errors

1. Preparing a JWT Token

2. Executing a Recipe

Supported Image Formats

3. Retrieve the Recipe Results

Adding Recipe Output Block

Accessing Execution Outputs

Step 1: Import Necessary Components

Step 2: Create a New Component Instance

Step 3: Define Component Characteristics

Step 4: Create and Add Inputs and Outputs

Step 5: Create and Add Controls (Optional)

Step 6: Define Execution Macro

Step 8: Export the Component

Step 9: Add the Component to App Blocks

Optional Settings:

Composing Patches

Dependencies

Creating Components with the Composition API

Adding Inputs/Outputs

Configuring ESBuild to Avoid Errors

Export Components and Patches

Building the Extension

Importing an Existing OpenAPI Specification

Example Configuration for OpenAI

Creating an OpenAPI Spec

Example Configuration for GetImg

Configure API in YAML

Patch Authentication

Filter APIs

Configure Blocks in YAML

Basic Metadata

Filter Inputs/Outputs

Transform

Hoist?

Control

Input

Socket Format Options

Rename

Run block to Generate Choices

Use JSONATA to Manipulate the format

Patch Security Scheme

Default Result

Special Cases

Getting Started

Extension Structure

extension.yaml

Directory Structure

Extension Discovery

Client Extension Programming

Scripts

Server Extensions Programming

Event Hooks

Block Factory

Supported Local APIs

Steps to Activate Local APIs

Step 1: Import Necessary Components

Step 2: Create a New Component Instance

Step 3: Define Component Characteristics

Step 4: Create and Add Inputs and Outputs

Step 5: Create and Add Controls (Optional)

Step 6: Define Execution Macro

Step 8: Export the Component

Step 9: Add the Component to App Blocks

Optional Settings:

Composing Patches

Dependencies

Creating Components with the Composition API

Adding Inputs/Outputs

Configuring ESBuild to Avoid Errors

Export Components and Patches

Building the Extension

Getting Started

Extension Structure

extension.yaml

Directory Structure

Extension Discovery

Client Extension Programming

Scripts

Server Extensions Programming

Event Hooks