Metadata-Version: 2.4
Name: llm-token-tracker
Version: 0.3.1
Summary: A package to track LLM token usage in context
Author: Laurin
License-Expression: MIT
Keywords: llm,token,tracker,xai,grok
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xai-sdk
Dynamic: license-file

# llm-token-tracker

[![PyPI version](https://img.shields.io/pypi/v/llm-token-tracker.svg)](https://pypi.org/project/llm-token-tracker/)

A Python package to track token usage in LLM interactions.

## Features

- Track token usage in LLM conversations
- Support for detailed token breakdowns (prompt, completion, reasoning, cached, etc.)
- Cost estimation for input and output tokens
- Configurable verbosity levels for logging
- Integration with custom loggers

## Installation

```bash
pip install llm-token-tracker
```

## Usage

```python
from llm_token_tracker import wrap_llm
from xai_sdk import Client
import logging

# Create and wrap a chat for token tracking
client = Client()
chat = client.chat.create(model="grok-3")
wrapped_chat = wrap_llm(chat)

response = wrapped_chat.sample("Hello, how are you?")
print(response.content)
# Console will log: Total tokens used in context: X

# For conversation context
wrapped_chat.append(system("You are Grok, a highly intelligent AI."))
wrapped_chat.append(user("What is the meaning of life?"))
response = wrapped_chat.sample()
print(response.content)
```

### Configuration Options

`wrap_llm` accepts several parameters to customize logging:

- `verbosity`: `"minimum"` (default), `"detailed"`, or `"max"`
  - `"minimum"`: Logs only total tokens used.
  - `"detailed"`: Logs a detailed usage summary.
  - `"max"`: Logs the full history of all token usages.
- `logger`: Optional `logging.Logger` instance. If provided, uses the logger instead of printing to console.
- `log_level`: Logging level (default `logging.INFO`).
- `quiet`: If `True`, disables all logging.
- `max_tokens`: Maximum tokens allowed in context (default 132000).
- `input_pricing`: Price per 1 million input tokens (default 0.2).
- `output_pricing`: Price per 1 million output tokens (default 0.5).
- `calculate_pricing`: If `True`, calculates and logs cost estimates (default `False`).

Example with custom logger:

```python
import logging

logger = logging.getLogger("my_llm_logger")
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
logger.addHandler(handler)

wrapped_chat = wrap_llm(chat, logger=logger, verbosity="detailed")
```

Note: Requires XAI_API_KEY environment variable set for authentication.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
