Merge branch 'develop' v0.7.4

CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.4] - 2023-12-15
+### Added
+- Drag/drop upload from call list page
+- Refresh call summary from call details page
+
+### Fixed
+- Accessibility improvements
+
 ## [0.7.3] - 2023-10-11
 ### Fixed
 - #187 - Got error message in PostCallAnalyticsWorkflow step function

README.md

@@ -318,7 +318,7 @@ Our companion solution, Live Call Analytics and Agent Assist (LCA), offers real-
 
 Check out the AWS blog post: [Post call analytics for your contact center with Amazon language AI services](https://www.amazon.com/post-call-analytics)
 
-PCA documentation and tutorials are available here: [Post Call Analytics](https://catalog.us-east-1.prod.workshops.aws/v2/workshops/2031cf73-22de-40c4-899a-5e4abd940e9a/en-US) 
+PCA documentation and tutorials are available here: [Post Call Analytics](./docs) 
 
 Also check out the companion sample solution - [Live call analytics for your contact center with Amazon language AI services](https://www.amazon.com/live-call-analytics). Live Call Analytics (LCA), offers real time-transcription and analytics capabilities by using the Amazon Transcribe and Amazon Comprehend real-time APIs. Unlike PCA, which transcribes and analyzes recorded audio after the call has ended, LCA transcribes and analyzes your calls as they are happening and provides real-time updates to supervisors and agents. You can configure LCA to store call recordings to the PCA’s ingestion S3 bucket, and use the two solutions together to get the best of both worlds. See Live call analytics for your contact center with Amazon language AI services for more information.
 

docs/README.md

@@ -0,0 +1,41 @@
+# CCI Post-Call Analytics
+
+![CCI headline banner](./images/banner.png)
+
+#### Why do we need Post-Call Analytics?!
+
+The AWS CCI Post-Call Analytics solution helps drive deeper quality management insights through automatic analysis of contact-center conversations, generating actionable insights such as product and service feedback loops that can be used to benefit the rest of the organization, or the best performing interactions such as those ending with a positive sentiment score.
+
+Typical areas of information that an organization's contact centers needs to know of their customers, and why they need it, are:
+
+| ![Who are you](./images/who-are-you.png) | ![What do you need](./images/what-do-you-need.png) | ![How did we do](./images/how-did-we-do.png) | ![Where can we improve](./images/where-to-improve.png) |
+| --- | --- | --- | --- |
+| **Who are you?** | **What do you need?** | **How did we do?** | **Where can we improve?** |
+| Accessing relevant customer data is crucial to problem resolution | Identifying problems correctly and efficiently impacts customer sentiment | Measuring how well the problem was handled and its impact on loyalty / retention | Analyzing the data to improve the customer experience and the bottom line |
+
+Today every experience we face is defined by the best consumer experiences we know. We also judge all that we do with an unconscious bias, and invariably compare these to the brands we are loyal too. With an AI-enabled post-call analytics solution and your preferred Business Intelligence reporting tool you can answer these questions, which can then help you generate positive outcomes such as:
+
+-   Improved quality management with contact center call resolution insights
+-   More efficient call review process
+-   Development of better scorecards to assess agent performance
+-   Targetted agent training and reinforcement
+
+#### Documentation structure
+
+The documentation is split into the following sections, walking through the installaion, configuration and running of the solution. It then continues into deeper-dives behind the scenes around how it works, how to further customise it, and then information about the underlying architecture and solution workflows.
+
+| Section | Description |
+| --- | --- |
+| [Introduction](./introduction/README.md) | An overview of all of the features of the Post-Call Analytics solution |
+| [Deployment](./deployment/README.md) | Installation and configuration instructions, along with an overview of the default data that can optionally be deployed |
+| User interface | Walkthrough of various user interface screens, as well as discussing application user management |
+| [Audio ingestion](./ingestion/README.md) | How to ingest audio files into the solution and how any errors will be handled, |
+| [Customization](./customization/README.md) | How to improve the accuracy of the transcriptions with your domain-specific words, and how to identify entities of interest |
+| [Generative AI](./generative_ai.md) | How you can use Amazon Bedrock to generate customized insights and detect topics without training a machine learning model |
+| [Output JSON structure](./output_json_structure.md) | Documentation on the main PCA JSON data format |
+| System architecture (WIP) | An overview of the server-side architectural components and data flows, along with details of the operational workflows |
+| Search and Reporting (WIP) | How to configure and use both the Amazon Kendra companion search application and Amazon QuickSight to help give you further insights into your customer call data |
+
+#### AWS Contact Center Intelligence
+
+For further details on every aspect of the AWS Contact Centre Intelligence solutions, including additional resources, Partner information and customer references, please visit the dedicated web page [here](https://aws.amazon.com/machine-learning/contact-center-intelligence/).

docs/customization/README.md

@@ -0,0 +1,10 @@
+
+
+#### Language service customisation 
+
+The primary AWS AI services used in this application are Amazon Transcribe and Amazon Comprehend, and this application is able to not only take advantage of some of their standard features but is also able to support a number of their language cusomisation features. This section deals with how you can define a simple configuration for such customisations yet still support multiple languages.
+
+| Documentation Section | Description |
+| --- | --- |
+| [Custom vocabulary](./custom-vocab.md) | How to configure the application for multi-language custom vocabulary support |
+| [Entity detection](./entity-detection.md) | How to configure the use of an Amazon Comprehend custom entity model for entity detection, or if that is not available how to use a simple string matching technique instead |

docs/customization/custom-vocab.md

@@ -0,0 +1,62 @@
+
+
+#### Custom vocabulary
+
+The [Custom Vocabulary](https://docs.aws.amazon.com/transcribe/latest/dg/custom-vocabulary.html)  feature of Amazon Transcribe allows customers to make the service pay particular attention to domain-specific words that they need to be correctly transcribed - typically this is brand names, internal project names, or common colloquial terms.
+
+**Custom vocabulary file format**
+
+The file format for this is a TAB-separated text file. This contains a single header line and four columns - it must be stressed that even if a column value for a particular row is blank then you must still tab to it, and you must not use space characters to line things up visually. An example few lines are shown below, but note that the columns are allowed to appear in any order in your file.
+
+| Phrase | DisplayAs | SoundsLike | IPA |
+| --- | --- | --- | --- |
+| Los-Angeles | Los Angeles |  | ɛ f b i aɪ |
+| F.B.I. | FBI |  |  |
+| Etienne |  | eh-tee-en |  |
+
+Only data in the **Phrase** column is mandatory, but the other columns must be present with at least a blank data entry. You can have data in one of either **SoundsLike** or **IPA** (but not both), and **DisplayAs** is used if you want the transcribed text displayed in a way different from **Phrase**. There are many rules that you have to adhere to:
+
+-   Any space character in a multi-word **Phrase** must be replaced by a `-`
+-   Any pronounced letters in a **Phrase**, such as in acronyms like F.B.I., must have a `.` after each letter
+-   Plurals of an acronym **Phrase** must separate out the `'s` from the acronym with a `-` (such as `FBIs` => `F.B.I.-s)`
+-   A **Phrase** that consists of a word and acronym must separate those sections with a `-` (such as `DynamoDB` => `Dynamo-D.B.)`
+-   Each sound hint in a **SoundsLike** field must be separated by a `-`
+-   **IPA** characters, or valid IPA character pairs, must be separated by a space
+-   There should be no leading or trailing spaces in any column
+
+This guide cannot teach someone how to build phonetic representations - the Amazon Transcribe documentation contains all necessary technical details. For further assistance and guidance on building your own vocabulary files, please contact your AWS account team.
+
+
+##### Custom vocabulary application configuration
+
+The application lets you configure a base name for your vocabularies in the configuration setting `VocabularyName`. This becomes the base name for all vocabulary files defined in Amazon Transcribe that will be used by the application, allowing you to define multiple language variants of the same vocabulary. For instance, if you configure the base name as **prod-vocab** then the application will try and use a Transcribe Custom Vocabulary as follows:
+
+![Custom vocabulary naming](../images/vocab-naming.en.png)
+
+Hence, whenever a file is processed, then the application will attempt to use vocabulary based upon the configured base name and the specified or identified language code, with the language code always appearing in lower-case. This means that for one installation you only have to make a single configuration setting for the vocabulary, such as `prod-vocab`, and the application will use the appropriate language-specific variant, such as `prod-vocab-es-us`.
+
+If the custom vocabulary language variant does not exist, such as **prod-vocab-es-us** not being defined, then audio files files ingested in the language `es-US` will be processed without any custom vocabulary - this will be indicated in the _Call Details_ screen for that call, as the **Custom Vocabulary** field will show `-` rather than the name of the vocabulary used.
+
+
+##### Creating a custom vocabulary in Amazon Transcribe
+
+The vocabulary file, with the relevant language suffix, needs to be uploaded to an S3 bucket. There is no restriction on this bucket, but it is recommended that you use the bucket defined in the `SupportFilesBucketName` configuration setting, which is used for other ancillary files such as entity files for entity recognition. Whilst it isn't mandatory, we also recommend that you name the files such that they match the vocabulary base name and the target language, so for the Spanish file in the above example we would recommend that the file is called **prod-vocab-es-us.txt** - you may end up have multiple language variant files in this bucket, so following this convention will make them easier to manage.
+
+Creation of multiple custom vocabulary files
+
+You will need to repeat this process once per language where you need Custom Vocabulary support
+
+Once uploaded then you need to navigate to the Amazon Transcribe section of the AWS Console and, on the left-hand menu, select _Custom vocabulary_. Hit the **Create vocabulary** button and you will be presented with this screen:
+
+![Create custom vocabulary](../images/create-vocab.en.png)
+
+Enter the parameters as follows:
+
+-   **Name** - the name of the vocabularly variant, matching the language naming convention
+-   **Language** - the language that this vocabulary variant will support
+-   **Vocabulary input source** - select _S3 Location_ as the input source, as table-formatted vocabulary files can only be imported from an S3 source locations
+-   **Vocabulary file location on S3** - use the _Browse S3_ button to file your uploaded file
+
+Amazon Transcribe will then begin the vocabulary generation process once you press the _Create vocabulary_ button, and it can take take several minutes to process. If there are any errors in the file, most likely in the IPA sections, then the process will terminate quickly with an error that should tell you roughly what the problem is with your file.
+
+For further assistance with any errors, please contact AWS Support.

docs/customization/entity-detection.md

@@ -0,0 +1,86 @@
+#### Standard entity detection
+
+Amazon Comprehend provides a [pre-built API](https://docs.aws.amazon.com/comprehend/latest/dg/how-entities.html)  to detect number of known entities within a block of text.
+
+| Type | Description |
+| --- | --- |
+| COMMERCIAL\_ITEM | A branded product |
+| DATE | A full date (for example, 11/25/2017), day (Tuesday), month (May), or time (8:30 a.m.) |
+| EVENT | An event, such as a festival, concert, election, etc. |
+| LOCATION | A specific location, such as a country, city, lake, building, etc |
+| ORGANIZATION | Large organizations, such as a government, company, religion, sports team, etc. |
+| OTHER | Entities that don't fit into any of the other entity categories |
+| PERSON | Individuals, groups of people, nicknames, fictional characters |
+| QUANTITY | A quantified amount, such as currency, percentages, numbers, bytes, etc. |
+| TITLE | An official name given to any creation or creative work, such as movies, books, songs, etc. |
+
+The application will send each segment of text from each speaker to Amazon Comprehend to detect any of these entities, and then embed tags for any detected entity within the output transcript of the call. By default, all of these entities are detected, but you are able to remove individual types from the detection process. This is done by changing the value for the `EntityTypes` configuration parameter, using the values shown in the [Configuration](../deployment/configuration.md#comprehend) section. For instance, if you are only interested in organization names, locations and dates the you would set his paramater to `ORGANIZATION | LOCATION | DATE`, noting the spaces between each term and the `|` character.
+
+
+#### Custom entity detection options
+
+There are two custom entity detection methods available to the application:
+
+1.  Context-sensitive identification of entities using an Amazon Comprehend [Custom Entity Recognition model](https://docs.aws.amazon.com/comprehend/latest/dg/custom-entity-recognition.html) 
+2.  String search technique using entity names and types defined in a CSV file
+
+Custom Entity detection via Amazon Comprehend requires a large amount of training data, and initially customers will not have this available. Essentially, it needs a list of customer entities and example sentences where those entities have been seen in context. This data takes time to acquire and annotate, so this application allows you to define just the entity list, and then it will use string-search techniques to identify them in the call transcripts. This will not find the entities in context, rather it will see them wherever they occur, but this means that once a customer has generated a large amount of call transcript data then they could then use that data to train a custom entity mode.
+
+The following configuration settings apply to entity detection:
+
+-   `EntityRecognizerEndpoint` - the Comprehend Custom Entity Recognizer model endpoint
+-   `EntityStringMap` - base name of a CSV file containing the customer entity values
+-   `EntityThreshold` - confidence threshold for accepting a Comprehen custom entity
+
+If a _EntityRecognizerEndpoint_ is defined and is available for the call language then it is used, and the _EntityThreshold_ value is used to decide whether or not to inject the entity data into the call. If the model does not exist for that language then the _EntityStringMap_ file is loaded instead. The application requires no further configuration, and will use the relevant method at all times.
+
+Both the endpoint name and the CSV filename are basenames, very similar to the custom vocabulary naming method. You declare in the configuration a basename, and then the application will append the language code to it and look for that file - again, this lets you define a single name that is applicable to multiple endpoints or files. For example, an English call would make the following interpretation:
+
+-   `EntityRecognizerEndpoint` = **prod-entities** => use endpoint **prod-entities-en**
+-   `EntityStringMap` = **prod-entities.csv** => use CSV file **prod-entities-en.csv**
+
+Note that unlike Amazon Transcribe, Amazon Comprehend just uses the language code and ignores the regional variant, so **fr-FR** and **fr-CA** audio files would both map to a **\-fr** addition to the basenames.
+
+
+##### Amazon Comprehend custom entity detection
+
+All information required to create a Custom Entity Detection model is in the [AWS documentation](https://docs.aws.amazon.com/comprehend/latest/dg/custom-entity-recognition.html)  for building and deploying a custom endpoint. Other than the endpoint naming convention mentioned previously everything else is as per the documentation.
+
+For the sake of consistency, we recommend that you upload the files required to create a Custom Entity Model to the S3 bucket defined by the `SupportFilesBucketName` configuration parameter. If you need further assistance in creating a custom model then please contact AWS for assistance.
+
+
+##### Simple entity string search
+
+There is no additional configuration required to use the simple file-based entity search mechanism - if there is no Amazon Comprehend Custom Entity endpoint available for the current language, but a CSV file can be found for the configured basename, then the feature is automatically enabled.
+
+The format of the CSV file, which exactly matches that for the Custom Entities source file, is as follows:
+
+| **Text** | **Type** |
+| --- | --- |
+| Amazon | CORPORATE |
+| Kindle | BRAND |
+| Fire TV | BRAND |
+| Prime Video | SERVICE |
+
+You define your entity types - there is no limit to the number of types that you can create, be we recommend no more than 25 types, as that currently is the limit of entity types on Amazon Comprehend's Custom Entity Detection; if you use more than that limit here then you will not be able to migrate the file to the custom model in the future.
+
+In order to use it the file must be uploaded to the S3 bucket defined in the `SupportFilesBucketName` configuration setting. Once there the application will load it in as and when necessary when it is processing the output from Amazon Transcribe.
+
+
+#### Detected entities
+
+Regardless of the method of entity detection being performed, the results are always shown in the same way. First, high up on the call details screen, there is a tabbed control bar as follows:
+
+![Entity header bar](../images/entity-header.en.png)
+
+Each of the tabs represents the type of the detected entity, and by clicking on a tab you will see the names of the unique entity values for that type that have been found in the audio transcript - these types could be from any of the entity detection sources discussed above.
+
+As you click through the various type tabs you will see that the entity values are highlighted in a different colour per entity type. Within the transcript itself, any text that triggered the identification of an entity is highlighted in the colour approriate to the entity type, as shown below.
+
+![Entity transcript](../images/entity-transcript.en.png)
+
+In this example we are showing 3 different entity types, which were all present in the entity header image example shown previously.
+
+-   **button** - _Vehicle\_part_
+-   **2019** - _Date_
+-   **Elantra** - _Commercial\_Item_