Jing997/copper-cathodes-world-monitor

Copper Cathode Commodity Monitor

A Streamlit dashboard for copper price intelligence, targeting copper producers and mining companies. Deployed on HuggingFace Spaces (free CPU tier).

The dashboard aggregates LME, COMEX, and SHFE-derived copper prices, macro stress signals, speculative positioning data, and RSS news sentiment into a single five-tab interface. It is intended as an educational and analytical reference — not a trading system.

Data Sources

Architecture

External APIs
  yfinance (HG=F, CNY=X)
  Alpha Vantage (COPPER)
  FRED API (PCOPPUSDM, STLFSI4, ...)
  akshare (SHFE front-month)
  feedparser RSS (6 feeds)
  CFTC Socrata API (COT)
  World Bank API (PCOPP.USD)
          |
          v
  cache_manager.py
    HuggingFace Dataset repo (Jing997/copper-monitor-cache)
    Parquet files with per-source TTL enforcement
    FinBERT score cache (permanent, keyed by headline hash)
          |
          v
  modules/
    price_fetcher.py    -- COMEX, LME spot, SHFE (transient), USD/CNY, forward curve
    macro_fetcher.py    -- FRED indicators, CFTC COT, World Bank monthly price
    news_fetcher.py     -- RSS headline fetch + copper keyword filter
    spread_calc.py      -- COMEX-LME basis, LME cash/3M spread, China import premium
    stress_index.py     -- 6-signal PCA composite market stress index
    sentiment.py        -- FinBERT batch scoring + Gemini daily brief
          |
          v
  app.py
    5-tab Streamlit UI (Price Overview, Spread & Arbitrage,
    Market Stress Index, Sentiment, News Feed)

Setup

1. Install dependencies

pip install -r requirements.txt

2. Configure secrets

The following secrets must be set before running locally or deploying to HuggingFace Spaces:

For local development, export secrets as environment variables:

export FRED_KEY="your_fred_key"
export ALPHAVANTAGE_KEY="your_alphavantage_key"
export GEMINI_API_KEY="your_gemini_key"   # optional
export HF_TOKEN="your_hf_token"

3. Run locally

streamlit run app.py

4. Deploy to HuggingFace Spaces

1. 1.Fork this repository to your GitHub account.
2. 2.Create a new HuggingFace Space (Streamlit SDK, free CPU tier).
3. 3.Link the Space to your forked GitHub repository.
4. 4.In the Space settings under Repository secrets, add the four secrets listed above.
5. 5.Push to the linked branch — the Space will build and deploy automatically.

Dashboard Tabs

Compliance Notes

• —Educational disclaimer: This dashboard is for educational and informational purposes only. Not financial advice.
• —SHFE data: Raw SHFE prices (CNY/MT) are never stored, logged, or displayed. Only the derived China Import Premium (a computed USD/MT value) appears in the UI, in accordance with the akshare research/derived-use license.
• —yfinance (COMEX): Raw OHLCV data from yfinance is kept in session-level st.cache_data only. It is never written to the HuggingFace Dataset cache.
• —RSS headlines: Only the headline title and source link are fetched and displayed. Article body content is never retrieved, stored, or shown, in accordance with RSS terms of service.
• —Alpha Vantage: A strict 24-hour TTL is enforced via cache_manager.is_stale("lme_spot"). The API is never called without first checking staleness. Maximum 25 calls per day.

Attribution

• —World Bank — Monthly copper price data (PCOPP.USD) provided by the World Bank, licensed under CC BY 4.0.
• —ProsusAI/finbert — Sentiment analysis model by ProsusAI, licensed under Apache 2.0.
• —Market Stress Index methodology — Inspired by the OFR Financial Stress Index (OFRwp-17-04) and the St. Louis Fed STLFSI4. Not a trading recommendation.