Metadata-Version: 2.5
Name: planisphere
Version: 0.2.0
Summary: Official Python client for the Planisphere compliant-AI gate/verify/records API.
Project-URL: Homepage, https://planisphere.ooo
Project-URL: API, https://api.planisphere.ooo/docs
Author: Planisphere US, Corp.
License: MIT
Keywords: ai,audit-trail,compliance,evidence,gate,governance
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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](https://planisphere.ooo) 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.

```bash
pip install planisphere
```

## Quickstart

```python
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:

```python
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

```python
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

```python
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](https://api.planisphere.ooo/signup), 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.
