Python: Policy Engine

Concept: Policy Engine | Sessions: RAILSession | Middleware: RAILMiddleware

PolicyEngine decides what happens after a response is scored: pass it through, block it, attempt an automatic regeneration, or hand it to your own callback. You rarely construct it directly — RAILSession and RAILMiddleware both take a policy= argument and build a PolicyEngine for you. This page covers the shared Policy enum and, at the bottom, how to drive PolicyEngine standalone for advanced orchestration.

Policies

Policy is a string enum, so you can pass either the member or its value interchangeably (Policy.BLOCK and "block" are the same thing):

Value	Behavior
`Policy.LOG_ONLY`	Always pass through — the score is attached but nothing is blocked. This is the default for both `RAILSession` and `RAILMiddleware`.
`Policy.BLOCK`	Raise `RAILBlockedError` when the score is below `threshold`.
`Policy.REGENERATE`	Call `/safe-regenerate` once and return the improved content in place of the original.
`Policy.CUSTOM`	Call your own async callback with the content and the raw eval response; the callback decides what happens. Requires `custom_callback` — supported by `RAILSession` and standalone `PolicyEngine`, not currently by `RAILMiddleware`.
`Policy.DPDP_ENFORCE`	Run a DPDP scan before the threshold check. Only takes effect when you construct `PolicyEngine` directly with a `dpdp=` config — see Standalone usage below.

Via RAILMiddleware

The common case — score every response from your own generation function and enforce a policy on it:

from rail_score_sdk import RAILMiddleware, Policy

async def my_model_call(messages, **kwargs):
    return "..."  # your model's response

mw = RAILMiddleware(
    api_key="YOUR_RAIL_API_KEY",
    generate_fn=my_model_call,
    threshold=7.0,
    policy=Policy.BLOCK,
)

result = await mw.run(messages=[{"role": "user", "content": "..."}])

Via RAILSession, with a custom callback

RAILSession forwards custom_callback into its PolicyEngine, so Policy.CUSTOM works here (unlike RAILMiddleware, which doesn’t currently expose a custom_callback parameter):

from rail_score_sdk import RAILSession, Policy

async def send_for_review(content: str, eval_response: dict, async_client) -> str | None:
    queue_for_human_review(content, eval_response)
    return None  # None keeps the original content; return a string to replace it

async with RAILSession(
    api_key="YOUR_RAIL_API_KEY",
    policy=Policy.CUSTOM,
    custom_callback=send_for_review,
) as session:
    result = await session.evaluate_turn(
        user_message="...",
        assistant_response="...",
    )

Handling a block

Policy.BLOCK raises RAILBlockedError rather than returning a result:

from rail_score_sdk import RAILBlockedError

try:
    result = await mw.run(messages=[...])
except RAILBlockedError as e:
    print(f"Blocked: score {e.score:.1f} < threshold {e.threshold:.1f}")
    print(e.issues)  # list of issue dicts, if any were returned

The result object

Whichever wrapper you use, a passing (or regenerated, log-only, or custom-handled) turn returns an EvalResult with:

Field	Type	Notes
`content`	`str`	The final content — the regenerated version if `was_regenerated` is `True`.
`score`, `confidence`	`float`	Overall score and model confidence.
`threshold_met`	`bool`	Whether `score >= threshold`.
`dimension_scores`	`dict`	Raw per-dimension scores from the API response.
`issues`, `improvement_suggestions`	`list`	Present when the underlying eval call requested them.
`was_regenerated`	`bool`	`True` if `Policy.REGENERATE` (or a custom callback) replaced the content.
`original_content`	`str \| None`	The pre-regeneration content, when `was_regenerated` is `True`.
`raw_response`	`dict`	The unparsed `result` dict from `/railscore/v1/eval`.
`dpdp`	optional	Populated when the session/middleware was configured with `dpdp=`.

Standalone usage

Most integrations go through RAILSession or RAILMiddleware. If you need to enforce a policy on evaluations you’re driving yourself — for example, Policy.DPDP_ENFORCE, which neither wrapper currently exposes — construct PolicyEngine directly. It expects the raw result dict from the API, which is what AsyncRAILClient.eval() returns (the sync RailScoreClient.eval() returns a parsed object instead, so use the async client here):

from rail_score_sdk import AsyncRAILClient
from rail_score_sdk.policies import PolicyEngine, Policy

async_client = AsyncRAILClient(api_key="YOUR_RAIL_API_KEY")
engine = PolicyEngine(
    policy=Policy.DPDP_ENFORCE,
    threshold=7.0,
    dpdp={"purpose": "customer_support", "jurisdiction": "IN"},
)

async with async_client:
    eval_response = await async_client.eval(content="...", mode="basic")
    result = await engine.enforce(
        content="...",
        eval_response=eval_response,
        async_client=async_client,
    )

A DPDP violation configured with action: "block" raises DPDPBlockedError — see the DPDP page for the violation model and configuration shape.

Costs follow the underlying call — enforcing a policy doesn’t add a separate charge beyond the /eval (and, for Policy.REGENERATE, /safe-regenerate) requests it makes. See Credits for what each endpoint costs.

​Policies

​Via RAILMiddleware

​Via RAILSession, with a custom callback

​Handling a block

​The result object

​Standalone usage

Policies

Via RAILMiddleware

Via RAILSession, with a custom callback

Handling a block

The result object

Standalone usage