Quickstart

The whole integration is one call before a consequential action. There is no runtime to adopt, no framework to standardise on, and no proxy in front of your traffic.

Install

pip install rotascale

Point it at your deployment

export ROTASCALE_URL="https://rotagrant.internal.example"
export ROTASCALE_API_KEY="rsk_..."

See Authentication for where the key comes from and what it is scoped to.

Ask before you act

from rotascale import Rotascale

rs = Rotascale()

decision = rs.authorize(
    grant_id="grt_01KZXYD62VG0",
    {"tool": ["payments.transfer"]},
    amount_minor=25_000_00,
    currency="EUR",
)

if decision.allowed:
    transfer(...)

By default authorize raises on a refusal, so the unsafe path is the one you have to write on purpose rather than the one you get by forgetting to check a return value.

What comes back

Decision(
    outcome="allow",
    allowed=True,
    reason="within grant",
    grant_id="grt_01KZXYD62VG0",
    ledger_id="led_01KZZWKNEPCJ",
)

Exhausted:
  the call allowance on this grant is spent; retrying cannot help

Six outcomes, not two. allow, deny, exhausted, gated, review_sync and review_async are different findings that send an operator to different places, which is why they are not collapsed into a boolean. See Outcomes.

Nothing is enforced yet

A grant created today starts in observe. It records what the check would have done and changes nothing. That is deliberate: run it against production for a fortnight and find out what your agents are actually doing before you decide whether to stop any of it.

The first week of observe data reliably contains at least one behaviour nobody knew about. That finding is usually worth the integration on its own.

When you are ready, move one grant up the ladder. See Move up the ladder.

Handling refusals properly

from rotascale import Blocked, Exhausted, Gated, ReviewRequired

try:
    rs.authorize(grant_id, {"tool": ["payments.transfer"]},
                 amount_minor=25_000_00, currency="EUR")
except Exhausted:
    # The allowance is spent. Retrying cannot help, and the agent is told so
    # rather than being left to loop.
    escalate_to_human()
except Gated:
    # Something untrusted entered this trajectory and the grant requires a
    # clean context for this action.
    escalate_to_human()
except ReviewRequired as exc:
    # A person has to decide. exc.review_id is the handle.
    park(exc.review_id)
except Blocked:
    # Policy said no.
    stop()

See Errors for the full hierarchy and what each one means.

Getting started

Core concepts

Guides

Integrations

What comes back

Nothing is enforced yet

Handling refusals properly

​What comes back

​Nothing is enforced yet

​Handling refusals properly

What comes back

Nothing is enforced yet

Handling refusals properly