Metadata-Version: 2.4
Name: agentguard-spend
Version: 0.1.9
Summary: Local-runtime spend caps and capability-gated model routing for AI agents. Prompts, API keys, and signing keys stay inside the customer runtime. Zero data plane involvement.
Project-URL: Homepage, https://agentguard.run
Project-URL: Contact, https://agentguard.run/contact
Project-URL: Repository, https://github.com/MerchantGuardOps/agentguard-site
Author-email: "Dunecrest Ventures Inc." <hello@agentguard.run>
License: AgentGuard(TM) Spend SDK — Alpha License
        Copyright (c) 2026 Dunecrest Ventures Inc.
        
        1. SCOPE.
        This software, including all files under packages/agentguard-spend-python/agentguard_spend/, is
        licensed by Dunecrest Ventures Inc. ("Licensor") subject to the following
        thresholds:
        
          (a) Evaluation Use. Internal evaluation, prototyping, and non-commercial
              development at any call volume.
        
          (b) Free Production Threshold. Production deployments processing 10,000
              or fewer enforcement calls per calendar month, in aggregate across
              all instances operated by the licensee, are permitted under this
              License without additional fee.
        
          (c) Commercial License Required. Production deployments processing more
              than 10,000 enforcement calls per calendar month, deployments
              operated for the benefit of third parties as a service, redistribution,
              sublicensing, public hosting, and republication each require a
              separate commercial license agreement with Licensor.
        
        Commercial-license inquiries: invest@agentguard.run
        
        2. NO PATENT LICENSE GRANTED.
        Nothing in this License grants, expressly or by implication, any patent license
        to any patent, patent application, or other intellectual property right of
        Licensor. All patent rights are expressly reserved. The patent applications
        identified in Section 7 are not licensed by this License.
        
        3. SEPARATE GRANT FOR DEMONSTRATION ASSETS.
        The following assets, and ONLY these assets, are released under the Apache
        License, Version 2.0, the text of which is reproduced or available at
        https://www.apache.org/licenses/LICENSE-2.0:
        
          - The test vectors under packages/agentguard-spend-python/test_vectors/
          - The documentation examples under packages/agentguard-spend-python/examples/
          - The contents of packages/agentguard-spend-python/README.md
        
        The source code under packages/agentguard-spend-python/agentguard_spend/ is NOT included in this
        Apache License 2.0 grant. The Python type definitions, policy engine,
        decision log, store implementation, cost table, and wrapper code under
        agentguard_spend/ are licensed only under the alpha evaluation terms of
        Section 1 above.
        
        4. WARRANTY DISCLAIMER.
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
        DUNECREST VENTURES INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY
        ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
        5. SUCCESSORS AND ASSIGNS.
        This License binds and benefits the parties' respective successors and assigns.
        In the event of an asset sale, merger, change of control, or other transfer of
        the Licensor's rights in this software, all rights and obligations under this
        License inure to the benefit of and are binding upon Licensor's successor or
        assignee. Outstanding evaluation grants survive change-of-control, but the
        successor or assignee may, upon thirty (30) days' written notice, terminate
        ongoing evaluation grants in favor of a commercial-license requirement.
        
        6. TERMINATION.
        Licensor may terminate this License with thirty (30) days' written notice for
        any reason or no reason. Upon termination, Licensee shall cease all use of the
        software under agentguard_spend/ and shall destroy all copies in Licensee's possession.
        
        7. PATENT NOTICE (35 U.S.C. § 287).
        Protected by U.S. patent-pending technology, including the following
        provisional patent applications filed with the United States Patent and
        Trademark Office:
        
          - Application No. 63/983,615 (filed February 15, 2026)
          - Application No. 63/983,621 (filed February 15, 2026)
          - Application No. 63/983,843 (filed February 16, 2026)
          - Application No. 63/984,626 (filed February 17, 2026)
          - Application No. 64/071,781 (filed May 21, 2026)
          - Application No. 64/071,789 (filed May 21, 2026)
        
        Additional patents pending. All patent rights expressly reserved per
        Section 2 above.
        
        AgentGuard(TM) is a trademark of Dunecrest Ventures Inc. (USPTO Serial
        No. 99462472, pending). MerchantGuard(TM) is a trademark of Dunecrest
        Ventures Inc. (USPTO Serial No. 99051215, pending).
        
        For commercial licensing: invest@agentguard.run
License-File: LICENSE
Keywords: agent-governance,ai-agent-security,ai-agents,anthropic,audit-log,bedrock,cryptographic-attestation,ed25519,llm,local-first,model-routing,no-proxy,openai,policy-enforcement,spend-control,tamper-evident
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: crewai>=0.30; extra == 'all'
Requires-Dist: hvac>=2; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: llama-index>=0.10; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
Requires-Dist: redis>=5; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == 'bedrock'
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: kms
Requires-Dist: boto3>=1.34; extra == 'kms'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index>=0.10; extra == 'llamaindex'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5; extra == 'redis'
Provides-Extra: vault
Requires-Dist: hvac>=2; extra == 'vault'
Description-Content-Type: text/markdown

# agentguard-spend (Python)

> Local-runtime spend caps and capability-gated model routing for AI agents.

> Also available in: [Español (LATAM)](README.es-419.md) · [Português (BR)](README.pt-BR.md)

Python 3.10+ port of [`@agentguard-run/spend`](https://www.npmjs.com/package/@agentguard-run/spend).
Byte-identical decision-log format and Ed25519 signing — verifiable across both
runtimes with the same public key.

Every policy decision runs inside your process. Prompts, provider API keys, and
signing keys never leave your runtime. Each enforcement decision produces an
Ed25519-signed, hash-chained receipt suitable for audit and compliance review.

## Why no proxy

Every funded competitor in AI spend governance (Portkey, Helicone, LiteLLM,
Cloudflare AI Gateway, Vercel AI Gateway) proxies your traffic. That means your
prompts and provider keys flow through their infrastructure. `agentguard-spend`
never sees any of that. The policy runs in your process. The signed log lives
in your storage.

The procurement consequence: your security review covers this SDK like any
other library, not like a vendor that handles your data.

## Status

Private preview. Designed for enterprise, OEM, and platform integration.

For evaluation access, OEM licensing, or strategic partnership inquiries:
`invest@agentguard.run`

## Install

```bash
pip install agentguard-spend
# Optional provider extras:
pip install "agentguard-spend[openai]"
pip install "agentguard-spend[anthropic]"
pip install "agentguard-spend[bedrock]"
# Or all of them:
pip install "agentguard-spend[all]"
```

Production dependency: `cryptography>=42` (for Ed25519). The provider SDKs
(openai, anthropic, boto3) are **peer/optional**; install only what you use.

## Quickstart

```python
import asyncio
from openai import OpenAI

from agentguard_spend import (
    SpendPolicy,
    SpendScope,
    SpendCap,
    SigningKeys,
    SpendGuardConfig,
    InMemorySpendStore,
    InMemoryDecisionLogStore,
    generate_keypair,
    with_spend_guard,
)

# Generate or load signing keys. They never leave your runtime.
# In production these come from your HSM / KMS / Vault.
private_key, public_key = generate_keypair()  # 32-byte seed + 32-byte pubkey

policy = SpendPolicy(
    id="finance-ops-v1",
    name="Finance ops daily caps",
    scope=SpendScope(tenantId="acme-corp"),
    caps=[
        SpendCap(
            amountCents=500,
            window="per_day",
            action="downgrade",
            downgradeTo="claude-sonnet-4-6",
            reason="Opus daily soft cap reached, route to Sonnet",
        ),
        SpendCap(
            amountCents=1000,
            window="per_day",
            action="block",
            reason="Hard daily ceiling",
        ),
    ],
    mode="enforce",
    version=1,
    effectiveFrom="2026-05-23T00:00:00.000Z",
)

openai_client = OpenAI()
guarded = with_spend_guard(
    openai_client,
    policy=policy,
    scope=SpendScope(tenantId="acme-corp", userId="alice", agentId="finance-bot"),
    config=SpendGuardConfig(
        policy=policy,
        spendStore=InMemorySpendStore(),
        logStore=InMemoryDecisionLogStore(),
        signingKeys=SigningKeys(privateKey=private_key, publicKey=public_key),
    ),
)

# Drop-in: same API as openai.chat.completions.create
completion = guarded.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

When the policy fires:

| Action      | Result                                                                  |
|-------------|-------------------------------------------------------------------------|
| `allow`     | Call passes through unchanged                                           |
| `downgrade` | The `model` parameter is rewritten to `downgradeTo`, then the call proceeds |
| `block`     | An `AgentGuardBlockedError` is raised before the provider is contacted  |
| `shadow`    | Call passes through; the decision is logged for analysis only           |

## Anthropic and Bedrock bindings

```python
from anthropic import Anthropic
from agentguard_spend.bindings import with_anthropic_spend_guard

raw = Anthropic()
guarded = with_anthropic_spend_guard(
    raw,
    policy=policy,
    scope=SpendScope(tenantId="acme-corp"),
)
guarded.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

```python
import boto3
from agentguard_spend.bindings import with_bedrock_spend_guard

raw = boto3.client("bedrock-runtime")
guarded = with_bedrock_spend_guard(
    raw,
    policy=policy,
    scope=SpendScope(tenantId="acme-corp"),
)
guarded.invoke_model(
    modelId="anthropic.claude-sonnet-4-v1:0",
    body=b'{"messages":[{"role":"user","content":"hi"}],"max_tokens":256}',
)
```

## Capability-gated escalation

You can require a capability tier on a policy:

```python
policy = SpendPolicy(
    # ...
    requiredCapability="payment_initiate",
)
```

Calls that do not present a `capabilityClaim` at or above this tier are blocked
immediately. Tiers (ascending): `read_only` < `data_write` < `payment_initiate`
< `payment_execute`.

## Verifying a signed log

Anyone with the public key can verify the chain:

```python
from agentguard_spend import verify_chain

entries = await load_entries()  # from your storage
result = await verify_chain(entries, public_key)
if not result.ok:
    print(f"chain invalid at sequence {result.sequence}: {result.reason}")
```

Each entry binds the previous entry's hash via SHA-256 and is signed with
Ed25519. Tampering with any field of any entry invalidates the chain from that
point forward.

## Cross-language interoperability

`agentguard-spend` (Python) and `@agentguard-run/spend` (TypeScript) produce
**byte-identical canonical-JSON serialization** for the same `SpendDecision`.
That means an Ed25519 signature created in either runtime verifies in the
other. The repo includes a cross-language parity test:

- Fixture: `test_vectors/fixed_decision.json`
- TS reference generator: `test_vectors/compute_expected_ts.js`
- Python assertion: `tests/test_cross_language_parity.py`

## License and usage thresholds

The SDK is **free** for:

- Evaluation, prototyping, and non-commercial development at any volume
- Production deployments processing **up to 10,000 enforcement calls per
  calendar month**

A separate commercial license is required for:

- Production deployments processing **more than 10,000 enforcement calls per
  month**
- Deployments operated as a service to third parties
- Redistribution, sublicensing, public hosting, republication

Inbound commercial-license inquiries: `invest@agentguard.run`

Full terms in `LICENSE`. All patent rights expressly reserved (see Section 2 of
`LICENSE`).

## Patent notice

Protected by 6 U.S. patent-pending applications:

- 63/983,615 · 63/983,621 · 63/983,843 · 63/984,626 (filed February 2026)
- 64/071,781 · 64/071,789 (filed May 21, 2026)

See `LICENSE` Section 7 and `PATENTS.md`.

## Links

- agentguard.run
- Contact: `invest@agentguard.run`
- TypeScript SDK: [`@agentguard-run/spend`](https://www.npmjs.com/package/@agentguard-run/spend)
