Metadata-Version: 2.4
Name: climeter
Version: 0.1.0
Summary: Stripe for AI Tool Usage — CLI Billing & Metering SDK
Author-email: Auvhx <hello@climeter.ai>
License: MIT
Project-URL: Homepage, https://climeter.ai
Project-URL: Documentation, https://climeter.ai/docs
Project-URL: Repository, https://github.com/auvhx/climeter
Project-URL: Bug Tracker, https://github.com/auvhx/climeter/issues
Keywords: cli,billing,metering,ai,agents,usage
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.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
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"

# 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)
