tappass — Zero Trust Control Plane for Agentic AI (Python SDK)

Runtime governance for your LLM, agent, and tool calls. Embed in your code, get a typed audit trail, surface governance decisions as Python exceptions.

What this SDK is for:

• Governing LLM calls, agent runs, and tool executions at runtime.
• Emitting structured audit events with correlation IDs.
• Handling governance decisions (block, redact, approve, trust-tier, break-glass) as typed exceptions in your code.

What this SDK is NOT for:

• Policy CRUD, compliance report generation, Verified credential issuance, retention config, break-glass invocation, tool-integrity approval. Those live in the TapPass dashboard — not in your agent code.

Requirements

• Python ≥ 3.11.
• tappass server ≥ 0.6.0. (The SDK rejects older servers at construction time.)

Install

pip install tappass

Quickstart — a governed chat call

from tappass import Agent

agent = Agent("https://tappass.example.com", api_key="tp_...")
r = agent.chat("Summarize Q4 revenue")
print(r.content)
print(r.session_id, r.audit_url)   # correlation IDs, deep link to dashboard

Quickstart — govern a CrewAI run

from crewai import Agent, Task, Crew
from tappass.integrations.crewai import guard_crew

crew = Crew(agents=[...], tasks=[...])

with guard_crew(crew, tappass_url="https://tappass.example.com", api_key="tp_...") as session:
    result = session.kickoff()
    print(session.id, session.audit_url)

Telemetry kill-switch

The SDK delivers audit events to your TapPass server asynchronously via a background reporter. To disable that delivery entirely, set either of:

export TAPPASS_DISABLE_TELEMETRY=1
export DO_NOT_TRACK=1     # community convention — consoledonottrack.com

This only suppresses audit-event delivery. It does not disable governance — govern() calls still run, decisions are still enforced, blocks still raise GovernanceBlocked. The distinction is deliberate: governance is the product you're paying for; telemetry is observability of your own usage.

Decisions are typed exceptions

from tappass import GovernanceDecision, PolicyBlockError, ApprovalRequired

try:
    r = agent.chat("Show me all customer SSNs")
except PolicyBlockError as e:
    print(f"Blocked by {e.blocked_by}: {e.reason}. See {e.audit_url}")
except ApprovalRequired as e:
    print(f"Awaiting approval: {e.approval_url}")
except GovernanceDecision as e:
    print(f"Governance decision: {e}")

Plan limits: per-minute limit and quota

Your workspace's plan caps governed calls per minute, and may carry a rolling quota (calls per window of hours). See both with tappass settings billing (-o json for the raw per_minute_limit and quota fields).

• Per-minute limit (HTTP 429, plan_rate_limited): the SDK waits Retry-After (at most 10 s; 1 s when the header is missing) and retries once. If that is refused too it raises PerMinuteLimitError (retry_after, limit).
• Quota (SUBSCRIPTION_EXHAUSTED): never retried; raises QuotaExceededError (quota, window_hours when the server sends them; the message names the quota and window).

Both subclass PlanLimitError (a TapPassError, and a GovernanceCallError on the govern() path, so enforce mode still fails closed).

from tappass import PerMinuteLimitError, QuotaExceededError

try:
    r = agent.chat("Summarize Q4 revenue")
except PerMinuteLimitError as e:
    print(f"Slow down: try again in {e.retry_after} s")
except QuotaExceededError as e:
    print(e)  # e.g. "...quota of 5000 calls per 5 hours, agreed with TapPass..."

Turn the retry off with Agent(..., retry_per_minute=False) (same on AsyncAgent).

What's new in 0.6

See CHANGELOG.md. Breaking changes — no back-compat with 0.5.x. See the migration guide.

Publishing a release

Releases ship to PyPI via GitHub Actions using OIDC Trusted Publishing — no long-lived API token is stored anywhere. The workflow is .github/workflows/release.yml.

One-time PyPI configuration

Only needed once per project (or whenever the workflow name / environment changes):

1. Log in to https://pypi.org/manage/account/publishing/.
2. Under Add a new pending publisher (if the project isn't on PyPI yet) or the existing project's Publishing tab, add a GitHub publisher with:
   • PyPI Project Name: tappass
   • Owner: tappass
   • Repository name: tappass-sdk
   • Workflow name: release.yml
   • Environment name: pypi
3. In the GitHub repo, go to Settings → Environments and create an environment named pypi. Optionally add a required-reviewers protection rule so a human approves each release.

That's it — no secrets, no tokens.

Cutting a release

1. Bump version in pyproject.toml (and __version__ in tappass/__init__.py).
2. Update CHANGELOG.md: flip ## [X.Y.Z] — Unreleased to ## [X.Y.Z] — YYYY-MM-DD.
3. Commit: git commit -am "release: X.Y.Z".
4. Tag and push:

   git tag vX.Y.Z
   git push origin main --tags
   

The workflow then:

1. Verifies the tag matches pyproject.toml version (fails the release if not).
2. Builds wheel + sdist.
3. Runs twine check.
4. Publishes to PyPI via OIDC.
5. Creates a GitHub Release with the wheel + sdist attached and auto-generated notes.

Dry run

To build the artifacts without publishing, use Actions → Release to PyPI → Run workflow with dry_run checked. The publish and github_release jobs are skipped; the build job's artifacts are retained for inspection.

License

Apache-2.0. See LICENSE.