Sentor Python SDK

Official Python SDK for the Sentor API — entity-based sentiment analysis, document clustering, and topic naming.

Stop guessing why ratings drop. Sentor pinpoints exactly how customers feel about specific entities — brands, products, features, competitors — using fine-tuned BERT models trained for aspect-based sentiment analysis.

Table of Contents

• Installation
• Quick Start
• API Reference
  • predict()
  • cluster()
  • generate_topic_name()
  • check_health()
• Error Handling
• Rate Limits
• Migration from sentor-ml

📦 Installation

pip install sentor-python-sdk

Get a free API key at dashboard.sentor.app.

🚀 Quick Start

from sentor import SentorClient

client = SentorClient("your_api_key")

results = client.predict([
    {
        "doc_id": "review-1",
        "doc": "Apple's new iPhone is amazing but the price is ridiculous.",
        "entities": ["Apple", "iPhone", "price"]
    }
])

for item in results["results"]:
    print(item["doc_id"], item["predicted_label"])
    for es in item.get("entity_sentiments", []):
        print(f"  {es['entity']}: {es['sentiment']} ({es['score']:.2f})")

📖 API Reference

predict(documents, language="en")

Score sentiment toward named entities in one or more documents.

results = client.predict(
    documents=[
        {
            "doc_id": "r1",
            "doc": "Samsung's camera is great but battery life is poor.",
            "entities": ["Samsung", "camera", "battery life"]
        }
    ],
    language="en"  # "en" or "nl"
)

Response shape:

{
    "results": [
        {
            "doc_id": "r1",
            "predicted_class": 0,        # 0=negative, 1=neutral, 2=positive
            "predicted_label": "negative",
            "probabilities": {"negative": 0.72, "neutral": 0.18, "positive": 0.10},
            "details": [...],            # per-sentence breakdown
            "entity_sentiments": [
                {"entity": "Samsung", "sentiment": "neutral", "score": 0.61},
                {"entity": "camera", "sentiment": "positive", "score": 0.88},
                {"entity": "battery life", "sentiment": "negative", "score": 0.91}
            ]
        }
    ]
}

Supported languages: en (English), nl (Dutch)

cluster(documents, language="en")

Group 5+ documents into thematic clusters using BERTopic + HDBSCAN.

results = client.cluster(
    documents=[
        {"doc_id": "r1", "text": "Shipping was incredibly fast.", "entities": ["shipping"]},
        # ... at least 5 documents
    ],
    language="en"
)

for cluster in results["clusters"]:
    print(cluster["cluster_id"], cluster["document_count"], cluster["top_words"])
# Cluster -1 = outliers that did not fit any topic

generate_topic_name(cluster_id, documents, ...)

Generate a 3–5 word label for a cluster using an LLM.

result = client.generate_topic_name(
    cluster_id=0,
    documents=cluster["documents"],
    top_words=cluster["top_words"],
    entities=["BrandName"],
    language="en"
)
print(result["topic_name"])  # e.g. "Shipping Delay Complaints"

check_health()

health = client.check_health()
# {"status": "healthy", "version": "...", "llm_status": "available"}

⚠️ Error Handling

from sentor import SentorClient
from sentor.exceptions import SentorAPIError, RateLimitError, AuthenticationError

client = SentorClient("your_api_key")

try:
    results = client.predict([...])
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limit hit. Retry after {e.retry_after}s")
except SentorAPIError as e:
    print(f"API error: {e.message} (code: {e.code})")

📊 Rate Limits

View full pricing →

🔄 Migration from sentor-ml

This package replaces sentor-ml. The import name (sentor) and all method signatures are unchanged — only the install command changes:

pip uninstall sentor-ml
pip install sentor-python-sdk

🔗 Links

• Sentor Dashboard — manage API keys and usage
• API Documentation
• PyPI Package
• Support

Built by NIKX Technologies B.V.