PrivyQ Python SDK (privyq)

The developer-facing interface to PrivyQ. It hides all cryptographic and gRPC detail behind three verbs, protect(), access(), verify(), so you think in terms of business intent, not primitives.

import privyq

privyq.configure(core_address="localhost:50051")

# Lock a record, attaching the access rules in the same call.
protected = privyq.protect(
    "Patient: John Doe. Plan: continue beta-blocker.",
    policy={"role": "doctor", "department": "cardiology", "purpose": "treatment", "expiry": "24h"},
    actor={"user_id": "dr_smith", "role": "doctor", "department": "cardiology"},
)

# Open it, only if the policy is satisfied.
result = privyq.access(protected, identity={"role": "doctor", "department": "cardiology", "purpose": "treatment"})
print(result.text)          # -> "Patient: John Doe. ..."
print(result.receipt.id)    # a signed, verifiable access receipt

# Verify the receipt cryptographically.
check = privyq.verify(result.receipt)
assert check.ok and check.signature_valid and check.chain_valid

Denied access raises PolicyViolationError, and the attempt is still recorded as tamper-evident evidence:

try:
    privyq.access(protected, identity={"role": "nurse"})
except privyq.PolicyViolationError as why:
    print(why)   # -> "policy violation: role condition failed ..."

Installation

pip install privyq            # from PyPI (once published)
pip install -e ".[dev]"       # from this repo, with test/lint extras

The SDK talks to a running PrivyQ core (privyqd). Point it at the core with configure(core_address=...) or the PRIVYQ_CORE_ADDRESS env var.

Policy shorthand

Policies accept two forms. The shorthand maps each key to a condition, lists become in, expiry becomes a before with duration expansion ("24h" → an absolute timestamp):

{"role": "doctor", "department": ["cardiology", "oncology"], "expiry": "24h"}

The structured form is explicit and supports every operator (BP App D):

{"conditions": [{"type": "role", "operator": "in", "value": ["doctor", "specialist"]}],
 "combination": "all"}

API surface

Exceptions follow a hierarchy rooted at PrivyQError (PolicyViolationError, KeyNotFoundError, CryptoError, CoreUnreachableError, …).

Configuration (ARCH §20.3)

Development

pip install -e ".[dev]"
pytest -q          # unit tests + integration (builds & launches the real core)
black privyq

The gRPC stubs under privyq/_proto/ are generated from core-go/pkg/proto/privyq.proto. Regenerate with ../scripts/gen-python-proto.sh (or make proto at the repo root).