Skip to main content
This analyzer enriches a prompt with structured linguistic signals — sentiment scores, named entities, topic categories, and a moderation verdict. It is a signal analyzer; it produces metrics you can use as termination thresholds in a combined policy, but it does not by itself make safety decisions (that’s Safety & Responsible AI).
Canonical namenatural-language
Pythonnatural_language
TypeScriptnaturalLanguage
Server keynlp_analyzer
CategoryContent Analysis

​
What it provides

Four independent sub-analyses, each toggleable:
  • Sentiment — overall sentiment (-1.0 very negative to +1.0 very positive) with a magnitude.
  • Entity extraction — named entities (people, organizations, locations, etc.).
  • Topic classification — high-level categories (requires text ≥ 20 bytes).
  • Content moderation — categories like Toxic, Insult, Profanity, Derogatory, Sexual, Violent, Death, Harm & Tragedy, Firearms & Weapons, Illicit Drugs.

​
How it works

Calls Google Cloud Natural Language API:
  • v1 (classification, entities) for topic and entity extraction.
  • v2 (sentiment, moderation) for sentiment and moderation scores.
Each sub-analysis is a separate API call. Disabling sub-analyses you do not need is the most effective latency lever.

​
Parameters

KeyTypeRequiredDefaultNotes
include_entitiesbooleanNotrueExtract named entities.
include_sentimentbooleanNotrueCompute sentiment score and magnitude.
include_moderationbooleanNotrueRun the v2 moderation classifier.
(Topic classification has no toggle; it always runs when input is ≥ 20 bytes.)

​
Outputs and metrics

{
  "language": "en",
  "sentiment": { "score": -0.78, "magnitude": 1.4 },
  "entities": [
    { "name": "OpenAI", "type": "ORGANIZATION", "salience": 0.4 }
  ],
  "topics": [{ "name": "/Computers & Electronics", "confidence": 0.91 }],
  "moderation": [
    { "category": "Toxic",     "confidence": 0.86 },
    { "category": "Profanity", "confidence": 0.71 }
  ],
  "metrics": {
    "processing_time_ms": 480.0,
    "sentiment_score": -0.78,
    "sentiment_magnitude": 1.4,
    "topic_count": 1,
    "entity_count": 1,
    "moderation_category_count": 2,
    "max_moderation_confidence": 0.86
  },
  "status": "OK"
}
MetricRangeSuggested thresholds
sentiment_score-1.0 to 1.0< -0.5 (negative), < -0.8 (very negative).
sentiment_magnitude≥ 0.0Strength regardless of polarity.
topic_countint—
entity_countint—
moderation_category_countint> 0 (any flag), >= 2 (multiple).
max_moderation_confidence0.0–1.0>= 0.5 (any flagged), >= 0.65 (high), >= 0.8 (very high).

​
Termination signals

SignalWhat it matches
Boolean: moderation_flaggedAny moderation category with confidence >= 0.5.
Match: moderation_categoryA specific category — e.g. Toxic, Insult, Profanity, Derogatory, Sexual, Violent, Death, Harm & Tragedy, Firearms & Weapons, Illicit Drugs.
Combine moderation_flagged with max_moderation_confidence >= 0.65 for stricter control than the default 0.5 cutoff.

​
Limits and cost

LimitValue
Max input tokens100,000
Requests / minute100 (per tenant)
Topic classification minimum20 bytes
Cost is Google Cloud Natural Language pricing — see the NL pricing page.

​
Typical latency

500–3000 ms depending on enabled analyses and input length. The biggest saving you can make is disabling sub-analyses you do not need; each one is its own API call.

​
When to use it

  • Best as a flag, not a block. Sentiment and entity counts are noisy. Use them to enrich your analysis log; reach for safety guardrails or YARA when you actually want to block.
  • Use moderation as a secondary signal. It overlaps with ShieldGemma but uses a different model family; agreement between the two raises confidence on a violation.
  • Disable what you do not use. If you do not need topic classification, the include_* toggles already disable sentiment, entities, and moderation; topic always runs but is fast.

​
Failure modes

  • NL API error → analyzer ERROR status; surfaced in analyzer_results.
  • Empty input → topic classification skipped; other sub-analyses produce empty results.

​
Next