Planisphere — Python client

Official Python client for the Planisphere compliant-AI API. Gate an AI action before it executes, get a signed, offline-verifiable evidence receipt, and route what needs a human. Zero dependencies — standard library only.

pip install planisphere

Quickstart

from planisphere_sdk import Planisphere, PlanisphereNeedsReview, PlanisphereBlocked

ps = Planisphere(api_key="ps_live_...")   # or ps_test_ for a free sandbox key

decision = ps.gate(
    pack="law",
    proposed_action="File this motion with the court.",
    surface="agent",
    source_key="agent:run:42",
    law_context={"matter_band": "litigation", "tool_id": "harvey"},
    idempotency_key="run-42",   # safe to retry — returns the original result, meters once
)

if decision["decision"] == "allow":
    ...  # proceed, and keep decision["evidence_packet"] as your receipt

Prefer exceptions? require_allow raises unless the action is allowed:

try:
    ps.require_allow(pack="law", proposed_action="...", surface="agent",
                     source_key="agent:run:42", law_context={...})
    do_the_thing()
except PlanisphereNeedsReview as e:
    route_to_reviewer(e.decision)   # pause the workflow
except PlanisphereBlocked as e:
    stop(e.decision)                # hard stop

Verify a receipt

kit = ps.verify_kit()                       # how to verify offline
result = ps.verify(seal_verification_payload)  # or check server-side
record = ps.get_record("law:check-citations:...")  # fetch a stored evidence packet

Reviews

ps.record_review(action_key="law:...", reviewer="jane@firm.com", decision="approved")
queue = ps.review_queue(status="pending")

Errors

PlanisphereError (base) → PlanisphereAuthError (401/403), PlanisphereRateLimited (429, with .retry_after), plus the decision signals PlanisphereBlocked / PlanisphereNeedsReview (both carry .decision). Every error carries .status and the parsed .body.

Sandbox

Get a free ps_test_ key with no card at POST /signup/test-key. Sandbox receipts are signed with a non-production key (dev_key: true) so they can never be mistaken for production evidence. Upgrade in place by completing checkout with the same email.

Records, never certification. Planisphere US, Corp.