nickel-concentration-risk-analyzer

<essential_principles> Nickel Supply Concentration Analysis Core Principles

All analyses must first establish the basis; different bases lead to differences in order of magnitude:

Basis	Description	Typical Numerical Difference
t_Ni_content	Nickel metal content (default for this Skill)	Baseline value
t_ore_wet	Wet tonnes of ore	Can reach 50-100x
t_NPI_product	NPI product tonnes	Approximately 10-15% Ni
t_matte	Nickel matte tonnes	Approximately 75% Ni

Mandatory Rules：

• If the basis of input data is unclear, it must be flagged as model_estimate
• Data with different bases must not be mixed in the same analysis
• Output must include the unit field

Each stage of the nickel supply chain must be calculated separately:

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

• mined: Mine production (nickel metal content)
• refined: Refined production (including smelting)
• "Indonesia 60% market share" usually refers to mined nickel content

Tier	Characteristics	Source	Use
0	Free, stable, consistent basis	USGS MCS, INSG	Baseline backbone
1	Free but scattered, requires integration	Company annual reports, financial reports	Mine-level anchor
2	Paid, more timely and complete	S&P Global MI	Accuracy verification, basis alignment
3	Recent policy/quota information	News, official announcements	Scenario input

Priority Order: Tier 0 establishes baseline → Tier 1 supplements mine-level → Tier 2 verifies accuracy

Policy production cuts do not need to be 100% implemented to cause an impact. Default model:

expected_cut = cut_value * execution_prob  # 預設 execution_prob = 0.5

Three-layer output:

• Hard cut: Policy fully implemented
• Half success: 50% implementation (or specified value)
• Soft landing: Only delaying commissioning/only cutting new capacity

Indicator	Formula	Interpretation
Country Share	country_prod / global_prod	Single-country share
CR_n	Σ top_n_share	Top N country/mine concentration
HHI	Σ share²	Market concentration (0-10000)
Policy Leverage	cut_amount / global_prod	Proportion of global supply that policy can lever

HHI interpretation: < 1500 low concentration, 1500-2500 moderate, > 2500 high concentration </essential_principles>

1. Analyze - Analyze global nickel supply structure and concentration indicators (CR_n, HHI, country share)
2. Scenario - Simulate the impact of policy/production cut scenarios on supply (RKAB quotas, export restrictions, etc.)
3. Validate - Verify the data basis and source reliability of market claims
4. Ingest - Extract and standardize nickel supply data from various data sources

Wait for a response before continuing.

After reading the workflow, please follow its steps completely.

<reference_index> Reference Documents (references/)

Document	Content
data-sources.md	Detailed descriptions and URLs of all data sources
unit-conversion.md	Unit conversion rules and assumptions
concentration-metrics.md	Detailed calculation methods for concentration indicators
indonesia-supply-structure.md	Indonesia nickel supply structure and key industrial parks
mine-level-anchors.md	Production anchors for major mines/industrial parks
failure-modes.md	Failure modes and mitigation strategies
</reference_index>

<workflows_index>

Workflow	Purpose
analyze.md	Supply structure and concentration analysis (CR_n, HHI, share)
scenario-engine.md	Policy Scenario Shock Simulation
validate-sources.md	Data Source and Definition Verification
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
nickel_pipeline.py	Core Data Pipeline
ingest_sources.py	Data Source Extraction
compute_concentration.py	Concentration Metric Calculation
scenario_impact.py	Scenario Shock Simulation
visualize_concentration.py	Concentration Analysis Visualization Charts
visualize_scenario.py	Scenario Shock Visualization Charts
</scripts_index>

<quick_start> CLI Quick Start:

# 分析當前全球鎳供給集中度
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 Quick Start:

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> When the Skill executes successfully:

• Correctly identifies data definitions (mined/refined/nickel content)
• Output includes unit field annotations
• Concentration metrics calculated correctly (share, CR_n, HHI)
• Scenario analysis outputs three-tier results (hard/half/soft)
• Data sources are traceable (source_id, confidence)
• Unit warnings trigger correctly (ore vs content) </success_criteria>

<input_schema> Input Parameter Definition

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

<data_pipeline_architecture> Data Pipeline Architecture

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

Standardized Field Schema:

Field	Type	Description
year	int	Year
country	string	Country
supply_type	string	mined/refined
product_group	string	NPI/matte/MHP/class1...
value	float	Value
unit	string	t_Ni_content / t_ore_wet / t_NPI_product
source_id	string	USGS/INSG/S&P/Company/Other
confidence	float	Source Quality Score (0-1)
</data_pipeline_architecture>