VeriSwarm Python SDK

Lightweight Python client for the VeriSwarm trust scoring API. Zero external dependencies -- uses only Python stdlib.

Install

pip install veriswarm

Quick Start

from veriswarm import VeriSwarmClient

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

# Check a trust decision before a sensitive action
decision = client.check_decision(
    agent_id="agt_123",
    action_type="post_public_message",
    resource_type="feed",
)
print(decision["decision"])  # "allow", "review", or "deny"

Event Ingestion

# 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-20T12:00:00Z",
    payload={"content_length": 140, "channel": "general"},
)

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

Agent Management

# Register a new agent
agent = client.register_agent({
    "tenant_id": "ten_your_workspace",
    "slug": "my-assistant",
    "display_name": "My Assistant",
    "description": "A helpful coding assistant",
})

# Get agent profile
profile = client.get_agent("agt_123")

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

# Get score history, breakdown, flags, timeline, manifests
history = client.get_agent_score_history("agt_123", limit=10)
breakdown = client.get_agent_score_breakdown("agt_123")
flags = client.get_agent_flags("agt_123")
timeline = client.get_agent_timeline("agt_123", limit=20)
manifests = client.get_agent_manifests("agt_123")

# Appeal a flag
client.appeal_flag("agt_123", flag_id=42)

# Agent API key management
keys = client.get_agent_api_keys("agt_123")
client.rotate_agent_api_key("agt_123")
client.revoke_agent_api_key("agt_123", key_id="key_456")

Provider Reports

# Submit a trust signal from your platform
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",
})

Guard (Security)

# PII tokenization (before sending to LLM)
result = client.tokenize_pii(text="Contact john@acme.com for details")
print(result["tokenized_text"])  # "Contact [VS:EMAIL:a1b2c3] for details"

# Rehydrate PII (after LLM processing)
original = client.rehydrate_pii(text=result["tokenized_text"], session_id=result["session_id"])

# PII session management
session = client.get_pii_session(result["session_id"])
client.revoke_pii_session(result["session_id"])

# Prompt injection scanning
scan = client.scan_injection(text="Ignore previous instructions and...")
print(scan["is_injection"])  # True

# Kill switch
client.kill_agent("agt_123", reason="Suspicious behavior detected")
client.unkill_agent("agt_123")

# Guard findings
findings = client.list_guard_findings(agent_id="agt_123")
client.update_guard_finding(finding_id=1, updates={"status": "resolved"})

# Guard policies
policies = client.list_guard_policies()
client.create_guard_policy({"name": "block-sql", "pattern": "DROP TABLE", "action": "block"})
client.update_guard_policy(policy_id=1, updates={"enabled": False})
client.delete_guard_policy(policy_id=1)

Passport (Identity)

# Verify agent identity
client.verify_agent_identity("agt_123")

# Delegations
client.create_delegation({"from_agent": "agt_123", "to_agent": "agt_456", "scope": "read"})
delegations = client.list_delegations()
client.revoke_delegation(delegation_id=1)

# Manifests
client.create_manifest("agt_123", {"capabilities": ["search", "summarize"]})
manifests = client.get_manifests("agt_123")

Vault (Audit Ledger)

# Query the immutable audit ledger
entries = client.query_vault_ledger(agent_id="agt_123", limit=20)

# Verify hash-chain integrity
verification = client.verify_vault_chain(limit=100)

# Export
job = client.export_vault(export_type="csv")
status = client.get_vault_export_status(job["job_id"])

Credentials (Portable JWT)

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

# Verify a credential from another agent
verified = client.verify_credential("eyJhbGciOiJFUzI1NiI...")
print(verified["veriswarm"]["policy_tier"])  # "tier_2"

Agent Self-Service

# Get own scores with improvement guidance
scores = client.get_my_scores()
print(scores["guidance"]["actions"])  # actionable improvement steps

Scoring Profiles

# Get current tenant profile
profile = client.get_scoring_profile()
print(profile["profile_code"])  # "general"

# Set tenant profile
client.set_scoring_profile("high_security")

Notifications

notifications = client.list_notifications()
client.mark_notification_read(notification_id=1)
client.mark_all_notifications_read()

IP Allowlist

# Get current allowlist
allowlist = client.get_ip_allowlist()

# Set allowlist
client.set_ip_allowlist(cidrs=["10.0.0.0/8", "192.168.1.0/24"], enabled=True)

Custom Domains

client.set_custom_domain(domain="trust.mycompany.com")
client.verify_custom_domain()
domain = client.get_custom_domain()
client.delete_custom_domain()

Team Management

members = client.list_team_members()
client.invite_team_member(email="alice@acme.com", role="admin")
client.remove_team_member(user_id="usr_789")

Workspaces

workspaces = client.list_workspaces()
client.switch_workspace(tenant_id="ten_456")

Trust Badges

url = client.get_badge_url("my-agent", style="compact", theme="dark")
# "https://api.veriswarm.ai/v1/badge/my-agent.svg?style=compact&theme=dark"

Reputation Lookup

rep = client.reputation_lookup(slug="my-agent")

Platform Status

status = client.get_platform_status()
print(status["status"])  # "operational" or "degraded"

OpenAI-Compatible LLM Proxy

VeriSwarm exposes an OpenAI-wire-compatible proxy at /v1/proxy/chat/completions and /v1/proxy/models. Every request flows through Guard scanning, the LLM router (cost / complexity / fallback), and a Vault audit entry — and the response shape matches openai.chat.completions.create(...) byte-for-byte.

The recommended integration is to use the OpenAI SDK directly and just override its base_url:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veriswarm.ai/v1/proxy",
    api_key=os.environ["VERISWARM_API_KEY"],
)

completion = client.chat.completions.create(
    model="claude-sonnet-4-6",  # or any model your tenant's router allows
    messages=[{"role": "user", "content": "What's the trust score for agt_42?"}],
)

Use the veriswarm package for trust, Guard, Passport, Vault, A2A, approvals, and compliance — the surfaces the OpenAI SDK doesn't cover.

All Methods