Metadata-Version: 2.5
Name: chitmark
Version: 0.4.0
Summary: Official Python SDK for Chitmark by Open Agent Ledger — trust decisions on agent-mediated actions (verify, feedback, challenge)
Project-URL: Homepage, https://chitmark.com
Project-URL: Documentation, https://chitmark.com/docs
Project-URL: Repository, https://github.com/nonameuserd/Chitmark
Project-URL: Issues, https://github.com/nonameuserd/Chitmark/issues
Author-email: Open Agent Ledger <dev@chitmark.com>
License: Proprietary — no open-source grant. Copyright (c) 2026 Open Agent Ledger. All rights reserved.
License-File: LICENSE
Keywords: agent-actions,anti-abuse,chitmark,open-agent-ledger,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.9.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.9.0; extra == 'verdict'
Description-Content-Type: text/markdown

# chitmark (Python)

Official Python SDK for Chitmark — trust decisions on agent-mediated actions, tuned by business outcomes (`verify` / `feedback` / `challenge`).

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

Requires Python ≥ 3.10.

## Install

```bash
pip install chitmark
# or
uv add chitmark
```

## Quick start

```python
from chitmark import Chitmark

client = Chitmark(api_key="ck_live_...")

verdict = client.verify(
    action="signup",
    session="sess_9f3a",
    surface="app.acme.com/signup",
    subject={
        "email": "buyer@acmecorp.com",
        "ip": "203.0.113.7",
        "userAgent": "...",
    },
)
# Persist verdict["eventId"] on the account row — feedback joins only on that id.
# Default pii_mode="hashed" minimizes email/IP before the wire.
```

## API

Three verbs:

| Method                  | Endpoint             | Purpose  |
| :---------------------- | :------------------- | :------- |
| `client.verify(...)`    | `POST /v1/verify`    | Decide   |
| `client.feedback(...)`  | `POST /v1/feedback`  | Learn    |
| `client.challenge(...)` | `POST /v1/challenge` | Escalate |

**Golden rule:** fail to `challenge`, never to `allow`. Timeouts return a degraded challenge verdict.

### Feedback

Attribution is a schema contract, not a lookup: store the `eventId` from
`verify` on the account row, then report outcomes against that same id — never
a derived or guessed id.

```python
# At signup: persist the join key
verdict = client.verify(action="signup", subject={"email": "a@b.com"})
db.accounts.update(user_id, chitmark_event_id=verdict["eventId"])

# Later, when a label matures (credit burn, chargeback, …):
client.feedback(
    event_id=account.chitmark_event_id,  # the stored join key — never guessed
    outcome="credit_burn",
    value=87.4,
    unit="usd",
    observed_at="2026-08-06T04:00:00Z",
)
```

### PII

| Mode               | Behavior                                                |
| :----------------- | :------------------------------------------------------ |
| `hashed` (default) | SHA-256 email, /24 IP truncation, minimized form fields |
| `none`             | Derived/header-shape signals only                       |
| `raw`              | Tenant opt-in only; higher compliance review            |

## Develop

```bash
cd packages/sdk-python
uv sync --extra dev   # or: pip install -e ".[dev]"
pytest
ruff check .
```

## Resources

- [API reference](https://chitmark.com/docs)
- [GitHub](https://github.com/nonameuserd/Chitmark)

## License

Proprietary — see [LICENSE](LICENSE).
