dashboard.py

#how to run
#writefile will create the file
#we cannot see pylance nor autocompletions when using %%writefile
#conda activate py313
#cd /d D:\OneDrive\Documents\Jupyter_Notebooks\polymarket
#streamlit run dashboard.py
#Libraries & imports used
#System and related
import sys;import inspect;import warnings;import functools;import time;import os;import json;import sqlite3;import datetime;import math
#Data & Data Types
import pandas;import requests;import threading
#Visualization & App
import streamlit;import plotly.express
from streamlit_autorefresh import st_autorefresh

#Global variables
IsExceptionRaised=False

# Decorator definition
def Exec_Decorator_GeneralChecks(TxtVersion:str="1.0",IsLogTimeNeeded:bool=False,TxtNameAuthor:str="Sgdva",TxtNameContributors:str="Sgdva"):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Checks for the general functions considered for a python and appends the version of it.

    :extrainfo:

    Only way to know what is considered general, go to this function and read the methods of it. So far we got:
    1. Set the version of said function.
    2. Execution timing for the routine.
    3. Author of function
    4. Contributors/forkers of function

    --------------
    Parameters, Raises & Returns:
    --------------
    :param TxtVersion: The version of the procedure to run.

    :param IsLogTimeNeeded: If we need to log the execution time the routine takes to be performed.

    :param TxtNameAuthor: (Optional) The author of the function.

    :param TxtNameContributors: (Optional) The contributors of the function.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A

    --------------
    # How-To-Use:
    append @Decorator_GeneralChecks before the function itself

    @Exec_Decorator_GeneralChecks(TxtVersion="1.2",IsLogTimeNeeded=True)

    def Exec_CopyFile...

    print(Exec_CopyFile.__version__)

    Exec_CopyFile(TxtToCopyFrom='C:/Users/U1245609/Downloads/Test.txt',TxtLocalPath='C:/Users/U1245609/Downloads/sss/Test.txt')

    print(Exec_CopyFile.execution_time)
    """
    #End: docstring
    global IsExceptionRaised
    def Decorator_Function(TxtRoutineToAnalyze):
        @functools.wraps(TxtRoutineToAnalyze)
        def Decorator_GeneralChecks(*args,**kwargs):
            global IsExceptionRaised
            TxtCallerFunction= TxtRoutineToAnalyze.__name__;IsExceptionRaised=False
            if IsLogTimeNeeded==True: # 1. if IsLogTimeNeeded==True
                NumTimeStart = time.perf_counter()
            try: # 1. try (General try for the function)
                VarResult=TxtRoutineToAnalyze(*args,**kwargs)
                return VarResult
            except Exception as ObjException: # 1. try (General try for the function)
                #Begin: ValueError:[1]
                if IsExceptionRaised==True: # 1. if IsExceptionRaised==True
                    raise
                else: # 1. if IsExceptionRaised==True
                    #TxtExceptionType = type(ObjException).__name__ 
                    #ObjException.__traceback__ = None   
                    #raise ValueError("Err01{}: Unhandled exception. Further Details: Type '{}'. Description: '{}'".format(TxtCallerFunction, TxtExceptionType,str(ObjException)))
                    raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
                #End: ValueError:[1]
            finally: # 1. try (General try for the function)
                if IsLogTimeNeeded==True: # 2. if IsLogTimeNeeded==True
                    Decorator_GeneralChecks.execution_time = round(time.perf_counter() - NumTimeStart,4)
        Decorator_GeneralChecks.__version__ = TxtVersion
        return Decorator_GeneralChecks         
    return Decorator_Function

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
@streamlit.cache_resource
def Return_DictTxtServerCache() -> dict:
    #Begin: docstring
    """Information:
    --------------
    :definitionWID: Returns a cached dictionary object shared across all Streamlit sessions. Used to persist server-level data until restart.

    --------------
    Parameters, Raises & Returns:
    --------------

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Dictionary with keys 'LastFetch' (float timestamp) and 'Data' (list).

    :rtype: dict

    --------------
    # Sample data:
    {"LastFetch": 0.0, "Data": []}

    --------------
    # How-To-Use:
    DictObjCache = Return_DictTxtServerCache()
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        return {
        "LastFetchEpoch": 0.0,
        "Data": [],
        # Precomputed display/notification artifacts so reruns are read-only:
        "Spikes": [],
        "ClosingSoon": [],
        "WatchData": [],
        "SortedData": [],
        "LastFetchISO": "",
        "IsFetching": False,
        "IsForceRefreshRequested": False,
        "LastFetchErr": ""}
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]


@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
@streamlit.cache_resource
def Return_DictObjBackgroundWorker() -> dict:
    #Begin: docstring
    """Information:
    --------------
    :definitionWID: Starts a daemon thread background worker that ensures scheduled refresh/update execution.

    --------------
    Parameters, Raises & Returns:
    --------------

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Dict with StopEvent, Thread object and Lock used for synchronization.

    :rtype: dict

    --------------
    # Sample data:
    N/A

    --------------
    # How-To-Use:
    DictObjWorker = Return_DictObjBackgroundWorker()
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name; IsExceptionRaised = False
    try: # 1. try (General try)
        ObjStopEvent = threading.Event(); ObjLock = threading.Lock()
        DictTxtCache = Return_DictTxtServerCache()
        def Exec_WorkerLoop():
            #Begin: docstring
            """Information:
            --------------
            :definitionWID: Worker loop that handles scheduled refresh/update execution.

            --------------
            Parameters, Raises & Returns:
            --------------

            :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

            :return: None

            :rtype: None

            --------------
            # Sample data:
            N/A

            --------------
            # How-To-Use:
            Exec_WorkerLoop()
            """ 
            #End: docstring
            while not ObjStopEvent.is_set(): # 1. while not ObjStopEvent.is_set
                try: # 1. try (worker cycle)
                    DictTxtConfig = Return_DictTxtConfig()
                    NumUpdateInterval = int(DictTxtConfig.get("NumUpdateInterval", 60))
                    NumFetchLimit = int(DictTxtConfig.get("NumFetchLimit", 100))
                    NumVolThreshold = float(DictTxtConfig.get("NumVolThreshold", 2000.0))
                    ArrTxtWatchlist = DictTxtConfig.get("ArrTxtWatchlist", [])
                    #Returns the warning 2026-01-25 18:29:13.547 Thread 'PolyOddWatcherWorker': missing ScriptRunContext! This warning can be ignored when running in bare mode.
                    #More info @ https://discuss.streamlit.io/t/warning-for-missing-scriptruncontext/83893/18
                    #For the fix we are going to move that call outside the worker loop (and outside the thread), so it runs on the main Streamlit script context only once.
                    #DictTxtCache = Return_DictTxtServerCache()
                    NumIntervalSec = max(1.0, NumUpdateInterval * 60.0)
                    NumNow = time.time(); NumLastFetch = float(DictTxtCache.get("LastFetchEpoch", 0.0))
                    IsNeverFetched = (NumLastFetch <= 0.0)
                    IsForceRefresh = bool(DictTxtCache.get("IsForceRefreshRequested", False))
                    IsTimeUp = IsNeverFetched or ((NumNow - NumLastFetch) >= NumIntervalSec) or (IsForceRefresh == True)
                    if IsForceRefresh == True: DictTxtCache["IsForceRefreshRequested"] = False

                    if IsTimeUp == True: # 1. if IsTimeUp == True
                        with ObjLock: # 1. with ObjLock
                            NumNow2 = time.time(); NumLastFetch2 = float(DictTxtCache.get("LastFetchEpoch", 0.0))
                            IsNeverFetched2 = (NumLastFetch2 <= 0.0); IsTimeUp2 = IsNeverFetched2 or ((NumNow2 - NumLastFetch2) >= NumIntervalSec)

                            if IsTimeUp2 == True: # 2. if IsTimeUp2 == True
                                try: # 2. try (Fetching data from the server)
                                    DictTxtCache["IsFetching"] = True;DictTxtCache["LastFetchErr"] = ""
                                    ArrDictTxtMarkets = Return_ArrDictTxtMarkets_Core(NumFetchLimit=NumFetchLimit,ArrTxtWatchlistIds=ArrTxtWatchlist)
                                    DictTxtCache["Data"] = ArrDictTxtMarkets;DictTxtCache["LastFetchEpoch"] = time.time();DictTxtCache["LastFetchISO"] = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
                                    if ArrDictTxtMarkets: # 3. if ArrDictTxtMarkets
                                        ArrDictTxtSpikes = Return_ArrDictTxtSuddenSpikes(ArrDictTxtCurrentData=ArrDictTxtMarkets,NumThreshold=NumVolThreshold)
                                        ArrDictTxtClosingSoon = Return_ArrDictTxtClosingSoon(ArrDictTxtCurrentData=ArrDictTxtMarkets)
                                        ArrTxtWatchData = [
                                        ItemData for ItemData in ArrDictTxtMarkets
                                        if str(ItemData.get("id")) in ArrTxtWatchlist or ItemData.get("slug") in ArrTxtWatchlist
                                        ]
                                        ArrTxtSortedData = sorted(ArrDictTxtMarkets,key=lambda ItemData: float(ItemData.get("volume", 0)),reverse=True)
                                        DictTxtCache["WatchData"] = ArrTxtWatchData;DictTxtCache["Spikes"] = ArrDictTxtSpikes
                                        DictTxtCache["ClosingSoon"] = ArrDictTxtClosingSoon;DictTxtCache["SortedData"] = ArrTxtSortedData
                                        if DictTxtConfig.get("IsSaveCSV") == True: Exec_SaveToCSV(ArrDictTxtData=ArrDictTxtMarkets)

                                        if DictTxtConfig.get("IsSendTelegramWatchlist") and ArrTxtWatchData: # 4. if DictTxtConfig.get("IsSendTelegramWatchlist") and ArrTxtWatchData
                                            TxtMsg = Return_TxtFormattedMessage("Your Watchlist Updates", ArrTxtWatchData)
                                            Exec_Telegram_SendMsg(TxtBotToken=DictTxtConfig["TxtBotToken"],TxtChatID=DictTxtConfig["TxtChatID"],
                                            TxtMessage=TxtMsg,TxtChatIDThread=DictTxtConfig.get("TxtChatIDThread", ""),IsSendHyperLinks=True)

                                        if DictTxtConfig.get("IsSendTelegramSpikes") and ArrDictTxtSpikes: # 5. if DictTxtConfig.get("IsSendTelegramSpikes") and ArrDictTxtSpikes
                                            TxtMsg = Return_TxtFormattedMessage("Sudden Volume Spikes", ArrDictTxtSpikes)
                                            Exec_Telegram_SendMsg(TxtBotToken=DictTxtConfig["TxtBotToken"],TxtChatID=DictTxtConfig["TxtChatID"],
                                            TxtMessage=TxtMsg,TxtChatIDThread=DictTxtConfig.get("TxtChatIDThread", ""),IsSendHyperLinks=True)

                                        if DictTxtConfig.get("IsSendTelegramClosing") and ArrDictTxtClosingSoon: # 6. if DictTxtConfig.get("IsSendTelegramClosing") and ArrDictTxtClosingSoon
                                            TxtMsg = Return_TxtFormattedMessage("Markets Closing Soon", ArrDictTxtClosingSoon)
                                            Exec_Telegram_SendMsg(TxtBotToken=DictTxtConfig["TxtBotToken"],TxtChatID=DictTxtConfig["TxtChatID"],
                                            TxtMessage=TxtMsg,TxtChatIDThread=DictTxtConfig.get("TxtChatIDThread", ""),IsSendHyperLinks=True)

                                        if DictTxtConfig.get("IsSendTelegramFeed") and ArrTxtSortedData: # 7. if DictTxtConfig.get("IsSendTelegramFeed") and ArrTxtSortedData
                                            TxtMsg = Return_TxtFormattedMessage("Top Market Feed", ArrTxtSortedData)
                                            Exec_Telegram_SendMsg(TxtBotToken=DictTxtConfig["TxtBotToken"],TxtChatID=DictTxtConfig["TxtChatID"],
                                            TxtMessage=TxtMsg,TxtChatIDThread=DictTxtConfig.get("TxtChatIDThread", ""),IsSendHyperLinks=True)
                                except Exception as ObjException: # 2. try (Fetching data from the server)
                                    DictTxtCache["LastFetchErr"] = str(ObjException)
                                finally: # 2. try (Fetching data from the server)
                                    DictTxtCache["IsFetching"] = False

                    for _ in range(30):
                        if ObjStopEvent.is_set(): break
                        if bool(DictTxtCache.get("IsForceRefreshRequested", False)) == True: break
                        time.sleep(1)
                except Exception: # 1. try (worker cycle)
                    time.sleep(5)

        ObjThread = threading.Thread(target=Exec_WorkerLoop, name="PolyOddWatcherWorker", daemon=True)
        ObjThread.start()
        return {"StopEvent": ObjStopEvent, "Thread": ObjThread, "Lock": ObjLock}

    except Exception as ObjException: # 1. try (General try)
        if IsExceptionRaised == True: # 99. if IsExceptionRaised == True
            raise
        else: # 99. if IsExceptionRaised == True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction, str(ObjException)))


@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_NumPruneDB(NumDaysToKeep:int=30) -> int:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Deletes records older than NumDaysToKeep.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param NumDaysToKeep: The number of days to keep records for.

    :raises ValueError:[1] If an unhandled exception occurs. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Number of records deleted.

    :rtype: int

    --------------
    # Sample data:
    N/A.

    --------------
    # How-To-Use:
    NumDeleted=Return_NumPruneDB(NumDaysToKeep=30)
    """
    #End: docstring
    global IsExceptionRaised
    try:
        ObjConn = sqlite3.connect("market_history.db")
        ObjCursor = ObjConn.cursor()
        # Calculate Threshold Date
        ObjThresholdDate = datetime.datetime.now() - datetime.timedelta(days=NumDaysToKeep)
        TxtThresholdIso = ObjThresholdDate.isoformat()
        # Execute Delete
        ObjCursor.execute("DELETE FROM vol_history WHERE last_updated < ?", (TxtThresholdIso,))
        NumDeleted = ObjCursor.rowcount
        ObjConn.commit(); ObjCursor.close(); ObjConn.close()
        return NumDeleted
    except Exception as e:
        if IsExceptionRaised: raise
        else: raise ValueError(f"Prune DB Failed: {e}")

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_SaveToCSV(ArrDictTxtData:list,TxtFilename:str="market_data_log.csv"):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Appends the current market data snapshot to a CSV log file for future analysis. 
    Adds a timestamp to every row to allow time-series analysis.
    :note: FLATTENS the data structure. Instead of dumping raw JSON, it extracts specific Market/Outcome rows for easier analysis in Excel/AI.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ArrDictTxtData: The list of dictionaries containing current market events.

    :param TxtFilename: The name of the CSV file to save the data to.

    :raises ValueError:[1] If an unhandled exception occurs. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A

    --------------
    # How-To-Use:
    Exec_SaveToCSV(ArrDictTxtData=ArrDictTxtData)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try)
        if not ArrDictTxtData: # 1. if No Data
            return
        ArrDictTxtCleanRows = []
        TxtTimestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        for ItemDictEvent in ArrDictTxtData: # 1. for ItemDictEvent
            # Extract Top-Level Event Data
            TxtEventTitle = ItemDictEvent.get('title', '')
            TxtEventID = str(ItemDictEvent.get('id', ''))

            # The 'markets' key contains the actual betting options. We must loop through them.
            ArrDictMarkets = ItemDictEvent.get('markets', [])

            for ItemDictMarket in ArrDictMarkets: # 2. for ItemDictMarket
                # Extract Specific Market Data
                TxtGroupTitle = ItemDictMarket.get('groupItemTitle', '') # Used in grouped markets (e.g. "January", "February")
                TxtQuestion = ItemDictMarket.get('question', '')

                # If GroupTitle exists, append it to Title for clarity (e.g. "Trump Deportation - <250k")
                if TxtGroupTitle and str(TxtGroupTitle).strip() != "": # 2. if TxtGroupTitle
                    TxtFullTitle = "{} - {}".format(TxtEventTitle, TxtGroupTitle)
                else: # 2. else
                    TxtFullTitle = TxtEventTitle

                # Parse Prices safely
                try: # 2. try (Parse Odds)
                    ArrTxtOutcomes = json.loads(ItemDictMarket.get('outcomes', '[]'))
                    ArrNumPrices = json.loads(ItemDictMarket.get('outcomePrices', '[]'))
                except: # 2. except (Parse Odds)
                    ArrTxtOutcomes = []; ArrNumPrices = []

                # Create a serialized string for easy AI parsing later: "Yes:0.55|No:0.45"
                ArrTxtOddsSummary = []
                for NumIndex in range(len(ArrTxtOutcomes)): # 3. for NumIndex
                    if NumIndex < len(ArrNumPrices): # 3. if valid index
                        ArrTxtOddsSummary.append("{}:{}".format(ArrTxtOutcomes[NumIndex], ArrNumPrices[NumIndex]))
                TxtOddsStr = "|".join(ArrTxtOddsSummary)

                # Build the Clean Row
                DictCleanRow = {
                    "LogTimestamp": TxtTimestamp,
                    "EventID": TxtEventID,
                    "MarketID": str(ItemDictMarket.get('id', '')),
                    "FullTitle": TxtFullTitle,
                    "RawQuestion": TxtQuestion,
                    "Volume": float(ItemDictMarket.get('volume', 0)),
                    "Liquidity": float(ItemDictMarket.get('liquidity', 0)),
                    "OddsSummary": TxtOddsStr,
                    "BestAsk": float(ItemDictMarket.get('bestAsk', 0)),
                    "BestBid": float(ItemDictMarket.get('bestBid', 0)),
                    "EndDate": ItemDictMarket.get('endDate', ''),
                    "URL": "https://polymarket.com/event/" + str(ItemDictEvent.get('slug', ''))
                }
                ArrDictTxtCleanRows.append(DictCleanRow)

        # Create DataFrame from the CLEAN rows
        if ArrDictTxtCleanRows: # 4. if ArrDictTxtCleanRows
            dfLog = pandas.DataFrame(ArrDictTxtCleanRows)

            # Check if file exists to write header
            IsHeaderNeeded = not os.path.exists(TxtFilename)

            # Append to CSV (mode='a') used to add new data to the end of an existing CSV file without overwriting its current conten
            dfLog.to_csv(TxtFilename, mode='a', header=IsHeaderNeeded, index=False)

    except Exception as ObjException: # 1. try (General try)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

# --- COMMUNICATION FUNCTIONS ---

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_Telegram_SendMsg(TxtBotToken:str,TxtChatID:str,TxtMessage:str,TxtChatIDThread:str="",IsSendHyperLinks:bool=False):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Sends a telegram message to the specified TxtChatID with the TxtBotToken given.

    :links:
    For more information, refer to the Telegram Bot API documentation: 
    - [Telegram Bot API](https://core.telegram.org/bots/api#sendmessage)
    --------------
    Parameters, Raises & Returns:
    --------------
    :param TxtBotToken: The token given by botfather for the bot, the format is like xxxx:xxxx.

    :param TxtChatID: The chat id the bot will be interacting to, to identify it, begin a chat with the bot, access to the url (IE: https://api.telegram.org/botxxx:xxxx/) to see the updates requested and detect the chatID.

    :param TxtMessage: it needs to be a text greater than 0 and less or equal to 4096 characters.

    :param TxtChatIDThread: (Optional) If there is a specific thread the bot should send the message to, it will be specified here.

    :param IsSendHyperLinks: (Optional) If the message should include hyperlinks, it will be specified here.

    :param VarVerify: It can be either a boolean to turn on/off SSL verification, or can be the path to the pem certificate file. - [Requests documents](https://requests.readthedocs.io/en/latest/user/advanced/)

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :raises ValueError:[2] If the length of TxtMessage is less than 1 or greater than 4096 characters.

    :raises ValueError:[3,4] If VarVerify is neither a bool or a valid string path.

    :raises requests.exceptions.RequestException:[1] If telegram request had an error code.

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A

    --------------
    # How-To-Use:

    Exec_Telegram_SendMsg(TxtBotToken="xxx:xxx",TxtChatID=-40965627,TxtMessage="Test")
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try
        if len(TxtMessage)<1: raise ValueError("Empty Message")
        TxtUrl = f'https://api.telegram.org/bot{TxtBotToken}/sendMessage'
        DictTxtData = {'chat_id': TxtChatID,'text': TxtMessage}
        if IsSendHyperLinks==True: # 1. if IsSendHyperLinks==True
            DictTxtData['parse_mode'] = 'HTML';DictTxtData['disable_web_page_preview'] = True
        if TxtChatIDThread and str(TxtChatIDThread).strip() != "": # 2. if TxtChatIDThread and str(TxtChatIDThread).strip() != ""
            DictTxtData['message_thread_id'] = TxtChatIDThread        
        ObjResponse = requests.post(url=TxtUrl, data=DictTxtData)
        JSONResponse = ObjResponse.json()
        if JSONResponse.get("ok") == False:  # 3. if JSONResponse.get("ok") == False
            IsExceptionRaised=True;raise requests.exceptions.RequestException(f"Telegram Error: {JSONResponse.get('description')}") 
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

# --- DATABASE & CONFIG FUNCTIONS ---

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_InitDB(TxtDBPath:str="market_history.db"):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Initializes the SQLite database to store market history. Checks for table existence and attempts schema migration if necessary.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param TxtDBPath: (Optional) Path to the SQLite database file. Default is "market_history.db".

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Exec_InitDB()
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        ObjConn = sqlite3.connect(TxtDBPath)
        ObjCursor = ObjConn.cursor()
        ObjCursor.execute('''
            CREATE TABLE IF NOT EXISTS vol_history (
                market_id TEXT PRIMARY KEY,
                title TEXT,
                last_volume REAL,
                last_odds TEXT,
                last_updated TEXT
            )
        ''')
        try: ObjCursor.execute("ALTER TABLE vol_history ADD COLUMN last_odds TEXT")
        except: pass
        ObjConn.commit(); ObjCursor.close(); ObjConn.close()
    except Exception as ObjException: # 1. try (General try for the function) 
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True    
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction, str(ObjException)))
        #End: ValueError:[1]  

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_DictTxtConfig() -> dict:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Loads configuration from JSON file 'config.json'. Returns empty dict if not found or error.

    --------------
    Parameters, Raises & Returns:
    --------------

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Dictionary containing configuration.

    :rtype: dict

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    DictConfig = Return_DictTxtConfig()
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        if os.path.exists("config.json"): # 1. if os.path.exists("config.json")
            with open("config.json", "r") as ObjFile:
                return json.load(ObjFile)
        return {}
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_SaveConfig(DictConfig:dict):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Saves the configuration dictionary to 'config.json'.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param DictConfig: The dictionary containing configuration settings.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Exec_SaveConfig(DictConfig=DictConfig)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        with open("config.json", "w") as ObjFile: # 1. with open("config.json", "w") as ObjFile
            json.dump(DictConfig, ObjFile)
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

# --- HELPER FUNCTIONS (FORMATTING) ---

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_TxtHumanVolume(NumVolume:float) -> str:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Formats numbers to K/M/B.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param NumVolume: The volume to format.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: The formatted volume.

    :rtype: str

    --------------
    # Sample data:
    NumVolume=1000000

    --------------
    # How-To-Use:
    TxtHumanVolume=Return_TxtHumanVolume(NumVolume=NumVolume)
    Expected: '1M'
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        if NumVolume >= 1_000_000_000: # 1. if NumVolume >= 1B
            return "${:.2f}B".format(NumVolume/1_000_000_000)
        elif NumVolume >= 1_000_000: # 1. if NumVolume >= 1B
            return "${:.2f}M".format(NumVolume/1_000_000)
        elif NumVolume >= 1_000: # 1. if NumVolume >= 1B
            return "${:.0f}K".format(NumVolume/1_000)
        else: # 1. if NumVolume >= 1B
            return "${:.0f}".format(NumVolume)
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_TxtMultiOutcomeOdds(ItemEvent:dict, TxtPrevOdds:str="") -> str:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Returns Full Odds Breakdown sorted by chance with Delta Trends. Calculates trends if previous odds are provided.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ItemEvent: The event dictionary containing market data.

    :param TxtPrevOdds: (Optional) String representing previous odds (format: "Name:Price|Name:Price") for trend calculation.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Formatted string with odds and trends.

    :rtype: str

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    TxtMultiOutcomeOdds=Return_TxtMultiOutcomeOdds(ItemEvent=ItemEvent,TxtPrevOdds=TxtPrevOdds)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        ArrDictTxtMarkets = ItemEvent.get('markets', [])
        ArrTxtCandidates = []

        # Parse Previous Odds
        DictTxtPrevOdds = {}
        if str(TxtPrevOdds).strip() != "": # 1. if str(TxtPrevOdds).strip() != ""
            try: # 2. try (Parse history)
                ArrTxtParts = TxtPrevOdds.split("|")
                for ItemTxtPart in ArrTxtParts: # 1. for TxtPart in ArrTxtParts
                    TxtKey, TxtVal = ItemTxtPart.split(":")
                    DictTxtPrevOdds[TxtKey] = float(TxtVal)
            except: # 2. try (Parse history)
                pass

        # Logic A: Multiple Markets (Grouped)
        for ItemMarket in ArrDictTxtMarkets: # 2. for ItemMarket in ArrDictTxtMarkets
            if ItemMarket.get('closed') == True: # 2. if ItemMarket.get('closed') == True
                continue 

            TxtGroupTitle = ItemMarket.get('groupItemTitle', '')
            try: # 3. try (Parse prices and outcomes)
                ArrNumPrices = json.loads(ItemMarket.get('outcomePrices', '["0","0"]'))
                ArrTxtOutcomes = json.loads(ItemMarket.get('outcomes', '["Yes","No"]'))
            except: # 3. try (Parse prices and outcomes)
                ArrNumPrices = ["0", "0"]; ArrTxtOutcomes = ["Yes", "No"]

            TxtName = ""; NumPrice = 0.0

            if TxtGroupTitle and len(ArrNumPrices) >= 1: # 3. if TxtGroupTitle and len(ArrNumPrices) >= 1
                TxtName = TxtGroupTitle
                NumPrice = float(ArrNumPrices[0]) 
            elif len(ArrTxtOutcomes) > 2: # 3. if TxtGroupTitle and len(ArrNumPrices) >= 1
                for CounterArrTxtOutcomes in range(len(ArrTxtOutcomes)): # 3. for CounterArrTxtOutcomes in range(len(ArrTxtOutcomes))
                    ArrTxtCandidates.append({"Name": ArrTxtOutcomes[CounterArrTxtOutcomes], "Price": float(ArrNumPrices[CounterArrTxtOutcomes])})
                continue 
            elif len(ArrTxtOutcomes) == 2 and not TxtGroupTitle: # 3. if TxtGroupTitle and len(ArrNumPrices) >= 1
                 TxtName = "Yes"; NumPrice = float(ArrNumPrices[0])

            if TxtName: # 4. if TxtName
                ArrTxtCandidates.append({"Name": TxtName, "Price": NumPrice})

        # Sort by Price Descending
        ArrTxtCandidates = sorted(ArrTxtCandidates, key=lambda ItemCandidate: ItemCandidate['Price'], reverse=True)

        # Build Rich String
        ArrTxtFormatted = []
        for ItemCandidate in ArrTxtCandidates: # 4. for ItemCandidate in ArrTxtCandidates
            NumYes = ItemCandidate['Price']; NumNo = 1.0 - NumYes

            # Trend Calculation
            TxtTrend = "(➖)"
            if ItemCandidate['Name'] in DictTxtPrevOdds: # 5. if History
                NumPrev = DictTxtPrevOdds[ItemCandidate['Name']]
                NumDiff = NumYes - NumPrev
                if abs(NumDiff) >= 0.005: # 6. if abs(NumDiff) >= 0.005
                    if NumDiff > 0: # 7. if NumDiff > 0
                        TxtTrend = "🔼{:.0%}".format(abs(NumDiff))
                    else: # 8. if NumDiff > 0
                        TxtTrend = "🔽{:.0%}".format(abs(NumDiff))

            # Format: ▶Name 🟢Yes X% 🔴No Y% Trend
            TxtStr = "▶{}: 🟢Yes {:.0%} 🔴No {:.0%} {}".format(ItemCandidate['Name'], NumYes, NumNo, TxtTrend)
            ArrTxtFormatted.append(TxtStr)

        if not ArrTxtFormatted: # 9. if not ArrTxtFormatted
            return "No active odds"
        return " | ".join(ArrTxtFormatted)

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_TxtOddsForDB(ItemMarket:dict) -> str:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Serializes market odds into a string format for database storage.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ItemMarket: The market dictionary containing odds data.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: A serialized string of odds (e.g., "Yes:0.5|No:0.5").

    :rtype: str

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    TxtOddsForDB = Return_TxtOddsForDB(ItemMarket)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        ArrDictTxtMarkets = ItemMarket.get('markets', [])
        ArrTxtSerialized = []
        for ItemSubMarket in ArrDictTxtMarkets: # 1. for ItemSubMarket in ArrDictTxtMarkets
            if ItemSubMarket.get('closed') == True: # 1. if ItemSubMarket.get('closed') == True
                continue

            TxtGroupTitle = ItemSubMarket.get('groupItemTitle', '')
            try: # 2. try (Safe JSON load)
                 ArrNumPrices = json.loads(ItemSubMarket.get('outcomePrices', '["0","0"]'))
            except: # 2. try (Safe JSON load)
                 ArrNumPrices = ["0", "0"]

            if TxtGroupTitle and len(ArrNumPrices) >= 1: # 2. if TxtGroupTitle and len(ArrNumPrices) >= 1
                ArrTxtSerialized.append("{}:{}".format(TxtGroupTitle, ArrNumPrices[0]))
            elif not TxtGroupTitle: # 2. if TxtGroupTitle and len(ArrNumPrices) >= 1
                 try: # 3. try (Safe JSON load)
                     ArrTxtOutcomes = json.loads(ItemSubMarket.get('outcomes', '["Yes","No"]'))
                 except: # 3. try (Safe JSON load)
                     ArrTxtOutcomes = ["Yes", "No"]

                 for CounterArrTxtOutcomes in range(len(ArrTxtOutcomes)): # 2. for CounterArrTxtOutcomes in range(len(ArrTxtOutcomes))
                      if CounterArrTxtOutcomes < len(ArrNumPrices): # 3. if CounterArrTxtOutcomes < len(ArrNumPrices)
                          ArrTxtSerialized.append("{}:{}".format(ArrTxtOutcomes[CounterArrTxtOutcomes], ArrNumPrices[CounterArrTxtOutcomes]))
        return "|".join(ArrTxtSerialized)
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

# --- CORE LOGIC FUNCTIONS ---
@streamlit.cache_data(ttl=60)
@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_ArrDictTxtMarkets(NumFetchLimit:int=100, ArrTxtWatchlistIds:list=[]) -> list:
    return Return_ArrDictTxtMarkets_Core(NumFetchLimit=NumFetchLimit, ArrTxtWatchlistIds=ArrTxtWatchlistIds)


def Return_ArrDictTxtMarkets_Core(NumFetchLimit:int=100, ArrTxtWatchlistIds:list=[]) -> list:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Fetches active market events via pagination and specific watchlist lookup.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param NumFetchLimit: Limit for the broad fetch of active markets.
    :param ArrTxtWatchlistIds: List of IDs or Slugs to specifically hunt for.

    :raises ValueError:[1] If an unhandled exception occurs during execution.

    :return: A list of unique market event dictionaries.

    :rtype: list

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Return_ArrDictTxtMarkets_Core = Return_ArrDictTxtMarkets_Core()
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    ArrJSONCombinedData = []

    try: # 1. try (General try for the function)
        # 1. Paginated Broad Fetch
        NumOffset = 0; NumBatchSize = 100 
        while len(ArrJSONCombinedData) < NumFetchLimit: # 1. while len(ArrJSONCombinedData) < NumFetchLimit
            try: # 2. try (Fetch batch)
                TxtBaseUrl = "https://gamma-api.polymarket.com/events?limit={}&active=true&closed=false&offset={}".format(NumBatchSize, NumOffset)
                ObjResponse = requests.get(TxtBaseUrl)
                ObjResponse.raise_for_status()
                ArrJSONBatch = ObjResponse.json()
                if not ArrJSONBatch: # 1. if not ArrJSONBatch
                    break 
                ArrJSONCombinedData.extend(ArrJSONBatch)
                NumOffset += NumBatchSize
                if len(ArrJSONCombinedData) >= NumFetchLimit: # 2. if len(ArrJSONCombinedData) >= NumFetchLimit
                    ArrJSONCombinedData = ArrJSONCombinedData[:NumFetchLimit];break
                time.sleep(0.05) 
            except Exception: # 2. try (Fetch batch)
                break

        # 2. Hunt for Missing Watchlist Items
        if len(ArrTxtWatchlistIds) > 0: # 3. if len(ArrTxtWatchlistIds) > 0
            for TxtWatchId in ArrTxtWatchlistIds: # 1. for TxtWatchId in ArrTxtWatchlistIds
                if len(TxtWatchId.strip()) > 0: # 4. if len(TxtWatchId.strip()) > 0
                    try: # 3. try (Fetch watchlist item)
                        TxtTarget = TxtWatchId.strip()
                        # Check if already present in broadly fetched data
                        IsAlreadyFound = any(str(ItemData.get('id')) == TxtTarget or ItemData.get('slug') == TxtTarget for ItemData in ArrJSONCombinedData)

                        if not IsAlreadyFound: # 5. if not IsAlreadyFound
                            # Try fetching by Slug first
                            TxtWatchUrl = "https://gamma-api.polymarket.com/events?slug={}".format(TxtTarget)
                            ObjWatchResponse = requests.get(TxtWatchUrl)

                            if ObjWatchResponse.status_code == 200: # 6. if ObjWatchResponse.status_code == 200
                                ArrJSONResult = ObjWatchResponse.json()
                                if isinstance(ArrJSONResult, list): # 7. if isinstance(ArrJSONResult, list)
                                    ArrJSONCombinedData.extend(ArrJSONResult)
                                else: # 7. if isinstance(ArrJSONResult, list)
                                    ArrJSONCombinedData.append(ArrJSONResult)
                            else: # 6. if ObjWatchResponse.status_code == 200
                                # Fallback: Try fetching by ID
                                TxtDirectUrl = "https://gamma-api.polymarket.com/events/{}".format(TxtTarget)
                                ObjDirectRes = requests.get(TxtDirectUrl)
                                if ObjDirectRes.status_code == 200: # 8. if ObjDirectRes.status_code == 200
                                    ArrJSONCombinedData.append(ObjDirectRes.json())
                    except: # 3. try (Fetch watchlist item)
                        pass 

        # Remove duplicates based on ID
        DictTxtUniqueRecords = {ItemData['id']: ItemData for ItemData in ArrJSONCombinedData if 'id' in ItemData}
        return list(DictTxtUniqueRecords.values())

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            return [] # Specific return for this function as per user code logic
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_ArrDictTxtSuddenSpikes(ArrDictTxtCurrentData:list, NumThreshold:float=2000.0) -> list:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Returns a list of sudden spikes based on volume.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ArrDictTxtCurrentData: List of current market data.

    :param NumThreshold: Threshold for volume.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: A list of unique market event dictionaries.

    :rtype: list

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    ArrDictTxtSuddenSpikes = Return_ArrDictTxtSuddenSpikes(ArrDictTxtCurrentData=ArrDictTxtCurrentData)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    ArrDictTxtSpikesFound = []
    try: # 1. try (General try for the function)
        ObjConn = sqlite3.connect("market_history.db")
        ObjCursor = ObjConn.cursor()
        TxtIsoNow = datetime.datetime.now().isoformat()

        for ItemEvent in ArrDictTxtCurrentData: # 1. for ItemEvent in ArrDictTxtCurrentData
            if ItemEvent.get('markets'): # 1. if ItemEvent.get('markets')
                TxtEventID = str(ItemEvent['id']); TxtTitle = ItemEvent['title']
                NumCurrentVol = float(ItemEvent.get('volume', 0))
                TxtCurrentOdds = Return_TxtOddsForDB(ItemEvent)

                ObjCursor.execute("SELECT last_volume, last_odds FROM vol_history WHERE market_id = ?", (TxtEventID,))
                VarResult = ObjCursor.fetchone()

                if VarResult: # 2. if VarResult
                    NumPrevVol = VarResult[0]
                    TxtPrevOdds = VarResult[1]
                    NumDiff = NumCurrentVol - NumPrevVol

                    if NumDiff >= NumThreshold: # 3. if NumDiff >= NumThreshold
                        # Store RAW Numbers in temporary keys for sorting
                        ArrDictTxtSpikesFound.append({
                            "Title": TxtTitle, 
                            "_NumDiff": NumDiff, 
                            "_NumVol": NumCurrentVol,
                            "Odds Breakdown": Return_TxtMultiOutcomeOdds(ItemEvent=ItemEvent, TxtPrevOdds=TxtPrevOdds),
                            "End Date": ItemEvent.get('endDate', 'N/A'),
                            "URL": "https://polymarket.com/event/" + ItemEvent['slug']
                        })

                # Upsert Logic
                ObjCursor.execute('''
                    INSERT INTO vol_history (market_id, title, last_volume, last_odds, last_updated) 
                    VALUES (?, ?, ?, ?, ?) 
                    ON CONFLICT(market_id) DO UPDATE SET 
                    last_volume=excluded.last_volume, last_odds=excluded.last_odds, last_updated=excluded.last_updated
                ''', (TxtEventID, TxtTitle, NumCurrentVol, TxtCurrentOdds, TxtIsoNow))

        ObjConn.commit(); ObjCursor.close(); ObjConn.close()

        # 3. Sort by RAW Numeric Difference (Highest First)
        ArrDictTxtSpikesFound = sorted(ArrDictTxtSpikesFound, key=lambda ItemSpike: ItemSpike['_NumDiff'], reverse=True)

        # 4. Format for Display (Convert numbers to Strings)
        for ItemSpike in ArrDictTxtSpikesFound: # 2. for ItemSpike in ArrDictTxtSpikesFound
            ItemSpike["Spike Amount"] = Return_TxtHumanVolume(NumVolume=ItemSpike.pop("_NumDiff"))
            ItemSpike["Current Volume"] = Return_TxtHumanVolume(NumVolume=ItemSpike.pop("_NumVol"))
        return ArrDictTxtSpikesFound
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1] 

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_ArrDictTxtClosingSoon(ArrDictTxtCurrentData:list) -> list:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Filters market events that are closing within the next 48 hours.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ArrDictTxtCurrentData: List of current market event dictionaries.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: List of dictionaries representing markets closing soon.

    :rtype: list

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Return_ArrDictTxtClosingSoon = ArrDictTxtClosingSoon(ArrDictTxtCurrentData=ArrDictTxtCurrentData)

    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    ArrDictTxtClosingFound = []
    try: # 1. try (General try for the function)
        ObjTimeNow = datetime.datetime.now(datetime.timezone.utc)

        for ItemEvent in ArrDictTxtCurrentData: # 1. for ItemEvent in ArrDictTxtCurrentData
            if ItemEvent.get('endDate'): # 1. if ItemEvent.get('endDate')
                try: # 2. try (Date parsing)
                    TxtEndDate = ItemEvent['endDate'].replace("Z", "+00:00")
                    ObjEndDate = datetime.datetime.fromisoformat(TxtEndDate)

                    # Calculate difference in hours
                    NumHoursLeft = (ObjEndDate - ObjTimeNow).total_seconds() / 3600

                    if 0 < NumHoursLeft <= 48: # 2. if 0 < NumHoursLeft <= 48
                         ArrDictTxtClosingFound.append({
                            "Title": ItemEvent['title'],
                            "Hours Left": round(NumHoursLeft, 1),
                            "End Date": ItemEvent['endDate'],
                            "Volume": Return_TxtHumanVolume(NumVolume=float(ItemEvent.get('volume', 0))),
                            "URL": "https://polymarket.com/event/" + ItemEvent['slug']
                        })
                except: # 2. try (Date parsing)
                    # Skip invalid dates silently as per logic
                    pass

        return ArrDictTxtClosingFound

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise 
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_DictTxtHistoryOdds(ArrQueryMarketIDs:list) -> dict:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Returns a dictionary of market history odds.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param ArrQueryMarketIDs: List of market IDs.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: Dictionary of market history odds.

    :rtype: dict

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    DictTxtHistoryOdds = Return_DictTxtHistoryOdds(ArrQueryMarketIDs=ArrQueryMarketIDs)

    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        DictTxtHistoryOdds = {}

        if not ArrQueryMarketIDs: # 1. if not ArrQueryMarketIDs
            return {}

        ObjConn = sqlite3.connect("market_history.db")
        ObjCursor = ObjConn.cursor()

        # Optimization: Use batch query instead of loop
        # Safe parameterized query for multiple IDs
        TxtPlaceholders = ','.join('?' * len(ArrQueryMarketIDs))
        TxtQuery = "SELECT market_id, last_odds FROM vol_history WHERE market_id IN ({})".format(TxtPlaceholders)

        ObjCursor.execute(TxtQuery, ArrQueryMarketIDs)
        ArrQueryResults = ObjCursor.fetchall()

        for TxtID, TxtOdds in ArrQueryResults: # 1. for for TxtID, TxtOdds in ArrQueryResults
            DictTxtHistoryOdds[str(TxtID)] = TxtOdds

        ObjCursor.close();ObjConn.close()
        return DictTxtHistoryOdds
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise 
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

# --- UI FUNCTIONS ---

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_RenderWelcomeWizard(DictCurrentConfig:dict={}):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Renders the configuration setup wizard using Streamlit. Allows users to configure API tokens, chat IDs, and monitoring preferences.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param DictCurrentConfig: (Optional) Dictionary containing current configuration settings. Defaults to empty dict.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Exec_RenderWelcomeWizard(DictCurrentConfig=ArrDictTxtCurrentData)

    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        streamlit.header("🧙‍♂️ PolyOddWatcher Configuration")

        # Load Defaults
        NumDefFetch = int(DictCurrentConfig.get("NumFetchLimit", 500))
        NumDefDisplay = int(DictCurrentConfig.get("NumDisplayLimit", 20))
        TxtDefToken = DictCurrentConfig.get("TxtBotToken", "")
        TxtDefChat = DictCurrentConfig.get("TxtChatID", "")
        TxtDefThread = DictCurrentConfig.get("TxtChatIDThread", "") 
        NumDefInterval = int(DictCurrentConfig.get("NumUpdateInterval", 60))
        NumDefVolThreshold = float(DictCurrentConfig.get("NumVolThreshold", 2000.0))

        IsDefClose = DictCurrentConfig.get("IsFilterClosingSoon", True)
        IsDefHigh = DictCurrentConfig.get("IsFilterHighBets", True)
        IsDefCSV = DictCurrentConfig.get("IsSaveCSV", False)
        IsDefTeleSpikes = DictCurrentConfig.get("IsSendTelegramSpikes", True)
        IsDefTeleClosing = DictCurrentConfig.get("IsSendTelegramClosing", True)
        IsDefTeleFeed = DictCurrentConfig.get("IsSendTelegramFeed", True)
        IsDefTeleWatchlist = DictCurrentConfig.get("IsSendTelegramWatchlist", True) # New Default

        ArrTxtDefWatchlist = DictCurrentConfig.get("ArrTxtWatchlist", [])
        TxtDefWatchlist = ", ".join(ArrTxtDefWatchlist)

        TxtBotToken = streamlit.text_input("Telegram Bot Token", value=TxtDefToken, type="password", key="In_BotToken")
        TxtChatID = streamlit.text_input("Telegram Chat ID", value=TxtDefChat, type="password", key="In_ChatID")
        TxtChatIDThread = streamlit.text_input("Telegram Thread ID (Optional)", value=TxtDefThread, key="In_ChatIDThread")

        streamlit.subheader("Monitoring Scope")
        NumFetchLimit = streamlit.number_input("Scan Limit (Max Items)", min_value=100, value=NumDefFetch, step=500)

        streamlit.subheader("Dashboard Preferences")
        NumDisplayLimit = streamlit.number_input("Display Limit (Rows)", min_value=5, max_value=200, value=NumDefDisplay)
        NumUpdateInterval = streamlit.number_input("Update Interval (Minutes)", min_value=1, value=NumDefInterval)

        streamlit.markdown("**Manual Watchlist (Max 5):**")
        TxtWatchlistRaw = streamlit.text_area("Watchlist Items (Slug or ID)", value=TxtDefWatchlist, help="Example: will-the-us-invade-mexico-in-2026")

        streamlit.markdown("**Alert Triggers:**")
        NumVolThreshold = streamlit.number_input("Volume Spike Threshold ($)", min_value=100.0, value=float(NumDefVolThreshold), step=100.0)

        # Notification Configs
        ObjCol1, ObjCol2 = streamlit.columns(2)
        with ObjCol1: # 1. with ObjCol1
            streamlit.markdown("##### Dashboard Filters")
            IsFilterClosingSoon = streamlit.checkbox("Show: Closing Soon (48h)", value=IsDefClose)
            IsFilterHighBets = streamlit.checkbox("Show: Sudden Volume Spikes", value=IsDefHigh)
            streamlit.markdown("##### Data Logging")
            IsSaveCSV = streamlit.checkbox("💾 Save History to CSV", value=IsDefCSV, help="Appends all fetched data to market_data_log.csv for future AI analysis.")
        with ObjCol2: # 2. with ObjCol2
            streamlit.markdown("##### Telegram Notifications")
            IsSendTelegramWatchlist = streamlit.checkbox("Send: Your Watchlist", value=IsDefTeleWatchlist)
            IsSendTelegramClosing = streamlit.checkbox("Send: Closing Soon", value=IsDefTeleClosing)
            IsSendTelegramSpikes = streamlit.checkbox("Send: Sudden Volume Spikes", value=IsDefTeleSpikes)            
            IsSendTelegramFeed = streamlit.checkbox("Send: Full Market Feed", value=IsDefTeleFeed)

        # Test Button
        streamlit.divider()
        if streamlit.button("Test Telegram Connection 🤖"): # 5. if streamlit.button
            if str(TxtBotToken)!="" and str(TxtChatID)!="": # 3. if TxtDefToken!="" and TxtDefChat!=""
                try: # 2. try (Test connection)
                    # Note: Exec_Telegram_SendMsg must be defined elsewhere or added subsequently
                    Exec_Telegram_SendMsg(TxtBotToken=str(TxtBotToken),TxtChatID=str(TxtChatID),TxtMessage="✅PolyOddWatcher Test: Connection Successful!",TxtChatIDThread=str(TxtChatIDThread))
                    streamlit.toast("Message Sent!", icon="✅")
                except Exception as ObjException: # 2. try (Test connection)
                    streamlit.error("Failed: {}".format(str(ObjException)))
            else: # 3. if TxtDefToken!="" and TxtDefChat!=""
                streamlit.warning("Please fill in fields and Save Configuration first.")
        # Save Button (Standard button, not form_submit)
        IsSubmit = streamlit.button("Save Configuration 💾")
        if IsSubmit==True: # 1. if IsSubmit==True
            ArrTxtWatchlist = [TxtItem.strip() for TxtItem in TxtWatchlistRaw.split(",") if TxtItem.strip() != ""]
            DictNewConfig = {
            "TxtBotToken": TxtBotToken, "TxtChatID": TxtChatID, "TxtChatIDThread": TxtChatIDThread,
            "NumFetchLimit": NumFetchLimit, "NumDisplayLimit": NumDisplayLimit, "NumUpdateInterval": NumUpdateInterval,
            "NumVolThreshold": NumVolThreshold,
            "IsFilterClosingSoon": IsFilterClosingSoon, "IsFilterHighBets": IsFilterHighBets, "IsSaveCSV": IsSaveCSV,
            "IsSendTelegramWatchlist": IsSendTelegramWatchlist,
            "IsSendTelegramClosing": IsSendTelegramClosing,
            "IsSendTelegramSpikes": IsSendTelegramSpikes,
            "IsSendTelegramFeed": IsSendTelegramFeed,
            "ArrTxtWatchlist": ArrTxtWatchlist, "IsConfigured": True
            }
            Exec_SaveConfig(DictConfig=DictNewConfig)
            if "IsEditing" in streamlit.session_state: # 2. if "IsEditing" in streamlit.session_state
                del streamlit.session_state["IsEditing"]
            streamlit.success("Saved! Loading Dashboard...")
            time.sleep(1);streamlit.rerun()

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Return_TxtFormattedMessage(TxtTitle:str, ArrDictTxtData:list) -> str:
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Formats a list of dictionary data into a clean, markdown-style string for Telegram messages. Limits to top 10 items to respect API limits.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param TxtTitle: The title header for the message (e.g., "Sudden Spikes").

    :param ArrDictTxtData: The list of dictionaries containing event data.

    :raises ValueError:[1] If an unhandled exception occurs during execution.

    :return: A formatted string ready for transmission.

    :rtype: str

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Return_TxtFormattedMessage(TxtTitle=TxtTitle,ArrDictTxtData=ArrDictTxtData)

    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name;IsExceptionRaised=False
    try: # 1. try (General try for the function)
        if not ArrDictTxtData: return ""
        ArrTxtLines = ["🚨 *{}* 🚨".format(TxtTitle)]
        # Limit to top 10 to avoid hitting Telegram message size limits
        for ItemDictEvent in ArrDictTxtData[:10]: # 1. for ItemDictEvent
            # --- A. RESOLVE TITLE & LINK ---
            # Try Processed "Title" -> Raw "title" -> Unknown
            TxtName = ItemDictEvent.get('Title', ItemDictEvent.get('title', 'Unknown'))
            # Escape HTML characters in title to prevent breaking the message
            TxtName = TxtName.replace("<", "&lt;").replace(">", "&gt;").replace("&", "&amp;")

            # Resolve URL (Processed "URL" -> Raw "slug" construction)
            TxtUrl = ItemDictEvent.get('URL', '')
            if TxtUrl == "": # 1. if no URL
                TxtSlug = ItemDictEvent.get('slug', '')
                if TxtSlug: TxtUrl = f"https://polymarket.com/event/{TxtSlug}"
                else: TxtUrl = "https://polymarket.com"

            # --- B. RESOLVE VOLUME ---
            TxtVol = ItemDictEvent.get('Spike Amount', '')
            if TxtVol == "": TxtVol = ItemDictEvent.get('Volume', '')
            if TxtVol == "": # 2. if still empty, calc from raw
                NumRawVol = float(ItemDictEvent.get('volume', 0))
                TxtVol = Return_TxtHumanVolume(NumVolume=NumRawVol)

            # --- C. RESOLVE ODDS (Leading Option) ---
            TxtOddsRaw = ItemDictEvent.get('Odds Breakdown', '')

            # If Raw Data (Feed/Watchlist), we might not have odds calculated yet. Calc them now.
            if TxtOddsRaw == "" or TxtOddsRaw == "N/A": # 3. if missing odds
                # We need to fetch history? For feed we might skip history to be fast, or pass empty history
                # We can reuse the existing function!
                TxtOddsRaw = Return_TxtMultiOutcomeOdds(ItemEvent=ItemDictEvent, TxtPrevOdds="")

            # Extract ONLY the Leading Option (First part before the pipe |)
            TxtLeadingOption = ""
            if "▶" in TxtOddsRaw: # 4. if valid odds string
                ArrSplit = TxtOddsRaw.split("|")
                if len(ArrSplit) > 0: # 5. if valid odds string
                    TxtLeadingOption = " " + ArrSplit[0].strip() # Add space for formatting

            # --- D. CONSTRUCT LINE ---
            # Format: • <a href="URL">Title</a>: $Vol ▶Leading...
            TxtLine = f"• <a href='{TxtUrl}'>{TxtName}</a>: {TxtVol}{TxtLeadingOption}"
            ArrTxtLines.append(TxtLine)

        return "\n".join(ArrTxtLines)

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]


@Exec_Decorator_GeneralChecks(TxtVersion="1.0")
def Exec_RenderDashboard(DictConfig:dict):
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Renders the main dashboard interface, including settings sidebar, metrics, and data visualizations.

    --------------
    Parameters, Raises & Returns:
    --------------
    :param DictConfig: Dictionary containing configuration settings.

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    DictConfig = Return_DictTxtConfig()

    --------------
    # How-To-Use:
    Exec_RenderDashboard(DictConfig)
    """
    #End: docstring
    global IsExceptionRaised
    TxtCallerFunction = inspect.currentframe().f_code.co_name; IsExceptionRaised=False
    try: # 1. try (General try for the function)
        # --- CONFIG (force types) ---
        NumUpdateInterval = int(DictConfig.get("NumUpdateInterval", 60))          # minutes
        NumFetchLimit     = int(DictConfig.get("NumFetchLimit", 100))
        NumDisplayLimit   = int(DictConfig.get("NumDisplayLimit", 20))
        NumVolThreshold   = float(DictConfig.get("NumVolThreshold", 2000.0))
        ArrTxtWatchlist   = DictConfig.get("ArrTxtWatchlist", [])

        # Auto rerun (does not mean fetch; fetch is controlled below)
        st_autorefresh(interval=5 * 1000, key="ui_heartbeat")

        # Server-side cache (survives browser refresh)
        DictTxtServerCache = Return_DictTxtServerCache()
        if DictTxtServerCache.get("IsFetching") == True: # 10. if DictTxtServerCache.get("IsFetching") == True
            streamlit.info("🔄 Refreshing data in background…")
        if not DictTxtServerCache.get("Data"): # 11. if not DictTxtServerCache.get("Data")
            streamlit.warning("Waiting for first background refresh…")    

        # Session state (ONLY for UI flow state, not data caching)
        if "IsEditing" not in streamlit.session_state:streamlit.session_state["IsEditing"] = False

        # --- TIME COMPUTATION (single source of truth) ---
        NumNow = time.time()
        NumLastFetch = float(DictTxtServerCache.get("LastFetchEpoch", 0.0))
        NumElapsedSec = max(0.0, NumNow - NumLastFetch) if NumLastFetch > 0 else 0.0
        NumIntervalSec = max(1.0, NumUpdateInterval * 60.0)
        NumRemainingSec = max(0.0, NumIntervalSec - NumElapsedSec)

        # --- SIDEBAR & CONTROLS ---
        with streamlit.sidebar: # 1. with streamlit.sidebar
            streamlit.header("⚙️ Settings")

            #if streamlit.button("Refresh Now 🔄", width="stretch"): # 12. if streamlit.button("Refresh Now 🔄", width="stretch")
            if streamlit.button("Refresh Now 🔄", use_container_width=True): # 12. if streamlit.button("Refresh Now 🔄", width="stretch")
                DictTxtServerCache["LastFetchEpoch"] = 0.0;DictTxtServerCache["IsForceRefreshRequested"] = True
                DictTxtServerCache["IsFetching"] = True;streamlit.rerun()


            # Status Indicator (correct even after browser refresh)
            if float(DictTxtServerCache.get("LastFetchEpoch", 0.0)) <= 0: # 1. if float(DictTxtServerCache.get("LastFetchEpoch", 0.0)) <= 0
                streamlit.caption("Last update: never")
                streamlit.caption(f"Next auto-refresh: {NumUpdateInterval} mins")
                streamlit.progress(0.0)
            else: # 1. if float(DictTxtServerCache.get("LastFetchEpoch", 0.0)) <= 0
                streamlit.caption(f"Last update: {int(NumElapsedSec // 60)} mins ago")
                streamlit.caption(f"Next auto-refresh: {int(math.ceil(NumRemainingSec / 60.0))} mins")
                streamlit.progress(min(1.0, NumElapsedSec / NumIntervalSec))

            streamlit.divider()

            if streamlit.button("Edit Configuration ✏️"): # 2. if streamlit.button("Edit Configuration ✏️")
                streamlit.session_state["IsEditing"] = True
                streamlit.rerun()

            if streamlit.button("Test Telegram 🤖"): # 3. if streamlit.button("Test Telegram 🤖")
                try: # 2. try (Telegram test)
                    Exec_Telegram_SendMsg(TxtBotToken=DictConfig["TxtBotToken"],TxtChatID=DictConfig["TxtChatID"],
                    TxtMessage="✅ PolyOddWatcher Dashboard Test!",TxtChatIDThread=DictConfig.get("TxtChatIDThread", ""))
                    streamlit.toast("Sent!", icon="✅")
                except Exception as ObjException: # 2. try (Telegram test)
                    streamlit.error("Error: {}".format(str(ObjException)))

            # --- DATABASE MAINTENANCE ---
            streamlit.markdown("#### 🗄️ Database Maintenance")
            NumPruneDays = streamlit.number_input(
            "Days of History to Keep:",
            min_value=1, value=30, step=1,
            help="Older records will be deleted to keep the dashboard fast.")
            if streamlit.button("🧹 Prune Old History"): # 4. if streamlit.button("🧹 Prune Old History")
                try: # 3. try (Prune old history)
                    NumDeleted = Return_NumPruneDB(NumDaysToKeep=NumPruneDays)
                    streamlit.toast(f"Cleaned! Removed {NumDeleted} old records.", icon="🧹")
                except Exception as ObjException: # 3. try (Prune old history)
                    streamlit.error("Prune Failed: {}".format(str(ObjException)))

            streamlit.divider()
            streamlit.markdown("**Scan Scope:** {} items".format(NumFetchLimit))
            streamlit.markdown("**Refresh:** {} mins".format(NumUpdateInterval))
            streamlit.markdown("**Spike Threshold:** ${:,.0f}".format(NumVolThreshold))

        # --- DISPLAY PHASE (ALWAYS READ-ONLY) ---
        ArrDictTxtMarkets = DictTxtServerCache.get("Data", [])
        ArrTxtWatchData = DictTxtServerCache.get("WatchData", [])
        ArrDictTxtSpikes = DictTxtServerCache.get("Spikes", [])
        ArrDictTxtClosingSoon = DictTxtServerCache.get("ClosingSoon", [])
        ArrTxtSortedData = DictTxtServerCache.get("SortedData", [])

        if ArrDictTxtMarkets: # 4. if ArrDictTxtMarkets
            # History odds for display (read-only query)
            ArrTxtDisplayIDs = [str(ItemArr['id']) for ItemArr in ArrDictTxtMarkets]
            DictTxtHistoryOdds = Return_DictTxtHistoryOdds(ArrTxtDisplayIDs)

            # UI Metrics
            ObjCol1, ObjCol2, ObjCol3 = streamlit.columns(3)
            ObjCol1.metric("Markets Monitored", len(ArrDictTxtMarkets))
            NumTotalVol = sum([float(ItemData.get('volume', 0)) for ItemData in ArrDictTxtMarkets])
            ObjCol2.metric("Total Volume", Return_TxtHumanVolume(NumVolume=NumTotalVol))
            ObjCol3.metric("Spikes (Last Check)", len(ArrDictTxtSpikes), delta_color="inverse")

            # Watchlist
            if ArrTxtWatchData: # 5. if ArrTxtWatchData
                streamlit.subheader("👀 Your Watchlist")
                ArrTxtWatchlistTable = []
                for ItemEvent in ArrTxtWatchData: # 1. for ItemEvent in ArrTxtWatchData
                    TxtPrev = str(DictTxtHistoryOdds.get(str(ItemEvent['id']), None))
                    ArrTxtWatchlistTable.append({
                    "Title": ItemEvent['title'],
                    "Odds Breakdown": Return_TxtMultiOutcomeOdds(ItemEvent=ItemEvent, TxtPrevOdds=TxtPrev),
                    "Volume": Return_TxtHumanVolume(NumVolume=float(ItemEvent.get('volume', 0))),
                    "End Date": ItemEvent.get('endDate', 'N/A'),
                    "URL": "https://polymarket.com/event/" + ItemEvent['slug']})
                ObjdfWatch = pandas.DataFrame(ArrTxtWatchlistTable)
                ObjdfWatch.index = ObjdfWatch.index + 1
                streamlit.dataframe(
                ObjdfWatch, use_container_width=True,    
                #ObjdfWatch, width="stretch",
                column_config={"URL": streamlit.column_config.LinkColumn("Link", display_text="Open 🔗")})
            elif len(ArrTxtWatchlist) > 0: # 5. if ArrTxtWatchData
                streamlit.subheader("👀 Your Watchlist")
                streamlit.warning("No watchlist items found. Check Slug spelling.")

            # Chart (Top 10 by volume)
            streamlit.subheader("📊 Top Market Volume")
            ArrTxtChartData = [{"Title": ItemEvent['title'], "Volume": float(ItemEvent.get('volume', 0))}
                               for ItemEvent in ArrTxtSortedData[:10]]
            ObjdfChart = pandas.DataFrame(ArrTxtChartData)
            ObjFig = plotly.express.bar(ObjdfChart, x='Title', y='Volume', color='Volume')
            #streamlit.plotly_chart(ObjFig, width="stretch")
            streamlit.plotly_chart(ObjFig, use_container_width=True)

            # Alerts tables
            ObjColAlert1, ObjColAlert2 = streamlit.columns(2)

            with ObjColAlert1: # 2. with ObjColAlert1
                if DictConfig.get("IsFilterHighBets"): # 6. if DictConfig.get("IsFilterHighBets")
                    streamlit.subheader("🚨 Sudden Volume Spikes (>${:,.0f})".format(NumVolThreshold))
                    if ArrDictTxtSpikes: # 7. if ArrDictTxtSpikes
                        ObjdfSpikes = pandas.DataFrame(ArrDictTxtSpikes)
                        ObjdfSpikes.index = ObjdfSpikes.index + 1
                        streamlit.dataframe(
                            #ObjdfSpikes, width="stretch",
                            ObjdfSpikes, use_container_width=True,
                            column_config={"URL": streamlit.column_config.LinkColumn("Link", display_text="Open 🔗")}
                        )
                    else: # 7. if ArrDictTxtSpikes
                        streamlit.caption("No spikes > ${:,.0f} detected.".format(NumVolThreshold))

            with ObjColAlert2: # 3. with ObjColAlert2
                if DictConfig.get("IsFilterClosingSoon"): # 8. if DictConfig.get("IsFilterClosingSoon")
                    streamlit.subheader("⏳ Closing Soon (<48h)")
                    if ArrDictTxtClosingSoon: # 9. if ArrDictTxtClosingSoon
                        ObjdfClosing = pandas.DataFrame(ArrDictTxtClosingSoon)
                        ObjdfClosing.index = ObjdfClosing.index + 1
                        streamlit.dataframe(
                        #ObjdfClosing, width="stretch",
                        ObjdfClosing, use_container_width=True,
                        column_config={"URL": streamlit.column_config.LinkColumn("Link", display_text="Open 🔗")})
                    else: # 9. if ArrDictTxtClosingSoon
                        streamlit.caption("No tracked markets closing soon.")

            # Full feed
            streamlit.subheader("📋 Full Market Feed (Top {})".format(NumDisplayLimit))
            ArrTxtFullList = []
            for ItemEvent in ArrTxtSortedData[:NumDisplayLimit]: # 2. for ItemEvent in ArrTxtSortedData[:NumDisplayLimit]
                TxtPrev = str(DictTxtHistoryOdds.get(str(ItemEvent['id']), None))
                ArrTxtFullList.append({
                "Title": ItemEvent['title'],
                "Volume": Return_TxtHumanVolume(NumVolume=float(ItemEvent.get('volume', 0))),
                "Odds Breakdown": Return_TxtMultiOutcomeOdds(ItemEvent=ItemEvent, TxtPrevOdds=TxtPrev),
                "End Date": ItemEvent.get('endDate', 'N/A'),
                "URL": "https://polymarket.com/event/" + ItemEvent['slug']})
            ObjdfFull = pandas.DataFrame(ArrTxtFullList)
            ObjdfFull.index = ObjdfFull.index + 1
            streamlit.dataframe(
            ObjdfFull, use_container_width=True,
            #ObjdfFull, width="stretch",
            column_config={"URL": streamlit.column_config.LinkColumn("Link", display_text="Open 🔗")})

    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]


def Exec_Main():
    #Begin: docstring
    """Information:
    --------------
    --------------
    :definitionWID: Entry point for the application. Initializes the database, loads configuration, and directs the user to either the dashboard or setup wizard.

    --------------
    Parameters, Raises & Returns:
    --------------

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Exec_Main()
    """
    #End: docstring
    try: # 1. try (General try for the function)
        streamlit.set_page_config(page_title="Polymarket Universal Watcher", layout="wide")
        Exec_InitDB()
        # ✅ Start background scheduler (runs even if UI is closed)
        Return_DictObjBackgroundWorker()
        DictTxtConfig = Return_DictTxtConfig()

        IsEditing = streamlit.session_state.get("IsEditing", False)
        IsConfigured = DictTxtConfig.get("IsConfigured", False)

        if IsConfigured and not IsEditing: # 1. if IsConfigured and not IsEditing
            Exec_RenderDashboard(DictConfig=DictTxtConfig)
        else: # 1. if IsConfigured and not IsEditing
            Exec_RenderWelcomeWizard(DictCurrentConfig=DictTxtConfig)

    except Exception as ObjException: # 1. try (General try for the function)
        # We catch exceptions at the top level to prevent ugly tracebacks on the UI
        streamlit.error("Critical Error: {}".format(str(ObjException)))

def Exec_RunWorkerOnly():
    #Begin: docstring
    """Information:
    --------------
    :definitionWID: Runs the background worker as a standalone process (no Streamlit session required).

    --------------
    Parameters, Raises & Returns:
    --------------

    :raises ValueError:[1] If an unhandled exception occurs during execution. How to get the log? ExceptionLog: except ValueError as TxtExceptionValueError

    :return: None

    :rtype: None

    --------------
    # Sample data:
    N/A. Architecture specific.

    --------------
    # How-To-Use:
    Exec_RunWorkerOnly()
    """
    #End: docstring
    try: # 1. try (General try for the function)
        Return_DictObjBackgroundWorker()
        while True:
            time.sleep(60)
    except Exception as ObjException: # 1. try (General try for the function)
        #Begin: ValueError:[1]
        if IsExceptionRaised==True: # 99. if IsExceptionRaised==True
            raise
        else: # 99. if IsExceptionRaised==True
            raise ValueError("Err01{}: Unhandled exception. Further Details: '{}'".format(TxtCallerFunction,str(ObjException)))
        #End: ValueError:[1]

if __name__ == "__main__":
    if "--worker" in sys.argv:
        Exec_RunWorkerOnly()
    else:
        Exec_Main()