wasde-ingestor

<essential_principles> WASDE Ingestor 核心原則

1. 商品範圍

WASDE 涵蓋三大類商品，每類有不同的表格結構與單位：

2. 表格結構一致性

所有供需表遵循相同的平衡公式：

Ending Stocks = Beginning Stocks + Production + Imports - Total Use - Exports

3. 版本控制

• 每月報告可能修正前期數據
• 使用 content_hash 追蹤數據變化
• 保留 revision_flag 標記修正值

4. 解析優先級

1. PDF 結構化解析（優先）
2. HTML 表格解析（fallback）
3. TXT 固定寬度解析（legacy） </essential_principles>

1. Ingest – 抓取並解析最新或指定月份的 WASDE 報告
2. Backfill – 批量回補歷史 WASDE 數據
3. Validate – 驗證現有數據與最新報告的一致性
4. Configure – 配置商品範圍、輸出路徑等參數

等待回應後再繼續。

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

<reference_index> 商品參考文件 (references/)

<workflows_index>

<templates_index>

<scripts_index>

<examples_index> 範例輸出 (examples/)

<quick_start> CLI 快速開始：

# 抓取最新報告的所有商品
macro-skills wasde ingest --commodities=all --out=./data

# 只抓取穀物類
macro-skills wasde ingest --commodities=grains --out=./data

# 回補過去 24 個月的大豆數據
macro-skills wasde backfill --commodity=soybeans --months=24 --out=./data

# 驗證現有數據
macro-skills wasde validate --data-dir=./data

Library 快速開始：

from macro_skills.wasde import WASDEIngestor

ingestor = WASDEIngestor(
    commodities=["wheat", "corn", "soybeans"],
    scope=["us", "world"],
    output_dir="./data/wasde"
)

result = ingestor.ingest_latest()
print(result.status)

</quick_start>

<success_criteria> Skill 成功執行時：

• 正確識別商品類別與對應表格
• 解析所有指定商品的供需數據
• 單位正確轉換與標記
• 通過平衡公式驗證
• 輸出標準化 parquet 數據集
• 生成 ingest_status 報告 </success_criteria>

<detailed_usage_examples> 詳細使用範例

範例 1：抓取最新玉米與大豆數據

User: 幫我抓取最新 WASDE 的玉米和大豆供需數據

Assistant 執行步驟:
1. 讀取 workflows/ingest.md
2. 呼叫 discover_releases.py 找到最新發布 (2025-01-10)
3. 下載 PDF 報告
4. 解析 corn_us, corn_world, soybeans_us, soybeans_world 表格
5. 驗證平衡公式
6. 輸出 parquet 檔案
7. 回報 ingest_status

預期輸出:
- ./data/wasde/curated/corn_us_balance.parquet
- ./data/wasde/curated/corn_world_balance.parquet
- ./data/wasde/curated/soybeans_us_balance.parquet
- ./data/wasde/curated/soybeans_world_balance.parquet

範例 2：回補歷史小麥數據並追蹤修正

User: 回補過去 12 個月的小麥數據，我想追蹤 USDA 的修正歷程

Assistant 執行步驟:
1. 讀取 workflows/backfill.md
2. 確定日期範圍 (2024-01 至 2024-12)
3. 依序處理 12 期報告
4. 比對每期數據，標記修正值
5. 輸出包含 revision_flag 的完整歷史數據

預期輸出:
- 12 期小麥數據
- 修正追蹤報告

範例 3：驗證現有數據一致性

User: 檢查我現有的 WASDE 數據是否與最新報告一致

Assistant 執行步驟:
1. 讀取 workflows/validate.md
2. 載入現有 parquet 檔案
3. 抓取最新報告
4. 逐欄位比對
5. 標記差異與修正
6. 輸出驗證報告

預期輸出:
- validation_report.json (差異列表)
- 修正建議

</detailed_usage_examples>

<data_pipeline_architecture> 數據流水線架構

[USDA WASDE Website]
         |
         v
+-------------------+
| discover_releases |  --> 找到 PDF URL 與發布日期
+-------------------+
         |
         v
+-------------------+
|   fetch_report    |  --> 下載 PDF (fallback: HTML)
+-------------------+
         |
         v
+-------------------+
|   parse_tables    |  --> 提取供需表格數據
+-------------------+
         |
         v
+-------------------+
|   normalize_data  |  --> 標準化欄位與單位
+-------------------+
         |
         v
+-------------------+
|   validate_data   |  --> 平衡公式與範圍檢查
+-------------------+
         |
         v
+-------------------+
|   write_output    |  --> Parquet / JSON
+-------------------+
         |
         v
[Curated Dataset]

目錄結構：

data/wasde/
├── raw/                    # 原始 PDF 檔案
│   └── 2025-01-10/
│       └── wasde0125.pdf
├── intermediate/           # 中間解析結果
│   └── 2025-01-10/
│       ├── tables.json
│       └── ingest_status.json
└── curated/                # 最終標準化數據
    ├── corn_us_balance.parquet
    ├── corn_world_balance.parquet
    ├── wheat_us_balance.parquet
    └── ...

</data_pipeline_architecture>