AWS Comprehend ExecModule

Overview

AwsComprehendModule brings Amazon Comprehend real-time text analysis into ValkyrAI workflows. It preserves n8n's dominant-language, sentiment, and entity operations while adding key-phrase, syntax, detailed PII, and PII-presence analysis. Every request uses a verified IntegrationAccount, an exact AWS region, bounded UTF-8 text, normalized output, credential redaction, deterministic attempt accounting, and annotation-backed Workflow Studio discovery.

The connector implements seven synchronous operations:

• detect_dominant_language ranks probable language codes.
• detect_sentiment returns a prevailing sentiment and four scores.
• detect_entities extracts named entities and can use a custom entity-recognizer endpoint.
• detect_key_phrases extracts scored noun phrases.
• detect_syntax returns tokens and part-of-speech predictions.
• detect_pii_entities returns PII types and character offsets.
• contains_pii_entities returns PII type scores without character offsets.

Comprehend output is probabilistic. Use it to rank, route, redact, or review content; do not use it as the sole basis for decisions affecting a person's rights, eligibility, employment, finances, healthcare, safety, or access to services.

Usage

1. Create a dedicated AWS IAM principal with only the Comprehend actions needed by the workflow.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsComprehendModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Choose an exact AWS region, one operation, and reviewed text no larger than 5,000 UTF-8 bytes.
5. Supply languageCode for every operation except detect_dominant_language.
6. Route PII and low-confidence results through an approved human or policy decision before an external action.

Never place AWS credentials in module input, logs, examples, or output. Credential-like input fields are rejected before provider access. The connector does not echo source text in its output.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the seven documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom service endpoints are not accepted.
text	string	Every execution	None	Non-blank UTF-8 text, at most 5,000 bytes. Newlines and tabs are allowed; unsafe control characters are rejected.
languageCode	string	Every operation except detect_dominant_language	None	Provider language code such as en, es, or zh-TW; the selected operation and region determine actual support.
endpointArn	string	Optional for detect_entities	None	Amazon Comprehend endpoint ARN in the exact selected region. Rejected for other operations.

Operation-specific fields are fail-closed. detect_dominant_language rejects languageCode, and all operations except detect_entities reject endpointArn.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls. Each billable analysis is single-attempt.
resultType	string	Success	languages, sentiment, entities, keyPhrases, syntaxTokens, piiEntities, or piiLabels.
items	array	Success	Bounded normalized findings for the selected operation.
count	integer	Success	Number of returned findings.
sentiment	string	Sentiment success	POSITIVE, NEGATIVE, NEUTRAL, or MIXED.
sentimentScores	object	Sentiment success	Provider scores for positive, negative, neutral, and mixed classifications.
containsPii	boolean	PII success	Whether AWS returned at least one PII entity or label.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Entity and phrase findings include bounded text, confidence score, and UTF-8 character offsets when AWS supplies them. Syntax findings include the token ID, token text, offsets, and a scored part-of-speech tag. Detailed PII findings intentionally provide types and offsets without copying the sensitive span into output.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Comprehend
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the operations selected by the workflow:

• comprehend:DetectDominantLanguage
• comprehend:DetectSentiment
• comprehend:DetectEntities
• comprehend:DetectKeyPhrases
• comprehend:DetectSyntax
• comprehend:DetectPiiEntities
• comprehend:ContainsPiiEntities

Custom entity analysis also requires access to the exact configured endpoint. The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, VPC endpoint overrides, asynchronous S3 jobs, custom classifier inference, model training, endpoint lifecycle, flywheels, resource policies, tagging, and batch APIs are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, language, text, and optional custom endpoint belong in module parameters or mapped input.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-comprehend-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"detect_sentiment\",\"region\":\"us-west-2\",\"languageCode\":\"en\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
detect_dominant_language	Returns scored language codes for the text.	Non-storage but billable external processing; exactly one provider attempt.
detect_sentiment	Returns the prevailing sentiment and all four class scores.	Non-storage but billable external processing; exactly one provider attempt.
detect_entities	Returns names, places, dates, organizations, quantities, and other entity types; supports a same-region custom endpoint.	Non-storage but billable external processing; exactly one provider attempt.
detect_key_phrases	Returns scored key noun phrases and offsets.	Non-storage but billable external processing; exactly one provider attempt.
detect_syntax	Returns token boundaries and part-of-speech predictions.	Non-storage but billable external processing; exactly one provider attempt.
detect_pii_entities	Returns PII types, scores, and character offsets.	Sensitive-data processing; exactly one provider attempt.
contains_pii_entities	Returns scored PII type labels without exact spans.	Sensitive-data processing; exactly one provider attempt.

The module does not create Comprehend resources or modify source text. AWS may retain service telemetry under the account's AWS terms and configuration; review that policy before processing confidential or regulated content.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing or malformed operation, region, text, language, credential-like input, or endpoint ARN; oversized text; endpoint-region mismatch.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_COMPREHEND_HTTP_400	Unsupported language, text encoding or provider constraint.	Usually no	Check the operation's current AWS language and region support.
AWS_COMPREHEND_HTTP_403	IAM denies the selected action or custom endpoint.	No	Grant only the missing action on the intended account or endpoint.
AWS_COMPREHEND_HTTP_429 / 500 / 503	Provider throttle or transient service pressure.	Reported as retryable, not automatically replayed	Reconcile the request ID, input hash, and billing evidence before an orchestrated retry.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reported as retryable, not automatically replayed	Treat acceptance and billing as ambiguous; inspect provider evidence before replay.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, region, reviewed input hash, and request evidence.

Provider exception text is never copied into output, preventing credential echoes and unbounded provider payloads.

Example

Triage a reviewed support message before routing it:

{
  "operation": "detect_sentiment",
  "region": "us-west-2",
  "languageCode": "en",
  "text": "The outage is blocking our launch and we need help today."
}

Expected result shape:

{
  "status": "success",
  "operation": "detect_sentiment",
  "attempts": 1,
  "resultType": "sentiment",
  "count": 1,
  "sentiment": "NEGATIVE",
  "sentimentScores": {
    "positive": 0.01,
    "negative": 0.94,
    "neutral": 0.04,
    "mixed": 0.01
  },
  "items": [
    {
      "sentiment": "NEGATIVE",
      "scores": {
        "positive": 0.01,
        "negative": 0.94,
        "neutral": 0.04,
        "mixed": 0.01
      }
    }
  ],
  "requestId": "aws-request-reference"
}

The expected workflow combines sentiment with urgency, customer tier, incident state, and an explicit policy before routing to a human owner. A negative label alone is never authorization for an irreversible action.

Notes

• Pagination: these seven real-time analysis operations return one response and do not expose pagination tokens. Asynchronous and resource-list operations are intentionally outside this connector version.
• Rate limits: quotas vary by operation, account, region, and text size. The AWS SDK's own retries are disabled so attempts and billing ambiguity remain deterministic.
• API limits: ValkyrAI caps each request at 5,000 UTF-8 bytes even if a provider operation currently permits more. Language support differs by operation and may evolve; AWS is authoritative after local syntax validation.
• Idempotency: analysis does not mutate source text or create a Comprehend object. Repeating identical input can incur another charge and results may change as provider models evolve.
• Billable ambiguity: every analysis is sent exactly once. If transport fails after AWS accepts it, reconcile the provider request and reviewed text hash before replaying.
• Destructive behavior: the connector never changes or deletes text, models, endpoints, datasets, jobs, or policies. It does send text to AWS and initiate billable processing.
• PII: contains_pii_entities is useful as a low-detail routing gate. detect_pii_entities returns offsets for redaction workflows but intentionally omits the source span. Keep the original text in an approved confidential store.
• Custom entities: endpointArn must be an Amazon Comprehend ARN in the selected region. The connector does not create, update, or delete endpoints.
• Output shape: results are plain maps and arrays without AWS SDK objects. Confidence values retain provider precision.
• Provider verification boundary: deterministic tests cover validation, fixed regional routing, account isolation, custom endpoint scope, all seven dispatch paths, normalized envelopes, PII non-echo, failure retryability, single-attempt billing, redaction, registration, and metadata. Live AWS behavior remains unverified until an authorized Comprehend credential and reviewed text are supplied.
• Functional reference: n8n's AWS Comprehend node exposes dominant-language, sentiment, and entity detection. ValkyrAI preserves that surface and adds key phrases, syntax, detailed PII, a low-detail PII guard, strict UTF-8 bounds, verified account enforcement, normalized findings, and conservative replay behavior.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsComprehendModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS S3 ExecModule
• AWS Lambda ExecModule
• AWS Textract ExecModule
• AWS Transcribe ExecModule
• n8n AWS Comprehend reference
• Amazon Comprehend real-time analysis
• Integration Account Console