spendguard-sdk
Python SDK for Agentic SpendGuard — the audit-chain spend control layer for LLM agents. Talks to the Agentic SpendGuard sidecar over Unix-domain-socket gRPC; gates each LLM / tool-call boundary through a Contract DSL evaluator and an atomic budget ledger with KMS-signed, immutable audit chain.
Install
# Core only (raw client, no framework integration)
pip install spendguard-sdk
# With the integration you need
# Pydantic-AI auto-install is temporarily fail-closed because
# CVE-2026-25580 affects pydantic-ai/pydantic-ai-slim before 1.56.0,
# and PyPI does not currently expose a fixed 1.56.0+ release.
# Install spendguard-sdk plus a vetted non-vulnerable pydantic-ai
# release when upstream publishes one.
pip install 'spendguard-sdk[langchain]'
pip install 'spendguard-sdk[langgraph]'
pip install 'spendguard-sdk[openai-agents]'
Quickstart (Pydantic-AI)
import asyncio
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from spendguard import SpendGuardClient, new_uuid7
from spendguard.integrations.pydantic_ai import (
RunContext,
SpendGuardModel,
run_context,
)
from spendguard._proto.spendguard.common.v1 import common_pb2
async def main():
client = SpendGuardClient(
socket_path="/var/run/spendguard/adapter.sock",
tenant_id="00000000-0000-4000-8000-000000000001",
)
await client.connect()
await client.handshake()
guarded = SpendGuardModel(
inner=OpenAIModel("gpt-4o-mini"),
client=client,
budget_id="44444444-4444-4444-8444-444444444444",
window_instance_id="55555555-5555-4555-8555-555555555555",
unit=common_pb2.UnitRef(
unit_id="66666666-6666-4666-8666-666666666666",
token_kind="output_token",
model_family="gpt-4",
),
pricing=common_pb2.PricingFreeze(
pricing_version="demo-pricing-v1",
price_snapshot_hash=b"<32 bytes>",
fx_rate_version="demo-fx-v1",
unit_conversion_version="demo-units-v1",
),
claim_estimator=lambda messages, settings: [
common_pb2.BudgetClaim(
budget_id="44444444-4444-4444-8444-444444444444",
unit=common_pb2.UnitRef(
unit_id="66666666-6666-4666-8666-666666666666",
token_kind="output_token",
model_family="gpt-4",
),
amount_atomic="500",
direction=common_pb2.BudgetClaim.DEBIT,
window_instance_id="55555555-5555-4555-8555-555555555555",
)
],
)
agent = Agent(model=guarded)
async with run_context(RunContext(run_id=str(new_uuid7()))):
result = await agent.run("Say hello in three words.")
print(result.output)
asyncio.run(main())
If a contract rule denies the call, agent.run(...) raises
spendguard.DecisionStopped carrying reason_codes and
matched_rule_ids.
API surface (core)
| Symbol | Purpose |
|---|---|
SpendGuardClient |
UDS gRPC client to the sidecar |
DecisionStopped, DecisionSkipped, ApprovalRequired |
per-decision exceptions |
derive_idempotency_key(...) |
deterministic key from (tenant, run, step, llm_call, trigger) |
new_uuid7() |
UUID v7 helper |
Wire-protocol compatibility
This SDK pins to a specific protobuf wire version. Check the
sidecar's published version against spendguard.__version__; minor
versions are wire-compatible, major bumps are breaking. (Not yet
enforced at handshake; planned for v0.2.)
License
Apache-2.0.
Metadata
Release files for spendguard-sdk 0.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spendguard_sdk-0.6.1.tar.gz | 5.9 MB | With provenance | Details for spendguard_sdk-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spendguard_sdk-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for spendguard_sdk-0.6.1-py3-none-any.whl |
Total release size: 11.9 MB
Release files / spendguard_sdk-0.6.1.tar.gz
| Download URL | spendguard_sdk-0.6.1.tar.gz |
|---|---|
| Size | 5.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6bccd0c15626f7f1f275e6ca0c36c1d4c97a8f70be965c58e5d8c3c78c0fda7
|
|
BLAKE2b-256 checksum How to use checksums |
4636cf352afb6752e15ccdfcd646479a3b236e63eeb73b84fd7202d0b0769a2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logRelease files / spendguard_sdk-0.6.1-py3-none-any.whl
| Download URL | spendguard_sdk-0.6.1-py3-none-any.whl |
|---|---|
| Size | 6.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c929421fbe78a7e45643de761902c61911181415fd8ff9a5b365a400748a35b
|
|
BLAKE2b-256 checksum How to use checksums |
70e8a6fe4dcdf8a2520c67d1954d8d88631af6689fbe12ddd4f7930d08a777cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logSecurity for spendguard-sdk 0.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for spendguard_sdk-0.6.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.