# Brainiall NLP API — Full Documentation

## Overview

Brainiall NLP API provides a suite of specialized NLP models optimized with ONNX for CPU inference. Each model is purpose-built for a specific task, delivering higher accuracy at 100-1000x lower cost compared to general-purpose LLMs.

All models run on CPU — no GPU required. Typical latency: 30-500ms per request.

Pricing: $0.0005-$0.002 per request. Compare: AWS Comprehend = $500/1M, Azure Text Analytics = $700/1M, GPT-4o = $2,500/1M.

## Base URL

https://apim-ai-apis.azure-api.net/v1/nlp

## Authentication

Three authentication methods (use any one):

1. Bearer Token: `Authorization: Bearer YOUR_KEY`
2. API Key: `api-key: YOUR_KEY`
3. Subscription Key: `Ocp-Apim-Subscription-Key: YOUR_KEY`

Get your API key at https://brainiall.com

## Endpoints

### POST /toxicity

Detect toxic content across 6 categories. Uses a multi-label BERT classifier trained on Jigsaw Toxic Comment Classification data.

Request:
```json
{"text": "Your text to analyze"}
```

Response:
```json
{
  "text": "Your text to analyze",
  "is_toxic": false,
  "scores": {
    "toxic": 0.0012,
    "severe_toxic": 0.0001,
    "obscene": 0.0005,
    "threat": 0.0002,
    "insult": 0.0008,
    "identity_hate": 0.0001
  },
  "max_score": 0.0012,
  "max_category": "toxic"
}
```

Categories:
- toxic: General toxicity
- severe_toxic: Extremely toxic content
- obscene: Obscene language
- threat: Threatening content
- insult: Insults
- identity_hate: Identity-based hate speech

The `is_toxic` field is `true` when any category score exceeds 0.5.

### POST /sentiment

Classify text sentiment as positive or negative with confidence score. Uses DistilBERT fine-tuned on SST-2.

Request:
```json
{"text": "Your text to analyze"}
```

Response:
```json
{
  "text": "Your text to analyze",
  "sentiment": "positive",
  "confidence": 0.9847,
  "scores": {
    "positive": 0.9847,
    "negative": 0.0153
  }
}
```

### POST /entities

Extract named entities using NER (Named Entity Recognition). Uses BERT-base fine-tuned on CoNLL-2003.

Request:
```json
{"text": "Your text to analyze"}
```

Response:
```json
{
  "text": "Your text to analyze",
  "entities": [
    {"text": "Entity Name", "label": "PER", "start": 0, "end": 11, "score": 0.9987}
  ],
  "entity_count": 1
}
```

Entity labels:
- PER: Person names
- ORG: Organization names
- LOC: Location names
- MISC: Miscellaneous entities (events, nationalities, works of art)

### POST /pii

Detect personally identifiable information using pattern matching and regex. Designed for GDPR/CCPA compliance workflows.

Request:
```json
{"text": "Your text to analyze"}
```

Response:
```json
{
  "text": "Your text to analyze",
  "pii_found": true,
  "entities": [
    {"type": "email", "value": "user@example.com", "start": 10, "end": 26}
  ],
  "pii_count": 1
}
```

PII types detected:
- email: Email addresses
- phone: Phone numbers (US and international formats)
- ssn: Social Security Numbers (XXX-XX-XXXX format)
- credit_card: Credit card numbers (Visa, Mastercard, Amex, Discover)

### POST /language

Detect text language from 217 supported languages. Uses fastText model (lid.176.ftz) for high-speed detection (<1ms typical).

Request:
```json
{"text": "Your text to analyze"}
```

Response:
```json
{
  "text": "Your text to analyze",
  "language": "en",
  "confidence": 0.9876,
  "language_name": "English"
}
```

Common language codes: en (English), es (Spanish), fr (French), de (German), pt (Portuguese), zh (Chinese), ja (Japanese), ko (Korean), ar (Arabic), hi (Hindi), ru (Russian), it (Italian), nl (Dutch), pl (Polish), tr (Turkish), vi (Vietnamese), th (Thai), id (Indonesian).

### GET /health

Service health check. Returns model load status.

Response:
```json
{
  "status": "healthy",
  "models": {
    "toxicity": "loaded",
    "sentiment": "loaded",
    "ner": "loaded",
    "pii": "loaded",
    "language": "loaded"
  }
}
```

## Code Examples

### Python: Content Moderation Pipeline

```python
import requests

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

def moderate_content(text: str) -> dict:
    """Run content moderation pipeline: toxicity + PII + language."""
    toxicity = requests.post(f"{BASE_URL}/toxicity", headers=HEADERS, json={"text": text}).json()
    pii = requests.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": text}).json()
    language = requests.post(f"{BASE_URL}/language", headers=HEADERS, json={"text": text}).json()

    return {
        "text": text,
        "language": language["language"],
        "is_toxic": toxicity["is_toxic"],
        "toxic_categories": {k: v for k, v in toxicity["scores"].items() if v > 0.5},
        "has_pii": pii["pii_found"],
        "pii_types": [e["type"] for e in pii.get("entities", [])],
        "action": "block" if toxicity["is_toxic"] else ("redact" if pii["pii_found"] else "allow")
    }

result = moderate_content("Please contact John at john@example.com for details")
print(f"Action: {result['action']}")
print(f"Language: {result['language']}")
print(f"PII found: {result['pii_types']}")
```

### Python: Batch Sentiment Analysis

```python
import requests
from concurrent.futures import ThreadPoolExecutor
import time

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

reviews = [
    "Absolutely love this product! Best purchase ever.",
    "Terrible quality. Broke after one week.",
    "It's decent for the price. Nothing extraordinary.",
    "Amazing customer service! They resolved my issue immediately.",
    "Would not recommend. Very disappointing experience.",
    "Great value for money. Exactly what I needed.",
    "The worst experience I've had with any company.",
    "Exceeded my expectations in every way!",
]

def analyze(text):
    resp = requests.post(f"{BASE_URL}/sentiment", headers=HEADERS, json={"text": text})
    return resp.json()

start = time.time()
with ThreadPoolExecutor(max_workers=10) as pool:
    results = list(pool.map(analyze, reviews))
elapsed = time.time() - start

positive = sum(1 for r in results if r["sentiment"] == "positive")
negative = len(results) - positive
print(f"Analyzed {len(reviews)} reviews in {elapsed:.2f}s")
print(f"Positive: {positive}, Negative: {negative}")
for text, result in zip(reviews, results):
    icon = "+" if result["sentiment"] == "positive" else "-"
    print(f"  [{icon}] {result['confidence']:.3f} | {text[:60]}")
```

### Python: Entity Extraction Pipeline

```python
import requests

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

def extract_all_entities(text: str) -> dict:
    """Extract named entities and PII from text."""
    ner = requests.post(f"{BASE_URL}/entities", headers=HEADERS, json={"text": text}).json()
    pii = requests.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": text}).json()

    return {
        "persons": [e["text"] for e in ner["entities"] if e["label"] == "PER"],
        "organizations": [e["text"] for e in ner["entities"] if e["label"] == "ORG"],
        "locations": [e["text"] for e in ner["entities"] if e["label"] == "LOC"],
        "emails": [e["value"] for e in pii.get("entities", []) if e["type"] == "email"],
        "phones": [e["value"] for e in pii.get("entities", []) if e["type"] == "phone"],
    }

text = """
Tim Cook, CEO of Apple Inc., announced the opening of a new office in Austin, Texas.
For inquiries, contact press@apple.com or call 1-800-275-2273.
"""
entities = extract_all_entities(text)
print(f"Persons: {entities['persons']}")
print(f"Organizations: {entities['organizations']}")
print(f"Locations: {entities['locations']}")
print(f"Emails: {entities['emails']}")
print(f"Phones: {entities['phones']}")
```

### Python: Async NLP Analysis

```python
import asyncio
import httpx

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

async def analyze_text_async(text: str) -> dict:
    """Run all NLP analyses concurrently for maximum speed."""
    async with httpx.AsyncClient() as client:
        tasks = [
            client.post(f"{BASE_URL}/toxicity", headers=HEADERS, json={"text": text}),
            client.post(f"{BASE_URL}/sentiment", headers=HEADERS, json={"text": text}),
            client.post(f"{BASE_URL}/entities", headers=HEADERS, json={"text": text}),
            client.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": text}),
            client.post(f"{BASE_URL}/language", headers=HEADERS, json={"text": text}),
        ]
        responses = await asyncio.gather(*tasks)
        results = [r.json() for r in responses]

    return {
        "text": text,
        "language": results[4]["language"],
        "sentiment": results[1]["sentiment"],
        "sentiment_confidence": results[1]["confidence"],
        "is_toxic": results[0]["is_toxic"],
        "toxic_max_category": results[0]["max_category"],
        "toxic_max_score": results[0]["max_score"],
        "entities": results[2]["entities"],
        "entity_count": results[2]["entity_count"],
        "pii_found": results[3]["pii_found"],
        "pii_entities": results[3].get("entities", []),
    }

async def batch_analyze_async(texts: list[str]) -> list[dict]:
    """Analyze multiple texts concurrently."""
    tasks = [analyze_text_async(text) for text in texts]
    return await asyncio.gather(*tasks)

# Usage
async def main():
    texts = [
        "The new iPhone release exceeded expectations with record sales.",
        "Contact support@company.com or call 555-123-4567 for help.",
        "Le president Macron a visite la Tour Eiffel a Paris.",
    ]
    results = await batch_analyze_async(texts)
    for r in results:
        print(f"[{r['language']}] {r['sentiment']} ({r['sentiment_confidence']:.2f}) | "
              f"Toxic: {r['is_toxic']} | Entities: {r['entity_count']} | PII: {r['pii_found']}")

asyncio.run(main())
```

### Python: GDPR PII Redaction Pipeline

```python
import requests
import re

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

def redact_pii(text: str) -> dict:
    """Detect and redact PII from text for GDPR compliance."""
    pii_result = requests.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": text}).json()
    ner_result = requests.post(f"{BASE_URL}/entities", headers=HEADERS, json={"text": text}).json()

    redacted = text
    replacements = []

    # Redact PII (email, phone, SSN, credit card)
    for entity in sorted(pii_result.get("entities", []), key=lambda e: e["start"], reverse=True):
        mask = f"[REDACTED_{entity['type'].upper()}]"
        redacted = redacted[:entity["start"]] + mask + redacted[entity["end"]:]
        replacements.append({"type": entity["type"], "original": entity["value"], "mask": mask})

    # Redact person names from NER
    for entity in sorted(ner_result.get("entities", []), key=lambda e: e["start"], reverse=True):
        if entity["label"] == "PER":
            mask = "[REDACTED_NAME]"
            redacted = redacted[:entity["start"]] + mask + redacted[entity["end"]:]
            replacements.append({"type": "name", "original": entity["text"], "mask": mask})

    return {
        "original": text,
        "redacted": redacted,
        "pii_count": len(replacements),
        "replacements": replacements,
    }

# Usage
text = "John Smith's email is john.smith@company.com and his SSN is 123-45-6789."
result = redact_pii(text)
print(f"Original: {result['original']}")
print(f"Redacted: {result['redacted']}")
print(f"PII found: {result['pii_count']}")
```

### Python: Chat Moderation with Context

```python
import requests
from dataclasses import dataclass

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

@dataclass
class ModerationResult:
    allowed: bool
    reason: str
    language: str
    toxic_score: float
    toxic_category: str
    has_pii: bool

def moderate_chat_message(message: str, allowed_languages: list[str] = None) -> ModerationResult:
    """Moderate a single chat message. Returns whether it should be allowed."""
    # Run all checks in parallel (use async in production)
    toxicity = requests.post(f"{BASE_URL}/toxicity", headers=HEADERS, json={"text": message}).json()
    pii = requests.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": message}).json()
    language = requests.post(f"{BASE_URL}/language", headers=HEADERS, json={"text": message}).json()

    # Check toxicity
    if toxicity["is_toxic"]:
        return ModerationResult(
            allowed=False,
            reason=f"Toxic content detected: {toxicity['max_category']} ({toxicity['max_score']:.2f})",
            language=language["language"],
            toxic_score=toxicity["max_score"],
            toxic_category=toxicity["max_category"],
            has_pii=pii["pii_found"],
        )

    # Check language restrictions
    if allowed_languages and language["language"] not in allowed_languages:
        return ModerationResult(
            allowed=False,
            reason=f"Language not allowed: {language['language_name']}",
            language=language["language"],
            toxic_score=toxicity["max_score"],
            toxic_category=toxicity["max_category"],
            has_pii=pii["pii_found"],
        )

    # Check PII (warn but allow)
    return ModerationResult(
        allowed=True,
        reason="approved" if not pii["pii_found"] else "approved_with_pii_warning",
        language=language["language"],
        toxic_score=toxicity["max_score"],
        toxic_category=toxicity["max_category"],
        has_pii=pii["pii_found"],
    )

# Usage
messages = [
    "This product is amazing!",
    "Contact me at user@email.com",
    "Bonjour, comment allez-vous?",
]

for msg in messages:
    result = moderate_chat_message(msg, allowed_languages=["en"])
    status = "PASS" if result.allowed else "BLOCK"
    print(f"[{status}] {msg[:40]}... | {result.reason}")
```

### Python: Error Handling with Retry

```python
import requests
import time
from typing import Optional

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"

class BrainiallNLP:
    def __init__(self, api_key: str, max_retries: int = 3, timeout: int = 10):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        })
        self.max_retries = max_retries
        self.timeout = timeout

    def _request(self, endpoint: str, text: str) -> dict:
        for attempt in range(self.max_retries):
            try:
                resp = self.session.post(
                    f"{BASE_URL}/{endpoint}",
                    json={"text": text},
                    timeout=self.timeout,
                )
                resp.raise_for_status()
                return resp.json()
            except requests.exceptions.HTTPError as e:
                if resp.status_code == 429:
                    wait = 2 ** attempt
                    time.sleep(wait)
                    continue
                raise
            except requests.exceptions.ConnectionError:
                if attempt < self.max_retries - 1:
                    time.sleep(1)
                    continue
                raise
        raise Exception(f"Failed after {self.max_retries} retries")

    def toxicity(self, text: str) -> dict:
        return self._request("toxicity", text)

    def sentiment(self, text: str) -> dict:
        return self._request("sentiment", text)

    def entities(self, text: str) -> dict:
        return self._request("entities", text)

    def pii(self, text: str) -> dict:
        return self._request("pii", text)

    def language(self, text: str) -> dict:
        return self._request("language", text)

    def full_analysis(self, text: str) -> dict:
        return {
            "toxicity": self.toxicity(text),
            "sentiment": self.sentiment(text),
            "entities": self.entities(text),
            "pii": self.pii(text),
            "language": self.language(text),
        }

# Usage
nlp = BrainiallNLP(api_key="YOUR_KEY")
result = nlp.sentiment("This is a great product!")
print(f"Sentiment: {result['sentiment']} ({result['confidence']:.3f})")
```

### Python: FastAPI Integration

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import httpx

app = FastAPI()

NLP_BASE = "https://apim-ai-apis.azure-api.net/v1/nlp"
NLP_HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

class TextInput(BaseModel):
    text: str

class ModerationResponse(BaseModel):
    allowed: bool
    language: str
    sentiment: str
    is_toxic: bool
    has_pii: bool
    entities: list[dict]

@app.post("/api/moderate", response_model=ModerationResponse)
async def moderate_text(input: TextInput):
    """Content moderation endpoint using Brainiall NLP."""
    async with httpx.AsyncClient() as client:
        toxicity_task = client.post(f"{NLP_BASE}/toxicity", headers=NLP_HEADERS, json={"text": input.text})
        sentiment_task = client.post(f"{NLP_BASE}/sentiment", headers=NLP_HEADERS, json={"text": input.text})
        pii_task = client.post(f"{NLP_BASE}/pii", headers=NLP_HEADERS, json={"text": input.text})
        language_task = client.post(f"{NLP_BASE}/language", headers=NLP_HEADERS, json={"text": input.text})
        entities_task = client.post(f"{NLP_BASE}/entities", headers=NLP_HEADERS, json={"text": input.text})

        import asyncio
        responses = await asyncio.gather(toxicity_task, sentiment_task, pii_task, language_task, entities_task)
        toxicity, sentiment, pii, language, entities = [r.json() for r in responses]

    if toxicity["is_toxic"]:
        raise HTTPException(status_code=422, detail=f"Content blocked: {toxicity['max_category']}")

    return ModerationResponse(
        allowed=True,
        language=language["language"],
        sentiment=sentiment["sentiment"],
        is_toxic=toxicity["is_toxic"],
        has_pii=pii["pii_found"],
        entities=entities["entities"],
    )
```

### Python: LangChain Tool Integration

```python
from langchain_core.tools import tool
from langchain_brainiall import ChatBrainiall
from langgraph.prebuilt import create_react_agent
import requests

NLP_BASE = "https://apim-ai-apis.azure-api.net/v1/nlp"
NLP_HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

@tool
def analyze_sentiment(text: str) -> str:
    """Analyze the sentiment of text. Returns positive or negative with confidence."""
    result = requests.post(f"{NLP_BASE}/sentiment", headers=NLP_HEADERS, json={"text": text}).json()
    return f"Sentiment: {result['sentiment']} (confidence: {result['confidence']:.2f})"

@tool
def detect_toxicity(text: str) -> str:
    """Check if text contains toxic content across 6 categories."""
    result = requests.post(f"{NLP_BASE}/toxicity", headers=NLP_HEADERS, json={"text": text}).json()
    if result["is_toxic"]:
        return f"TOXIC: {result['max_category']} (score: {result['max_score']:.2f})"
    return f"Not toxic. Max score: {result['max_score']:.3f} ({result['max_category']})"

@tool
def extract_entities(text: str) -> str:
    """Extract named entities (persons, organizations, locations) from text."""
    result = requests.post(f"{NLP_BASE}/entities", headers=NLP_HEADERS, json={"text": text}).json()
    if not result["entities"]:
        return "No entities found."
    entities = [f"{e['text']} ({e['label']})" for e in result["entities"]]
    return f"Found {len(entities)} entities: {', '.join(entities)}"

@tool
def detect_pii(text: str) -> str:
    """Detect personally identifiable information (emails, phones, SSNs, credit cards)."""
    result = requests.post(f"{NLP_BASE}/pii", headers=NLP_HEADERS, json={"text": text}).json()
    if not result["pii_found"]:
        return "No PII detected."
    pii_items = [f"{e['type']}: {e['value']}" for e in result["entities"]]
    return f"PII found: {', '.join(pii_items)}"

@tool
def detect_language(text: str) -> str:
    """Detect the language of text. Supports 217 languages."""
    result = requests.post(f"{NLP_BASE}/language", headers=NLP_HEADERS, json={"text": text}).json()
    return f"Language: {result['language_name']} ({result['language']}) - confidence: {result['confidence']:.2f}"

# Create an AI agent with NLP tools
llm = ChatBrainiall(model="claude-sonnet-4-6")
agent = create_react_agent(llm, [analyze_sentiment, detect_toxicity, extract_entities, detect_pii, detect_language])

result = agent.invoke({"messages": [("human", "Analyze this customer review for sentiment and any PII: 'John Smith loved the product. Contact him at john@example.com'")]})
for msg in result["messages"]:
    print(f"{msg.type}: {msg.content}")
```

### Python: CrewAI Content Analysis

```python
from crewai import Agent, Task, Crew
from crewai.tools import tool
import requests

NLP_BASE = "https://apim-ai-apis.azure-api.net/v1/nlp"
NLP_HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

@tool("Sentiment Analyzer")
def sentiment_tool(text: str) -> str:
    """Analyze sentiment of customer feedback text."""
    result = requests.post(f"{NLP_BASE}/sentiment", headers=NLP_HEADERS, json={"text": text}).json()
    return f"{result['sentiment']} ({result['confidence']:.2f})"

@tool("Entity Extractor")
def entity_tool(text: str) -> str:
    """Extract named entities from text."""
    result = requests.post(f"{NLP_BASE}/entities", headers=NLP_HEADERS, json={"text": text}).json()
    return str(result["entities"])

analyst = Agent(
    role="Customer Feedback Analyst",
    goal="Analyze customer feedback for sentiment trends and key entities",
    backstory="Expert NLP analyst specializing in customer satisfaction metrics",
    tools=[sentiment_tool, entity_tool],
)

task = Task(
    description="Analyze these customer reviews and summarize sentiment trends: {reviews}",
    agent=analyst,
    expected_output="Summary with sentiment distribution and key entities mentioned",
)

crew = Crew(agents=[analyst], tasks=[task])
result = crew.kickoff(inputs={"reviews": "Great product! Fast shipping. Would buy again."})
```

### JavaScript: Full NLP Analysis

```javascript
const BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp";
const HEADERS = {
  "Content-Type": "application/json",
  Authorization: "Bearer YOUR_KEY",
};

async function analyzeText(text) {
  const endpoints = ["toxicity", "sentiment", "entities", "pii", "language"];
  const results = {};

  await Promise.all(
    endpoints.map(async (endpoint) => {
      const response = await fetch(`${BASE_URL}/${endpoint}`, {
        method: "POST",
        headers: HEADERS,
        body: JSON.stringify({ text }),
      });
      results[endpoint] = await response.json();
    })
  );

  return {
    text,
    language: results.language.language,
    sentiment: results.sentiment.sentiment,
    confidence: results.sentiment.confidence,
    is_toxic: results.toxicity.is_toxic,
    entity_count: results.entities.entity_count,
    pii_found: results.pii.pii_found,
  };
}

const analysis = await analyzeText(
  "John from Google in NYC emailed john@google.com — great product!"
);
console.log(JSON.stringify(analysis, null, 2));
```

### JavaScript: Express.js Content Moderation Middleware

```javascript
import express from "express";

const app = express();
app.use(express.json());

const NLP_BASE = "https://apim-ai-apis.azure-api.net/v1/nlp";
const API_KEY = "YOUR_KEY";
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${API_KEY}`,
};

// Moderation middleware
async function moderateContent(req, res, next) {
  const text = req.body.message || req.body.content || req.body.text;
  if (!text) return next();

  try {
    const [toxicityRes, piiRes] = await Promise.all([
      fetch(`${NLP_BASE}/toxicity`, {
        method: "POST",
        headers,
        body: JSON.stringify({ text }),
      }),
      fetch(`${NLP_BASE}/pii`, {
        method: "POST",
        headers,
        body: JSON.stringify({ text }),
      }),
    ]);

    const toxicity = await toxicityRes.json();
    const pii = await piiRes.json();

    if (toxicity.is_toxic) {
      return res
        .status(422)
        .json({ error: "Content blocked", category: toxicity.max_category });
    }

    req.moderation = { is_toxic: false, has_pii: pii.pii_found, pii_types: pii.entities?.map((e) => e.type) || [] };
    next();
  } catch (err) {
    next(); // Fail open — log error but don't block
  }
}

app.post("/api/messages", moderateContent, (req, res) => {
  res.json({ status: "sent", moderation: req.moderation });
});

app.listen(3000);
```

### JavaScript: Batch Analysis with Rate Limiting

```javascript
const BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp";
const API_KEY = "YOUR_KEY";

async function batchAnalyze(texts, endpoint, concurrency = 5) {
  const results = [];
  for (let i = 0; i < texts.length; i += concurrency) {
    const batch = texts.slice(i, i + concurrency);
    const batchResults = await Promise.all(
      batch.map(async (text) => {
        const response = await fetch(`${BASE_URL}/${endpoint}`, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${API_KEY}`,
          },
          body: JSON.stringify({ text }),
        });
        return response.json();
      })
    );
    results.push(...batchResults);
    if (i + concurrency < texts.length) {
      await new Promise((resolve) => setTimeout(resolve, 100));
    }
  }
  return results;
}

// Analyze 100 customer reviews
const reviews = ["Great product!", "Terrible service", /* ... */];
const sentiments = await batchAnalyze(reviews, "sentiment", 10);

const positive = sentiments.filter((r) => r.sentiment === "positive").length;
console.log(`Positive: ${positive}/${sentiments.length} (${((positive / sentiments.length) * 100).toFixed(1)}%)`);
```

### curl: All Endpoints

```bash
BASE="https://apim-ai-apis.azure-api.net/v1/nlp"
KEY="YOUR_KEY"

# Toxicity
curl -s -X POST "$BASE/toxicity" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $KEY" \
  -d '{"text": "You are wonderful!"}' | python3 -m json.tool

# Sentiment
curl -s -X POST "$BASE/sentiment" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $KEY" \
  -d '{"text": "Best product ever!"}' | python3 -m json.tool

# Entities
curl -s -X POST "$BASE/entities" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $KEY" \
  -d '{"text": "Satya Nadella leads Microsoft from Redmond."}' | python3 -m json.tool

# PII
curl -s -X POST "$BASE/pii" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $KEY" \
  -d '{"text": "Email me at test@test.com, SSN 123-45-6789"}' | python3 -m json.tool

# Language
curl -s -X POST "$BASE/language" \
  -H "Content-Type: application/json" -H "Authorization: Bearer $KEY" \
  -d '{"text": "Bonjour le monde"}' | python3 -m json.tool

# Health
curl -s "$BASE/health" -H "Authorization: Bearer $KEY" | python3 -m json.tool
```

## Use Cases

### Content Moderation for Chat Applications

Moderate user messages in real-time for chat apps, forums, and social platforms. Combine toxicity detection with PII scanning to block harmful content and protect user privacy.

```python
import requests

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

def should_allow_message(message: str) -> tuple[bool, str]:
    """Returns (allowed, reason) for a chat message."""
    toxicity = requests.post(f"{BASE_URL}/toxicity", headers=HEADERS, json={"text": message}).json()

    if toxicity["scores"]["severe_toxic"] > 0.3:
        return False, "severe_toxic"
    if toxicity["scores"]["threat"] > 0.3:
        return False, "threat"
    if toxicity["is_toxic"]:
        return False, toxicity["max_category"]

    pii = requests.post(f"{BASE_URL}/pii", headers=HEADERS, json={"text": message}).json()
    if pii["pii_found"]:
        pii_types = [e["type"] for e in pii["entities"]]
        if "ssn" in pii_types or "credit_card" in pii_types:
            return False, f"sensitive_pii: {pii_types}"

    return True, "allowed"
```

### Customer Review Analysis

Analyze large volumes of product reviews for sentiment trends, extract mentioned entities, and detect review spam.

```python
import requests
from collections import Counter

BASE_URL = "https://apim-ai-apis.azure-api.net/v1/nlp"
HEADERS = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

def analyze_reviews(reviews: list[str]) -> dict:
    """Analyze a batch of customer reviews."""
    sentiments = []
    all_entities = []
    languages = Counter()

    for review in reviews:
        sent = requests.post(f"{BASE_URL}/sentiment", headers=HEADERS, json={"text": review}).json()
        ent = requests.post(f"{BASE_URL}/entities", headers=HEADERS, json={"text": review}).json()
        lang = requests.post(f"{BASE_URL}/language", headers=HEADERS, json={"text": review}).json()

        sentiments.append(sent["sentiment"])
        all_entities.extend([e["text"] for e in ent["entities"] if e["label"] in ("ORG", "PER")])
        languages[lang["language"]] += 1

    positive_rate = sentiments.count("positive") / len(sentiments) * 100
    entity_freq = Counter(all_entities).most_common(10)

    return {
        "total_reviews": len(reviews),
        "positive_rate": f"{positive_rate:.1f}%",
        "top_entities": entity_freq,
        "languages": dict(languages),
    }
```

### GDPR/CCPA Compliance Pipeline

Scan documents and databases for PII to ensure regulatory compliance. Combine PII detection with NER for comprehensive coverage.

### Email Classification and Routing

Use language detection + sentiment + entity extraction to automatically classify and route incoming emails to the right department.

### Social Media Monitoring

Monitor social media mentions for brand sentiment, toxicity directed at your brand, and identify key influencers (person entities) discussing your products.

## Migration Guides

### Migrating from AWS Comprehend

Replace AWS Comprehend API calls with Brainiall NLP:

```python
# Before: AWS Comprehend ($500/1M requests)
import boto3
comprehend = boto3.client("comprehend")
result = comprehend.detect_sentiment(Text="Great product!", LanguageCode="en")
print(result["Sentiment"])  # "POSITIVE"

# After: Brainiall NLP ($1/1M requests — 500x cheaper)
import requests
result = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/nlp/sentiment",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={"text": "Great product!"}
).json()
print(result["sentiment"])  # "positive"
```

### Migrating from Azure Text Analytics

```python
# Before: Azure Text Analytics ($700/1M requests)
from azure.ai.textanalytics import TextAnalyticsClient
client = TextAnalyticsClient(endpoint, credential)
result = client.analyze_sentiment(["Great product!"])

# After: Brainiall NLP ($1/1M requests — 700x cheaper)
import requests
result = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/nlp/sentiment",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={"text": "Great product!"}
).json()
```

### Migrating from Google Cloud Natural Language

```python
# Before: Google Cloud NLP ($1,000/1M requests for sentiment)
from google.cloud import language_v1
client = language_v1.LanguageServiceClient()
document = language_v1.Document(content="Great product!", type_=language_v1.Document.Type.PLAIN_TEXT)
sentiment = client.analyze_sentiment(request={"document": document})

# After: Brainiall NLP ($1/1M requests — 1000x cheaper)
import requests
result = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/nlp/sentiment",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={"text": "Great product!"}
).json()
```

### Replacing LLM-based NLP with Specialized Models

Using GPT-4o for sentiment costs ~$2,500/1M requests. Brainiall NLP does the same task for $1/1M — 2,500x cheaper:

```python
# Before: GPT-4o for sentiment ($2,500/1M)
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Classify sentiment as positive or negative: 'Great product!'"}],
)
# Costs ~$0.0025 per request, 500ms+ latency

# After: Brainiall NLP ($0.001 per request, <50ms latency)
import requests
result = requests.post(
    "https://apim-ai-apis.azure-api.net/v1/nlp/sentiment",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={"text": "Great product!"}
).json()
# 2,500x cheaper, 10x faster
```

## MCP Server

### Configuration (Claude Desktop / Cursor / Cline)

```json
{
  "mcpServers": {
    "brainiall-nlp": {
      "url": "https://apim-ai-apis.azure-api.net/mcp/nlp/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}
```

### Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| analyze_toxicity | Detect toxic content (6 categories) | text (string) |
| analyze_sentiment | Positive/negative sentiment | text (string) |
| extract_entities | NER: PER, ORG, LOC, MISC | text (string) |
| detect_pii | Find emails, phones, SSNs, credit cards | text (string) |
| detect_language | Identify language (217 supported) | text (string) |
| check_nlp_service | Health check | none |

## Pricing

| Endpoint | Price per request | Monthly cost (1M requests) |
|----------|------------------|---------------------------|
| Toxicity | $0.001 | $1,000 |
| Sentiment | $0.001 | $1,000 |
| Entities | $0.002 | $2,000 |
| PII | $0.002 | $2,000 |
| Language | $0.0005 | $500 |

### Cost Comparison with Alternatives

| Provider | Sentiment (1M req) | Entities (1M req) | PII (1M req) |
|----------|-------------------|-------------------|--------------|
| **Brainiall NLP** | **$1,000** | **$2,000** | **$2,000** |
| AWS Comprehend | $500 | $500 | $500 |
| Azure Text Analytics | $700 | $700 | $700 |
| Google Cloud NLP | $1,000 | $1,000 | $1,000 |
| GPT-4o (LLM) | $2,500 | $5,000 | $5,000 |
| GPT-4o mini (LLM) | $75 | $150 | $150 |

Note: LLM-based NLP is 50-5,000x more expensive and 10-50x slower for the same task. Specialized models deliver higher accuracy for specific tasks at a fraction of the cost.

## Models

All models are ONNX-optimized for CPU inference (no GPU required):

| Model | Architecture | Training Data | Accuracy | Latency |
|-------|-------------|---------------|----------|---------|
| Toxicity | Multi-label BERT | Jigsaw Toxic Comments | 97.5% AUC-ROC | ~500ms |
| Sentiment | DistilBERT | SST-2 | 91.3% accuracy | ~250ms |
| NER | BERT-base | CoNLL-2003 | 91.0 F1 | ~30ms |
| PII | Regex + patterns | — | 99.9% precision | ~1ms |
| Language | fastText lid.176.ftz | 217 languages | 98.5% accuracy | <1ms |

## Technical Details

- Runtime: ONNX Runtime (CPU optimized)
- Infrastructure: Azure Container Apps + NVIDIA A10 GPU VMs
- Latency: 1ms (language) to 500ms (toxicity)
- Rate limit: No hard limit (fair use)
- Max text length: 5,000 characters per request
- Encoding: UTF-8
- Response format: JSON

## Links

- Website: https://brainiall.com
- Get API Key: https://brainiall.com
- LLM Gateway: https://github.com/fasuizu-br/brainiall-llm-gateway
- Image APIs: https://github.com/fasuizu-br/brainiall-image-api
- Speech AI: https://github.com/fasuizu-br/speech-ai-examples