Skip to content

NIKX-Tech/sentor-python-sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

33 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Sentor Python SDK

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

PyPI Python License GitHub Stars
Website Dashboard Docs

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

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

Plan Per Minute Per Day Per Month
Free 5 100 1,000
Starter 60 1,000 10,000
Growth 200 3,000 30,000
Business 500 10,000 100,000
Enterprise Custom Custom Custom

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


Built by NIKX Technologies B.V.

About

A Python SDK to make the Sentor ML usage simpler for developers.

Resources

License

Stars

2 stars

Watchers

0 watching

Forks

Packages

 
 
 

Contributors

Languages