lithium-supply-demand-gap-radar

<essential_principles> Core Principles of Lithium Industry Chain Supply and Demand Radar

<principle name="supply_chain_layers"> **Supply Chain Layers**

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

Mining → Processing → Battery
(礦端)   (化學品)    (終端需求)

Layer	Representative Data	Typical Delay
Upstream (Mining)	Lithium mine production, export volume	Annual/Quarterly
Midstream (Processing)	Lithium carbonate/hydroxide price	Weekly/Daily
Downstream (Battery/EV)	EV sales, battery installed capacity(GWh)	Monthly

Mandatory Rules：

Supply analysis must specify the layer (mining vs refining)
Demand proxies must clarify conversion assumptions (kWh → kg Li)
Price analysis must distinguish between lithium carbonate and lithium hydroxide </principle>

<principle name="data_level_fallback"> **Data Level Fallback**

Automatically select data sources based on the

data_level

parameter:

data_level	Price Data	Supply and Demand Data	Reliability
`free_nolimit`	CME Futures/Proxy Index	USGS/IEA/Australian Government	Medium
`free_limit`	SMM/Fastmarkets Pages	+ Corporate 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 proxies
The actual data level used must be marked in the output </principle>

<principle name="li_content_conversion"> **Li Content Conversion**

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

Assumption Scenario	kg Li / kWh	Remarks
Conservative Estimate	0.12	Including assumption of increasing LFP proportion
Neutral Estimate	0.15	Mixed NMC/LFP
Aggressive Estimate	0.18	High-nickel NMC dominated

python

li_demand_kt = battery_gwh * kg_per_kwh * 1000  # Unit: kt LCE

Mandatory Rules：

Demand estimates must output three scenarios (conservative/neutral/aggressive)
The output must include the
```
kg_per_kwh_assumption
```
field </principle>

<principle name="regime_classification"> **Price Regime Classification**

Lithium price cycles are divided into four phases:

Regime	Characteristics	Trading Implications
`downtrend`	12-26 week momentum < 0, slope < 0	Bearish dominance, avoid going long
`bottoming`	Momentum converges, volatility decreases, mean reversion	Wait and see, wait for confirmation
`uptrend`	Momentum > 0, slope > 0	Long window opens
`overheat`	Extreme positive momentum, amplified volatility	Profit-taking risk

Indicator Combination：

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

<principle name="etf_transmission"> **ETF Transmission**

The sensitivity of ETFs to lithium prices is affected by their holding 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 has processing fee buffer
Downstream (Battery)	0.3 - 0.8	Affected by competition/technology routes

Calculation Formula：

python

ETF_beta_li = Σ(weight_i * beta_i_to_lithium)

Mandatory Rules：

Must calculate rolling beta (recommended 52-week rolling)
Transmission break judgment: beta < 0.3 and lasts > 8 weeks </principle>

</essential_principles>

<intake> **What operation do you want to perform?**

Full Analysis - Complete supply-demand × price × transmission integrated analysis (generate full report)
Balance Nowcast - Only calculate real-time supply-demand balance estimate (gap expansion/contraction)
Price Regime - Only analyze price patterns and cycle position
ETF Exposure - Only analyze ETF holding structure and lithium price sensitivity
Ingest Data - Extract and standardize data from various data sources

Please respond to continue. </intake>

<routing> | Response | Workflow | Description | |---------------------------------------------------|------------------------------|----------------------------| | 1, "full", "analyze", "完整", "報告", "LIT" | workflows/full-analysis.md | Complete supply-demand × price × transmission integrated analysis | | 2, "balance", "nowcast", "供需", "缺口", "gap" | workflows/balance-nowcast.md | Real-time supply-demand balance estimate | | 3, "price", "regime", "價格", "週期", "型態" | workflows/price-regime.md | Price pattern and cycle analysis | | 4, "etf", "exposure", "holding", "傳導", "敏感度" | workflows/etf-exposure.md | ETF exposure and transmission analysis | | 5, "ingest", "data", "fetch", "抓取", "擷取" | workflows/ingest.md | Data extraction and standardization |

After reading the workflow, please follow its steps completely. </routing>

<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 holding structure and industry chain segmentation
supply-chain-mapping.md	Complete lithium supply chain mapping (mining → chemicals → batteries)
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 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 regime classification
compute_etf_beta.py	ETF transmission sensitivity calculation
visualize_analysis.py	Comprehensive visualization of analysis results
inflection_point_chart.py	Specialized visualization for inflection point analysis ⭐
</scripts_index>

<quick_start> CLI Quick Start:

bash

# Complete analysis of LIT ETF (default 10-year lookback, weekly frequency)
python scripts/lithium_pipeline.py analyze --ticker=LIT --lookback=10 --freq=weekly

# Only calculate supply-demand balance Nowcast
python scripts/lithium_pipeline.py balance --asof=2026-01-16

# Analyze price regimes (lithium carbonate + lithium hydroxide)
python scripts/lithium_pipeline.py regime --chem=both

# Calculate ETF transmission sensitivity to lithium prices
python scripts/lithium_pipeline.py etf-beta --ticker=LIT --window=52

# ✨ Generate visualization charts (complete dashboard)
python scripts/visualize_analysis.py
# Output: output/lithium_analysis_YYYY-MM-DD.png

Visualization Output：

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

Library Quick Start:

python

from lithium_pipeline import LithiumSupplyDemandRadar

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

# Complete analysis
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 is executed successfully:

Correctly identify data levels and use corresponding sources
Supply-demand balance index calculated correctly (including three scenarios)
Clear price regime classification (downtrend/bottoming/uptrend/overheat)
ETF transmission sensitivity calculated correctly (rolling beta)
Output includes complete invalidation conditions
Data sources are traceable (source_id, data_level)
Unit conversion assumptions are clearly marked
Visualization charts are generated and meet specifications (300 DPI, PNG, file name includes date)
Reports and charts are output together in the output/ directory </success_criteria>

<input_schema> Input Parameter Definition

yaml

# Required parameters
etf_ticker: string      # Target ETF (default LIT)
lookback_years: int     # Lookback years (recommended 10-15)
price_freq: string      # weekly | daily (recommended weekly)

# Range parameters
region_focus:           # Key regions for supply/demand (optional)
  - China
  - Australia
  - Chile
  - Argentina
  - US
  - EU

chem_focus: string      # carbonate | hydroxide | both (default both)

# Data level
data_level: string      # free_nolimit | free_limit | paid_low | paid_high

# Data source switches
sources:
  usgs: boolean
  iea_ev_outlook: boolean
  australia_req: boolean
  abs_exports: boolean
  fastmarkets: boolean
  smm: boolean
  etf_holdings: boolean

# Output format
output_format: string   # markdown | json (default markdown)

</input_schema>

<data_pipeline_architecture> Data Pipeline Architecture

[Data Sources]
     |
     v
+--------------------+
|   ingest_sources   |  --> USGS, IEA, Australia REQ/ABS
+--------------------+      Fastmarkets/SMM (methodology/price)
     |                      Global X LIT factsheet
     v
+--------------------+
|   normalize        |  --> Unified schema + unit annotation
+--------------------+
     |
     +-------------------+-------------------+
     |                   |                   |
     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 metric name
value	float	Numeric 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>

lithium-supply-demand-gap-radar

NPX Install

Tags

SKILL.md Content (Chinese)