Generative for Javascript – Pryon Help

askGenerativeQuestion

askGenerativeQuestion sends a request containing the user query questionText, and other optional parameters, which calls the Generative Exchange Event API and returns the newly-created exchange, along with a stream yielding the generative response text.

Parameters

askGenerativeQuestion takes in an options input object that contains subfields and sub-objects.

Mandatory parameters are:

Parameter	Data type	Definition
`questionText`	string	Input query, or question being asked
`collectionID`	string	Knowledge collection, or index, that the exchange is performed against Note: The collection ID is located for each collection under the Configuration > Advanced tab and allows the exchange operation to automatically use the active version of the collection
`sseCallback`	function	Callback that handles the askGenerative response and fires off events based on the incoming `state` of the response
`errorCallback`	function	Callback that fires off events if the API returns an error

Optional parameters are:

Parameter	Data type	Definition
`maxRetries`	number	Specifies the maximum retry attempts made by the SDK after an error; between 0 and 10
`maxOutputs`	number	Specifies the number of outputs to be returned (min 3, max 10); default is 3
`tagIDs`	array	An array of tag IDs for filtering; defaults to [] if not provided (for more information, see Using Tags)
`contentGroupIDs`	array	An array of content group IDs for filtering; defaults to [] if not provided
`asUser`	string	The email of a user; allows a user to impersonate another user and is only allowed for users logged in via the `initialize` method

Parent parameter		Data type	Definition
`conversationParameters`		object	Passed with the generative exchange to modify the collection configuration with sub-objects, including:
	Child parameter
	`randomness`	number	Controls the randomness of the generated text, ranging from 0 to 1; higher values result in more random text, while lower values produce more focused and deterministic text
	`minAnswerInContextScore`	number	Sets the minimum score of the AICs to be considered when generating a response
	`deltaBeamCutOff`	number	Maximum allowable AIC score delta from the highest score to be considered when generating a response
	`verifiedAnswerThreshold`	number	Verified answer threshold to be considered as a final answer
	`outOfDomainScoreThreshold`	number	Best answer score threshold that out of domain message should be returned as a final answer
	`outOfDomainMessage`	string	Best answer score threshold that out of domain message should be returned as a final answer
	`conversationalContext`	string	Obtained from the previous response; enhances the generative response

Function signature

Ask a question by updating variables in the following code:

Show code

await askGenerativeQuestion({
 questionText: questionText,
 collectionID: collectionID,
 sseCallback: (ev) => { console.log(ev) },
 errorCallback: (error) => { throw error },
 asUser: asUser
})

askGenerativeQuestion accepts the following options structure.

Show code

export interface AskGenerativeQuestionOptions {
  questionText: string
  collectionID: string
  sseCallback: (message: GenerativeExchangeResponseData) => void
  errorCallback: (error: any) => void
  maxRetries?: number,
  conversationContext?: string
  maxOutputs?: number
  tagIDs?: string[]
  contentGroupIDs?: string[]
  asUser: asUser
  conversationParameters?: {
    randomness?: number,
    minAnswerInContextScore?: number,
    deltaBeamCutOff?: number,
    verifiedAnswerThreshold?: number,
    outOfDomainScoreThreshold?: number,
    outOfDomainMessage?: string,
  }
}

Response

askGenerativeQuestion yields the text of the generative response, piece by piece, as it is received from the generative exchange API. In general, askGenerativeQuestion follows a SSE model where updates are denoted by states.

Generative Exchange SSE States

askGenerativeQuestion returns no value. The user provides an sseCallback and an errorCallback to handle the response. The API response contains different fields and behaviors based on the response.state, which the developer uses to fire off events and trigger different behavior.

GENERATIVE_EXCHANGE_RESPONSE_DELTA

Returns the next token in the response. Below is an example of the JSON object when the response data has this flag.

Show code

{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA", 
"generative_exchange_conversation_data": { 
     "data": { 
         "text": "Yoda" 
     } 
}

EXCHANGE_RESPONSE_COMPLETE

To learn more about the ExchangeResponseData, refer to the Retrieval JavaScript Library.

Show code

{ 
  "metadata": {
    "uuid":"8558510d-4276-4d64-9daf-94e470c0475f",
    "create_time":"2024-07-15T17:13:03.963754Z",
    "update_time":"2024-07-15T17:13:03.963754Z"
    },
  "state":"EXCHANGE_RESPONSE_COMPLETE",
  "exchange_response_data": ExchangeResponseData object (See the AskQuestion Documentation)
}

GENERATIVE_EXCHANGE_RESPONSE_COMPLETE

The generative exchange response is now complete. The metadata and full response object is returned. Below is an example of the JSON object when the response data has this flag.

Show code

{
    metadata: {
      uuID: 'd7e2f91e-17e9-4e28-8eeb-d3edcd5d2080',
      create_time: '2024-07-17T18:40:04.368798Z',
      update_time: '2024-07-17T18:40:04.368798Z',
      response_time_millis: 2442
    },
    state: 'GENERATIVE_EXCHANGE_RESPONSE_COMPLETE',
    generative_exchange_conversation_data: {
      data: {
        text: ' Cows drink 30-50 gallons of water each day. [1]',
        reference:  [
          {
            text_index_start: 46,
            text_index_end: 49,
            exchange_output_index: 1
           }
         ],
        generative_exchange_id: 'be2bf4ca-c437-401c-b84b-adff9804d66a',
        knowledge_domain_id: '04ff710a-5f16-4d0f-bead-168514fb9eac',
        exchange_id: 'e659fd3b-a1ea-42bd-8387-ad59ef139b9a',
        collection_id: '62bc94d7-9018-4bd1-b342-c7d75f689355'
      },
      conversation_context: '764829c8-60ea-3046-aad1-0814d7ec6ac3~d4393980-ea7c-4986-be77-6b97091218c4\n' +
        '---end-of-context---\n' +
        'How much water do cows drink\n' +
        'Cows drink 30-50 gallons of water each day.'
    }
}

GENERATIVE_EXCHANGE_INPUT_DELTA

Show code

{ 
  "state":"GENERATIVE_EXCHANGE_INPUT_DELTA",
  "exchange_input_text":"What"
  }

GENERATIVE_EXCHANGE_INPUT_COMPLETE

Show code

{ 
  "metadata": {
    "uuID":"8558510d-4276-4d64-9daf-94e470c0475f",
    "create_time":"2024-07-15T17:13:03.963754Z",
    "update_time":"2024-07-15T17:13:03.963754Z"
    },
  "state":"GENERATIVE_EXCHANGE_INPUT_COMPLETE",
  "exchange_input_text":"What is pryon"
  }

Error

Signifies an error has occurred. In this case nothing is returned except a object with the state of ERROR.

Fields for later calls

The GENERATIVE_EXCHANGE_RESPONSE_COMPLETE state contains information that other features use and are needed for later calls.

// Used for generating and updating ratings
const exchangeID = response.generative_exchange_conversation_data.data.generative_exchange_id

Example code

The following code asks a question, and prints out the exchange id from the completed generated question.

Client development

Show code

import { GenerativeExchangeResponseEvent, GenerativeExchangeResponseData, askGenerativeQuestion } from "pryon-client"

const askGenerativeExchange = () => { 
    const handleSSE = async (message: GenerativeExchangeResponseData) => { 
        if(message.state === GenerativeExchangeResponseEvent.GENERATIVE_EXCHANGE_RESPONSE_COMPLETE){ 
        console.log(message.generative_exchange_conversation_data.data) 
    } 
    } 
    const handleError = async (error: string) => {        
        throw new Error(error.toString()) 
    } 

    await askGenerativeQuestion({ 
        questionText: 'What does a cow drink?', 
        collectionID: "62bc94d7-9018-4bd1-b342-c7d75f689355", 
        sseCallback: handleSSE, 
        errorCallback: handleError, 
    }); 
}

Node development

Show code

import  { GenerativeExchangeResponseEvent, askGenerativeQuestion } from "pryon-node"

const handleSSE = async ( message ) => {
  if (message.state === GenerativeExchangeResponseEvent.GENERATIVE_EXCHANGE_RESPONSE_COMPLETE) {
    console.log(message.generative_exchange_conversation_data.data)
  }
}

const handleError = async (error) => {
  throw new Error(error.toString())
}

await askGenerativeQuestion({
  questionText: 'What does a cow drink?',
  collectionID: "62bc94d7-9018-4bd1-b342-c7d75f689355",
  sseCallback: handleSSE,
  errorCallback: handleError,
});

createGenerativeExchangeRating

Providing a rating adds feedback to a response. Ratings can be created for a specific exchange or askQuestion response using the exchangeID.

More information is available in the Generative Feedback API.

Parameters

The mandatory parameters are:

Parameters Data type Description

generativeExchangeID string ID of the exchange for which the rating is created

rating

number

Rank value or FeedbackRank provided for the output with the corresponding outputs:

'POSITIVE' = 5
'NEGATIVE' = 1

The optional parameters are:

Parameter	Data type	Description
`standardMessage`	string	Optional string input for user comments used to categorize the output, including: It was irrelevant to my question It was on the right track but didn't give me enough detail It answered my question, but the content is incorrect or outdated I have another reason
`userComment`	string	Optional freeform user comment text for feedback provider
`asUser`	string	The email of a user; allows a user to impersonate another user and is only allowed for users logged in via the `initialize` method

Function signature

Send feedback by updating variables in the following code:

Show code

rating = await createGenerativeExchangeRating({
 generativeExchangeID: generative_exchange_id,
 rating: FeedbackRank.POSITIVE,
 asUser: asUser,
})

createExchangeRating accepts the following options structure.

Show code

interface CreateGenerativeExchangeRatingOptions {
  generativeExchangeID: string,
  rating: number,
  message?: string,
  freeformText?: string,
  asUser?: string
}

Response

In the case of a successful request, the response is a GenerativeRatingItem. A request failure throws a PryonError.

Show code

{
  data: {
    metadata: {
      uuid: '4a24b285-934f-4ef4-9f2e-ad1ee8d5b7b6',
      create_time: '2024-07-23T16:51:14.000366Z',
      update_time: '2024-07-23T16:51:14.000366Z',
      response_time_millis: 73
    },
    data: {
      rating_id: '8d01f472-d31b-4444-860f-c1f46fac86fa',
      generative_exchange_id: 'b87a7e8a-5363-49b6-be62-b374e4aa28ce',
      creator_id: 'JwvJAxmaDGX4B4GolA4MO8DCV51XeQxi',
      rank: 5,
      message: 'Positive feedback'
    }
  }
}

Fields for later calls

// Used for updating and deleting ratings
const ratingID = response.data.data.rating_id

Example code

The following code submits a positive Feedback rating for a generative exchange.

Client development

Show code

import { FeedbackRank, login, askGenerativeQuestion, createGenerativeExchangeRating, GenerativeExchangeResponseEvent } from "pryon-client"

const handleSSE = async (message) => {
    console.log(message)
    if (message.state === GenerativeExchangeResponseEvent.GENERATIVE_EXCHANGE_RESPONSE_COMPLETE) {
        const createRating = await createGenerativeExchangeRating({
            generativeExchangeID: message?.generative_exchange_conversation_data?.data?.generative_exchange_id,
            rating: FeedbackRank.POSITIVE
        })
        console.log(createRating)
    }
}
const handleError = async (error) => {
    throw new Error(error.toString())
}

await askGenerativeQuestion({
    questionText: 'What does a cow drink?',
    collectionID: '62bc94d7-9018-4bd1-b342-c7d75f689355',
    sseCallback: handleSSE,
    errorCallback: handleError,
});

Node development

Show code

import  { FeedbackRank, login, askGenerativeQuestion, createGenerativeExchangeRating, GenerativeExchangeResponseEvent } from "pryon-node"

const handleSSE = async (message) => {
    console.log(message)
    if (message.state === GenerativeExchangeResponseEvent.GENERATIVE_EXCHANGE_RESPONSE_COMPLETE) {
        const createRating = await createGenerativeExchangeRating({
            generativeExchangeID: message?.generative_exchange_conversation_data?.data?.generative_exchange_id,
            rating: FeedbackRank.POSITIVE
        })
        console.log(createRating)
    }
}
const handleError = async (error) => {
    throw new Error(error.toString())
}

await askGenerativeQuestion({
    questionText: 'What does a cow drink?',
    collectionID: '62bc94d7-9018-4bd1-b342-c7d75f689355',
    sseCallback: handleSSE,
    errorCallback: handleError,
});

updateGenerativeExchangeRating

A rating can be updated for a specific exchange or askQuestion response using the generativeExchangeID and the ratingID. Only existing ratings can be updated.

Parameters

The mandatory parameters are:

Parameter	Data type	Definition
`ratingID`	string	ID of the created rating

The optional parameters are:

Parameter	Data type	Definition
`generativeExchangeID`	string	Optional string input of ID of the generative exchange for which the rating is created
`rating`	string	Rank value or `FeedbackRank` provided for the output with the corresponding outputs: `'POSITIVE' = 5` `'NEGATIVE' = 1` Either rating, `standardMessage`, or `userComment` must be input
`standardMessage`	string	String input for user comments. Typically used to categorize the output. Common categories include: It was irrelevant to my question It was on the right track but didn't give me enough detail It answered my question, but the content is incorrect or outdated I have another reason Either rating, `standardMessage`, or `userComment` must be input
`userComment`	string	Freeform user comment for feedback provider
`asUser`	string	The email of a user; allows a user to impersonate another user and is only allowed for users logged in via the `initialize` method

Function signature

Update a rating by adjusting variables in the following code:

Show code

await createGenerativeExechangeRating({
  generativeExchangeID: generative_exchange_id,
  rating: FeedbackRank.POSITIVE,
  asUser: user,
})

updateExchangeRating accepts the following options structure.

Show code

interface CreateGenerativeExchangeRatingOptions {
  ratingID: string,
  generativeExchangeID: string,
  rating: number,
  message?: string,
  freeformText?: string,
  asUser?: string,
}

Response

In the case of a successful request, the response is an GenerativeRatingItem. A request failure throws a PryonError.

Show code

{
  data: {
    metadata: {
      uuid: '4a24b285-934f-4ef4-9f2e-ad1ee8d5b7b6',
      create_time: '2024-07-23T16:51:14.000366Z',
      update_time: '2024-07-23T16:51:14.000366Z',
      response_time_millis: 73
    },
    data: {
      rating_id: '8d01f472-d31b-4444-860f-c1f46fac86fa',
      generative_exchange_id: 'b87a7e8a-5363-49b6-be62-b374e4aa28ce',
      creator_id: 'JwvJAxmaDGX4B4GolA4MO8DCV51XeQxi',
      rank: 5,
      message: 'Positive feedback'
    }
  }
}

Example code

The following code updates a rating.

Client development

Show code

import { FeedbackRank, updateGenerativeExchangeRating } from "pryon-client"

const updateRating = await updateGenerativeExchangeRating({ 
    ratingID: createRating.data.data.rating_id,
    generativeExchangeID: message.generative_exchange_conversation_data.data.generative_exchange_id, 
    rating: FeedbackRank.NEGATIVE,     
  })

Node development

Show code

const  { FeedbackRank, updateGenerativeExchangeRating } = require("pryon-node")

const updateRating = await updateGenerativeExchangeRating({ 
  ratingID: createRating.data.data.rating_id,
  generativeExchangeID: message.generative_exchange_conversation_data.data.generative_exchange_id, 
  rating: FeedbackRank.NEGATIVE,             
});

deleteGenerativeExchangeRating

A rating can be deleted for a specific exchange or askQuestion response using the generativeExchangeID. Only existing ratings can be deleted.

After authentication, initialization, asking a question and creating a rating, the user may delete a rating. The user may not delete a rating that has not been created or a rating that has been previously deleted.

Delete a rating by updating variables in the following code:

Show code

response = await deleteGenerativeExchangeRating({
 ratingID: rating_id,
 asUser: asUser,
})

deleteExchangeRating accepts the following options structure:

Show code

interface DeleteGenerativeExchangeRatingOptions {
  ratingID: string,
  asUser?: string
}

Parameters

The mandatory parameters are:

Parameter	Data type	Description
`ratingID`	string	ID of the rating to be deleted

The optional parameters are:

Parameter	Data type	Definition
`asUser`	string	The email of a user; allows a user to impersonate another user and is only allowed for users logged in via the `initialize` method

Response

Deleting a rating does not return a response. A request failure throws a PryonError.

The following code deletes a rating.

Example code

Client Development

Show code

import { FeedbackRank, deleteGenerativeExchangeRating } from "pryon-client"

const deleteRating = await deleteGenerativeExchangeRating({
    ratingID: createRating.data.data.rating_id,
})

Node Development

Show code

const  { FeedbackRank, deleteGenerativeExchangeRating } = require("pryon-node")

const deleteRating = await deleteGenerativeExchangeRating({
    ratingID: createRating.data.data.rating_id,
})