# climeter

**Stripe for AI Tool Usage** — zero-dependency Python SDK for CLI billing & metering.

→ [climeter.auvh.ai](https://climeter.auvh.ai)

---

## Install

```bash
pip install climeter
```

## Configure

```bash
export CLIMETER_API_KEY=clm_xxx
```

Or programmatically:

```python
import climeter
climeter.configure(api_key="clm_xxx", tool_slug="my-tool")
```

## Usage

### Decorator (2 lines)

```python
from climeter import meter

@meter.track(price=0.01)
def search(query: str):
    return do_search(query)
```

### Context manager

```python
from climeter import meter

with meter.track_usage("search", price=0.01):
    result = do_search(query)
```

### Manual

```python
meter.record("search", price=0.01, metadata={"query_len": len(query)})
```

### Async

```python
@meter.track(price=0.01)
async def search(query: str):
    return await do_search_async(query)
```

## Features

| Feature | Detail |
|---|---|
| **Zero deps** | stdlib only (`threading`, `urllib`, `json`, `os`) |
| **Fire-and-forget** | never blocks your CLI — background thread |
| **Offline resilience** | buffers up to 100 events in memory, retries automatically |
| **Batch submission** | events batched for efficiency |
| **Decorator + context manager + functional API** | your choice |
| **Async support** | works with `asyncio` |

## CLI

```bash
climeter init      # set up API key → writes to .env
climeter status    # show current config
climeter diagnose  # check config + test connection
```

## License

MIT — [climeter.auvh.ai](https://climeter.auvh.ai)
