@aws-amplify/predictions 5.5.6-api-v6-models.b3abc9b.0 → 6.0.0

package/lib-esm/providers/AmazonAIIdentifyPredictionsProvider.js

@@ -0,0 +1,330 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Amplify, ConsoleLogger as Logger, fetchAuthSession, } from '@aws-amplify/core';
+import { Category, PredictionsAction, getAmplifyUserAgentObject, } from '@aws-amplify/core/internals/utils';
+import { getUrl } from '@aws-amplify/storage';
+import { DetectFacesCommand, DetectLabelsCommand, DetectModerationLabelsCommand, DetectTextCommand, RecognizeCelebritiesCommand, RekognitionClient, SearchFacesByImageCommand, } from '@aws-sdk/client-rekognition';
+import { AnalyzeDocumentCommand, DetectDocumentTextCommand, TextractClient, } from '@aws-sdk/client-textract';
+import { PredictionsValidationErrorCode } from '../errors/types/validation';
+import { assertValidationError } from '../errors/utils/assertValidationError';
+import { isFileSource, isIdentifyBytesSource, isIdentifyCelebrities, isIdentifyFromCollection, isIdentifyLabelsInput, isIdentifyTextInput, isStorageSource, isValidIdentifyInput, } from '../types';
+import { categorizeRekognitionBlocks, categorizeTextractBlocks, } from './IdentifyTextUtils';
+import { blobToArrayBuffer, makeCamelCase, makeCamelCaseArray } from './Utils';
+const logger = new Logger('AmazonAIIdentifyPredictionsProvider');
+export class AmazonAIIdentifyPredictionsProvider {
+    getProviderName() {
+        return 'AmazonAIIdentifyPredictionsProvider';
+    }
+    identify(input) {
+        assertValidationError(isValidIdentifyInput(input), PredictionsValidationErrorCode.InvalidInput);
+        if (isIdentifyTextInput(input)) {
+            logger.debug('identifyText');
+            return this.identifyText(input);
+        }
+        else if (isIdentifyLabelsInput(input)) {
+            logger.debug('identifyLabels');
+            return this.identifyLabels(input);
+        }
+        else {
+            logger.debug('identifyEntities');
+            return this.identifyEntities(input);
+        }
+    }
+    /**
+     * Verify user input source and converts it into source object readable by Rekognition and Textract.
+     * Note that Rekognition and Textract use the same source interface, so we need not worry about types.
+     * @param {IdentifySource} source - User input source that directs to the object user wants
+     * to identify (storage, file, or bytes).
+     * @return {Promise<Image>} - Promise resolving to the converted source object.
+     */
+    configureSource(source) {
+        return new Promise((res, rej) => {
+            if (isStorageSource(source)) {
+                const storageConfig = {
+                    accessLevel: source.level,
+                    targetIdentityId: source.identityId,
+                };
+                getUrl({ key: source.key, options: storageConfig })
+                    .then(value => {
+                    const parser = /https:\/\/([a-zA-Z0-9%\-_.]+)\.s3\.[A-Za-z0-9%\-._~]+\/([a-zA-Z0-9%\-._~/]+)\?/;
+                    const parsedURL = value.url.toString().match(parser) ?? '';
+                    if (parsedURL.length < 3)
+                        rej('Invalid S3 key was given.');
+                    res({
+                        S3Object: {
+                            Bucket: parsedURL[1],
+                            Name: decodeURIComponent(parsedURL[2]),
+                        },
+                    });
+                })
+                    .catch(err => rej(err));
+            }
+            else if (isFileSource(source)) {
+                blobToArrayBuffer(source.file)
+                    .then(buffer => {
+                    res({ Bytes: new Uint8Array(buffer) });
+                })
+                    .catch(err => rej(err));
+            }
+            else if (isIdentifyBytesSource(source)) {
+                const bytes = source.bytes;
+                if (bytes instanceof Blob) {
+                    blobToArrayBuffer(bytes)
+                        .then(buffer => {
+                        res({ Bytes: new Uint8Array(buffer) });
+                    })
+                        .catch(err => rej(err));
+                }
+                if (bytes instanceof ArrayBuffer || bytes instanceof Buffer) {
+                    res({ Bytes: new Uint8Array(bytes) });
+                }
+                // everything else can be directly passed to Rekognition / Textract.
+                res({ Bytes: bytes });
+            }
+            else {
+                rej('Input source is not configured correctly.');
+            }
+        });
+    }
+    /**
+     * Recognize text from real-world images and documents (plain text, forms and tables). Detects text in the input
+     * image and converts it into machine-readable text.
+     * @param {IdentifySource} source - Object containing the source image and feature types to analyze.
+     * @return {Promise<IdentifyTextOutput>} - Promise resolving to object containing identified texts.
+     */
+    async identifyText(input) {
+        const { credentials } = await fetchAuthSession();
+        assertValidationError(!!credentials, PredictionsValidationErrorCode.NoCredentials);
+        const { identifyText = {} } = Amplify.getConfig().Predictions?.identify ?? {};
+        const { region = '', defaults = {} } = identifyText;
+        const { format: configFormat = 'PLAIN' } = defaults;
+        this.rekognitionClient = new RekognitionClient({
+            region,
+            credentials,
+            customUserAgent: _getPredictionsIdentifyAmplifyUserAgent(),
+        });
+        this.textractClient = new TextractClient({
+            region,
+            credentials,
+            customUserAgent: _getPredictionsIdentifyAmplifyUserAgent(),
+        });
+        let inputDocument;
+        inputDocument = await this.configureSource(input.text?.source);
+        // get default value if format isn't specified in the input.
+        const format = input.text?.format ?? configFormat;
+        const featureTypes = []; // structures we want to analyze (e.g. [TABLES, FORMS]).
+        if (format === 'FORM' || format === 'ALL')
+            featureTypes.push('FORMS');
+        if (format === 'TABLE' || format === 'ALL')
+            featureTypes.push('TABLES');
+        if (featureTypes.length === 0) {
+            /**
+             * Empty featureTypes indicates that we will identify plain text. We will use rekognition (suitable
+             * for everyday images but has 50 word limit) first and see if reaches its word limit. If it does, then
+             * we call textract and use the data that identify more words.
+             */
+            const textractParam = {
+                Document: inputDocument,
+            };
+            const rekognitionParam = {
+                Image: inputDocument,
+            };
+            const detectTextCommand = new DetectTextCommand(rekognitionParam);
+            const rekognitionData = await this.rekognitionClient.send(detectTextCommand);
+            const rekognitionResponse = categorizeRekognitionBlocks(rekognitionData.TextDetections);
+            if (rekognitionResponse.text.words.length < 50) {
+                // did not hit the word limit, return the data
+                return rekognitionResponse;
+            }
+            const detectDocumentTextCommand = new DetectDocumentTextCommand(textractParam);
+            const { Blocks } = await this.textractClient.send(detectDocumentTextCommand);
+            if ((rekognitionData.TextDetections?.length ?? 0) > (Blocks?.length ?? 0)) {
+                return rekognitionResponse;
+            }
+            return categorizeTextractBlocks(Blocks);
+        }
+        else {
+            const param = {
+                Document: inputDocument,
+                FeatureTypes: featureTypes,
+            };
+            const analyzeDocumentCommand = new AnalyzeDocumentCommand(param);
+            const { Blocks } = await this.textractClient.send(analyzeDocumentCommand);
+            return categorizeTextractBlocks(Blocks);
+        }
+    }
+    /**
+     * Identify instances of real world entities from an image and if it contains unsafe content.
+     * @param {IdentifyLabelsInput} input - Object containing the source image and entity type to identify.
+     * @return {Promise<IdentifyLabelsOutput>} - Promise resolving to an array of identified entities.
+     */
+    async identifyLabels(input) {
+        const { credentials } = await fetchAuthSession();
+        assertValidationError(!!credentials, PredictionsValidationErrorCode.NoCredentials);
+        const { identifyLabels = {} } = Amplify.getConfig().Predictions?.identify ?? {};
+        const { region = '', defaults = {} } = identifyLabels;
+        const { type = 'LABELS' } = defaults;
+        this.rekognitionClient = new RekognitionClient({
+            region,
+            credentials,
+            customUserAgent: _getPredictionsIdentifyAmplifyUserAgent(),
+        });
+        const inputImage = await this.configureSource(input.labels?.source);
+        const param = { Image: inputImage };
+        const servicePromises = [];
+        // get default argument
+        const entityType = input.labels?.type ?? type;
+        if (entityType === 'LABELS' || entityType === 'ALL') {
+            servicePromises.push(this.detectLabels(param));
+        }
+        if (entityType === 'UNSAFE' || entityType === 'ALL') {
+            servicePromises.push(this.detectModerationLabels(param));
+        }
+        return Promise.all(servicePromises).then(data => {
+            let identifyResult = {};
+            // concatenate resolved promises to a single object
+            data.forEach(val => {
+                identifyResult = { ...identifyResult, ...val };
+            });
+            return identifyResult;
+        });
+    }
+    /**
+     * Calls Rekognition.detectLabels and organizes the returned data.
+     * @param {DetectLabelsInput} param - parameter to be passed onto Rekognition
+     * @return {Promise<IdentifyLabelsOutput>} - Promise resolving to organized detectLabels response.
+     */
+    async detectLabels(param) {
+        const detectLabelsCommand = new DetectLabelsCommand(param);
+        const data = await this.rekognitionClient.send(detectLabelsCommand);
+        if (!data.Labels)
+            return {}; // no image was detected
+        const detectLabelData = data.Labels.map(label => {
+            const boxes = label.Instances?.map(instance => makeCamelCase(instance.BoundingBox)) || [];
+            return {
+                name: label.Name,
+                boundingBoxes: boxes,
+                metadata: {
+                    confidence: label.Confidence,
+                    parents: makeCamelCaseArray(label.Parents),
+                },
+            };
+        });
+        return { labels: detectLabelData };
+    }
+    /**
+     * Calls Rekognition.detectModerationLabels and organizes the returned data.
+     * @param {Rekognition.DetectLabelsRequest} param - Parameter to be passed onto Rekognition
+     * @return {Promise<IdentifyLabelsOutput>} - Promise resolving to organized detectModerationLabels response.
+     */
+    async detectModerationLabels(param) {
+        const detectModerationLabelsCommand = new DetectModerationLabelsCommand(param);
+        const data = await this.rekognitionClient.send(detectModerationLabelsCommand);
+        if (data.ModerationLabels?.length !== 0) {
+            return { unsafe: 'YES' };
+        }
+        else {
+            return { unsafe: 'NO' };
+        }
+    }
+    /**
+     * Identify faces within an image that is provided as input, and match faces from a collection
+     * or identify celebrities.
+     * @param {IdentifyEntityInput} input - object containing the source image and face match options.
+     * @return {Promise<IdentifyEntityOutput>} Promise resolving to identify results.
+     */
+    async identifyEntities(input) {
+        const { credentials } = await fetchAuthSession();
+        assertValidationError(!!credentials, PredictionsValidationErrorCode.NoCredentials);
+        const { identifyEntities = {} } = Amplify.getConfig().Predictions?.identify ?? {};
+        const { region = '', celebrityDetectionEnabled = false, defaults = {}, } = identifyEntities;
+        const { collectionId: collectionIdConfig = '', maxEntities: maxFacesConfig = 50, } = defaults;
+        // default arguments
+        this.rekognitionClient = new RekognitionClient({
+            region,
+            credentials,
+            customUserAgent: _getPredictionsIdentifyAmplifyUserAgent(),
+        });
+        const inputImage = await this.configureSource(input.entities?.source);
+        const param = { Attributes: ['ALL'], Image: inputImage };
+        if (isIdentifyCelebrities(input.entities) &&
+            input.entities.celebrityDetection) {
+            assertValidationError(celebrityDetectionEnabled, PredictionsValidationErrorCode.CelebrityDetectionNotEnabled);
+            const recognizeCelebritiesCommand = new RecognizeCelebritiesCommand(param);
+            const data = await this.rekognitionClient.send(recognizeCelebritiesCommand);
+            const faces = data.CelebrityFaces?.map(celebrity => ({
+                boundingBox: makeCamelCase(celebrity.Face?.BoundingBox),
+                landmarks: makeCamelCaseArray(celebrity.Face?.Landmarks),
+                metadata: {
+                    ...makeCamelCase(celebrity, ['Id', 'Name', 'Urls']),
+                    pose: makeCamelCase(celebrity.Face?.Pose),
+                },
+            })) ?? [];
+            return { entities: faces };
+        }
+        else if (isIdentifyFromCollection(input.entities) &&
+            input.entities.collection) {
+            const { collectionId = collectionIdConfig, maxEntities: maxFaces = maxFacesConfig, } = input.entities;
+            // Concatenate additional parameters
+            const updatedParam = {
+                ...param,
+                CollectionId: collectionId,
+                MaxFaces: maxFaces,
+            };
+            const searchFacesByImageCommand = new SearchFacesByImageCommand(updatedParam);
+            const data = await this.rekognitionClient.send(searchFacesByImageCommand);
+            const faces = data.FaceMatches?.map(match => {
+                const externalImageId = match.Face?.ExternalImageId
+                    ? this.decodeExternalImageId(match.Face.ExternalImageId)
+                    : undefined;
+                return {
+                    boundingBox: makeCamelCase(match.Face?.BoundingBox),
+                    metadata: {
+                        externalImageId,
+                        similarity: match.Similarity,
+                    },
+                };
+            }) ?? [];
+            return { entities: faces };
+        }
+        else {
+            const detectFacesCommand = new DetectFacesCommand(param);
+            const data = await this.rekognitionClient.send(detectFacesCommand);
+            const faces = data.FaceDetails?.map(detail => {
+                // face attributes keys we want to extract from Rekognition's response
+                const attributeKeys = [
+                    'Smile',
+                    'Eyeglasses',
+                    'Sunglasses',
+                    'Gender',
+                    'Beard',
+                    'Mustache',
+                    'EyesOpen',
+                    'MouthOpen',
+                ];
+                const faceAttributes = makeCamelCase(detail, attributeKeys);
+                faceAttributes.emotions = detail.Emotions?.map(emotion => emotion.Type);
+                return {
+                    boundingBox: makeCamelCase(detail.BoundingBox),
+                    landmarks: makeCamelCaseArray(detail.Landmarks),
+                    ageRange: makeCamelCase(detail.AgeRange),
+                    attributes: faceAttributes,
+                    metadata: {
+                        confidence: detail.Confidence,
+                        pose: makeCamelCase(detail.Pose),
+                    },
+                };
+            }) ?? [];
+            return { entities: faces };
+        }
+    }
+    decodeExternalImageId(externalImageId) {
+        return ('' + externalImageId).replace(/::/g, '/');
+    }
+}
+function _getPredictionsIdentifyAmplifyUserAgent() {
+    return getAmplifyUserAgentObject({
+        category: Category.Predictions,
+        action: PredictionsAction.Identify,
+    });
+}

package/lib-esm/{Providers → providers}/AmazonAIInterpretPredictionsProvider.d.ts

@@ -1,9 +1,8 @@
-import { AbstractInterpretPredictionsProvider } from '../types/Providers';
 import { InterpretTextInput, InterpretTextOutput } from '../types';
-export declare class AmazonAIInterpretPredictionsProvider extends AbstractInterpretPredictionsProvider {
-    private comprehendClient;
-    constructor();
+export declare class AmazonAIInterpretPredictionsProvider {
+    private comprehendClient?;
     getProviderName(): string;
+    interpret(input: InterpretTextInput): Promise<InterpretTextOutput>;
     interpretText(input: InterpretTextInput): Promise<InterpretTextOutput>;
     private detectKeyPhrases;
     private detectSyntax;

package/lib-esm/providers/AmazonAIInterpretPredictionsProvider.js

@@ -0,0 +1,204 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Amplify, fetchAuthSession } from '@aws-amplify/core';
+import { Category, PredictionsAction, getAmplifyUserAgentObject, } from '@aws-amplify/core/internals/utils';
+import { ComprehendClient, DetectDominantLanguageCommand, DetectEntitiesCommand, DetectKeyPhrasesCommand, DetectSentimentCommand, DetectSyntaxCommand, } from '@aws-sdk/client-comprehend';
+import { PredictionsValidationErrorCode } from '../errors/types/validation';
+import { assertValidationError } from '../errors/utils/assertValidationError';
+import { isInterpretTextOthers, isValidInterpretInput, } from '../types';
+export class AmazonAIInterpretPredictionsProvider {
+    getProviderName() {
+        return 'AmazonAIInterpretPredictionsProvider';
+    }
+    interpret(input) {
+        assertValidationError(isValidInterpretInput(input), PredictionsValidationErrorCode.InvalidInput);
+        return this.interpretText(input);
+    }
+    async interpretText(input) {
+        const { credentials } = await fetchAuthSession();
+        assertValidationError(!!credentials, PredictionsValidationErrorCode.NoCredentials);
+        const { interpretText = {} } = Amplify.getConfig().Predictions?.interpret ?? {};
+        const { region = '', defaults = {} } = interpretText;
+        const { type: defaultType = '' } = defaults;
+        const { text: textSource } = input;
+        const { source, type = defaultType } = textSource;
+        const { text } = source;
+        let language;
+        if (isInterpretTextOthers(textSource)) {
+            language = textSource.source.language;
+        }
+        this.comprehendClient = new ComprehendClient({
+            credentials,
+            region,
+            customUserAgent: getAmplifyUserAgentObject({
+                category: Category.Predictions,
+                action: PredictionsAction.Interpret,
+            }),
+        });
+        const doAll = type === 'all';
+        let languageCode = language;
+        if (doAll || type === 'language') {
+            const languageDetectionParams = {
+                Text: text,
+            };
+            languageCode = await this.detectLanguage(languageDetectionParams);
+        }
+        let entitiesPromise;
+        if (doAll || type === 'entities') {
+            assertValidationError(!!languageCode, PredictionsValidationErrorCode.NoLanguage);
+            const entitiesDetectionParams = {
+                Text: text,
+                LanguageCode: languageCode,
+            };
+            entitiesPromise = this.detectEntities(entitiesDetectionParams);
+        }
+        let sentimentPromise;
+        if (doAll || type === 'sentiment') {
+            assertValidationError(!!languageCode, PredictionsValidationErrorCode.NoLanguage);
+            const sentimentParams = {
+                Text: text,
+                LanguageCode: languageCode,
+            };
+            sentimentPromise = this.detectSentiment(sentimentParams);
+        }
+        let syntaxPromise;
+        if (doAll || type === 'syntax') {
+            assertValidationError(!!languageCode, PredictionsValidationErrorCode.NoLanguage);
+            const syntaxParams = {
+                Text: text,
+                LanguageCode: languageCode,
+            };
+            syntaxPromise = this.detectSyntax(syntaxParams);
+        }
+        let keyPhrasesPromise;
+        if (doAll || type === 'keyPhrases') {
+            assertValidationError(!!languageCode, PredictionsValidationErrorCode.NoLanguage);
+            const keyPhrasesParams = {
+                Text: text,
+                LanguageCode: languageCode,
+            };
+            keyPhrasesPromise = this.detectKeyPhrases(keyPhrasesParams);
+        }
+        const [textEntities, sentiment, syntax, keyPhrases] = await Promise.all([
+            entitiesPromise,
+            sentimentPromise,
+            syntaxPromise,
+            keyPhrasesPromise,
+        ]);
+        return {
+            textInterpretation: {
+                keyPhrases,
+                language: languageCode,
+                sentiment,
+                syntax,
+                textEntities,
+            },
+        };
+    }
+    async detectKeyPhrases(params) {
+        try {
+            const detectKeyPhrasesCommand = new DetectKeyPhrasesCommand(params);
+            const data = await this.comprehendClient.send(detectKeyPhrasesCommand);
+            const { KeyPhrases = [] } = data || {};
+            return KeyPhrases.map(({ Text: text }) => {
+                return { text };
+            });
+        }
+        catch (err) {
+            if (err.code === 'AccessDeniedException') {
+                throw new Error('Not authorized, did you enable Interpret Text on predictions category Amplify CLI? try: ' +
+                    'amplify predictions add');
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    async detectSyntax(params) {
+        try {
+            const detectSyntaxCommand = new DetectSyntaxCommand(params);
+            const data = await this.comprehendClient.send(detectSyntaxCommand);
+            const { SyntaxTokens = [] } = data || {};
+            return this.serializeSyntaxFromComprehend(SyntaxTokens);
+        }
+        catch (err) {
+            if (err.code === 'AccessDeniedException') {
+                throw new Error('Not authorized, did you enable Interpret Text on predictions category Amplify CLI? try: ' +
+                    'amplify predictions add');
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    serializeSyntaxFromComprehend(tokens) {
+        let response = [];
+        if (tokens && Array.isArray(tokens)) {
+            response = tokens.map(({ Text: text = '', PartOfSpeech: { Tag: syntax = '' } = {} }) => {
+                return { text, syntax };
+            });
+        }
+        return response;
+    }
+    async detectSentiment(params) {
+        try {
+            const detectSentimentCommand = new DetectSentimentCommand(params);
+            const data = await this.comprehendClient.send(detectSentimentCommand);
+            const { Sentiment: predominant = '', SentimentScore: { Positive: positive = 0, Negative: negative = 0, Neutral: neutral = 0, Mixed: mixed = 0, } = {}, } = ({} = data);
+            return { predominant, positive, negative, neutral, mixed };
+        }
+        catch (err) {
+            if (err.code === 'AccessDeniedException') {
+                throw new Error('Not authorized, did you enable Interpret Text on predictions category Amplify CLI? try: ' +
+                    'amplify predictions add');
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    async detectEntities(params) {
+        try {
+            const detectEntitiesCommand = new DetectEntitiesCommand(params);
+            const data = await this.comprehendClient.send(detectEntitiesCommand);
+            const { Entities = [] } = data || {};
+            return this.serializeEntitiesFromComprehend(Entities);
+        }
+        catch (err) {
+            if (err.code === 'AccessDeniedException') {
+                throw new Error('Not authorized, did you enable Interpret Text on predictions category Amplify CLI? try: ' +
+                    'amplify predictions add');
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    serializeEntitiesFromComprehend(data) {
+        let response = [];
+        if (data && Array.isArray(data)) {
+            response = data.map(({ Type: type, Text: text }) => {
+                return { type, text };
+            });
+        }
+        return response;
+    }
+    async detectLanguage(params) {
+        try {
+            const detectDominantLanguageCommand = new DetectDominantLanguageCommand(params);
+            const data = await this.comprehendClient.send(detectDominantLanguageCommand);
+            const { Languages: [{ LanguageCode }] = [{}] } = ({} = data || {});
+            assertValidationError(!!LanguageCode, PredictionsValidationErrorCode.NoLanguage);
+            return LanguageCode;
+        }
+        catch (err) {
+            if (err.code === 'AccessDeniedException') {
+                throw new Error('Not authorized, did you enable Interpret Text on predictions category Amplify CLI? try: ' +
+                    'amplify predictions add');
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+}

package/lib-esm/providers/IdentifyTextUtils.d.ts

@@ -0,0 +1,16 @@
+import { IdentifyTextOutput } from '../types';
+import { BlockList, TextDetectionList } from '../types/AWSTypes';
+/**
+ * Organizes blocks from Rekognition API to each of the categories and and structures
+ * their data accordingly.
+ * @param {BlockList} source - Array containing blocks returned from Textract API.
+ * @return {IdentifyTextOutput} -  Object that categorizes each block and its information.
+ */
+export declare function categorizeRekognitionBlocks(blocks: TextDetectionList): IdentifyTextOutput;
+/**
+ * Organizes blocks from Textract API to each of the categories and and structures
+ * their data accordingly.
+ * @param {BlockList} source - Array containing blocks returned from Textract API.
+ * @return {IdentifyTextOutput} -  Object that categorizes each block and its information.
+ */
+export declare function categorizeTextractBlocks(blocks: BlockList): IdentifyTextOutput;