Python SDK

Lightweight client for the VeriSwarm trust scoring API. Zero dependencies, standard library only.

GitHub: github.com/veriswarm/veriswarm-sdk/tree/main/packages/sdk-python

Installation

pip install veriswarm

Requires Python 3.8+. For LangChain integration: pip install veriswarm[langchain]

Authentication

from veriswarm_client import VeriSwarmClient

client = VeriSwarmClient(
    base_url="https://api.veriswarm.ai",
    api_key="vsk_your_workspace_key",
)

Find your API key in the dashboard under Settings > API Keys.

Parameter	Type	Default	Description
base_url	str	Required	API base URL
api_key	str	Required	Workspace API key (vsk_...)
timeout_seconds	int	15	Request timeout

Core Operations

Check a Trust Decision

decision = client.check_decision(
    agent_id="agt_123",
    action_type="post_public_message",
    resource_type="feed",
)

if decision["decision"] == "allow":
    pass  # Proceed
elif decision["decision"] == "review":
    pass  # Queue for human review
else:
    pass  # Deny

Returns decision ("allow", "review", or "deny"), reason_code, and policy_tier.

Register an Agent

agent = client.register_agent({
    "tenant_id": "ten_your_workspace",
    "slug": "my-assistant",
    "display_name": "My Assistant",
})

Report Events

# Single event
client.ingest_event(
    event_id="evt_unique_123",
    agent_id="agt_123",
    source_type="platform",
    event_type="message.sent",
    occurred_at="2026-03-24T12:00:00Z",
    payload={"content_length": 140, "channel": "general"},
)

# Batch (up to 50 per request)
client.ingest_events_batch([
    {"event_id": "evt_1", "agent_id": "agt_123", "source_type": "platform",
     "event_type": "message.sent", "occurred_at": "2026-03-24T12:00:00Z", "payload": {}},
    {"event_id": "evt_2", "agent_id": "agt_123", "source_type": "platform",
     "event_type": "tool.invoked", "occurred_at": "2026-03-24T12:01:00Z", "payload": {}},
])

Get Trust Scores

scores = client.get_agent_scores("agt_123")
print(f"Risk: {scores['risk']['score']}, Tier: {scores['policy_tier']}")

Also available: get_agent_score_history(agent_id, limit=10) and get_agent_score_breakdown(agent_id).

Moderation Flags

flags = client.get_agent_flags("agt_123")
client.appeal_flag("agt_123", flag_id=42)

Provider Reports

client.ingest_provider_report({
    "agent_id": "agt_123",
    "provider_event_id": "provider-evt-456",
    "report_type": "spam",
    "severity": "high",
    "confidence": 0.91,
    "summary": "Burst spam detected in #general",
})

Portable Credentials

# Issue (requires agent key auth)
result = client.issue_credential()
jwt_token = result["credential"]

# Verify
verified = client.verify_credential(jwt_token)
print(verified["payload"]["veriswarm"]["policy_tier"])

Agent Self-Service

my_scores = client.get_my_scores()
print(my_scores["guidance"]["actions"])  # Improvement steps

Scoring Profiles

profile = client.get_scoring_profile()
client.set_scoring_profile("high_security")

Trust Badges

url = client.get_badge_url("my-agent", style="compact", theme="dark")

Guard PII Tokenization

Detect and replace PII with reversible [VS:TYPE:ID] tokens before sending data to external tools or models. Rehydrate on demand when the original values are needed.

Methods

Method	Description
tokenize_pii(text, agent_id=None)	Detect PII and return tokenized text with a session ID
rehydrate_pii(text, session_id)	Replace [VS:TYPE:ID] tokens with original values
get_pii_session(session_id)	Retrieve metadata for a tokenization session
revoke_pii_session(session_id)	Permanently delete stored PII mappings for a session
VeriSwarmClient.guard_proxy_config(proxy_url)	Static method -- returns MCP client config dict pointing at a Guard Proxy URL

Example: Tokenize, Process, Rehydrate

# Tokenize before sending to an external tool
result = client.tokenize_pii(
    "Contact Jane Doe at jane@example.com or 555-0123",
    agent_id="agt_123",
)
safe_text = result["text"]        # "Contact [VS:PERSON:a1] at [VS:EMAIL:a2] or [VS:PHONE:a3]"
session_id = result["session_id"]

# ... pass safe_text to external tool / model ...

# Rehydrate when you need the original values back
original = client.rehydrate_pii(safe_text, session_id)
print(original["text"])  # "Contact Jane Doe at jane@example.com or 555-0123"

# Clean up when done
client.revoke_pii_session(session_id)

Guard Proxy Config

Generate an MCP client configuration block pointing at a Guard Proxy instance:

config = VeriSwarmClient.guard_proxy_config("https://guard-proxy.veriswarm.ai")

LangChain Integration

The SDK includes a callback handler that automatically reports tool calls, completions, and failures to VeriSwarm.

from veriswarm.adapters.langchain import VeriSwarmCallbackHandler

handler = VeriSwarmCallbackHandler(
    api_key="vsk_your_key",
    agent_id="agt_your_agent",
    enforce=True,       # Optional: enable enforcement
    on_deny="raise",    # "raise", "skip", or "log"
)

agent = initialize_agent(tools, llm, callbacks=[handler])

on_deny	Behavior
"raise"	Raises PermissionError when a tool call is denied
"skip"	Raises PermissionError (caller should catch and skip)
"log"	Logs a warning and allows the call to proceed

Error Handling

from veriswarm_client import VeriSwarmClient, VeriSwarmClientError

try:
    decision = client.check_decision(agent_id="agt_123", action_type="post_message")
except VeriSwarmClientError as e:
    print(f"API error: {e}")

For the full method reference, see the API documentation.