- user-set notifications & alerts

Author: FlyingFathead

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

@@ -194,6 +194,9 @@ 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/db_utils.py

@@ -237,6 +237,38 @@ def get_due_reminders(db_path, current_utc_time_str):
     rows = _execute_sql(db_path, sql, (current_utc_time_str,), fetch_all=True)
     return [{'reminder_id': r[0], 'user_id': r[1], 'chat_id': r[2], 'reminder_text': r[3]} for r in rows] if rows else []
 
+def get_past_reminders_for_user(db_path, user_id, limit=5):
+    """
+    Gets the most recent 'past' reminders (status != 'pending') for a user,
+    ordered by the time they were due or created. 
+    Typically we consider 'sent','failed_*','deleted' as "past."
+    """
+    if not DB_INITIALIZED_SUCCESSFULLY:
+        logging.error("DB not initialized. Cannot get past reminders.")
+        return []
+
+    sql = f"""
+        SELECT reminder_id, reminder_text, due_time_utc, status 
+        FROM {REMINDERS_TABLE_NAME}
+        WHERE user_id = ? 
+          AND status != 'pending'
+        ORDER BY due_time_utc DESC
+        LIMIT ?
+    """
+    rows = _execute_sql(db_path, sql, (user_id, limit), fetch_all=True)
+    if not rows:
+        return []
+    # Build a list of dicts
+    reminders = []
+    for row in rows:
+        reminders.append({
+            'reminder_id': row[0],
+            'reminder_text': row[1],
+            'due_time_utc': row[2],
+            'status': row[3]
+        })
+    return reminders
+
 def update_reminder_status(db_path, reminder_id, new_status):
     """Updates the status of a reminder (e.g., to 'sent' or 'failed')."""
     if not DB_INITIALIZED_SUCCESSFULLY:

src/main.py

@@ -59,6 +59,7 @@
     ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD
 )
 
+import db_utils
 from bot_token import get_bot_token
 from api_key import get_api_key
 import bot_commands
@@ -168,10 +169,6 @@ def __init__(self):
         from config_paths import CHAT_LOG_FILE_PATH
         self.chat_log_file = CHAT_LOG_FILE_PATH
 
-        # Read the reminder setting using the full parser and the Reminders section
-        self.reminders_enabled = self._parser.getboolean('Reminders', 'EnableReminders', fallback=False)
-        self.logger.info(f"Reminders Enabled according to config: {self.reminders_enabled}")
-
         # Attempt to get bot & API tokens
         try:
             self.telegram_bot_token = get_bot_token()
@@ -528,6 +525,10 @@ def run(self):
         # Get the asyncio event loop
         loop = asyncio.get_event_loop()
 
+        # Force DB init
+        if not db_utils.DB_INITIALIZED_SUCCESSFULLY:
+            db_utils._create_tables_if_not_exist(db_utils.REMINDERS_DB_PATH)
+
         # If reminders are enabled in config, launch reminder poller
         if self.reminders_enabled:
             loop.create_task(reminder_poller(application))

src/reminder_handler.py

@@ -5,10 +5,12 @@
 from datetime import datetime, timezone
 from config_paths import CONFIG_PATH, REMINDERS_DB_PATH
 import db_utils
+from db_utils import get_past_reminders_for_user
 
 # Load config to get MaxAlertsPerUser
 config = configparser.ConfigParser()
 config.read(CONFIG_PATH)
+SHOW_PAST_REMINDERS_COUNT = config.getint('Reminders', 'ShowPastRemindersCount', fallback=0)
 
 try:
     MAX_ALERTS_PER_USER = config.getint('Reminders', 'MaxAlertsPerUser', fallback=30)
@@ -81,19 +83,54 @@ async def handle_view_reminders(user_id):
         logger.error("Attempt to view reminders but DB not available!")
         return "Error: DB not available. Cannot view reminders."
 
-    reminders = db_utils.get_pending_reminders_for_user(REMINDERS_DB_PATH, user_id)
-    if not reminders:
-        logger.info(f"User {user_id} has no pending reminders.")
-        return "You currently have no pending reminders."
-
-    logger.info(f"User {user_id} is viewing {len(reminders)} reminders.")
-    lines = ["Here are your current reminders:"]
-    for r in reminders:
-        rid = r['reminder_id']
-        text = r['reminder_text']
-        due_utc = r['due_time_utc']
-        lines.append(f"• Reminder #{rid}: due {due_utc}, text: '{text}'")
-    return "\n".join(lines)
+    # 1) Get the pending
+    pending_reminders = db_utils.get_pending_reminders_for_user(REMINDERS_DB_PATH, user_id)
+    if pending_reminders:
+        lines = ["<b>Your current (pending) reminders:</b>"]
+        for idx, r in enumerate(pending_reminders, start=1):
+            rid = r['reminder_id']
+            text = r['reminder_text']
+            due_utc = r['due_time_utc']
+            lines.append(f"• Reminder #{idx} (ID {rid}) due <i>{due_utc}</i>\n   “{text}”")
+        pending_section = "\n".join(lines)
+    else:
+        pending_section = "You have no <b>pending</b> reminders."
+
+    # 2) Optionally get the past ones
+    if SHOW_PAST_REMINDERS_COUNT > 0:
+        past = get_past_reminders_for_user(REMINDERS_DB_PATH, user_id, SHOW_PAST_REMINDERS_COUNT)
+        if past:
+            lines = [f"<b>Up to {SHOW_PAST_REMINDERS_COUNT} most recent past reminders:</b>"]
+            for idx, r in enumerate(past, start=1):
+                rid = r['reminder_id']
+                text = r['reminder_text']
+                due_utc = r['due_time_utc']
+                status = r['status']
+                lines.append(f"• (ID {rid}) was <i>{status}</i> at {due_utc}, text: “{text}”")
+            past_section = "\n".join(lines)
+        else:
+            past_section = "(No past reminders found.)"
+    else:
+        past_section = ""  # or omit entirely
+
+    # 3) Combine them for your final message
+    full_msg = f"{pending_section}\n\n{past_section}".strip()
+    return full_msg
+
+    # // old logic; no past reminders
+    # reminders = db_utils.get_pending_reminders_for_user(REMINDERS_DB_PATH, user_id)
+    # if not reminders:
+    #     logger.info(f"User {user_id} has no pending reminders.")
+    #     return "You currently have no pending reminders."
+
+    # logger.info(f"User {user_id} is viewing {len(reminders)} reminders.")
+    # lines = ["Here are your current reminders:"]
+    # for r in reminders:
+    #     rid = r['reminder_id']
+    #     text = r['reminder_text']
+    #     due_utc = r['due_time_utc']
+    #     lines.append(f"• Reminder #{rid}: due {due_utc}, text: '{text}'")
+    # return "\n".join(lines)
 
 
 async def handle_delete_reminder(user_id, reminder_id):

src/text_message_handler.py

@@ -1154,8 +1154,18 @@ async def handle_message(bot, update: Update, context: CallbackContext, logger)
                                 chat_history.append({"role": "system", "content": result_msg})
 
                         elif action == 'view':
-                            result_msg = await handle_view_reminders(user_id)
-                            chat_history.append({"role": "system", "content": result_msg})
+                            raw_result = await handle_view_reminders(user_id)
+                            prefix = (
+                                "Here are the user's alerts. Use the user's language when replying and Telegram-compliant "
+                                "HTML tags instead of Markdown! List the reminders without their database id #'s to the user, "
+                                "since the numbers are only for database reference [i.e. to delete/edit, etc]). "
+                                "If the user wasn't asking about past reminders, don't list them. KÄYTÄ VASTAUKSESSA HTML:ÄÄ. ÄLÄ KÄYTÄ MARKDOWNIA.\n\n"
+                            )
+                            final_result = prefix + raw_result
+
+                            # Now store that prefixed message in the chat history
+                            chat_history.append({"role": "system", "content": final_result})
+                            context.chat_data['chat_history'] = chat_history
 
                         elif action == 'delete':
                             if not reminder_id:
@@ -1186,6 +1196,10 @@ async def handle_message(bot, update: Update, context: CallbackContext, logger)
                         final_reply_content = response_json['choices'][0]['message'].get('content', '')
                         final_reply = final_reply_content.strip() if final_reply_content else ""
 
+                        if not final_reply:
+                            # Provide a fallback message to avoid sending an empty string
+                            final_reply = "🤔"
+
                         # log & send
                         bot.log_message(
                             message_type='Bot',