v0.761 – user-set notifications & alerts

Author: FlyingFathead

.catgitinclude

@@ -8,3 +8,5 @@ src/modules.py
 src/text_message_handler.py
 src/utils.py
 config/config.ini
+src/reminder_poller.py
+src/reminder_handler.py

README.md

@@ -9,6 +9,8 @@
 - **🗺 Geolocation and map lookups via MapTiler API**
   - (with weather forecasts around the world in all OpenAI API supported languages)
 - **🧭 Navigation instructions via Openrouteservice API**  
+- **🔔 Timed reminders & notifications system**
+  - Users can schedule alerts that trigger at specific times. Configurable per-user limits and optional listing of past reminders
 - **📊 Daily token usage tracking & rate limiting for API usage / cost management**
 - **🔍 Perplexity API models alongside OpenAI models**
   - Useful for fact-checking and supplementing OpenAI's cutoff dates
@@ -238,7 +240,11 @@ If you run into any issues, consult the logs or reach out on the repository's [I
 ---
 
 # Changelog
-- v0.76 – **Premium mode auto-switching** + usage DB synergy
+- v0.761 - **Timed notifications / user reminders**
+  - Brand-new feature: users can set timed reminders (alerts) by requesting reminders that the bot stores in an SQLite database. A separate poller picks them up as soon as they are due, and the bot automatically notifies the user on set times.
+  - The custom function calling view action can also list your recently passed or deleted reminders (configurable in `[Reminders]` -> `ShowPastRemindersCount`).
+  - The bot ensures a max limit of pending reminders per user (set with `MaxAlertsPerUser`; set to 0 for unlimited alerts).
+- v0.76 - **Premium mode auto-switching** + usage DB synergy
   - Added daily usage-based auto-switch logic between “premium” vs. “mini” models (see `[ModelAutoSwitch]` in `config.ini`).
   - Once you exceed the `PremiumTokenLimit`, the bot seamlessly switches to the fallback model.
   - If that fallback also goes past `MiniTokenLimit`, the bot can either deny usage or proceed, according to `FallbackLimitAction`.

config/config.ini

@@ -181,6 +181,22 @@ ELASTICSEARCH_PASSWORD =
 [HolidaySettings]
 EnableHolidayNotification = true
 
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+# User-assignable reminders
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+[Reminders]
+# Enable or disable the reminder/alert functionality
+EnableReminders = True
+
+# Maximum number of pending reminders per user; set to 0 for unlimited
+MaxAlertsPerUser = 100
+
+# How often (in seconds) the bot checks for due reminders
+PollingIntervalSeconds = 5
+
+# How many old/past reminders to list
+ShowPastRemindersCount = 5
+
 # ~~~~~~~~~~~~~~~
 # Perplexity API
 # ~~~~~~~~~~~~~~~

src/api_get_stock_prices.py

@@ -15,7 +15,7 @@
 from datetime import datetime
 
 # Configure logging
-logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
+# logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
 
 # Utility function to get API key
 def get_api_key():

src/api_get_stock_prices_alphavantage.py

@@ -15,7 +15,7 @@
 from datetime import datetime
 
 # Configure logging
-logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
+# logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
 
 # Utility function to get API key
 def get_api_key():

src/api_get_stock_prices_yfinance.py

@@ -13,7 +13,7 @@
 from datetime import datetime
 
 # Configure logging
-logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
+# logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
 
 # Search for stock symbol (Using yfinance for direct data fetching)
 async def search_stock_symbol(keyword):

src/api_key.py

@@ -8,7 +8,7 @@
 from config_paths import CONFIG_PATH, API_TOKEN_PATH # Import the centralized CONFIG_PATH
 
 # Set up basic logging
-logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+# logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
 
 # Flag to enable or disable fallback to environment variable if the key is not found in the file
 ENABLE_KEY_READING_FALLBACK = True

src/bot_token.py

@@ -8,7 +8,7 @@
 from config_paths import CONFIG_PATH, TOKEN_FILE_PATH
 
 # Set up basic logging configuration
-logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', handlers=[logging.StreamHandler(sys.stdout)])
+# logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', handlers=[logging.StreamHandler(sys.stdout)])
 
 class BotTokenError(Exception):
     """Custom exception for bot token retrieval failures."""

src/config_paths.py

@@ -34,6 +34,10 @@
 NWS_RETRIES = 0
 NWS_RETRY_DELAY = 2
 
+# read the reminders db
+data_directory_name = 'data' # Default name for data directory
+REMINDERS_DB_FILENAME = 'reminders.db' # Default name for the reminders DB file
+
 # Attempt to read the configuration file
 if CONFIG_PATH.exists():
     try:
@@ -48,7 +52,10 @@
 
         # Ensure the logs directory exists
         LOGS_DIR.mkdir(parents=True, exist_ok=True)
-        
+
+        # Read data directory name from config
+        data_directory_name = config['DEFAULT'].get('DataDirectory', 'data')
+
         # Update log file paths
         LOG_FILE_PATH = LOGS_DIR / config['DEFAULT'].get('LogFile', 'bot.log')
         CHAT_LOG_FILE_PATH = LOGS_DIR / config['DEFAULT'].get('ChatLogFile', 'chat.log')
@@ -106,6 +113,18 @@
     # CHAT_LOG_MAX_SIZE already set to 10 MB
     # Elasticsearch settings already set to defaults
 
+# Define the Data Directory path
+DATA_DIR = BASE_DIR / data_directory_name
+# Ensure the data directory exists
+try:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+except OSError as e:
+    logger.error(f"Could not create data directory {DATA_DIR}: {e}")
+
+# Path for the reminders database
+REMINDERS_DB_PATH = DATA_DIR / REMINDERS_DB_FILENAME
+logger.info(f"Reminders database path set to: {REMINDERS_DB_PATH}")
+
 # Define paths for token files
 TOKEN_FILE_PATH = BASE_DIR / 'config' / 'bot_token.txt'
 API_TOKEN_PATH = BASE_DIR / 'config' / 'api_token.txt'

src/custom_functions.py

@@ -5,10 +5,25 @@
 # you can add your own custom bot functionalities via OpenAI's API function calls with this.
 
 import logging
+import configparser
+from config_paths import CONFIG_PATH
 
 # from api_get_openrouteservice import get_route, get_directions_from_addresses
 # from elasticsearch_handler import search_es  # Import the Elasticsearch search function
 
+# load and use logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# Read the config for enabled/disabled function calls
+config = configparser.ConfigParser()
+config.read(CONFIG_PATH)
+try: # Use try-except for safety
+    enable_reminders = config.getboolean('Reminders', 'EnableReminders', fallback=False)
+except (configparser.NoSectionError, configparser.NoOptionError):
+    enable_reminders = False
+
+# silently observe the chat
 async def observe_chat():
     # Log observation or perform any silent monitoring if needed
     logging.info("Bot is currently observing the chat.")
@@ -149,6 +164,150 @@ async def observe_chat():
     }
 })
 
+# ~~~~~~~~~~~~~~~~~~~~~~
+# reminders (if enabled)
+# ~~~~~~~~~~~~~~~~~~~~~~
+
+if enable_reminders:
+    manage_reminder_function = {
+        'name': 'manage_reminder',
+        'description': """Manages user reminders (alerts); use if the user requests alerts, a timed notification, etc (hälytys, muistutus, ajastettu viesti..) Specify the action: 'add' to create, 'view' to list pending, 'delete' to remove by ID, or 'edit' to modify by ID. 
+        If you're unsure of the user's time zone, ask it first, and set the UTC alert accordingly. For instance, Finland is UTC+2 in winter and UTC+3 during summertime. Add the reminder in the user's own language! Suomeksi, jos käyttäjä puhuu suomea! Always ask the user's timezone if unsure.
+- For 'add': requires 'reminder_text' and exact 'due_time_utc' (ISO 8601 format, e.g., '2025-04-04T10:00:00Z'). Calculate UTC from user input based on current system UTC time. Notifications can be up to around 4000 characters or more.
+- For 'view': no other parameters needed.
+- For 'delete': requires 'reminder_id'.
+- For 'edit': requires 'reminder_id' and at least one of 'reminder_text' or 'due_time_utc'.""",
+        'parameters': {
+            'type': 'object',
+            'properties': {
+                'action': {
+                    'type': 'string',
+                    'enum': ['add', 'view', 'delete', 'edit'],
+                    'description': "The operation: 'add', 'view', 'delete', or 'edit'."
+                },
+                'reminder_text': {
+                    'type': 'string',
+                    'description': "Text of the reminder, in the user's requested language. You can be a bit creative, like: 'Hey! You asked me to remind you... etc, emojis and basic Telegram HTML formatting is allowed.'. Required for 'add', optional for 'edit'."
+                },
+                'due_time_utc': {
+                    'type': 'string',
+                    'description': "Due time in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Required for 'add', optional for 'edit'."
+                },
+                'reminder_id': {
+                    'type': 'integer',
+                    'description': "ID of the reminder. Required for 'delete' and 'edit'."
+                }
+            },
+            'required': ['action']
+        }
+    }
+    custom_functions.append(manage_reminder_function) # Directly append if enabled
+    logger.info("Reminder function 'manage_reminder' appended to custom_functions list.")
+else:
+    logger.info("Reminders disabled in config.ini => 'manage_reminder' function not added.")
+
+# # original reminder method (tryout)
+# if enable_reminders:
+#     # 1) Add a reminder
+#     custom_functions.append({
+#         'name': 'add_reminder',
+#         'description': (
+#             "[Use if the user wants to set a reminder for a future time.] "
+#             "Accept user text and a date/time in UTC (YYYY-MM-DDTHH:MM:SSZ). "
+#             "If user says 'in 5 minutes', parse that to a UTC time. "
+#             "Return success/failure, and the ID of the reminder if successful."
+#         ),
+#         'parameters': {
+#             'type': 'object',
+#             'properties': {
+#                 'due_time_utc': {
+#                     'type': 'string',
+#                     'description': (
+#                         "The date/time in UTC, e.g. 2025-01-02T13:00:00Z. "
+#                         "If user says something like 'in 5 minutes', parse into UTC. "
+#                         "If date/time is missing, ask user for clarification."
+#                     )
+#                 },
+#                 'reminder_text': {
+#                     'type': 'string',
+#                     'description': (
+#                         "What does the user want to be reminded of? E.g. 'Take out the trash'."
+#                     )
+#                 }
+#             },
+#             'required': ['due_time_utc', 'reminder_text']
+#         }
+#     })
+
+#     # 2) View all pending reminders
+#     custom_functions.append({
+#         'name': 'view_reminders',
+#         'description': (
+#             "[Use if the user wants to see their current/pending reminders.] "
+#             "No arguments needed."
+#         ),
+#         'parameters': {
+#             'type': 'object',
+#             'properties': {},
+#             'required': []
+#         }
+#     })
+
+#     # 3) Delete a reminder
+#     custom_functions.append({
+#         'name': 'delete_reminder',
+#         'description': (
+#             "[Use if the user wants to delete/cancel an existing reminder by ID.] "
+#             "Reminders are typically identified by an integer ID."
+#         ),
+#         'parameters': {
+#             'type': 'object',
+#             'properties': {
+#                 'reminder_id': {
+#                     'type': 'integer',
+#                     'description': (
+#                         "The ID number of the reminder to delete. "
+#                         "If user doesn't know the ID, prompt them to /viewreminders first or if they ask for you to show them their reminders."
+#                     )
+#                 }
+#             },
+#             'required': ['reminder_id']
+#         }
+#     })
+
+#     # 4) Edit a reminder (optional)
+#     custom_functions.append({
+#         'name': 'edit_reminder',
+#         'description': (
+#             "[Use if user wants to update an existing reminder. Provide the ID plus new text/time.] "
+#             "Either 'due_time_utc' or 'reminder_text' or both can be changed."
+#         ),
+#         'parameters': {
+#             'type': 'object',
+#             'properties': {
+#                 'reminder_id': {
+#                     'type': 'integer',
+#                     'description': "The ID of the reminder to edit."
+#                 },
+#                 'due_time_utc': {
+#                     'type': 'string',
+#                     'description': (
+#                         "The new date/time in UTC, e.g. 2025-01-02T13:00:00Z. "
+#                         "If user says 'tomorrow 10am', parse that into a UTC string."
+#                     )
+#                 },
+#                 'reminder_text': {
+#                     'type': 'string',
+#                     'description': "The updated reminder text."
+#                 }
+#             },
+#             'required': ['reminder_id']
+#         }
+#     })
+
+# else:
+#     logging.info("Reminders are disabled in config.ini => not adding reminder functions.")
+
 # # jul 26 / 2024
 # custom_functions.append({
 #     'name': 'get_rss_feed',