Supported Transformers

This page lists down all the supported transformers that currently exist in Bharat SahAIyak along with a guide on how to use them.

Generic Transformers

Code Runner Transformer

This type of transformer is capable of running custom JS code in an isolated environment. The XMessage is also passed as a global variable which can be accessed using $0, inside the JS code. The XMessage is provided in the form of a stringified JSON of XMessage. The code may only modify the XMessage.payload and XMessage.transformer.metaData part of the XMessage. The code 'must' return a response XMessage in stringified format regardless of whether the XMessage was modified inside the code or not.

Config Parameters

Name	Type	Required	Description
code	String	YES	The code to execute in the runner.

States

Name	Type	Required	Description
onSuccess	String	NO	The target id of the state to jump when GET request successfully completes. By default this jumps to global 'done' state.
onError	String	NO	The target id of the state to jump when GET request fails. By default this jumps to global 'error' state.

Example Usage

In this example code runner takes in XMessage, and modifies msg.payload.text to value modifiedMessage.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "CODE_RUNNER",
                "config": {
                    "code": "const msg = JSON.parse($0); msg.payload.text = 'modifiedMessage'; return JSON.stringify(msg);"
                }
            }
        ]
    }
}

note

There is a hard limit of 64MB of memory provided to the runner.

HTTP GET Transformer

This type of transformer does a simple GET request, given a url, query string and headers. If the request completes successfully, it attaches the response of the request to the metaData.httpResponse property of the XMessage. If the request fails, it throws an error with the failed response code.

Config Parameters

Name	Type	Required	Description
url	String	YES	The url of the endpoint for GET request.
query	String	NO	The query string for the GET request starting with '?'.
headers	JSON	NO	The headers for the GET request.

States

Name	Type	Required	Description
onSuccess	String	NO	The target id of the state to jump when GET request successfully completes. By default this jumps to global 'done' state.
onError	String	NO	The target id of the state to jump when GET request fails. By default this jumps to global 'error' state.

Example Usage

This given example below performs GET request on url https://cat-fact.herokuapp.com/facts/ with query ?myval=val&myval2=val2 and headers {"header_one": "header_val_one"}. Which on success sets metaData.httpResponse to the response from request.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "HTTP_GET,
                "config": {
                    "url": "https://cat-fact.herokuapp.com/facts/",
                    "query": "?myval=val&myval2=val2",
                    "headers": {
                        "header_one": "header_val_one"
                    }
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "3"
                }
            }
        ]
    }
}

HTTP POST Transformer

This type of transformer does a simple POST request, given a url, request body and headers. If the request completes successfully, it attaches the response of the request to the metaData.httpResponse property of the XMessage. If the request fails, it throws an error with the failed response code.

Config Parameters

Name	Type	Required	Description
url	String	YES	The url of the endpoint for POST request.
body	JSON	NO	The request body of the POST request.
headers	JSON	NO	The headers for the POST request.

States

Name	Type	Required	Description
onSuccess	String	NO	The target id of the state to jump when POST request successfully completes. By default this jumps to global 'done' state.
onError	String	NO	The target id of the state to jump when POST request fails. By default this jumps to global 'error' state.

Example Usage

This given example below performs POST request on url https://cat-fact.herokuapp.com/facts with headers {"header_one": "header_val_one"} and body {"body_one": "body_val_one"} . Which on success sets metaData.httpResponse to the response from request.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "HTTP_POST",
                "config": {
                    "url": "https://cat-fact.herokuapp.com/facts",
                    "body": {
                        "body_one": "body_val_one"
                    },
                    "headers": {
                        "header_one": "header_val_one"
                    }
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "3"
                }
            },
        ]
    }
}

Field Setter Transformer

This type of transformer can set fields of XMessage provided. This takes in setters key as JSON which is in the format of Record<string, string>. This defines the fields that need to be set, where the key is the parameter which needs to be set in XMessage and value is the parameter in XMessage which should be used as value. If value is a normal string or JSON, the value will be used directly, if the value is enclosed in {{}} like {{xmsg:payload.text}} or {{history:payload.text}}, it will be extracted from XMessage or from the most recent history message respectively.

Config Parameters

Name	Type	Required	Description
setters	JSON	YES	JSON in Record<string, string> which defines the fields that need to be set in XMessage.

States

Name	Type	Required	Description
onSuccess	String	NO	The target id of the state to jump when transformat sets values to XMessage successfully. By default this jumps to global 'done' state.
onError	String	NO	The target id of the state to jump when field setter fails to set values to XMessage. By default this jumps to global 'error' state.

Example Usage

This transformer sets payload.text field of XMessage to transformer.metadata.httpResponse.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "FIELD_SETTER",
                "config": {
                    "setters": {
                        "payload.text": "{{msg:transformer.metadata.httpResponse}}"
                    }
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "4"
                }
            }
        ]
    }
}

LLM Transformer

TBD

Config Parameters

Name	Type	Required	Description
APIKey	String	YES	API_KEY for OPENAI
model	String	YES	OPENAI Model GPT-3.5 Turbo, GPT-4 etc.
outboundURL	String	NO	Endpoint of service which sends message to end user. Required if enableStream is set to true.
bhashiniUserId	String	NO	user id for bhashini (required if provider is set to bhashini)
bhashiniAPIKey	String	NO	API key for bhashini (required if provider is set to bhashini)
bhashiniURL	String	NO	Base url for bhashini (required if provider is set to bhashini)
provider	String	NO	LLM API provider (optional), default is openAI
languageProvider	String	NO	Provider service to be used.
prompt	String	NO	LLM prompt, priority would be to use xmsg.transformer.metaData.prompt, if this null then the value passed here will be used.
corpusPrompt	String	NO	Specific instructions on corpus.
temperature	number	NO	The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
enableStream	Boolean	NO	boolean which allowes user to get streaming responses if enabled. By default this is set to false.
outputLanguage	String	NO	Stream output language. Defaults to 'en'.

States

Name	Type	Required	Description
onSuccess	String	NO	TBD
onError	String	NO	TBD

Example Usage

TBD

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "LLM",
                "config": {
                    "APIKey": "****************",
                    "model": "GPT-4",
                    "prompt": "How to grow wheat?"
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "3"
                }
            }
        ]
    }
}

Neural Coreference Transformer

TBD

Config Parameters

Name	Type	Required	Description
prompt	String	YES	GPT prompt used to get coreferenced output.
APIKey	String	YES	openAI API key.

States

Name	Type	Required	Description
onSuccess	String	NO	TBD
onError	String	NO	TBD

Example Usage

TBD

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "NEURAL_COREFERENCE",
                "config": {
                    "prompt": "Azure",
                    "APIKey": "****************"
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "3"
                }
            }
        ]
    }
}

SQL Query Builder Transformer

TBD

Config Parameters

Name	Type	Required	Description
APIKey	String	YES	openAI API key.
model	String	YES	OPENAI Model GPT-3.5 Turbo, GPT-4 etc.
xlsxIds	String	YES	list of excel ids to search from.
outboundURL	String	YES	Endpoint of service which sends message to end user.
outputLanguage	String	YES	stream output language.
excelParserURL	String	YES	Base url for excel parser.
bhashiniUserId	String	YES	user id for bhashini (required if provider is set to bhashini)
bhashiniAPIKey	String	YES	API key for bhashini (required if provider is set to bhashini)
bhashiniURL	String	YES	Base url for bhashini (required if provider is set to bhashini)
prompt	String	NO	LLM prompt. (optional)
temperature	String	NO	The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. (default: 0)

States

Name	Type	Required	Description
onSuccess	String	NO	TBD
onError	String	NO	TBD

Translate Transformer

This transformer can be used to translate a text from one language to another based on the provided config. By default it translates the payload.text field of the current XMessage. If the process is completed successfully, it replaces the value of payload.text with the translated text as well as saves the translated text in xmsg.transformer.metaData.translatedQuery. Config Parameters

Name	Type	Required	Description
provider	String	YES	translate service provider (Bhashini
inputLanguage	String	YES	Input text language. If not provided, xmsg.transformer.metaData.inputLanguage will be used. Defaults to en.
outputLanguage	String	YES	The expected output language. If not provided, xmsg.transformer.metaData.outputLanguage will be used. Defaults to en.
bhashiniUserId	String	YES	user id for bhashini (required if provider is set to bhashini)
bhashiniAPIKey	String	YES	API key for bhashini (required if provider is set to bhashini)
bhashiniURL	String	YES	Base url for bhashini (required if provider is set to bhashini)

States

Name	Type	Required	Description
onSuccess	String	NO	The target id of the state to jump when the entire text is translated successfully. By default this jumps to global 'done' state.
onError	String	NO	The target id of the state to jump when translation process fails. By default this jumps to global 'error' state.

Example Usage

This given example below translates input language to output language, that is from hindi to english, using the provider Azure. Supported Languages By Azure Supported Languages By Bhashini

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "TRANSLATE",
                "config": {
                    "provider": "Azure",
                    "inputLanguage": "hi",
                    "outputLanguage": "en"
                },
                "states": {
                    "onSuccess": "2",
                    "onError": "3"
                }
            }
        ]
    }
}

If-Else Transformers

Random Binary Transformer

This type of transformer, outputs a binary state randomly. It can either be an 'if' or an 'else'. The value of the output state is attached to the metaData.state property of the XMessage.

Config Parameters

None

States

Name	Type	Required	Description
if	String	YES	The target id of the state to jump when transformer outputs an 'if' state.
else	String	YES	The target id of the state to jump when transformer outputs an 'else' state. This is also the default state in case of an error.

Example Usage

This given example below, moves to if or else state depending on random binary output from the condition Math.random() > 0.5.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "RANDOM_BINARY",
                "states": {
                    "if": "2",
                    "else": "4"
                }
            }
        ]
    }
}

Doc Retriever Transformer

This type of transformer retrieves data chunks using provided config.url from provided list of documentIds (as config.documentIds) and save them to xmsg.transformer.metaData.retrievedChunks and also stringified version for this as xmsg.transformer.metaData.retrievedChunksStringified.

Config Parameters

Name	Type	Required	Description
url	string	YES	URL to retrieve the data chunks from.
documentIds	string	YES	list of documents to search from
staticNoContentResponse	string	NO	Bot response message incase no related docs are found, If provided, it'll be attached to the XMessage.payload.text in case no related docs are found. (optional)
topK	number	NO	Int describing number of top matched chunks to retrieve. Defaults to 6. (optional)
searchAll	Boolean	NO	Boolean Set this to true in order to seach through all docs uploaded via an organization.
logic	string	NO	String Type of retrieval logic that needs to be used. Accepted values: "custom"
recipeConfig	JSON	NO	Optional JSON configuration for the search recipe. Used for advanced query customization.
threshold	number	NO	Precentage similarity threshold.

States

Name	Type	Required	Description
if	String	YES	The target id of the state to jump when transformer outputs an 'if' state.
else	String	YES	The target id of the state to jump when transformer outputs an 'else' state. This is also the default state in case of an error.

Example Usage

This example given below, fetches chunks from https://doc-retriever.samagra.io URL, with IDs ID_1, ID_2, and saves retrieved chunks to xmsg.transformer.metaData.retrievedChunks and stringified version to xmsg.transformer.metaData.retrievedChunksStringified.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "DOC_RETRIEVER",               
                "config": {
                    "url": "https://doc-retriever.samagra.io",
                    "documentIds": ["<ID_1>", "<ID_2>"]
                }
                "states": {
                    "if": "2",
                    "else": "4"
                }
            }
        ]
    }
}

Retry Transformers

Simple Retry Transformer

This type of transformer, if attached to the error state of any transformer and outputs two states, retry which is the target id of the node that needs to be retried, or else error which is the target id of the node to jump to in case all the retries have been exausted.

Config Parameters

Name	Type	Required	Description
retries	number	YES	The number of retries to attempt before erroring out. The default value is 0 and leads to a retry attempt not being made.
delay	number	YES	The number of milliseconds to wait before attempting a retry.

States

Name	Type	Required	Description
retry	String	YES	The target id of the node to retry. By default this will move to global 'done' state.
error	String	NO	The target id of the node to jump to when all the retries have been exausted. By default this will move to global 'error' state.

Example Usage

This example given below, executes transformer with ID 1 for a total of 5 times. And will error out to transformer with ID 4 after exhausting 5 retries.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "2",
                "type": "SIMPLE_RETRY",
                "config": {
                    "retries": 5,
                    "delay": 5000
                },
                "states": {
                    "retry": "1",
                    "error": "4"
                }
            }
        ]
    }
}

Switch-Case Transformers

Label Classifier Transformer

This type of transformer, outputs an arbitary label based on a scores of classification returned by an external API. An example of this would be, the type of mood a sentence is written in. The state outputted by the transformer is stored in metaData.state property of consumed XMessage.

Config Parameters

Name	Type	Required	Description
url	String	YES	The url of the API endpoint which returns the label scores.
prompt	String	YES	The input prompt to classify. Required if XMessage.payload.text is undefined. The XMessage.payload.text takes precedence over prompt if provided.
headers	JSON	NO	Headers for request (optional)
existingLabel	String	NO	If provided, this label would always be returned regardless of highest score, unless another label passes supersedeThreshold. (optional)
supersedeThreshold	number	NO	The threshold value on and above which, a label may supersede an existingLabel. 0.95 by default. (optional)
suppressedLabels	String[]	NO	The labels that should be suppressed (not considered for final result state) unless they pass the supressionThreshold value (optional).
suppressionThreshold	number	NO	The threshold value on and above which no labels will be suppressed. 0.95 by default. (optional)
persistLabel	Boolean	NO	If true, the label will be persisted in the metaData of XMessage. Default value if false. (optional)
minimumThreshold	number	NO	If provided, a label must reach this threshold score to be considered for final result. Default is 0. (optional)

States

Arbitarily generated by the transformer based on API response.

Example Usage

This example given below, classifies the prompt based by performing a POST request to url provided, and sets xmsg.transformer.metaData.state to label provided in POST response.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "LABEL_CLASSIFIER",
                "config": {
                    "url": "https://api-inference.huggingface.co/models/GautamR/akai_flow_classifier_pest_seed_scheme",
                    "prompt": "paddy and crops",
                    "existingLabel": "LABEL_0",
                    "supersedeThreshold": "0.4",
                    "suppressedLabels": ["LABEL_2"]
                    "suppressionThreshold": 0.99,
                    "persistLabel": true,
                    "minimumThreshold": 0.6,
                },
                "states": {
                    "LABEL_0": "3",
                    "LABEL_1": "4",
                    "LABEL_2": "7",
                    "LABEL_3": "7",
                    "LABEL_4": "5",
                    "LABEL_5": "6",
                    "LABEL_6": "7",
                    "default": "6"
                }
            }
        ]
    }
}

State Restore Transformers

User Feedback Loop Transformer

A transformer that pauses the flow of the state machine, send the user a message, and restores the state of the state machine to a node specified by restoreState field when the user responds to the message.

Config Parameters

Name	Type	Required	Description
prompt	String	NO	A prompt to send the user to reply to. If not provided, default XMessage.payload will be used.

{
    "logicDef": {
        "id": "myTestMachine",
        "transformers": [
            {
                "id": "1",
                "type": "USER_FEEDBACK_LOOP",
                "config": {
                    "prompt": ""
                },
                "states": {
                    restoreState: "1"
                }
            }
        ]
    }
}