SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslithium-supply-demand-gap-radar

lithium-supply-demand-gap-radar

General & other

View repository

Updated 10-15 20:04

About this skill

<essential_principles> Lithium Industry Chain Supply-Demand Radar Core Principles

The lithium industry chain must be analyzed in layers and must not be conflated:

Mining → Processing → Battery
(礦端)   (化學品)    (終端需求)
Layer Representative Data Typical Lag
Upstream (mining end) Lithium mine production, export volume Annual/Quarterly
Midstream (chemicals) Lithium carbonate/lithium hydroxide prices Weekly/Daily
Downstream (battery/EV) EV sales, battery installations (GWh) Monthly

Mandatory Rules：

  • Supply analysis must specify the layer (mining end vs refining end)
  • Demand proxy must have explicit conversion assumptions (kWh → kg Li)
  • Price analysis must distinguish lithium carbonate vs lithium hydroxide

Based on data_level parameters, automatically select the data source:

data_level Price Data Supply-Demand Data Reliability
free_nolimit CME futures/proxy index USGS/IEA/Australian government Medium
free_limit SMM/Fastmarkets pages + Company financial reports Medium-high
paid_low SMM full series + Benchmark basic High
paid_high Fastmarkets API + S&P/BNEF/WoodMac Highest

Mandatory Rules：

  • When price data is insufficient, use CME contracts or related stock baskets as a proxy
  • The actual data tier used must be annotated in the output

The conversion from battery demand to lithium demand must have explicit assumptions:

Assumption Scenario kg Li / kWh Notes
Conservative estimate 0.12 Includes an assumption of rising LFP share
Neutral estimate 0.15 Mixed NMC/LFP
Aggressive estimate 0.18 High-nickel NMC dominant 
li_demand_kt = battery_gwh * kg_per_kwh * 1000  # 單位: kt LCE

Mandatory Rules：

  • Demand estimates must output three scenarios (conservative/neutral/aggressive)
  • Output must include kg_per_kwh_assumption field

The lithium price cycle is divided into four stages:

Regime Characteristics Trading Implications
downtrend 12-26 week momentum < 0, slope < 0 Bears dominate, avoid going long
bottoming Momentum converging, volatility declining, mean reversion Wait and see, await confirmation
uptrend Momentum > 0, slope > 0 Long window opens
overheat Momentum extremely positive, volatility expanding Risk of profit-taking

Indicator Combination：

  • 12-week / 26-week momentum (ROC)
  • Trend slope (linear regression)
  • Volatility (ATR / standard deviation)
  • Mean reversion strength (deviation from MA)

ETF sensitivity to lithium prices is affected by holdings structure:

Holding Type Beta to Lithium Prices Volatility Characteristics
Upstream (mining) 1.5 - 2.5 High leverage, high volatility
Midstream (refining) 0.8 - 1.2 Follows but with processing fee buffer
Downstream (battery) 0.3 - 0.8 Affected by competition/technology route

Calculation formula：

ETF_beta_li = Σ(weight_i * beta_i_to_lithium)

Mandatory rules：

  • Need to calculate rolling beta (52-week rolling recommended)
  • Transmission break determination: beta < 0.3 and persists > 8 weeks

</essential_principles>

  1. Full Analysis - Complete supply-demand × price × transmission integrated analysis (generate full report)
  2. Balance Nowcast - Only calculate real-time supply-demand balance estimate (gap widening/narrowing)
  3. Price Regime - Only analyze price patterns and cycle position
  4. ETF Exposure - Only analyze ETF holdings structure and lithium price sensitivity
  5. Ingest Data - Extract and standardize data from each data source

Wait for response before continuing.

After reading the workflow, please fully follow its steps.

<reference_index> Reference documents (references/)

Document Content
data-sources.md Detailed description and URLs of all data sources
unit-conversion.md Unit conversion rules (LCE/Li/GWh)
price-methodology.md Price data methodology (Fastmarkets/SMM)
etf-holdings-structure.md LIT holdings structure and industry chain segmentation
supply-chain-mapping.md Complete lithium supply chain mapping (mine→chemicals→battery)
failure-modes.md Failure modes and mitigation strategies
</reference_index>

<workflows_index>

Workflow Purpose
full-analysis.md Complete supply-demand × price × transmission integrated analysis
balance-nowcast.md Real-time supply-demand balance estimate
price-regime.md Price pattern and cycle analysis
etf-exposure.md ETF holdings exposure and transmission analysis
ingest.md Data extraction and standardization
</workflows_index>

<templates_index>

Template Purpose
output-json.md JSON output structure template
output-markdown.md Markdown report template
config.yaml Analysis parameter configuration template
data-schema.yaml Data Schema definition
</templates_index>

<scripts_index>

Script Purpose
lithium_pipeline.py Core data pipeline
ingest_sources.py Data source extraction
compute_balance.py Supply-demand balance calculation
classify_regime.py Price pattern classification
compute_etf_beta.py ETF transmission sensitivity calculation
visualize_analysis.py Comprehensive visualization of analysis results
inflection_point_chart.py Dedicated visualization for inflection point analysis ⭐
</scripts_index>

<quick_start> CLI quick start:

# 完整分析 LIT ETF（預設 10 年回看、週度頻率）
python scripts/lithium_pipeline.py analyze --ticker=LIT --lookback=10 --freq=weekly

# 僅計算供需平衡 Nowcast
python scripts/lithium_pipeline.py balance --asof=2026-01-16

# 分析價格型態（碳酸鋰 + 氫氧化鋰）
python scripts/lithium_pipeline.py regime --chem=both

# 計算 ETF 對鋰價的傳導敏感度
python scripts/lithium_pipeline.py etf-beta --ticker=LIT --window=52

# ✨ 生成視覺化圖表（完整儀表板）
python scripts/visualize_analysis.py
# 輸出：output/lithium_analysis_YYYY-MM-DD.png

Visualization output：

  • 📊 6-in-1 professional dashboard (18" × 12", 300 DPI)
  • 📁 Automatically saved to output/ directory
  • 📅 Filename includes the current date
  • 🎨 Full Chinese support

Library quick start:

from lithium_pipeline import LithiumSupplyDemandRadar

radar = LithiumSupplyDemandRadar(
    etf_ticker="LIT",
    lookback_years=10,
    price_freq="weekly",
    chem_focus="both",
    data_level="free_nolimit"
)

# 完整分析
result = radar.full_analysis()
print(f"Balance Index: {result['balance_index']:.2f}")
print(f"Price Regime: {result['price_regime']}")
print(f"ETF Beta to Li: {result['etf_beta_li']:.2f}")
print(f"Thesis: {result['thesis']}")

</quick_start>

<success_criteria> When the Skill executes successfully:

  • Correctly identify data level and use corresponding sources
  • Supply-demand balance index calculated correctly (including three scenarios)
  • Price pattern classification clear (downtrend/bottoming/uptrend/overheat)
  • ETF transmission sensitivity calculated correctly (rolling beta)
  • Output includes complete invalidation conditions (invalidation)
  • Data sources traceable (source_id, data_level)
  • Unit conversion assumptions clearly annotated
  • Visualization charts generated and meet specifications(300 DPI, PNG, filename includes date)
  • Reports and charts output together under the output/ directory </success_criteria>

<input_schema> Input parameter definitions

# 必要參數
etf_ticker: string      # 目標 ETF（預設 LIT）
lookback_years: int     # 回看年限（建議 10-15）
price_freq: string      # weekly | daily（建議 weekly）

# 範圍參數
region_focus:           # 供應/需求重點區（選填）
  - China
  - Australia
  - Chile
  - Argentina
  - US
  - EU

chem_focus: string      # carbonate | hydroxide | both（預設 both）

# 數據等級
data_level: string      # free_nolimit | free_limit | paid_low | paid_high

# 數據源開關
sources:
  usgs: boolean
  iea_ev_outlook: boolean
  australia_req: boolean
  abs_exports: boolean
  fastmarkets: boolean
  smm: boolean
  etf_holdings: boolean

# 輸出格式
output_format: string   # markdown | json（預設 markdown）

</input_schema>

<data_pipeline_architecture> Data pipeline architecture

[Data Sources]
     |
     v
+--------------------+
|   ingest_sources   |  --> USGS, IEA, Australia REQ/ABS
+--------------------+      Fastmarkets/SMM (方法學/價格)
     |                      Global X LIT factsheet
     v
+--------------------+
|   normalize        |  --> 統一 schema + 單位標註
+--------------------+
     |
     +-------------------+-------------------+
     |                   |                   |
     v                   v                   v
+-----------+    +-----------+    +-----------+
| supply_   |    | price_    |    | etf_      |
| demand    |    | series    |    | holdings  |
+-----------+    +-----------+    +-----------+
     |                   |                   |
     v                   v                   v
+-----------+    +-----------+    +-----------+
| balance_  |    | classify_ |    | compute_  |
| nowcast   |    | regime    |    | etf_beta  |
+-----------+    +-----------+    +-----------+
     |                   |                   |
     +-------------------+-------------------+
                         |
                         v
              +--------------------+
              |   generate_insight |  --> Thesis + Targets + Invalidation
              +--------------------+
                         |
                         v
              +--------------------+
              |   format_output    |  --> JSON + Markdown
              +--------------------+

Standardized field Schema:

Field Type Description
date date Data date
metric_type string supply/demand/price/etf
metric_name string Specific indicator name
value float Value
unit string kt_LCE/USD_per_kg/GWh/pct
region string Country/Region
source_id string USGS/IEA/SMM/Fastmarkets/etc
data_level string Data Level
confidence float Source Quality Score (0-1)
</data_pipeline_architecture>