Budget Manual

[AlexHTW]

For now budget settings can only be adjusted through the .env file, so this manual serves to avoid misunderstandings and provide some guidance on the dependencies and achieving your desired budget settings. Also useful as a reference for contributors who want to implement new features that are related to budgets.

Relevant .env Variables

The budget settings involve the following environment variables:

• ADMIN_USER_IDS: A comma separated list of users who have unrestricted access to bot. No budgets are ever applied and special commands might be added in future releases.
• ALLOWED_TELEGRAM_USER_IDS: A comma separated list of users who are allowed to use the bot. Setting it to * allows everyone (default). You can see the ID of a user in the logs for every interaction with the bot.
• USER_BUDGETS: A comma separated list of $-amounts representing the budget allowance for each user in the same order as the user list. Setting it to * (default) gives all users unlimited budgets. For an unrestricted user-list (ALLOWED_TELEGRAM_USER_IDS = *) every person interacting with the bot receives their own budget for the amount of the first value in USER_BUDGET.
• GUEST_BUDGET: A single value for the $-amount of the guest budget. Guests are users in group chats who are not listed in ALLOWED_TELEGRAM_USER_IDS but are allowed to interact with the bot because they are in a group chat with an allowed user and the bot. Every guest shares the budget amount and doesn't get their own budget. If a user is in ALLOWED_TELEGRAM_USER_IDS they do not have access to the shared guest budget and still use their own budget in requests from a group. Guest budgets are only applied if ALLOWED_TELEGRAM_USER_IDS is not set to *. (default 100.0)
• BUDGET_PERIOD: Setting for the time frame of all budgets. The following values are available:
  • daily: Resets the defined budgets every day to the full amount.
  • monthly: Resets the budget on the first day of every month to the full amount. (default)
  • all-time: Never resets the budget. Additional budget has to be added to the existing amount.

Default Behavior

Unrestricted Access for Everybody

The current default behavior (if you don't set them in the .env) is that there are no restrictions on who can use the bot and how much everybody can spend. Guest budgets are not applied because without specific users, there are no guests.
Budgets are never applied to users in the ADMIN_USER_IDS, even if they are also listed in the ALLOWED_TELEGRAM_USER_IDS.

Possible Setups

The goal of the described options is to give as much flexibility as possible without bloating the environment configuration and code with special cases. Following are some setups that could be useful to different applications of the bot. I hope to extend this list with more suggestions from your use-cases.

Admin Access Only

If you want to run the bot for yourself and don't care about budgets, set your ID in ADMIN_USER_IDS and set ALLOWED_TELEGRAM_USER_IDS to anything that is not * or someone else's Telegram user ID.
I recommend your own ID or a special character like - for clarity.
Example:

# admin access only
ADMIN_USER_IDS=12345
ALLOWED_TELEGRAM_USER_IDS=12345

No Budgets Needed

If you want to give all your specified users access without limiting their spending don't add any of the budget variables to your .env or set USER_BUDGETS=*.
Example:

# no budgets
ADMIN_USER_IDS=1234
ALLOWED_TELEGRAM_USER_IDS=6666,7777,8888
USER_BUDGETS=*

Limited Access for Users

If you want to give all your specified users access within an individual spending limit set their budgets in USER_BUDGETS in the same order as they are listed in ALLOWED_TELEGRAM_USER_IDS. Not specifying the BUDGET_PERIOD variable will give each user their individual budget amount every month. Setting BUDGET_PERIOD to daily will give them the budget amount every day.
Setting BUDGET_PERIOD to all-time will give them the budget amount once. When an all-time budget amount is used up, you can add additional budget by increasing the existing budget amount with the new budget or by resetting the users tracked spending (see Resetting Tracked Spending).
Example:

# limited access for users
ADMIN_USER_IDS=12345
ALLOWED_TELEGRAM_USER_IDS=6666,7777,8888
USER_BUDGETS=10.0,1.0,100.0
BUDGET_PERIOD=all-time
# user 12345 has no budget restrictions
# user 6666 has a budget of $10.00
# user 7777 has a budget of $1.00
# user 8888 has a budget of $100.00

Limited Access for Everybody

If you want your bot to be openly available to everybody but limit their spending allowance, add a single budget value to USER_BUDGETS and your desired BUDGET_PERIOD. Any guest budgets are ignored.
Everybody receives their own budget of the specified value for the budget period.

# no budgets
ADMIN_USER_IDS=1234
ALLOWED_TELEGRAM_USER_IDS=*
USER_BUDGETS=10.0
# everybody gets their own $10 budget to be used in private chats or group chats. Admin has unlimited budget.

Access Only in Admin Groups

If you want to allow everybody in a group of yours access to the bot within a shared budget, set your ID in the ADMIN_USER_IDS, the ALLOWED_TELEGRAM_USER_IDS to something other than *, the GUEST_BUDGET to the desired spending limit of all group members (excluding you) and your desired BUDGET_PERIOD.
Example:

# access only in admin groups
ADMIN_USER_IDS=12345
ALLOWED_TELEGRAM_USER_IDS=12345
GUEST_BUDGET=5.0
BUDGET_PERIOD=daily
# all members in group chats with the user 12345 and the bot can access the bot up to a combined total limit of $5 a day. 
# Admin user 12345 has unlimited private and group access to the bot.

No Guests Allowed

If you don't want people other than your specified admins and users to be able to use the bot in groups set GUEST_BUDGET=0.
Example:

# no guests allowed
ADMIN_USER_IDS=12345
ALLOWED_TELEGRAM_USER_IDS=6666,7777,8888
GUEST_BUDGET=0
# Only specified users can access the bot in group chats.

Combining Scenarios

The described setups serve to explain the dependencies of the different environment variables. More use-cases can be achieved by combining some of the setups as long as the scenarios don't contradict each other. To realize more advanced setups consider running multiple bots with different settings.
For example you could use one bot instance with the Limited Access for Everybody setup to showcase the bot and find new users that you add to another bot instance with the Limited Access for Users setup.
A different case where you would need multiple bot instances is when you want to realize multiple budget periods. For example to give different users budgets with different periods (e.g. a bot with daily budgets and a bot with monthly budgets).

Additional Information

Request Pricing

The prices used for calculating the cost of usage for all three kinds of requests (chatGPT, Dall-E image generation, Whisper transcription) can be adjusted in the following .env-variables: `

• TOKEN_PRICE
  • per 1000 Tokens
  • default: 0.002
    • standard price for gpt-3.5-turbo (default model)
• IMAGE_PRICES
  • comma-separated list of three values for the prices per image of three different image sizes "256x256","512x512","1024x1024"
  • default: 0.016,0.018,0.02
• TRANSCRIPTION_PRICE
  • per minute of audio transcription
  • default: 0.006

Adjust the prices if using other models than the default (e.g. GPT-4) or if you want to "charge" different prices from your users than you pay to OpenAI.

Usage Logs

All successful requests are tracked by day and request type per user_id in the usage_logs directory. You can use these to retrieve usage information or statistics for a user.

Access

If you run the bot through using the repository (python3 bot/main.py or docker compose up) you can just access them in your file-system, if you run the bot using the provided dockerhub/ghcr (docker run) image, try one of the methods suggested here.

Structure

The usage log for one user contains general information and a daily usage history.
(hint: your IDE or text editor probably supports a function to format the .json documents into an easier readable form, like below. For VSCode use Ctrl+Shift+I)
Example user_id.json :

{
    "user_name": "@username",
    "current_cost": {
        "day": 0.204,
        "month": 12.00302,
        "all_time": 52.316,
        "last_update": "2023-03-23"
    },
    "usage_history": {
        "chat_tokens": {
            "2023-03-14": 315,
            "2023-03-15": 924,

        },
        "transcription_seconds": {
            "2023-03-14": 1.9735,
            "2023-03-15": 67.586,
            "2023-03-16": 10.587,
        },
        "number_images": {
            "2023-03-15": [
                3,
                0,
                0
            ],
            "2023-03-23": [
                0,
                1,
                0
            ]
        }
    }
}

The current_cost fields are used to calculate the remaining budget of a user for each budget_period. If you change prices for requests in the .env file, previous requests are not recalculated, only future requests added to the current_cost will apply the new price.

Guests convert to Users

Each guest also receives their own usage log. Thus, if a previous guest becomes a user in the ALLOWED_TELEGRAM_USER_IDS list, their usage log will not reset automatically and their previous guest usage is deducted from their budget.
Additionally all guest usage is logged together in a separate file usage_logs/guests.json so that the guest budget can be shared between all guests.

Resetting Tracked Spending

To reset a users cost you can delete their usage log file and a completely new one will be generated on next usage or manually adjust the values in current_cost to 0.
This could be useful for the guest to user conversion or to manually reset a users budget. A future admin command could be implemented to take care of that.

Future Enhancements

Requested

• admin command(s) to manage users and budgets via chat Add users via chat #108
  • possibly using buttons submenu
  • additional non-user command to request access from admin(s)
• admin command to get specific user stats as requested here
  • possibly additional summary stats of all users

Other Ideas, open for discussion

• shared budgets as discussed here
• admin command to reset a users usage

Disclaimer

The usage and cost tracking is calculated in the bot and not through OpenAI API calls. As this is a volunteer community project we can't guarantee a bug-free and 100% exact tracking and take no responsibility for unexpected charges.
Make sure to be defensive in your user and budget settings for the bot and set soft and hard usage limits in your OpenAI account settings. Keep your API key secure and don't publish it in your own public remote repositories.
Please report any discrepancies or unexpected behaviors you can find.

[n3d1117]

Hi @AlexHTW, how does the "Limited Access for Everybody" scenario work? I set:

ADMIN_USER_IDS=12345
ALLOWED_TELEGRAM_USER_IDS=6666,7777,8888
USER_BUDGETS=1.0
BUDGET_PERIOD=daily

to allow 1$ daily budget for everyone. But when user 6666 writes, I get:

2023-04-11 12:03:50,037 - root - WARNING - No budget set for user id: 6666. Budget list shorter than user list.
2023-04-11 12:03:50,037 - root - WARNING - User @xxx (id: 6666) reached their usage limit

What am I missing? Thanks!

[AlexHTW]

Hey @n3d1117,
the limited access for everybody only works for * - user lists. (Previously you were not able to set budgets for * user lists at all.)
When you have a defined user-list you have to provide a specific budget for every user.
If there is a user-list defined, my primary concern was to protect against mistakes in the USER_BUDGETS setup and consciously be aware of the additional budget you are giving out when adding a new user.
Especially with the outlook of adding users through a command in the future I think it's better to be explicit and let the code handle the additional effort.

I do empathize with your use-case, especially if you add and remove users very frequently, I am just a bit worried about unexpected behavior and additional special cases in future development.
Still, if you definitely want to add a case for if len(USER_BUDGETS)==1 then apply that to every user, I am happy to implemented it, shouldn't be much effort.

[n3d1117]

Thanks for the clarification @AlexHTW, makes sense. I added:

USER_BUDGETS=1.0,1.0,1.0

and it's working now. Not sure how frequent my use case is, let's leave it like this for the time being. Thanks again!