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
• Compatibility with xAI and OpenAI models

Installation

pip install llm-token-tracker

Usage

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)

OpenAI Compatibility

For OpenAI models using the responses API:

from openai import OpenAI
from llm_token_tracker import wrap_llm

client = OpenAI()
wrapped_client = wrap_llm(client, provider="openai")

response = wrapped_client.responses.create(
    model="gpt-4.1",
    input="Tell me a three sentence bedtime story about a unicorn."
)
print(response.content)
# Console will log: Total tokens used in context: X

Configuration Options

wrap_llm accepts several parameters to customize logging:

• provider: "xai" (default) or "openai" to specify the LLM provider.
• 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:

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

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.