jasonrkeen/global-diamond-supply-value-intelligence-model

# 全球钻石供应与价值情报模型 这是一个可复现的研究流水线，用于考察天然原钻供应、地理集中度、综合单位价值、贸易摩擦、需求状况、实验室培育钻石替代压力以及估值的不确定性。 本项目将官方观测数据、经核实的生产商披露、初步估算、概率预测和条件情景区分开来。它被设计为透明的商品情报研究，而非钻石鉴定估价或投资工具。 ## 它能产出什么 - 年度供应量、价值、HHI 集中度以及价值压力指标 - 最新的各国产量敞口 - 设定随机种子的 5,000 次蒙特卡洛代理单位价值区间 - 产量图表和自动化情报简报 - 交互式 Streamlit 情报仪表板 - 基于生产商校准的 2025 年估算和 2026 年预测 - 自动生成的两页执行摘要 PDF 简报 - 针对钻石异质性的明确方法论限制说明 ## 快速开始 ``` python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate pip install -r requirements.txt python main.py ``` 在流水线完成后启动交互式仪表板： ``` streamlit run app.py ``` 该仪表板将官方观测数据、初步估算和预测区分开来；展示不确定性区间、Comtrade 覆盖范围、指定情景、驱动因素敏感度、经核实的生产商披露以及已知的证据局限性。 每次流水线运行还会在 `output/pdf/diamond_supply_value_intelligence_brief.pdf` 生成一份两页的执行摘要 PDF 简报。其中包括核心指标、基于分类感知的预测区间、图表、覆盖范围、数据治理和局限性说明。 使用以下命令运行测试套件： ``` python -m pytest -q ``` ## 当前参考结果 使用官方的 2024 年 KP（Kimberley Process）全球摘要以及内置的经核实披露登记表，当前的参考运行结果大约为： - 107.9 百万克拉的 2024 年官方产量； - 102.8 百万克拉的基于生产商校准的 2025 年中位数估算； - 105.2 百万克拉的 2026 年中位数预测； - 2026 年 P10-P90 区间接近 95.2-115.6 百万克拉；以及 - 受监管的预测置信分数为 46.2/100。 随着数据源、覆盖范围和假设的更新，结果也会发生变化。请在本地复现这些结果，而不是将 README 中的数字视为实时报价。 ## 官方数据模式 将 `.env.example` 复制为 `.env`，然后设置 `DIAMOND_LIVE_DATA=1`。流水线将使用官方的 `comtradeapicall.previewFinalData()` 函数，该函数不需要 API 密钥。它会分别请求每个报告国-年份数据，指定伙伴为 `World`，包含四个钻石子目（`710210`、`710221`、`710231`、`710239`）以及进口/出口贸易流向。每个微小的请求量都能轻松保持在预览限制之下。 成功的报告国-年份响应会被缓存在 `data/cache/comtrade` 下；后续运行不会再次请求这些观测数据。`COMTRADE_REQUEST_DELAY` 控制着请求配速，瞬时失败会进行指数退避重试。部分完成的响应会在数据源登记表中标记为 `partial`，而不会被当作完整数据呈现。 一个为空但成功的 Comtrade 响应会被记录上持久的 `no_data` 标记，且不会被重复请求。流水线会写入 `comtrade_coverage_matrix.csv`，在 `latest_reporter_trade.csv` 中选择每个报告国的最新可用周期，并生成一张按区段划分的贸易额图表。这使得不完整的官方报告依然可见，而不会将数据缺失等同于零贸易或技术故障。 Kimberley Process 的产量统计采用受控的手动导入工作流，因为公开的统计接口没有提供稳定且文档化的 API。请下载官方表格，将其字段转换为 `data/external/kimberley_process_production_template.csv` 中定义的 schema，并将其保存为： ``` data/external/kimberley_process_production.csv ``` 对于首选的官方 PDF 路径，请在 `.env` 中设置 `KP_GLOBAL_SUMMARY_URL` 和 `KP_EXPECTED_YEAR`，然后运行： ``` python download_kp.py python main.py ``` 下载器会验证 PDF 签名。解析器会提取参与国的产量、进口和出口字段，重新计算每克拉的产值，拒绝存在实质性数据不一致的表格，并保存标准化的缓存文件。如果 KP 更改了其 PDF 版式，该数据源会被标记为 `invalid`；请使用标准化的 CSV 模板，而不是默默接受错位的列。 当文件通过 schema 验证后，它将替换掉演示用的产量序列。`outputs/data/source_status.csv` 会记录每个数据层的状态：是实时的、缓存的、本地提供的、已禁用的、无效的，还是不可用的。 USGS 的工业钻石和宝石出版物被保留作为背景参考数据源，而不会被合并到天然宝石级原钻的产量中。工业合成钻石的产量和价格属于具有不同经济学意义的序列，如果强行合并，将会扭曲天然钻石的价值指数。 ## 模型逻辑 价值压力指数结合了供应紧张度（30%）、需求强度（30%）、贸易摩擦（25%）和实验室培育钻石压力（-15%）。HHI 用于衡量国家级的生产集中度。蒙特卡洛情景会在最新的综合单位价值基础上，对供应、需求、贸易摩擦和实验室培育钻石替代因素进行冲击测试。 这些权重是透明的分析假设，而不是拟合出的因果估算值。在用于决策之前，应先进行敏感性测试和专家校准。 ## 2025 年初步估算与 2026 年预测 当存在官方的 KP 产量基准时，流水线会运行设定随机种子的 10,000 次路径预测。2025 年这一层级被标记为 `preliminary_estimate`；2026 年被标记为 `forecast`。产量和单位价值驱动因素存储在 `data/forecast/forecast_drivers.csv` 中，包含数据源类别、置信度、平均效应、波动率和注释。输出结果包括 P10/P50/P90 区间、压缩后的模拟数据、元数据和一张预测图表。 当官方的 2025 年 KP 实际数据可用时，2025 年估算将被自动指定进行替换。预测假设属于情景输入，而非因果估算，绝不可被表述为钻石报价或投资指导。 如果存在经核实的生产商披露数据，产量路径将基于生产商数据进行校准。2025 年全年实际数据将被固定；季度观测数据和次要证据会被排除在外。建模得出的 2025 年变动仅适用于 2024 年官方基准数据中未覆盖的残余部分。经核实的 2026 年生产商指导数据会被直接抽样，而一般性的产量冲击则应用于剩余市场。`producer_calibration_bridge.csv` 会记录已覆盖的实际数据、指导数量以及残余部分的计算方法。 预测治理输出结果包括指定的下行/基准/上行情景、驱动因素敏感度登记表、置信分数，以及可选的经核实生产商披露登记表。请将 `producer_disclosures_template.csv` 复制为 `producer_disclosures.csv`，保留原始来源的 URL 和发布日期，只有在核查了相关的公司或政府披露信息后，才能将某一行标记为 `verified`。 内置的初始登记表使用了 De Beers、Petra Diamonds 和 Lucara Diamond 的主要公司披露数据。报告期和基准差异在注释中予以保留。每增加一家不同的已核实生产商，都会带来保守的 3 分置信度提升，上限为 15 分；这是一个数据覆盖范围的代理指标，而不是关于统计准确性的声明。校准计算过程会被写入 `forecast_confidence_calibration.csv`。 ## 文档 - [方法论](docs/METHODOLOGY.md) - [数据字典](docs/DATA_DICTIONARY.md) - [数据源登记表](docs/SOURCES.md) ## 数据路线图 包含的 CSV 是一个演示数据集，由经过四舍五入的、说明性的市场观测数据汇编而成。它并不被视为具有权威性的历史序列。正式发布版应针对以下内容添加特定于数据源的适配器和溯源字段： - Kimberley Process 产量和原钻贸易统计数据 - USGS 矿产商品摘要 - UN Comtrade HS 7102 贸易流向 - 各公司的产量和库存披露 - World Bank/IMF 宏观经济指标 - 官方制裁和进口限制公告 ## 重要限制说明 钻石不是一种同质化的商品。综合的每克拉价格可能会因为钻石组合的变化而发生变化。它是一个代理指标，而不是宝石学鉴定估价，也不是可直接交易的现货价格。本项目将分析信号与报价区分开来，不应被用作投资建议。 ## 仓库结构 ``` app.py Streamlit intelligence dashboard data/external/ User-supplied official KP source data/forecast/ Drivers, scenarios, disclosures, limitations data/sample/ Demonstration fallback input docs/ Methodology, dictionary, source register src/ Ingestion, scoring, forecasts, governance, reports tests/ Reproducibility and validation tests output/pdf/ Generated executive PDF outputs/ Generated charts, data, reports, forecast artifacts download_kp.py Controlled official KP PDF downloader main.py End-to-end pipeline entry point ``` ## 许可证 MIT。对于后续添加的每一个实时数据源，请自行核实其授权和再分发条款。

标签：Kubernetes, Python, 代码示例, 供应链分析, 商品智能, 安全规则引擎, 数据分析, 无后门, 蒙特卡洛模拟, 逆向工具, 量化预测