AWS nova documentation change
Summary
Added detailed implementation examples for chat history events, clarified transcript handling requirements, and introduced best practices for storing FINAL vs SPECULATIVE outputs
Security assessment
The changes emphasize proper handling of conversation transcripts and distinguish between FINAL/SPECULATIVE outputs, which helps prevent inaccurate history logging. While this improves data integrity, there's no evidence of addressing a specific security vulnerability. Security documentation is added through best practices for auditing and conversation preservation.
Diff
diff --git a/nova/latest/nova2-userguide/sonic-chat-history.md b/nova/latest/nova2-userguide/sonic-chat-history.md index 0bc6cee6a..f39a59f26 100644 --- a//nova/latest/nova2-userguide/sonic-chat-history.md +++ b//nova/latest/nova2-userguide/sonic-chat-history.md @@ -10,0 +11,9 @@ Amazon Nova 2 Sonic responses include ASR (Automatic Speech Recognition) transcr +Refer to the following resources for more information on managing chat history: + + 1. [Logging chat history](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/chat-history-logger) + + 2. [Resuming conversations](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/resume-conversation) + + + + @@ -13 +22 @@ Amazon Nova 2 Sonic responses include ASR (Automatic Speech Recognition) transcr -A conversation history can be included only once, after the system/speech prompt and before audio streaming begins. Overall chat history cannot be larger than 40KB. +A conversation history can be included only once, after the system/speech prompt and before audio streaming begins. Overall chat history cannot be larger than 40KB. The following diagram shows when chat history is passed in during the event lifecycle: @@ -22,0 +32,15 @@ Each historical message requires three events: `contentStart`, `textInput` and ` + { + "event": { + "contentStart": { + "promptName": "<prompt-id>", + "contentName": "<content-id>", + "type": "TEXT", + "interactive": true, + "role": "ASSISTANT", + "textInputConfiguration": { + "mediaType": "text/plain" + } + } + } + } + @@ -24,0 +49,10 @@ Each historical message requires three events: `contentStart`, `textInput` and ` + { + "event": { + "textInput": { + "promptName": "<prompt-id>", + "contentName": "<content-id>", + "content": "Take your time, Don. I'll be here when you're ready." + } + } + } + @@ -26,0 +61,9 @@ Each historical message requires three events: `contentStart`, `textInput` and ` + { + "event": { + "contentEnd": { + "promptName": "<prompt-id>", + "contentName": "<content-id>" + } + } + } + @@ -34 +77 @@ Repeat these three events for each message in your chat history, alternating bet - * Chat history can only be included once per session + * Chat history can only be included **once** per session @@ -36 +79 @@ Repeat these three events for each message in your chat history, alternating bet - * Chat history must be sent after the system prompt and before audio streaming begins + * Chat history must be sent **after the system prompt** and **before audio streaming begins** @@ -49 +92,76 @@ Repeat these three events for each message in your chat history, alternating bet -Amazon Nova 2 Sonic provides transcripts for both user speech and assistant responses. These transcripts should be stored for chat history management. +During a conversation, Amazon Nova 2 Sonic sends ASR transcripts through output events. Each transcript is delivered as a sequence of three events: contentStart, textOutput, and contentEnd. + +**Example: User speech transcript:** + +1\. contentStart - Indicates the beginning of a transcript: + + + { + "event": { + "contentStart": { + "additionalModelFields": "{\"generationStage\":\"FINAL\"}", + "completionId": "<completion-id>", + "contentId": "<content-id>", + "promptName": "<prompt-id>", + "role": "USER", + "sessionId": "<session-id>", + "textOutputConfiguration": { + "mediaType": "text/plain" + }, + "type": "TEXT" + } + } + } + +2\. textOutput - Contains the actual transcript content: + + + { + "event": { + "textOutput": { + "completionId": "<completion-id>", + "content": "hello how are you", + "contentId": "<content-id>", + "promptName": "<prompt-id>", + "role": "USER", + "sessionId": "<session-id>" + } + } + } + +3\. contentEnd - Marks the end of the transcript: + + + { + "event": { + "contentEnd": { + "completionId": "<completion-id>", + "contentId": "<content-id>", + "promptName": "<prompt-id>", + "sessionId": "<session-id>", + "stopReason": "PARTIAL_TURN", + "type": "TEXT" + } + } + } + +The same three-event pattern applies for both USER and ASSISTANT roles. Extract the `content` field from the `textOutput` event and the `role` field from the `contentStart` event to build your chat history. + +## Best practices + +Always store chat history to enable: + + * Session resumptions across difference devices + + * Conversation logging and auditing + + * Context preservation for follow-up interactions + + + + +Important: When saving chat history, use text outputs based on their generationStage: + + * Speculative - A preview of what Nova 2 Sonic plans to say, generated before audio synthesis begins + + * Final - The actual sentence-level transcription of what was spoken in the audio response @@ -51 +168,0 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp -**User transcripts:** Appear in `textOutput` events with `role: "USER"` and `generationStage: "FINAL"`. @@ -53 +169,0 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp -**Assistant transcripts:** Appear in `textOutput` events with `role: "ASSISTANT"` and `generationStage: "FINAL"` after audio generation completes. @@ -55 +170,0 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp -## Best practices @@ -57 +172 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp - * Store transcripts from both USER and ASSISTANT roles +Always save the FINAL text output to your chat history, as it represents the accurate record of the conversation. @@ -59 +174 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp - * Monitor total chat history size and trim if approaching 40KB limit +Example of FINAL output (save this to chat history): @@ -61 +175,0 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp - * Implement session recovery logic to resume conversations after disconnections @@ -63 +177,8 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp - * Use FINAL transcripts for accurate chat history, not SPECULATIVE ones + ContentStart event: { + "additionalModelFields": "{\"generationStage\":\"FINAL\"}", + "completionId": "<completion-id>", + "contentId": "<content-id>", + "role": "ASSISTANT", + "sessionId": "<session-id>", + "type": "TEXT" + } @@ -64,0 +186 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp +Example of SPECULATIVE output (optional preview, not for history): @@ -66,0 +189,8 @@ Amazon Nova 2 Sonic provides transcripts for both user speech and assistant resp + ContentStart event: { + "additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}", + "completionId": "<completion-id>", + "contentId": "<content-id>", + "role": "ASSISTANT", + "sessionId": "<session-id>", + "type": "TEXT" + }