Documentation
Python

Python SDK

rail-score-sdkv2.1.1 on PyPI

The official Python client for the RAIL Score API. Supports sync and async operations, type-safe responses, middleware for LLM pipelines, and drop-in wrappers for OpenAI, Anthropic, and Gemini.

Migration note: This package replaces the deprecated rail-score package. Import path changed from rail_score.RailScore to rail_score_sdk.RailScoreClient.

Installation

Base package

pip install rail-score-sdk

With provider integrations

pip install "rail-score-sdk[openai]"        # OpenAI wrapper
pip install "rail-score-sdk[anthropic]"     # Anthropic wrapper
pip install "rail-score-sdk[google]"        # Google Gemini wrapper
pip install "rail-score-sdk[integrations]"  # All integrations

Requirements: Python 3.8 – 3.12

Dependencies: httpx, requests, pydantic

Client Initialization

Synchronous
from rail_score_sdk import RailScoreClient

# Pass API key directly
client = RailScoreClient(api_key="rail_your_api_key")

# Or set RAIL_API_KEY environment variable
client = RailScoreClient()  # reads from env
Async
from rail_score_sdk import AsyncRAILClient

client = AsyncRAILClient(api_key="rail_your_api_key")

result = await client.eval(content="...", mode="basic")

Core Methods

client.eval()

Score content across RAIL dimensions. Returns scores, confidence, and optional explanations.

result = client.eval(
    content="Based on our analysis, renewable energy adoption has increased 30% globally.",
    mode="basic",             # "basic" or "deep"
    dimensions=None,          # Optional: ["fairness", "safety"]
    weights=None,             # Optional: {"safety": 60, "privacy": 40}
    context=None,             # Optional context string
    include_explanations=False,
    include_issues=False,
    include_suggestions=False,
    domain="general",
    usecase="general"
)

# Access results
print(result.rail_score.score)       # 8.5
print(result.rail_score.confidence)  # 0.85
print(result.dimension_scores["fairness"].score)  # 9.0
print(result.credits_consumed)       # 1.0
print(result.from_cache)             # False

client.protected_evaluate()

Evaluate content against a quality threshold. Returns improvement guidance if below threshold.

result = client.protected_evaluate(
    content="AI response that might have quality issues...",
    threshold=7.0,   # Minimum acceptable score
    mode="basic"     # "basic" (0.5 cr) or "deep" (1.0 cr)
)

if result.improvement_needed:
    print(f"Score: {result.rail_score.score} — below threshold")
    print(f"How to fix: {result.improvement_prompt}")
else:
    print(f"Passed with score: {result.rail_score.score}")

client.protected_regenerate()

Regenerate content to fix identified issues (4 credits). Pass the issues from a previous evaluation.

improved = client.protected_regenerate(
    content="Original text with bias and safety issues...",
    issues_to_fix={
        "fairness": {"score": 3, "explanation": "Gender bias detected"},
        "safety": {"score": 4, "explanation": "Missing safety disclaimers"}
    }
)

print(improved.improved_content)       # Rewritten text
print(improved.issues_addressed)       # ["fairness", "safety"]

client.compliance_check()

Assess content against one or more regulatory frameworks.

# Single framework (5 credits)
result = client.compliance_check(
    content="System that processes user data for personalized ads...",
    framework="gdpr"
)

print(f"Compliance: {result.compliance_score.label}")   # "Good", "Poor", etc.
print(f"Score: {result.compliance_score.score}/10")
print(f"Passed: {result.requirements_passed}/{result.requirements_checked}")

for issue in result.issues:
    print(f"  [{issue.severity}] {issue.description}")

# Multiple frameworks (8-10 credits)
result = client.compliance_check(
    content="Healthcare data processing system...",
    frameworks=["hipaa", "gdpr", "ccpa"],
    context={"domain": "healthcare", "processes_personal_data": True}
)

client.health() / client.version()

Check API status (free, no credits).

health = client.health()   # {"status": "healthy", "service": "rail-score-engine"}
version = client.version() # {"version": "1.0.2", "api_version": "v1", ...}

Error Handling

The SDK provides a granular exception hierarchy for precise error handling:

from rail_score_sdk import (
    RailScoreClient,
    AuthenticationError,
    InsufficientCreditsError,
    ValidationError,
    ContentTooHarmfulError,
    RateLimitError,
    RAILBlockedError,
)

client = RailScoreClient(api_key="rail_your_api_key")

try:
    result = client.eval(content="...", mode="deep")
except AuthenticationError:
    print("Invalid API key — check your rail_ key")
except InsufficientCreditsError as e:
    print(f"Need {e.required} credits, have {e.balance}")
except ValidationError as e:
    print(f"Invalid request: {e}")
except ContentTooHarmfulError:
    print("Content refused — critical violations detected")
except RateLimitError:
    print("Rate limited — retry after backoff")
except RAILBlockedError:
    print("Request blocked by policy")
ExceptionHTTP CodeWhen
AuthenticationError401Invalid or missing API key
InsufficientCreditsError402Not enough credits
ValidationError400Invalid parameters
ContentTooHarmfulError422Regeneration refused
RateLimitError429Too many requests
RAILBlockedError403Policy enforcement block

Sessions & Middleware

RAILSession

Multi-turn conversation tracking with adaptive quality gating.

from rail_score_sdk import RailScoreClient, RAILSession

client = RailScoreClient(api_key="rail_your_api_key")
session = RAILSession(client)

# Each turn is automatically evaluated
response1 = session.add_turn(content="First AI response about climate change...")
response2 = session.add_turn(content="Follow-up with more specific data...")

# Session tracks context across turns
print(session.history)        # List of all turn evaluations
print(session.average_score)  # Running average across turns

RAILMiddleware

Wrap any LLM call with RAIL evaluation. Automatically blocks or regenerates below-threshold responses.

from rail_score_sdk import RailScoreClient, RAILMiddleware

client = RailScoreClient(api_key="rail_your_api_key")
middleware = RAILMiddleware(client, threshold=7.0)

@middleware.wrap
def generate(prompt):
    return llm.complete(prompt)  # Your LLM call here

# Middleware evaluates output and blocks/regenerates if needed
result = generate("Write a hiring recommendation...")

PolicyEngine

Configurable policy enforcement with custom callbacks for production pipelines.

from rail_score_sdk import PolicyEngine

engine = PolicyEngine(
    mode="block",          # "log_only", "block", "regenerate", "custom"
    threshold=7.0,
    on_block=lambda result: notify_admin(result)  # Custom callback
)

Score Labels

RangeLabel
9.0 – 10.0Excellent
7.0 – 8.9Good
5.0 – 6.9Needs improvement
3.0 – 4.9Poor
0.0 – 2.9Critical
Provider Integrations →View on PyPI