Generative for Python – Pryon Help

ask_generative_question

ask_generative_question sends a request containing the query (questionText), as well as 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. This allows you to display the answer in real time, printing across the screen like a typewriter.

Ask a question by updating variables in the following code:

Show code

generative_answer = ''
async for chunk in pryon.ask_generative_question("who is gandalf", <collection_ID>):
  generative_answer += chunk.answer_text_chunk

Parameters

Mandatory parameters are:

Parameter Data type Definition

question_text string Input query, or question being asked

collection_id

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

Optional parameters are:

Parameter	Data type	Definition
`max_extractive_outputs`	number	The maximum number of extractive outputs to use when generating an answer.
`tag_id`	array	An array of tag IDs for filtering. Defaults to [] if not provided. For more information, see Using Tags.
`content_group_id`	array	An array of content group IDs for filtering. Defaults to [] if not provided.
`conversation_context`	string	Obtained from the previous response Enhances the generative response
`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
`min_answers_in_context_score`	number	Sets the minimum score of the AICs to be considered when generating a response
`delta_beam_cutoff`	number	Maximum allowable AIC score delta from the highest score to be considered when generating a response
`verified_answer_threshold`	number	Verified answer threshold to be considered as a final answer
`out_of_domain_score_threshold`	number	Best answer score threshold that out of domain message should be returned as a final answer
`out_of_domain_message`	string	Best answer score threshold that out of domain message should be returned as a final answer

Response

In the case of a successful request, the response is an AsyncGenerator of the corresponding GenerativeExchangeItemChunk.

Note: Optional fields may not be present on every chunk, for example, generative_exchange_id, context, and reference are only present on the final chunk.

The extractive_answers field contains a list of responses from the retrieval step used as the basis for the generative answer.

Below is a representation of a GenerativeExchangeItemChunk in JSON. The actual response is structured using a number of nested Python dataclass objects.

In case of an error, the generator will yield an PryonError instead of a GenerativeExchangeItemChunk.

Show code

{
  collection_id:
  knowledge_domain_id:
  exchange_id: 
  question: {
    text: 
  },
  extractive_answers: [
    {
      output_id:
      summary_text:
      subject_ids: []
      attachments: {
        [attachment_name]: {
          content_type:
          content:
        }
      }
      context: {}
    }
  ]
  answer_text_chunk:
  cumulative_answer_text:
  generative_exchange_id:
  context:
  reference: {
    text_index_start:
    text_index_end:
    exchange_output_index:
  }
}

Example code

This code authenticates, asks a question, and iterates over the chunks of the generative answer as they are received from the API to obtain the full answer text and metadata.

Show code

import pryon
from pryon.types.errors import PryonError
  
async def main():
  await pryon.login(<clientId>, <secret>)
  
  generative_answer_chunks = pryon.ask_generative_question(
      "Who founded Pryon?",
      <collection_id>,
      max_extractive_outputs=4,
      generative_conversation_parameters=pryon.GenerativeConversationParameters(
          randomness=0.3,
          min_answers_in_context_score=0.5,
          delta_beam_cutoff=0.12,
      ),
  )
  
  answer_text = ''
  generative_exchange_id = None
  async for chunk in generative_answer_chunks:
    if isinstance(chunk, PryonError):
      return # handle the exception in some way
    answer_text += chunk.answer_text_chunk
    generative_exchange_id = chunk.generative_exchange_id

create_generative_exchange_rating

Providing a rating adds feedback to a generative answer. You can create, update, or delete a rating.

A rating can be created for a specific exchange or ask_generative_question response using the exchangeID.

Show code

rating = await pryon.create_generative_exchange_rating(
  gen_exchange.generative_exchange_id,
  FeedbackRank.POSITIVE,
  "Answers my question",
)

Parameters

The mandatory parameters are:

Parameters Data type Description

generative_exchange_id 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
`message`	string	Optional user comment which provides additional context on the rating
`freeform_text`	string	Optional freeform user comment text for feedback provider

Response

In the case of a successful request, the response is an GenerativeExchangeRatingOutput.

Show code

@dataclass
class GenerativeExchangeRatingOutput:
    rating_id: str
    generative_exchange_id: str
    create_time: DateTimePattern['%Y-%m-%dT%H:%M:%SZ']

    exchange_output_ids: Optional[list[str]] = None
    rank: Optional[int] = None
    freeform_text: Optional[str] = None
    creator_id: Optional[str] = None
    question: Optional[str] = None
    message: Optional[str] = None
    update_time: Optional[Annotated[datetime, Pattern('%Y-%m-%dT%H:%M:%SZ')]] = None

Example code

This code authenticates, asks a generative question about Pryon, and submits a positive Feedback rating for the generative output.

Show code

import pryon
from pryon.types.errors import PryonError
  
async def main():
  await pryon.login(<clientId>, <secret>)
  
  generative_answer_chunks = pryon.ask_generative_question(
      "Who founded Pryon?",
      <collection_id>,
      max_extractive_outputs=4,
      generative_conversation_parameters=pryon.GenerativeConversationParameters(
          randomness=0.3,
          min_answers_in_context_score=0.5,
          delta_beam_cutoff=0.12,
      ),
  )
  
  answer_text = ''
  async for chunk in generative_answer_chunks:
    if isinstance(chunk, PryonError):
      return # handle the exception in some way
    answer_text += chunk.answer_text_chunk
    
  rating = await pryon.create_generative_exchange_rating(
    chunk.generative_exchange_id, # this will pull the id from the last chunk
    FeedbackRank.POSITIVE,
    "good answer",
    "at least I think so",
  )

update_generative_exchange_rating

An existing generative rating can be updated using the rating_id and the generative_exchange_id of the associated exchange. Both of these can be attained from the response to the create_generative_exchange_rating.

Below is an example of how to update a rating.

Show code

rating = await pryon.update_generative_exchange_rating(
  rating.rating_id, # you can get this from the result of `create_generative_exchange_rating`
  FeedbackRank.NEGATIVE,
  "Responses did not answer my question",
)

Parameters

The mandatory parameters are:

Parameter	Data type	Description
`rating_id`	string	ID of the created rating

The optional parameters are:

Parameter	Data type	Description
`rating`	number	Rank value or `FeedbackRank` provided for the output
`message`	string	Optional user comment which provides additional context on the rating
`freeform_text`	string	Optional freeform user comment text for feedback provider

Note: Either rating or message must be specified, or the update will fail.

Response

In the case of a successful request, the response is a GenerativeExchangeRatingOutput.

delete_generative_exchange_rating

A generative rating can be deleted using the rating_id. 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.

Below is an example of how to delete a rating.

Show code

await pryon.delete_generative_exchange_rating(rating.rating_id)

Parameters

The mandatory parameters are:

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

In the case of a successful request, None is returned.