Planisphere — Python client

Source preview: 0.2.0

This source checkout includes recording and buffered recording. The public registry was still on 0.1.0 at the September 20 audit; installing that release does not provide these newer methods. Use the documented HTTP connection helper until the tested 0.2.0 package is published and its registry contents verified.

BufferedRecorder is an in-memory queue, not durable capture. submit() copies the input and returns without doing network work; it raises if the queue is full or closed. pending_count includes in-flight records, and last_error / on_error expose a failed send. Explicitly call close() (or use the context manager) and handle its exception. Failed batches remain pending for a later flush() or close() retry. An abrupt exit can lose pending data. Use a durable outbox when the workflow requires crash recovery; never equate submission with a receipt.

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(pack="law", action_key=decision["action_key"],
                 reviewer="jane@firm.com", decision="approved")
queue = ps.review_queue(pack="law", status="pending")

Only decide a review after the named reviewer has actually reviewed the work. With an API key, reviewer is a caller assertion; it is not an authenticated human identity. Both review methods require the policy pack.

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

Create a free workspace at Sign up, verify your email, then create a ps_test_ key in the console's Keys tab. No card is required. Sandbox receipts retain dev_key: true. Upgrade the verified workspace from Billing; existing records keep their original signatures.

Records, never certification. Planisphere US, Corp.