TradeChart 2.2.0__tar.gz → 2.2.1__tar.gz

{tradechart-2.2.0 → tradechart-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TradeChart
-Version: 2.2.0
+Version: 2.2.1
 Summary: Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts.
 Author-email: "TRADELY.DEV" <dev@tradely.dev>
 License: Apache-2.0
@@ -45,7 +45,7 @@ Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
 Dynamic: license-file
 
-# TradeChart — Library Edition v2.2.0
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
@@ -116,11 +116,20 @@ Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …)
 
 ### How it works
 
-Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` checks the disk store before touching the network:
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
 
 1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
-2. **Disk store** — CSV file per `(ticker, duration)` pair, persists across sessions.
-3. **Live provider chain** — yfinance → TradingView → Stooq. On success the result is written to disk automatically.
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
 
 ```python
 tc.store("/data/myproject")
@@ -129,7 +138,10 @@ tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
 # Later — same session or a completely new one:
 tc.chart("AAPL", "3mo")                   # served from disk, no network call
 tc.data("MSFT", "3mo")                    # same
-tc.heatmap(tc.SECTOR_GROUPS["mag7"], "3mo") # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
 ```
 
 ### Clearing stored data
@@ -557,7 +569,7 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 0 | **Disk store** | `tc.store(path)` called once | Fastest — served from local CSV, no network. Persists across sessions. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
 | 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
@@ -569,7 +581,7 @@ If all live providers fail and no disk data exists, a `DataFetchError` is raised
 ## Notes
 
 **Persistent disk store**  
-When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. Subsequent fetches — even in a new Python session — read from disk rather than the network. Use `tc.clear_cache(disk=True)` to wipe stored files and force a fresh fetch from providers.
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
 
 **In-memory caching**  
 Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.

{tradechart-2.2.0 → tradechart-2.2.1}/README.md

@@ -1,4 +1,4 @@
-# TradeChart — Library Edition v2.2.0
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
@@ -69,11 +69,20 @@ Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …)
 
 ### How it works
 
-Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` checks the disk store before touching the network:
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
 
 1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
-2. **Disk store** — CSV file per `(ticker, duration)` pair, persists across sessions.
-3. **Live provider chain** — yfinance → TradingView → Stooq. On success the result is written to disk automatically.
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
 
 ```python
 tc.store("/data/myproject")
@@ -82,7 +91,10 @@ tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
 # Later — same session or a completely new one:
 tc.chart("AAPL", "3mo")                   # served from disk, no network call
 tc.data("MSFT", "3mo")                    # same
-tc.heatmap(tc.SECTOR_GROUPS["mag7"], "3mo") # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
 ```
 
 ### Clearing stored data
@@ -510,7 +522,7 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 0 | **Disk store** | `tc.store(path)` called once | Fastest — served from local CSV, no network. Persists across sessions. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
 | 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
@@ -522,7 +534,7 @@ If all live providers fail and no disk data exists, a `DataFetchError` is raised
 ## Notes
 
 **Persistent disk store**  
-When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. Subsequent fetches — even in a new Python session — read from disk rather than the network. Use `tc.clear_cache(disk=True)` to wipe stored files and force a fresh fetch from providers.
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
 
 **In-memory caching**  
 Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.

{tradechart-2.2.0 → tradechart-2.2.1}/TradeChart.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TradeChart
-Version: 2.2.0
+Version: 2.2.1
 Summary: Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts.
 Author-email: "TRADELY.DEV" <dev@tradely.dev>
 License: Apache-2.0
@@ -45,7 +45,7 @@ Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
 Dynamic: license-file
 
-# TradeChart — Library Edition v2.2.0
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
@@ -116,11 +116,20 @@ Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …)
 
 ### How it works
 
-Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` checks the disk store before touching the network:
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
 
 1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
-2. **Disk store** — CSV file per `(ticker, duration)` pair, persists across sessions.
-3. **Live provider chain** — yfinance → TradingView → Stooq. On success the result is written to disk automatically.
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
 
 ```python
 tc.store("/data/myproject")
@@ -129,7 +138,10 @@ tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
 # Later — same session or a completely new one:
 tc.chart("AAPL", "3mo")                   # served from disk, no network call
 tc.data("MSFT", "3mo")                    # same
-tc.heatmap(tc.SECTOR_GROUPS["mag7"], "3mo") # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
 ```
 
 ### Clearing stored data
@@ -557,7 +569,7 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 0 | **Disk store** | `tc.store(path)` called once | Fastest — served from local CSV, no network. Persists across sessions. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
 | 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
@@ -569,7 +581,7 @@ If all live providers fail and no disk data exists, a `DataFetchError` is raised
 ## Notes
 
 **Persistent disk store**  
-When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. Subsequent fetches — even in a new Python session — read from disk rather than the network. Use `tc.clear_cache(disk=True)` to wipe stored files and force a fresh fetch from providers.
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
 
 **In-memory caching**  
 Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.

{tradechart-2.2.0 → tradechart-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "TradeChart"
-version = "2.2.0"
+version = "2.2.1"
 description = "Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{tradechart-2.2.0 → tradechart-2.2.1}/tradechart/__init__.py

@@ -87,7 +87,7 @@ from tradechart.utils.exceptions import (
 )
 from tradechart.utils.validation import VALID_DURATIONS
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"
 __all__ = [
     "terminal", "theme", "watermark", "config",
     "chart", "compare", "heatmap", "data", "export", "clear_cache",

{tradechart-2.2.0 → tradechart-2.2.1}/tradechart/data/fetcher.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import time
 from typing import Sequence
 
+import pandas as pd
+
 from tradechart.config.logger import get_logger
 from tradechart.config.settings import get_settings
 from tradechart.data.models import MarketData
@@ -12,6 +14,19 @@ from tradechart.data.provider_base import BaseProvider
 from tradechart.utils.exceptions import DataFetchError
 
 
+def _merge(stored: pd.DataFrame, fresh: pd.DataFrame) -> pd.DataFrame:
+    """Merge stored history with freshly-fetched rows.
+
+    Historical rows from *stored* are preserved as-is.  Any row whose
+    timestamp also appears in *fresh* is overwritten by the fresh value
+    (handles end-of-day corrections / partial bars).  Rows that exist only
+    in *fresh* (new bars) are appended.  The result is sorted by date.
+    """
+    combined = pd.concat([stored, fresh])
+    combined = combined[~combined.index.duplicated(keep="last")]
+    return combined.sort_index()
+
+
 class _Cache:
     """Simple TTL-based in-memory cache."""
 
@@ -49,25 +64,8 @@ class DataFetcher:
         self._cache = _Cache()
         self._log = get_logger()
 
-    def fetch(self, ticker: str, duration: str) -> MarketData:
-        # 1 — in-memory cache (fastest)
-        cached = self._cache.get(ticker, duration)
-        if cached is not None:
-            self._log.detail("Cache hit for %s/%s", ticker, duration)
-            self._log.summary(f"✓ Data loaded from cache ({cached.provider})")
-            return cached
-
-        # 2 — persistent disk store (avoids network for already-fetched data)
-        disk_store = get_settings().disk_store
-        if disk_store is not None:
-            disk_data = disk_store.load(ticker, duration)
-            if disk_data is not None:
-                self._log.detail("Disk store hit for %s/%s", ticker, duration)
-                self._log.summary(f"✓ Data loaded from disk store ({len(disk_data.df)} rows)")
-                self._cache.put(disk_data)  # promote to memory cache
-                return disk_data
-
-        # 3 — live provider chain
+    def _fetch_live(self, ticker: str, duration: str) -> MarketData:
+        """Try each provider in order and return the first successful result."""
         errors: list[str] = []
         for provider in self._providers:
             self._log.section(f"Trying provider: {provider.name}")
@@ -79,10 +77,6 @@ class DataFetcher:
                     errors.append(msg)
                     continue
                 data.clean().downsample()
-                self._cache.put(data)
-                # 4 — persist to disk store for future sessions
-                if disk_store is not None:
-                    disk_store.save(data)
                 self._log.detail("Fetched %d rows from %s", len(data.df), provider.name)
                 self._log.summary(f"✓ Data fetched via {provider.name} ({len(data.df)} rows)")
                 return data
@@ -90,12 +84,59 @@ class DataFetcher:
                 msg = f"{provider.name} failed: {exc}"
                 self._log.detail(msg)
                 errors.append(msg)
-
         raise DataFetchError(
             f"All data providers failed for {ticker}/{duration}.\n"
             + "\n".join(f"  • {e}" for e in errors)
         )
 
+    def fetch(self, ticker: str, duration: str) -> MarketData:
+        # 1 — in-memory cache (fastest)
+        cached = self._cache.get(ticker, duration)
+        if cached is not None:
+            self._log.detail("Cache hit for %s/%s", ticker, duration)
+            self._log.summary(f"✓ Data loaded from cache ({cached.provider})")
+            return cached
+
+        disk_store = get_settings().disk_store
+
+        # 2 — persistent disk store
+        disk_data: MarketData | None = None
+        if disk_store is not None:
+            disk_data = disk_store.load(ticker, duration)
+            if disk_data is not None and not disk_store.is_stale(ticker, duration):
+                # Data is fresh — serve directly, no network call needed
+                self._log.detail("Disk store hit for %s/%s", ticker, duration)
+                self._log.summary(f"✓ Data loaded from disk store ({len(disk_data.df)} rows)")
+                self._cache.put(disk_data)
+                return disk_data
+            # disk_data may be stale (or absent) — fall through to live fetch,
+            # then merge the new rows on top of the stored history
+
+        # 3 — live provider chain (only fetches what the provider returns for
+        #     this duration, typically the most recent N bars)
+        fresh = self._fetch_live(ticker, duration)
+
+        # 4 — merge fresh rows onto stored history, then persist
+        if disk_store is not None:
+            if disk_data is not None:
+                merged_df = _merge(disk_data.df, fresh.df)
+                result = MarketData(
+                    ticker=ticker, duration=duration,
+                    provider=fresh.provider, df=merged_df,
+                )
+                self._log.detail(
+                    "Merged disk (%d rows) + live (%d rows) → %d rows",
+                    len(disk_data.df), len(fresh.df), len(merged_df),
+                )
+            else:
+                result = fresh
+            disk_store.save(result)
+            self._cache.put(result)
+            return result
+
+        self._cache.put(fresh)
+        return fresh
+
     def clear_cache(self) -> None:
         """Flush the in-memory data cache."""
         self._cache.clear()

{tradechart-2.2.0 → tradechart-2.2.1}/tradechart/data/store.py

@@ -2,12 +2,30 @@
 
 from __future__ import annotations
 
+import time
 from pathlib import Path
 
 import pandas as pd
 
 from tradechart.data.models import MarketData
 
+# Maximum age (seconds) for a stored file before it is considered stale and
+# re-fetched from a live provider.  Keyed by the user-facing duration string;
+# the value matches the bar resolution so a daily-bar file never goes more
+# than one trading day without refreshing.
+_MAX_AGE: dict[str, int] = {
+    "1d":  4  * 3_600,        # intraday (5-min bars)  → 4 hours
+    "5d":  4  * 3_600,        # intraday (15-min bars) → 4 hours
+    "1mo": 24 * 3_600,        # daily bars             → 1 day
+    "3mo": 24 * 3_600,        # daily bars             → 1 day
+    "6mo": 24 * 3_600,        # daily bars             → 1 day
+    "1y":  7  * 24 * 3_600,   # weekly bars            → 1 week
+    "2y":  7  * 24 * 3_600,
+    "5y":  7  * 24 * 3_600,
+    "10y": 30 * 24 * 3_600,   # monthly bars           → 30 days
+    "max": 30 * 24 * 3_600,
+}
+
 
 class DiskStore:
     """Saves and loads MarketData as CSV files under a dedicated folder.
@@ -52,8 +70,25 @@ class DiskStore:
         """Return True if data for this (ticker, duration) pair is on disk."""
         return self._file_path(ticker, duration).exists()
 
+    def is_stale(self, ticker: str, duration: str) -> bool:
+        """Return True if the stored file is older than the bar-resolution threshold.
+
+        A fresh file is served as-is.  A stale file still holds valid
+        historical rows — the caller should merge fresh provider data on top
+        rather than discarding it.
+        """
+        path = self._file_path(ticker, duration)
+        if not path.exists():
+            return True
+        max_age = _MAX_AGE.get(duration, 24 * 3_600)
+        return time.time() - path.stat().st_mtime > max_age
+
     def load(self, ticker: str, duration: str) -> MarketData | None:
-        """Load a previously stored dataset.  Returns *None* on any error."""
+        """Load a previously stored dataset regardless of age.
+
+        Returns *None* only if the file is missing or unreadable.  Staleness
+        is a separate concern handled by :meth:`is_stale`.
+        """
         path = self._file_path(ticker, duration)
         if not path.exists():
             return None

{tradechart-2.2.0 → tradechart-2.2.1}/tradechart_examples/discord_demo_bot/discord_bot.py

@@ -100,6 +100,7 @@ MAX_QUEUE_SIZE = max(1, int(os.getenv("MAX_QUEUE_SIZE", "20")))
 tc.theme(os.getenv("THEME", "dark"))
 tc.terminal(os.getenv("TERMINAL", "none"))
 tc.watermark(os.getenv("WATERMARK", "True").lower() == "true")
+tc.store(DATA_DIR)  # persist fetched data to TradeChartBot_Data/tradechart_FetchData/
 
 # ============================================================
 # BUILT-IN SECTOR GROUPS (mirroring tc.SECTOR_GROUPS)
@@ -565,7 +566,8 @@ async def cmd_heatmap(
 # ============================================================
 
 @client.tree.command(name="clearcache", description="MOD ONLY: Clear the chart data cache")
-async def cmd_clearcache(interaction: discord.Interaction) -> None:
+@app_commands.describe(disk="Also wipe the persistent disk store and force a full re-fetch (default: False)")
+async def cmd_clearcache(interaction: discord.Interaction, disk: bool = False) -> None:
     if interaction.guild is None:
         await interaction.response.send_message("This bot only works in servers.", ephemeral=True)
         return
@@ -574,8 +576,9 @@ async def cmd_clearcache(interaction: discord.Interaction) -> None:
         await interaction.response.send_message("Only mods can clear the cache.", ephemeral=True)
         return
 
-    tc.clear_cache()
-    await interaction.response.send_message(EMOJI_GREEN + " Cache cleared.", ephemeral=True)
+    tc.clear_cache(disk=disk)
+    label = EMOJI_GREEN + " Cache cleared (memory + disk store)." if disk else EMOJI_GREEN + " Memory cache cleared."
+    await interaction.response.send_message(label, ephemeral=True)
 
 
 # ============================================================
@@ -929,8 +932,12 @@ async def cmd_help(interaction: discord.Interaction) -> None:
         inline=False,
     )
     embed.add_field(
-        name="/clearcache  (mod only)",
-        value="Clear cached chart data to force a fresh fetch.",
+        name="/clearcache [disk]  (mod only)",
+        value=(
+            "Clear cached chart data. Without `disk:True` only the in-memory cache is cleared "
+            "and stored data on disk is still reused. Use `disk:True` to wipe the disk store "
+            "and force a full re-fetch from the network."
+        ),
         inline=False,
     )
     embed.add_field(