SDK
Send governed-agent runtime decisions from application code.
Role
The SDK is the fastest path from an agent workflow to a live Clearance decision. Use it in the application or gateway code that already knows the actor, resource, operation, data class, policy reference, trace id, and decision outcome.
Install
During local development, install the Python SDK from this repo:
pip install -e sdk/pythonConfigure the project and token:
export CLEARANCE_API_URL="https://app.policystrata.com"
export CLEARANCE_INGEST_TOKEN="runner_token_..."
export CLEARANCE_PROJECT="support-bi-copilot"
export CLEARANCE_RELEASE="release_2026_07_06"For TypeScript and Node runtimes, install the TypeScript SDK:
npm install @policystrata/clearanceSend One Decision In Python
import clearance
clearance.init()
clearance.observe(
"warehouse.safe_query",
layer="sql",
summary="Tenant-scoped SQL query approved.",
action="allow",
data_classes=["customer_record"],
trace_id="trace_redacted_018",
span_id="span_sql_01",
)Send One Decision In TypeScript
import { init, observe } from "@policystrata/clearance";
init();
await observe("warehouse.safeQuery", {
layer: "sql",
summary: "Tenant-scoped SQL query approved.",
action: "allow",
dataClasses: ["customer_record"],
traceId: "trace_redacted_018",
spanId: "span_sql_01",
});Guard A Runtime Operation
Use the context manager when the application should emit a decision around a governed operation.
import clearance
clearance.configure(agent_key="support-bi-copilot")
with clearance.decision(
"retrieval.search_accounts",
layer="retrieval",
summary="Retrieval checked tenant and entitlement scope.",
action="allow",
data_classes=["account_record"],
):
search_accounts()If the guarded block raises, the SDK emits a deny decision before re-raising
the original exception.
Inspect Blockers
Agents and reviewer tools can ask Clearance for release blockers without raw SQL or trace payloads.
import clearance
clearance.init()
blockers = clearance.explain_blockers(limit=50)
held_actions = clearance.query(
dataset="runtime_events",
decision="require_approval",
)import { explainBlockers, query } from "@policystrata/clearance";
const blockers = await explainBlockers({ limit: 50 });
const heldActions = await query({
dataset: "runtime_events",
decision: "require_approval",
});Create A Review Decision
Human approval is a primitive in Clearance. Use review decisions for explicit approval, block, or scoped waiver state.
import clearance
clearance.create_review_decision(
packId="pack_support_bi_20260706",
decision="waived",
reason="Accepted for this release candidate only.",
waiverScope={
"releaseCandidate": "release_2026_07_06",
"environment": "production",
"findingIds": ["pol_sql_001"],
"expiresAt": "2026-08-06T00:00:00.000Z",
},
)import { createReviewDecision } from "@policystrata/clearance";
await createReviewDecision({
packId: "pack_support_bi_20260706",
decision: "blocked",
reason: "Tenant scope evidence is missing.",
});CLI
Store local credentials:
clearance auth \
--api-url https://app.policystrata.com \
--token "$CLEARANCE_INGEST_TOKEN" \
--project support-bi-copilotSend a single smoke-test decision:
clearance decision warehouse.safe_query \
--layer sql \
--action log_only \
--summary "SDK smoke decision from local development"The TypeScript SDK ships the same clearance decision command when installed
from the package build.
How It Maps To The Platform
| SDK field | Platform surface |
|---|---|
project | Project and release history |
agent_key | Agent inventory |
operation, layer | Live decisions table and filters |
action | Allow, deny, redact, approval-required, quarantine, or log-only decision |
trace_id, span_id | Link to external observability traces |
policy_refs, control | Decision inspector and evidence exports |
Contract Source
The SDK contract types are generated from schemas/*.schema.json:
bun run contracts:generateGenerated SDK files:
sdk/typescript/src/contracts.generated.tssdk/python/clearance/contracts.py