Metadata-Version: 2.5
Name: token-usage-analytics
Version: 1.0.0
Summary: Lightweight SDK for tracking AI usage metrics across OpenAI, Anthropic, and Google AI providers
Project-URL: Homepage, https://tokenusage.transitiv-dev.com/dashboard
Project-URL: Documentation, https://tokenusage.transitiv-dev.com/dashboard
Project-URL: Repository, https://github.com/jinal09-codaemon/token-usage-sdk.git
Project-URL: Changelog, https://github.com/jinal09-codaemon/token-usage-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/jinal09-codaemon/token-usage-sdk/issues
Project-URL: Support, https://transitiv.ai
Author-email: Transitiv Technologies <jinal.r@transitiv.com>
Maintainer-email: Transitiv Engineering <jinal.r@transitiv.com>
License: Proprietary - Transitiv Technologies
License-File: LICENSE
Keywords: ai,analytics,anthropic,billing,claude,gemini,gpt,llm,metering,monitoring,openai,tokens,usage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Token Usage Analytics SDK

Lightweight, non-blocking Python SDK for tracking AI usage metrics across OpenAI, Anthropic, and Google AI providers.

[![PyPI version](https://badge.fury.io/py/token-usage-analytics.svg)](https://pypi.org/project/token-usage-analytics/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

**PyPI:** `token-usage-analytics` · **GitHub:** [jinal09-codaemon/token-usage-sdk](https://github.com/jinal09-codaemon/token-usage-sdk) · **Import:** `from ai_metering import ...`

## Installation

```bash
pip install token-usage-analytics
```

With provider-specific extras:

```bash
pip install token-usage-analytics[openai]      # OpenAI support
pip install token-usage-analytics[anthropic]   # Anthropic/Claude support
pip install token-usage-analytics[all]         # All providers
```

## Quick Start

```python
from ai_metering import MeteringClient

client = MeteringClient(
    api_key="usage_live_...",
    endpoint="https://tokenusage.transitiv-dev.com",
)

client.track_llm(
    provider="openai",
    model="gpt-4",
    input_tokens=150,
    output_tokens=50,
    feature="chat",
)
```

Or load from environment (see `.env.example`):

```python
from ai_metering import AIUsage

usage = AIUsage.from_env()
```

## Features

- **Non-blocking**: Usage tracking never delays your AI responses
- **Multi-provider**: OpenAI, Anthropic/Claude, Google Gemini
- **Auto-extraction**: Automatically extracts tokens from provider responses
- **Reliable**: Circuit breaker, retry queue, disk buffer for offline resilience
- **Secure**: HTTPS enforced, no PII in payloads

## Auto-Tracking with Wrappers

```python
from openai import OpenAI
from ai_metering import AIUsage

usage = AIUsage.from_env()
openai = usage.wrap(OpenAI())

response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
    usage_feature="my_feature",
)
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `USAGE_SDK_API_KEY` | Yes | API key from Token Usage Analytics (`usage_live_...`) |
| `METERING_BASE_URL` | Yes (prod) | API base URL, e.g. `https://tokenusage.transitiv-dev.com` |
| `ORGANIZATION_ID` | No | Scope events to an organization |
| `AI_METERING_DEBUG` | No | Debug logging (`true` / `false`) |

**Aliases:** `AI_METERING_API_KEY`, `METERING_API_KEY`, `AI_METERING_ENDPOINT`

Copy [`.env.example`](.env.example) to `.env` for local development.

## Development

```bash
git clone https://github.com/jinal09-codaemon/token-usage-sdk.git
cd token-usage-sdk
python -m pip install -e ".[dev,openai]"
pytest tests/ -v
python -m build
```

See [PUBLISHING.md](PUBLISHING.md) and [docs/GITHUB_SETUP.md](docs/GITHUB_SETUP.md) for GitHub + PyPI release steps.

## License

Proprietary - Transitiv Technologies. See [LICENSE](LICENSE) for details.

## Support

- Email: support@transitiv.com
- Issues: https://github.com/jinal09-codaemon/token-usage-sdk/issues
