Metadata-Version: 2.4
Name: climeter
Version: 0.1.2
Summary: The billing layer for AI tools — 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

Usage-based metering and billing for CLI tools and AI agents — Python SDK.

[![PyPI](https://img.shields.io/pypi/v/climeter)](https://pypi.org/project/climeter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🌐 [climeter.ai](https://climeter.ai) · 📖 [Docs](https://climeter.ai/docs/sdks/python)

---

## Install

```bash
pip install climeter
```

Python 3.8+. Zero runtime dependencies (stdlib only).

---

## Quick Start

```python
from climeter import meter

meter.configure(api_key="clmtr_...", tool_slug="my-tool")

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

Or set environment variables and skip `configure()`:

```bash
export CLIMETER_API_KEY=clmtr_...
export CLIMETER_TOOL_SLUG=my-tool
```

---

## Usage

### Decorator

```python
from climeter import meter

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

# Async — same decorator
@meter.track(price=0.01)
async def search_async(query: str):
    return await do_search_async(query)
```

### Context manager

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

# Async
async with meter.track_usage_async("search", price=0.01):
    result = await do_search_async(query)
```

### Manual

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

---

## API

| Method | Description |
|---|---|
| `meter.configure(api_key, tool_slug, api_url)` | Configure the global meter |
| `@meter.track(price, name, metadata)` | Decorator — records event after each call |
| `meter.track_usage(name, price, metadata)` | Sync context manager |
| `meter.track_usage_async(name, price, metadata)` | Async context manager |
| `meter.record(name, price, metadata)` | Manual event recording |
| `meter.flush()` | Force-flush pending events |
| `meter.shutdown()` | Flush and stop background thread |
| `meter.status()` | Returns `{configured, tool_slug, queue_size}` |

---

## CLI

```bash
climeter init      # set up API key
climeter status    # show current config
climeter diagnose  # test connection
```

---

## License

MIT © [CLIMeter](https://climeter.ai)
