Metadata-Version: 2.4
Name: planisphere
Version: 0.1.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

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(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.
