Python SDK

The official client is sentinelai-risk, a thin wrapper around the SentinelAI API with retries, timeouts, and error handling built in.

pip install sentinelai-risk

Quick example

from sentinelai import SentinelAIClient

client = SentinelAIClient(api_key="sk_...")

prompt = "What was Q3 revenue?"
llm_output = "Revenue grew 45% year over year."

result = client.verify(prompt=prompt, response=llm_output)

if result["status"] == "hallucinated":
    print(result["corrected"])  # serve the fix, not the flaw
else:
    print(result["score"], result["claims"])

`verify()` — the one-shot check

Field	Type	Meaning
`score`	`int`	0 (safe) to 100 (critical)
`status`	`str`	`trusted` (0–24), `needs_review` (25–59), `hallucinated` (60–100)
`decision`	`str`	`allow`, `warn`, `block`, or `escalate`
`action_taken`	`str`	The action executed by the policy engine
`claims`	`list[dict]`	Detector-level findings with severity and note
`corrected`	`str \| None`	Cleaned response when correction applies
`meta`	`dict`	Claims checked, detectors run, timestamp

`analyze()` — the raw API response

verify() is built on analyze(), which returns the full API payload: final_risk_score (0–1), flags, confidence, decision, action_taken, decision_reason, settings_version, thresholds_applied, and log_id for feedback reporting.

`correct()` — get the fixed text

safe_text = client.correct(prompt=prompt, response=llm_output)

Returns the original response when trusted, the corrected version otherwise.

Conversation context

Track a multi-turn session with ConversationTracker and score turns in context:

from sentinelai import ConversationTracker

tracker = ConversationTracker(client, session_id="sess-001")
tracker.add_turn(role="user", content="What's our Q3 revenue?")
tracker.add_turn(role="assistant", content="Q3 revenue was $2.1M.")

verdicts = tracker.analyze_conversation()      # per-turn verdicts
stats = tracker.get_risk_statistics()          # conversation-level risk
risky = tracker.get_high_risk_turns(threshold=0.7)

Batch analysis

results = client.analyze_batch([
    {"prompt": "A", "response": "..."},
    {"prompt": "B", "response": "..."},
])

Items are analyzed in parallel (default 5 workers).

Reliability

Automatic retries with exponential backoff on 429/5xx — capped at 60s
Timeouts that fail fast instead of hanging
Safe fallback — if the API is unreachable, analyze() returns {"decision": "allow", "fallback": true} rather than crashing your request path
Structured errors — SentinelAIError, SentinelAIConnectionError, SentinelAIAuthenticationError

The SDK works against both the managed cloud and your self-hosted instance. Point it at your own base URL with SentinelAIClient(api_key="...", base_url="http://localhost:8000").

Python SDK

On this page