Nickel Concentration Risk Analyzer

所有分析必須先確定口徑，不同口徑會導致數量級差異：

強制規則：

• 若輸入數據口徑不明確，必須標記為 model_estimate
• 同一分析中不得混用不同口徑數據
• 輸出必須包含 unit 欄位

鎳供給鏈各階段必須分開計算：

Mine Production (mined) → Intermediate (NPI/Matte/MHP) → Refined (class1/class2)

• mined: 礦場產量（鎳金屬含量）
• refined: 精煉產量（含冶煉）
• 「印尼 60% 市佔」通常指 mined nickel content

優先順序：Tier 0 建立 baseline → Tier 1 補充 mine-level → Tier 2 驗證精度

政策減產不需 100% 執行即可造成衝擊。預設模型：

expected_cut = cut_value * execution_prob  # 預設 execution_prob = 0.5

三層輸出：

• Hard cut: 政策完全落地
• Half success: 執行 50%（或指定值）
• Soft landing: 只延遲投產/只砍新增產能

HHI 判讀：< 1500 低集中、1500-2500 中等、> 2500 高集中

1. Analyze - 分析全球鎳供給結構與集中度指標（CR_n, HHI, country share）
2. Scenario - 模擬政策/減產情境對供給的衝擊（RKAB配額、出口限制等）
3. Validate - 驗證市場說法的數據口徑與來源可靠度
4. Ingest - 從各數據源擷取並標準化鎳供給數據

等待回應後再繼續。

讀取工作流程後，請完全遵循其步驟。

# 分析當前全球鎳供給集中度
python scripts/nickel_pipeline.py analyze --asof=2026-01-16 --scope=mined

# 生成集中度視覺化圖表（輸出到 output/ 目錄，檔名包含日期）
python scripts/visualize_concentration.py

# 模擬印尼減產 20% 的情境衝擊
python scripts/nickel_pipeline.py scenario --cut=20 --target=Indonesia --exec-prob=0.5

# 生成情境衝擊視覺化圖表
python scripts/visualize_scenario.py

# 驗證「印尼 60% 市佔」的數據來源
python scripts/nickel_pipeline.py validate --claim="Indonesia 60% share"

Library 快速開始：

from nickel_pipeline import NickelConcentrationAnalyzer

analyzer = NickelConcentrationAnalyzer(
    asof_date="2026-01-16",
    scope={"supply_type": "mined", "unit": "t_Ni_content"},
    data_level="free_nolimit"
)

# 計算集中度指標
result = analyzer.compute_concentration()
print(f"Indonesia share: {result['indonesia_share_2024']:.1%}")
print(f"HHI: {result['hhi_2024']:.0f}")

# 必要參數
asof_date: string (ISO)  # 分析基準日
horizon:
  history_start_year: int
  history_end_year: int
  forecast_end_year: int

# 範圍參數
scope:
  supply_type: string  # mined | refined | nickel_content (必填)
  product_group: string  # class1 | class2 | NPI | matte | MHP | mixed (選填)
  countries: array[string]  # 預設: Indonesia, Philippines, Russia, Canada, Australia, Other

# 情境參數 (scenario workflow 專用)
policy_scenarios:
  - name: string
    target_country: string  # 預設: Indonesia
    policy_variable: string  # ore_quota_RKAB | mine_permit | export_rule | smelter_capacity
    cut_type: string  # pct_global | pct_country | absolute
    cut_value: number
    start_year: int
    end_year: int
    execution_prob: number  # 0-1, 預設 0.5

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

[Data Sources]
     |
     v
+-------------------+
|   ingest_sources  |  --> Tier 0: USGS, INSG
+-------------------+      Tier 1: Company reports
     |                     Tier 2: S&P Global (optional)
     v
+-------------------+
|   normalize       |  --> 統一 schema + 單位標註
+-------------------+      (year, country, supply_type, value, unit, source_id)
     |
     v
+-------------------+
| compute_concentration | --> share, CR_n, HHI
+-------------------+
     |
     v
+-------------------+
|   scenario_impact |  --> expected_cut, global_hit_pct
+-------------------+
     |
     v
+-------------------+
|   generate_output |  --> JSON + Markdown
+-------------------+
     |
     v
[Analysis Result]

標準化欄位 Schema：