nickel-concentration-risk-analyzer

<essential_principles> 鎳供給集中度分析 核心原則

<principle name="unit_enforcement"> 口徑先行（Unit Enforcement）

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

強制規則：

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

</principle>

<principle name="supplytypeclarity"> 供給類型區分（Supply Type Clarity）

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

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

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

</principle>

<principle name="data_tiering"> 數據分層策略（Data Tiering）

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

<principle name="execution_probability"> 政策執行機率（Execution Probability）

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

expected_cut = cut_value * execution_prob  # 預設 execution_prob = 0.5

三層輸出：

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

</principle>

<principle name="concentration_metrics"> 集中度指標定義

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

<intake> 您想要執行什麼操作？

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

等待回應後再繼續。 </intake>

<routing>

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

<reference_index> 參考文件 (references/)

</reference_index>

<workflows_index>

</workflows_index>

<templates_index>

</templates_index>

<scripts_index>

</scripts_index>

<quick_start> CLI 快速開始：

# 分析當前全球鎳供給集中度
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}")

</quick_start>

<success_criteria> Skill 成功執行時：

• 正確識別數據口徑（mined/refined/nickel content）
• 輸出包含 unit 欄位標註
• 集中度指標計算正確（share, CR_n, HHI）
• 情境分析輸出三層結果（hard/half/soft）
• 數據來源可追溯（source_id, confidence）
• 單位警告正確觸發（ore vs content）

</success_criteria>

<input_schema> 輸入參數定義

# 必要參數
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

</input_schema>

<datapipelinearchitecture> 數據流水線架構

[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：

</datapipelinearchitecture>