Metadata-Version: 2.4
Name: nano-empire-tollbooth
Version: 0.3.0
Summary: Monetize any Python function with one decorator. Unlimited paper-mode metering, a one-time upgrade prompt around call 100, local ledger, signed receipts; Pro adds CSV/JSON export, higher caps, and CLI tools.
Author-email: Nano Empire <ops@nano-empire.dev>
License: MIT
Project-URL: Homepage, https://neuralempireai.com
Project-URL: Documentation, https://neuralempireai.com/docs/quickstart.html
Project-URL: Repository, https://github.com/roblambert9/nano-empire-tollbooth
Project-URL: Issue Tracker, https://github.com/roblambert9/nano-empire-tollbooth/issues
Project-URL: Live Demo, https://neuralempireai.com/simulator/
Keywords: monetize,python,decorator,billing,micropayment,agent,x402,api,pay-per-call,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=41.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# nano-empire-tollbooth

Monetize and meter any Python function with one decorator.

```python
from nano_empire_tollbooth import monetize

@monetize(price_usd=0.01)
def summarize(text: str) -> str:
    return my_llm(text)
```

Every call is metered and logged to a local JSONL ledger. Paper-mode metering is
unlimited and free — a one-time upgrade prompt prints around call 100, and the
function keeps working (it nags, it does not block).

## Install

```bash
pip install nano-empire-tollbooth
```

Python 3.9+, one dependency (pydantic).

## Command line

The package ships a `tollbooth` command that works over your local ledger:

```bash
tollbooth status                 # show tier (free/pro) and a ledger summary
tollbooth report                 # aggregate: calls, spend, by status
tollbooth report --json          # same, machine readable
tollbooth verify                 # integrity check of the ledger file
tollbooth export --format csv    # export the ledger (Pro)
tollbooth settle                 # batch-net released tolls into one charge-sized settlement (paper mode; --live fails closed until you wire your own rail)
```

## Free vs Pro

What Pro actually unlocks today. No overstated claims.

| | Free | Pro ($19/mo) |
|---|---|---|
| Metered calls | Unlimited (paper mode) | Unlimited (paper mode) |
| Local JSONL ledger | Yes | Yes |
| `report` and `verify` | Yes | Yes |
| Upgrade prompt | Shown after 100 calls | Suppressed |
| `tollbooth export` (CSV/JSON) | No | Yes |
| Default daily cap | $10 / agent | $1000 / agent |

**Pro is in private setup and not yet purchasable.** The licensing pipeline
(Ed25519-signed keys + checkout issuance) is built and tested but not wired live
yet — so there's no buy link here on purpose. Watch the
[repo](https://github.com/roblambert9/nano-empire-tollbooth) for availability.

When you have a key, activate it with:

```bash
export TOLLBOOTH_LICENSE_KEY=your-key
```

> License validation is a real offline check: each key carries an Ed25519
> signature from the issuer plus an expiry, verified locally with the published
> public key — no secret, no phone-home. A random, tampered, or expired key does
> not unlock Pro. Online revocation before expiry is on the roadmap.

## Live settlement (experimental)

The tollbooth includes an x402 hook so you can wire your own live settlement
verifier:

```python
from nano_empire_tollbooth import Tollbooth, TollboothConfig

booth = Tollbooth(TollboothConfig(paper_mode=False))

async def my_verifier(wallet, tx_signature, amount_usd):
    # verify a real on-chain or off-chain payment, return True/False
    return await check_payment(wallet, tx_signature, amount_usd)

booth.set_x402_verifier(my_verifier)
```

This ships the escrow lifecycle (lock, release, refund) and the verifier hook.
It does NOT include a hosted settlement backend. Connecting real funds is your
responsibility and is on the project roadmap. This is informational and not
financial advice.

## How metering works

1. Decorate any sync or async function with `@monetize(price_usd=...)`.
2. Each call writes a record to `logs/toll_ledger.jsonl` with a settlement hash.
3. In paper mode (default) nothing is charged. Set `paper_mode=False` plus your
   own verifier to move real funds.

## License

MIT
