openai-messages-token-helper

What it is and what it does

This package wraps OpenAI's tokenization logic to help you stay within token budgets when building chat conversations. It provides functions to count tokens in individual messages, images (for GPT-4 vision), and tool definitions, then uses those counts to automatically truncate old messages from a conversation history so the final message list fits within a model's token limit.

You supply a system prompt, optional few-shot examples, past messages, and a new user message, along with a target token budget and model name. The library calculates the token cost of each component using tiktoken for text and Pillow for image dimensions, then drops old messages from the history until everything fits. It also supports Azure OpenAI model names and can fall back to default limits if a model is unrecognized.

Use it for:

• Automatically truncate chat history to fit within a model's context window before sending to the OpenAI API.
• Calculate token costs for images in GPT-4 vision requests to budget vision-enabled conversations.
• Build few-shot prompts with known token budgets, ensuring examples fit alongside user messages.
• Estimate API costs by counting tokens before making requests to OpenAI.
• Handle tool definitions and tool-choice parameters in token calculations for function-calling workflows.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Estimates token usage for OpenAI Chat Completions API messages and builds message lists that fit within model token limits, accounting for text, images, tools, and few-shot examples.

Yes, if you are building applications that use OpenAI's Chat Completions API and need to manage token budgets programmatically. The library is straightforward, has low install friction, carries no known vulnerabilities, and solves a real operational problem—preventing token-limit errors by pre-calculating and truncating conversations. Maintenance is aging but the repository is active; use it with the understanding that updates may be infrequent.

Install

openai-messages-token-helper on PyPI

pip install openai-messages-token-helper

uv add openai-messages-token-helper

poetry add openai-messages-token-helper

Installing openai-messages-token-helper

Before you install

Low install friction; depends on openai, tiktoken, and pillow. Maintenance status is aging—last commit 2025-12-29, 228 days since release—but the repository is active and not archived. Supports Python 3.9, 3.10, and 3.11.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute freely with minimal restrictions.

Quickstart

from openai_messages_token_helper import build_messages

messages = build_messages(
    model="gpt-4",
    system_prompt="You are a helpful assistant.",
    new_user_content="Hello",
    past_messages=[]
)

Requires openai and tiktoken to be installed; model name must be recognized or fallback_to_default must be True.

Verify before relying

• Whether the package handles all current OpenAI model variants or only a fixed set.
• Performance characteristics when processing large message histories or many images in a single call.
• Whether token counts match OpenAI's actual billing exactly or are estimates.

Package facts

Evidence: openai_messages_token_helper-0.1.13-py3-none-any.whl

Tags

More Artificial Intelligence packages