Apply Restful API functionality to your search queries

Configure the tuning stage
Use cases and examples

The RestfulPostman tuning stage allows you to use the functionality of any Restful API (LLMs, AI Cloud Services, etc.) of your choosing to enhance your user's search experience.

By integrating your own AI with SmartHub, you agree to the Upland AI Disclaimer. This disclaimer appears on all components with AI functionality in the administration portal.

If you want to apply Restful API functionality to your indexed data, you can do so with the Autoclassifier Restful API Caller component.

Configure the tuning stage

In the SmartHub administration portal, click General Settings.
In the User Experience Tuning section, click Add Query Tuning.
From the User Experience Tuning window, select RestfulPostman from the User Experience Tuning drop-down list.
In the Name field, provide a name for your tuning stage.
In the Endpoint field, enter the endpoint URL for your RESTful API.
In the Request Headers field, enter the Key and Value for your RESTful API. You can click Add Header or Add Secure Header to add additional key-value pair request headers.
In the Request Body field, enter the body for your desired request to your API.

When you are replacing the placeholder in the request body, the property must be a string type.
In the Response Key Path field, you can specify the key path that you want to receive from the API response.
In the Response Datatype field, select the data type that you expect to receive from the response from the drop-down menu.
In the Output Type field, you can select either Single Valued or Multiple Valued.
Click Test Request. The response from your request body will be populated in the Response field.
In the Referenced Assemblies field, enter the assemblies your post processing script requires to run. The format for this field is one line per assembly, separated by a comma. You must specify the assembly using the Fully Qualified Assembly format. For example:
```
BAInsight.ElasticSearch.FederatorExtension, Version=1.0.0.0, 
Culture=neutral,PublicKeyToken=bd5ed2e4b6962cd0
```
In the Imported Namespaces field, Specify which namespaces to import in your post processing script. The format is one line per namespace. For example:
```
BAInsight.ElasticSearch.FederatorExtension.ElasticBackend.Backends
```
In the Post Processing Script you can enter a script to further process the results returned form your API.
To test your post processing script, click Compile.

Use cases and examples

Applying vector embeddings with a non-OpenAI model

For OpenAI-based embeddings generation, you can use the Azure OpenAI embeddings generator or OpenAI embeddings generator stages. However, if you are using a non-OpenAI model, you can use the RestfulPostman stage to generate embeddings for your user's search query. The following use case showcases Jina's jina-embeddings-v3 model.

In the Endpoint URL field, we provide the endpoint to the Jina Embedding API: https://api.jina.ai/v1/embeddings.
In the Request Header field, we provide the authorization header to the access the Jina API key: Authorization: Bearer jina_a3f3f997a2f144cca283e0aea79de474eGlE8xIn6nXOGnAw7iqVrooF9lUA.

In the Request Body field, we provide the request to Jina to apply embeddings:

{
    "model": "jina-embeddings-v3",
    "input": [
        "text": "{ContentPlaceholder}"
    ]
  }
                                                        

In the Request Answer Key Path field, we provide the path to the specific request field where our embeddings were generated: data[0].embedding.
In the Response Datatype field, we specify Number, and the Output Type as Multiple Valued.

For more information on usage of this AI model, see Embeddings in the Jina documentation.

Translating user queries from a different languages

You can use the RestfulPostman stage to translate a user query that is provided in a specific language to another language. Using Open AI, the following example will translate the user search query, provided in German, to English and produce search results that match the English query.

In the Endpoint URL field, we provide the endpoint url to the OpenAI API that will translate our query: https://api.openai.com/v1/chat/completions.
In the Request Header field, we provide the authorization header to the access the OpenAI API key: Authorization: Bearer $OPENAI_API_KEY.

In the Request Body field, we provide the request to OpenAI to translate the query:

{
    "model": "gpt-4o-mini",
    "messages": [
       {
        "role": "user",
        "content":"Translate the following Germn text into English, provide only the translated word: {ContentPlaceholder}"}
        ],
    "temperature":0.7
    
}
                                                        

In the Request Answer Key Path field, we provide the path to the specific request field where our embeddings were generated: choices[0].message.content.
In the Response Datatype field, we specify Text, and the Output Type as Single Valued.
In the Post-Processing Script field, we apply a script to direct SmartHub to use the OpenAI translated results to produce the search results:
```
Context.Query.QueryText=Context.Result;
```

Processing an output that is multi-valued

In the case that your response will be multi-valued, you can use the RestfulPostman stage to process the response and alter your search query. Using Open AI, the following example will retrieve all synonyms of the search query keyword and produce search results that also match the synonyms.

In the Endpoint URL field, we provide the endpoint url to the OpenAI API that will produce synonyms our query: https://api.openai.com/v1/chat/completions.
In the Request Header field, we provide the authorization header to the access the OpenAI API key: Authorization: Bearer $OPENAI_API_KEY.

In the Request Body field, we provide the request to OpenAI to produce synonyms to the query:

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "Give me all common English synonyms of the word {ContentPlaceholder}. Respond only with a comma-separated list of words, no brackets, no quotes, no explanations, no markdown."
        }
    ],
    "temperature": 0
}
                                                        

In the Request Answer Key Path field, we provide the path to the specific request field where our synonyms were generated: choices[0].message.content.
In the Response Datatype field, we specify Text, and the Output Type as Multiple Valued.
In the Post-Processing Script field, we apply a script to direct SmartHub to use the OpenAI generated synonyms to enhance the search results:
```
Context.Query.QueryText += " " + string.Join(" ", Context.Result);
```