Metadata-Version: 2.5
Name: chitmark
Version: 0.9.0
Summary: Chitmark Python SDK for Trust Decisions, Agent Attribution, and Agent Paid Access
Project-URL: Homepage, https://chitmark.com
Project-URL: Documentation, https://chitmark.com/docs
Author-email: Chitmark <dev@chitmark.com>
License: Proprietary: no open-source grant. Copyright (c) 2026 Chitmark. All rights reserved.
License-File: LICENSE
Keywords: agent-actions,allow-challenge-deny,anti-abuse,chitmark,credit-abuse,free-tier-abuse,free-trial-abuse,signup-abuse,trial-farming,trust-decisions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: cryptography>=43.0.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pyjwt>=2.15.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Provides-Extra: verdict
Requires-Dist: cryptography>=43.0.0; extra == 'verdict'
Requires-Dist: pyjwt>=2.15.0; extra == 'verdict'
Description-Content-Type: text/markdown

# Chitmark SDK for Python

Use Chitmark from a Python backend to screen costly actions, recognize enrolled agents with signed proof, and manage paid API access.

[![PyPI version](https://img.shields.io/pypi/v/chitmark.svg)](https://pypi.org/project/chitmark/)

## Install

Requires Python 3.10 or later. The package provides a typed, synchronous client.

```bash
python -m pip install chitmark
```

Create a scoped API key in the [Chitmark dashboard](https://chitmark.com/dashboard) and set `CHITMARK_API_KEY` in your server environment.

## Resolve agent attribution

Use a key with `attribution:read`. Replace the sample request with the inbound request from your server.

```python
import os

import httpx

from chitmark import Chitmark

request = httpx.Request("GET", "https://app.example.com/agent-task")
with Chitmark(api_key=os.environ["CHITMARK_API_KEY"]) as client:
    result = client.attribution.resolve(request=request)

print(result["identity"]["recognized"], result["principal"]["email"])
```

The SDK reads fresh signed evidence from `Chitmark-Agent-Proof`. Without evidence, the sample returns an unknown identity and null email. An enrolled agent can sign for different recipients in a network-enabled deployment. Each site receives its own subject, and principal claims require a current grant for the recipient and purpose. Email also requires consent, `attribution:email`, and raw mode on an eligible plan.

For relative request URLs, pass your configured HTTPS origin as `site`. See the [Attribution quickstart](https://chitmark.com/docs/guides/agent-attribution/) and [network proof guide](https://chitmark.com/docs/guides/agent-attribution-network/).

## Screen a signup

Use a key with `verify:write`. Generate and retain a session ID on your server for the attempt.

```python
import os
from uuid import uuid4

from chitmark import Chitmark, is_eligible_allow

with Chitmark(api_key=os.environ["CHITMARK_API_KEY"]) as client:
    verdict = client.verify(
        action="signup",
        session=str(uuid4()),
        surface="app.example.com/signup",
        subject={"email": "buyer@example.com"},
    )

print(verdict["decision"], is_eligible_allow(verdict), verdict["eventId"])
```

Grant value only after an explicit, non-degraded allow. Timeouts and transport failures on `verify` produce a degraded challenge. The default data mode hashes email before sending it. Store the returned `eventId` for outcome reporting.

| Method                             | Use                                                                                                                    |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `verify`                           | Get an allow, challenge, or deny verdict.                                                                              |
| `challenge` / `complete_challenge` | Issue and complete an additional check. Reuse the attempt's session.                                                   |
| `feedback`                         | Report an outcome against the stored `eventId` with a `feedback:write` key.                                            |
| `verify_verdict_token`             | Verify a signed receipt against the expected session and tenant. Install `chitmark[verdict]` for receipt verification. |

See the [Trust Decisions quickstart](https://chitmark.com/docs/quickstart/trust-decisions/), [Python SDK reference](https://chitmark.com/docs/sdk/python/), and [verdict token guide](https://chitmark.com/docs/guides/verdict-tokens/).

## Agent Paid Access

Use `client.charge(request)` to request a quote, continue checkout, or read purchase status. Sellers use separate scopes to reserve execution and record delivery. See the [Agent Paid Access guide](https://chitmark.com/docs/guides/agent-paid-access/).

## License

Proprietary. The distribution includes the license terms in `LICENSE`.
