QConnect / Client / get_recommendations

get_recommendations#

QConnect.Client.get_recommendations(**kwargs)#

Retrieves recommendations for the specified session. To avoid retrieving the same recommendations in subsequent calls, use NotifyRecommendationsReceived. This API supports long-polling behavior with the waitTimeSeconds parameter. Short poll is the default behavior and only returns recommendations already available. To perform a manual query against an assistant, use QueryAssistant.

Request Syntax

response = client.get_recommendations(
    assistantId='string',
    maxResults=123,
    sessionId='string',
    waitTimeSeconds=123
)

Parameters:

assistantId (string) –
[REQUIRED]

The identifier of the Amazon Q assistant. Can be either the ID or the ARN. URLs cannot contain the ARN.
maxResults (integer) – The maximum number of results to return per page.
sessionId (string) –
[REQUIRED]

The identifier of the session. Can be either the ID or the ARN. URLs cannot contain the ARN.
waitTimeSeconds (integer) – The duration (in seconds) for which the call waits for a recommendation to be made available before returning. If a recommendation is available, the call returns sooner than WaitTimeSeconds. If no messages are available and the wait time expires, the call returns successfully with an empty list.

Return type:

dict

Returns:

Response Syntax

{
    'recommendations': [
        {
            'data': {
                'details': {
                    'contentData': {
                        'rankingData': {
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW',
                            'relevanceScore': 123.0
                        },
                        'textData': {
                            'excerpt': {
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ],
                                'text': 'string'
                            },
                            'title': {
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ],
                                'text': 'string'
                            }
                        }
                    },
                    'generativeData': {
                        'completion': 'string',
                        'rankingData': {
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW',
                            'relevanceScore': 123.0
                        },
                        'references': [
                            {'... recursive ...'},
                        ]
                    },
                    'sourceContentData': {
                        'id': 'string',
                        'rankingData': {
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW',
                            'relevanceScore': 123.0
                        },
                        'textData': {
                            'excerpt': {
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ],
                                'text': 'string'
                            },
                            'title': {
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ],
                                'text': 'string'
                            }
                        },
                        'type': 'KNOWLEDGE_CONTENT'
                    }
                },
                'reference': {
                    'contentReference': {
                        'contentArn': 'string',
                        'contentId': 'string',
                        'knowledgeBaseArn': 'string',
                        'knowledgeBaseId': 'string'
                    },
                    'generativeReference': {
                        'generationId': 'string',
                        'modelId': 'string'
                    }
                }
            },
            'document': {
                'contentReference': {
                    'contentArn': 'string',
                    'contentId': 'string',
                    'knowledgeBaseArn': 'string',
                    'knowledgeBaseId': 'string'
                },
                'excerpt': {
                    'highlights': [
                        {
                            'beginOffsetInclusive': 123,
                            'endOffsetExclusive': 123
                        },
                    ],
                    'text': 'string'
                },
                'title': {
                    'highlights': [
                        {
                            'beginOffsetInclusive': 123,
                            'endOffsetExclusive': 123
                        },
                    ],
                    'text': 'string'
                }
            },
            'recommendationId': 'string',
            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW',
            'relevanceScore': 123.0,
            'type': 'KNOWLEDGE_CONTENT'|'GENERATIVE_RESPONSE'|'GENERATIVE_ANSWER'
        },
    ],
    'triggers': [
        {
            'data': {
                'query': {
                    'text': 'string'
                }
            },
            'id': 'string',
            'recommendationIds': [
                'string',
            ],
            'source': 'ISSUE_DETECTION'|'RULE_EVALUATION'|'OTHER',
            'type': 'QUERY'|'GENERATIVE'
        },
    ]
}

Response Structure

(dict) –
- recommendations (list) –
  
  The recommendations.
  - (dict) –
    
    Information about the recommendation.
    - data (dict) –
      
      Summary of the recommended content.
      - details (dict) –
        
        Details about the data.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: contentData, generativeData, sourceContentData. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        contentData (dict) –
        
        Details about the content data.
        
        rankingData (dict) –
        
        Details about the content ranking data.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        textData (dict) –
        
        Details about the content text data.
        
        excerpt (dict) –
        
        The text of the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
        
        title (dict) –
        
        The text of the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
        
        generativeData (dict) –
        
        Details about the generative data.
        
        completion (string) –
        
        The LLM response.
        
        rankingData (dict) –
        
        Details about the generative content ranking data.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        references (list) –
        
        The references used to generative the LLM response.
        
        (dict) –
        
        Summary of the data.
        
        sourceContentData (dict) –
        
        Details about the content data.
        
        id (string) –
        
        The identifier of the source content.
        
        rankingData (dict) –
        
        Details about the source content ranking data.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        textData (dict) –
        
        Details about the source content text data.
        
        excerpt (dict) –
        
        The text of the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
        
        title (dict) –
        
        The text of the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
        
        type (string) –
        
        The type of the source content.
      - reference (dict) –
        
        Reference information about the content.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: contentReference, generativeReference. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        contentReference (dict) –
        
        Reference information about the content.
        
        contentArn (string) –
        
        The Amazon Resource Name (ARN) of the content.
        
        contentId (string) –
        
        The identifier of the content.
        
        knowledgeBaseArn (string) –
        
        The Amazon Resource Name (ARN) of the knowledge base.
        
        knowledgeBaseId (string) –
        
        The identifier of the knowledge base. This should not be a QUICK_RESPONSES type knowledge base if you’re storing Amazon Q Content resource to it.
        
        generativeReference (dict) –
        
        Reference information about the generative content.
        
        generationId (string) –
        
        The identifier of the LLM model.
        
        modelId (string) –
        
        The identifier of the LLM model.
    - document (dict) –
      
      The recommended document.
      - contentReference (dict) –
        
        A reference to the content resource.
        
        contentArn (string) –
        
        The Amazon Resource Name (ARN) of the content.
        
        contentId (string) –
        
        The identifier of the content.
        
        knowledgeBaseArn (string) –
        
        The Amazon Resource Name (ARN) of the knowledge base.
        
        knowledgeBaseId (string) –
        
        The identifier of the knowledge base. This should not be a QUICK_RESPONSES type knowledge base if you’re storing Amazon Q Content resource to it.
      - excerpt (dict) –
        
        The excerpt from the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
      - title (dict) –
        
        The title of the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        text (string) –
        
        Text in the document.
    - recommendationId (string) –
      
      The identifier of the recommendation.
    - relevanceLevel (string) –
      
      The relevance level of the recommendation.
    - relevanceScore (float) –
      
      The relevance score of the recommendation.
    - type (string) –
      
      The type of recommendation.
- triggers (list) –
  
  The triggers corresponding to recommendations.
  - (dict) –
    
    A recommendation trigger provides context on the event that produced the referenced recommendations. Recommendations are only referenced in recommendationIds by a single RecommendationTrigger.
    - data (dict) –
      
      A union type containing information related to the trigger.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: query. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - query (dict) –
        
        Data associated with the QUERY RecommendationTriggerType.
        
        text (string) –
        
        The text associated with the recommendation trigger.
    - id (string) –
      
      The identifier of the recommendation trigger.
    - recommendationIds (list) –
      
      The identifiers of the recommendations.
      - (string) –
    - source (string) –
      
      The source of the recommendation trigger.
      - ISSUE_DETECTION: The corresponding recommendations were triggered by a Contact Lens issue.
      - RULE_EVALUATION: The corresponding recommendations were triggered by a Contact Lens rule.
    - type (string) –
      
      The type of recommendation trigger.

Exceptions

QConnect.Client.exceptions.ValidationException
QConnect.Client.exceptions.AccessDeniedException
QConnect.Client.exceptions.ResourceNotFoundException