Metadata-Version: 2.4
Name: costillery
Version: 1.0.1
Summary: Receipt intelligence SDK for AI agents — auto-capture AI API payment receipts
Author-email: The Skramme Company <dev@costillery.com>
License: MIT
Project-URL: Homepage, https://costillery.com
Project-URL: Documentation, https://docs.costillery.com
Project-URL: Repository, https://github.com/wytcab/costillery
Keywords: receipts,mpp,x402,payments,agents,expenses,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: httpx
Requires-Dist: httpx>=0.24.0; extra == "httpx"
Dynamic: license-file

# Costillery Python SDK
`pip install costillery`

Auto-capture AI API payment receipts and submit them to Costillery for expense intelligence, audit trails, and cost analytics.

## Quick Start — API Key Mode

```python
import os
from costillery import Costillery
import requests

# Get your API key at costillery.com
ledger = Costillery(api_key=os.environ["COSTILLERY_API_KEY"])

# Wrap a requests session — receipts captured automatically in the background
session = ledger.wrap_session(requests.Session())

# Make API calls as normal — Costillery captures Payment-Receipt headers
response = session.post(
    "https://api.openai.com/v1/chat/completions",
    json={"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}
)

# Or submit receipts manually
import asyncio
asyncio.run(ledger.submit_receipt(
    receipt_raw="<base64-encoded receipt>",
    service_url="https://api.openai.com/v1/chat/completions",
    metadata={"model": "gpt-4o", "cost_usd": 0.015}
))
```

## How It Works

1. **Wrap your HTTP session** — `wrap_session()` intercepts responses and auto-captures `Payment-Receipt` and `X-Payment-Response` headers
2. **Background batching** — receipts are buffered and submitted every 5 seconds or every 10 receipts (non-blocking)
3. **Flush on shutdown** — call `ledger.shutdown()` to flush remaining receipts before exit

## API Reference

| Method | Description |
|--------|-------------|
| `Costillery(api_key=...)` | Initialize with your Costillery API key |
| `ledger.wrap_session(session)` | Wrap a `requests.Session` — receipts auto-captured |
| `await ledger.submit_receipt(...)` | Manually submit a single receipt |
| `await ledger.submit_batch(receipts)` | Submit multiple receipts at once |
| `await ledger.flush()` | Flush pending receipts (async) |
| `await ledger.flush_now()` | Flush pending receipts (sync) |
| `await ledger.shutdown()` | Flush remaining receipts and stop background thread |
| `ledger.get_pending_count()` | Number of receipts currently queued |

## Configuration

```python
from costillery import Costillery

ledger = Costillery(
    api_key="al_live_xxx",
    endpoint="https://api.costillery.com",  # optional
    batch_size=10,       # flush every N receipts (default: 10)
    batch_interval=5.0,  # flush every N seconds (default: 5.0)
    debug=True,          # log submission results (default: False)
)
```

## Get Your API Key

Sign up at [costillery.com](https://costillery.com) — free tier includes 10,000 receipts/month.

## License

MIT
