| Name | openai-messages-token-helper JSON |
| Version |
0.1.10
JSON |
| download |
| home_page | None |
| Summary | A helper library for estimating tokens used by messages sent through OpenAI Chat Completions API. |
| upload_time | 2024-08-09 21:20:32 |
| maintainer | None |
| docs_url | None |
| author | Pamela Fox |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# openai-messages-token-helper
A helper library for estimating tokens used by messages and building messages lists that fit within the token limits of a model.
Currently designed to work with the OpenAI GPT models (including GPT-4 turbo with vision).
Uses the tiktoken library for tokenizing text and the Pillow library for image-related calculations.
## Installation
Install the package:
```sh
python3 -m pip install openai-messages-token-helper
```
## Usage
The library provides the following functions:
* [`build_messages`](#build_messages)
* [`count_tokens_for_message`](#count_tokens_for_message)
* [`count_tokens_for_image`](#count_tokens_for_image)
* [`get_token_limit`](#get_token_limit)
### `build_messages`
Build a list of messages for a chat conversation, given the system prompt, new user message,
and past messages. The function will truncate the history of past messages if necessary to
stay within the token limit.
Arguments:
* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo.
* `system_prompt` (`str`): The initial system prompt message.
* `tools` (`List[openai.types.chat.ChatCompletionToolParam]`): (Optional) The tools that will be used in the conversation. These won't be part of the final returned messages, but they will be used to calculate the token count.
* `tool_choice` (`openai.types.chat.ChatCompletionToolChoiceOptionParam`): (Optional) The tool choice that will be used in the conversation. This won't be part of the final returned messages, but it will be used to calculate the token count.
* `new_user_content` (`str | List[openai.types.chat.ChatCompletionContentPartParam]`): (Optional) The content of new user message to append.
* `past_messages` (`list[openai.types.chat.ChatCompletionMessageParam]`): (Optional) The list of past messages in the conversation.
* `few_shots` (`list[openai.types.chat.ChatCompletionMessageParam]`): (Optional) A few-shot list of messages to insert after the system prompt.
* `max_tokens` (`int`): (Optional) The maximum number of tokens allowed for the conversation.
* `fallback_to_default` (`bool`): (Optional) Whether to fallback to default model/token limits if model is not found. Defaults to `False`.
Returns:
* `list[openai.types.chat.ChatCompletionMessageParam]`
Example:
```python
from openai_messages_token_helper import build_messages
messages = build_messages(
model="gpt-35-turbo",
system_prompt="You are a bot.",
new_user_content="That wasn't a good poem.",
past_messages=[
{
"role": "user",
"content": "Write me a poem",
},
{
"role": "assistant",
"content": "Tuna tuna I love tuna",
},
],
few_shots=[
{
"role": "user",
"content": "Write me a poem",
},
{
"role": "assistant",
"content": "Tuna tuna is the best",
},
]
)
```
### `count_tokens_for_message`
Counts the number of tokens in a message.
Arguments:
* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo.
* `message` (`openai.types.chat.ChatCompletionMessageParam`): The message to count tokens for.
* `default_to_cl100k` (`bool`): Whether to default to the CL100k token limit if the model is not found.
Returns:
* `int`: The number of tokens in the message.
Example:
```python
from openai_messages_token_helper import count_tokens_for_message
message = {
"role": "user",
"content": "Hello, how are you?",
}
model = "gpt-4"
num_tokens = count_tokens_for_message(model, message)
```
### `count_tokens_for_image`
Count the number of tokens for an image sent to GPT-4-vision, in base64 format.
Arguments:
* `image` (`str`): The base64-encoded image.
Returns:
* `int`: The number of tokens used up for the image.
Example:
```python
Count the number of tokens for an image sent to GPT-4-vision:
```python
from openai_messages_token_helper import count_tokens_for_image
image = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA..."
num_tokens = count_tokens_for_image(image)
```
### `get_token_limit`
Get the token limit for a given GPT model name (OpenAI.com or Azure OpenAI supported).
Arguments:
* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo (OpenAI.com) or gpt-35-turbo (Azure).
* `default_to_minimum` (`bool`): Whether to default to the minimum token limit if the model is not found.
Returns:
* `int`: The token limit for the model.
Example:
```python
from openai_messages_token_helper import get_token_limit
model = "gpt-4"
max_tokens = get_token_limit(model)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "openai-messages-token-helper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Pamela Fox",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/98/39/137f3f92f23aacbf417874eb58bea75141b557e0b67bf3ab6641bd653c31/openai_messages_token_helper-0.1.10.tar.gz",
"platform": null,
"description": "# openai-messages-token-helper\n\nA helper library for estimating tokens used by messages and building messages lists that fit within the token limits of a model.\nCurrently designed to work with the OpenAI GPT models (including GPT-4 turbo with vision).\nUses the tiktoken library for tokenizing text and the Pillow library for image-related calculations.\n\n## Installation\n\nInstall the package:\n\n```sh\npython3 -m pip install openai-messages-token-helper\n```\n\n## Usage\n\nThe library provides the following functions:\n\n* [`build_messages`](#build_messages)\n* [`count_tokens_for_message`](#count_tokens_for_message)\n* [`count_tokens_for_image`](#count_tokens_for_image)\n* [`get_token_limit`](#get_token_limit)\n\n### `build_messages`\n\nBuild a list of messages for a chat conversation, given the system prompt, new user message,\nand past messages. The function will truncate the history of past messages if necessary to\nstay within the token limit.\n\nArguments:\n\n* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo.\n* `system_prompt` (`str`): The initial system prompt message.\n* `tools` (`List[openai.types.chat.ChatCompletionToolParam]`): (Optional) The tools that will be used in the conversation. These won't be part of the final returned messages, but they will be used to calculate the token count.\n* `tool_choice` (`openai.types.chat.ChatCompletionToolChoiceOptionParam`): (Optional) The tool choice that will be used in the conversation. This won't be part of the final returned messages, but it will be used to calculate the token count.\n* `new_user_content` (`str | List[openai.types.chat.ChatCompletionContentPartParam]`): (Optional) The content of new user message to append.\n* `past_messages` (`list[openai.types.chat.ChatCompletionMessageParam]`): (Optional) The list of past messages in the conversation.\n* `few_shots` (`list[openai.types.chat.ChatCompletionMessageParam]`): (Optional) A few-shot list of messages to insert after the system prompt.\n* `max_tokens` (`int`): (Optional) The maximum number of tokens allowed for the conversation.\n* `fallback_to_default` (`bool`): (Optional) Whether to fallback to default model/token limits if model is not found. Defaults to `False`.\n\n\nReturns:\n\n* `list[openai.types.chat.ChatCompletionMessageParam]`\n\nExample:\n\n```python\nfrom openai_messages_token_helper import build_messages\n\nmessages = build_messages(\n model=\"gpt-35-turbo\",\n system_prompt=\"You are a bot.\",\n new_user_content=\"That wasn't a good poem.\",\n past_messages=[\n {\n \"role\": \"user\",\n \"content\": \"Write me a poem\",\n },\n {\n \"role\": \"assistant\",\n \"content\": \"Tuna tuna I love tuna\",\n },\n ],\n few_shots=[\n {\n \"role\": \"user\",\n \"content\": \"Write me a poem\",\n },\n {\n \"role\": \"assistant\",\n \"content\": \"Tuna tuna is the best\",\n },\n ]\n)\n```\n\n### `count_tokens_for_message`\n\nCounts the number of tokens in a message.\n\nArguments:\n\n* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo.\n* `message` (`openai.types.chat.ChatCompletionMessageParam`): The message to count tokens for.\n* `default_to_cl100k` (`bool`): Whether to default to the CL100k token limit if the model is not found.\n\nReturns:\n\n* `int`: The number of tokens in the message.\n\nExample:\n\n```python\nfrom openai_messages_token_helper import count_tokens_for_message\n\nmessage = {\n \"role\": \"user\",\n \"content\": \"Hello, how are you?\",\n}\nmodel = \"gpt-4\"\nnum_tokens = count_tokens_for_message(model, message)\n```\n\n### `count_tokens_for_image`\n\nCount the number of tokens for an image sent to GPT-4-vision, in base64 format.\n\nArguments:\n\n* `image` (`str`): The base64-encoded image.\n\nReturns:\n\n* `int`: The number of tokens used up for the image.\n\nExample:\n\n```python\n\nCount the number of tokens for an image sent to GPT-4-vision:\n\n```python\nfrom openai_messages_token_helper import count_tokens_for_image\n\nimage = \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA...\"\nnum_tokens = count_tokens_for_image(image)\n```\n\n### `get_token_limit`\n\nGet the token limit for a given GPT model name (OpenAI.com or Azure OpenAI supported).\n\nArguments:\n\n* `model` (`str`): The model name to use for token calculation, like gpt-3.5-turbo (OpenAI.com) or gpt-35-turbo (Azure).\n* `default_to_minimum` (`bool`): Whether to default to the minimum token limit if the model is not found.\n\nReturns:\n\n* `int`: The token limit for the model.\n\nExample:\n\n```python\nfrom openai_messages_token_helper import get_token_limit\n\nmodel = \"gpt-4\"\nmax_tokens = get_token_limit(model)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A helper library for estimating tokens used by messages sent through OpenAI Chat Completions API.",
"version": "0.1.10",
"project_urls": {
"Home": "https://github.com/pamelafox/openai-messages-token-helper"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "307de5b14e914c0febd783ebe12c425c0674b975761e666ec596437de23eb78d",
"md5": "2ed56a39cbbccb57ddffeb77df616f79",
"sha256": "d14cf14c08846b87a240fa0df862ccc995eb9759cabbaa3f994946886c539e5e"
},
"downloads": -1,
"filename": "openai_messages_token_helper-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ed56a39cbbccb57ddffeb77df616f79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10542,
"upload_time": "2024-08-09T21:20:30",
"upload_time_iso_8601": "2024-08-09T21:20:30.483106Z",
"url": "https://files.pythonhosted.org/packages/30/7d/e5b14e914c0febd783ebe12c425c0674b975761e666ec596437de23eb78d/openai_messages_token_helper-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9839137f3f92f23aacbf417874eb58bea75141b557e0b67bf3ab6641bd653c31",
"md5": "8174047d36fb3954426c7b1ce391dfb1",
"sha256": "ccf1d58cced08012777d4c03d0a4eaff6ea815b59f9ba79a72e7bbabe3167c1d"
},
"downloads": -1,
"filename": "openai_messages_token_helper-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "8174047d36fb3954426c7b1ce391dfb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 396704,
"upload_time": "2024-08-09T21:20:32",
"upload_time_iso_8601": "2024-08-09T21:20:32.899958Z",
"url": "https://files.pythonhosted.org/packages/98/39/137f3f92f23aacbf417874eb58bea75141b557e0b67bf3ab6641bd653c31/openai_messages_token_helper-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-09 21:20:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pamelafox",
"github_project": "openai-messages-token-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openai-messages-token-helper"
}
