wasde-ingestor

<essential_principles> WASDE Ingestor 核心原則

1. 商品範圍

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

類別	商品	US 單位	World 單位
Grains	Wheat, Corn, Rice, Barley, Sorghum, Oats	million bushels / cwt	million metric tons
Oilseeds	Soybeans, Soybean Oil, Soybean Meal	million bushels / pounds	million metric tons
Cotton	Upland, Pima	million 480-lb bales	million 480-lb bales
Livestock	Beef, Pork, Poultry, Eggs, Dairy	million lbs / dozen / lbs	- (US only)
Sugar	Sugar	1,000 short tons	- (US + Mexico only)

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 - 配置商品範圍、輸出路徑等參數

等待回應後再繼續。

| Response | Workflow | Description | |-----------------------------------------|------------------------|---------------------| | 1, "ingest", "fetch", "parse", "latest" | workflows/ingest.md | 抓取解析 WASDE 報告 | | 2, "backfill", "historical", "batch" | workflows/backfill.md | 批量回補歷史數據 | | 3, "validate", "check", "verify" | workflows/validate.md | 驗證數據一致性 | | 4, "configure", "config", "setup" | workflows/configure.md | 配置參數 |

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

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

文件	內容
commodities-overview.md	所有商品總覽與單位對照
grains.md	穀物類（Wheat, Corn, Rice, Barley, Sorghum, Oats）
oilseeds.md	油籽類（Soybeans, Soybean Oil, Soybean Meal）
cotton.md	棉花（US & World）
livestock.md	畜產品（Beef, Pork, Poultry, Eggs, Dairy）
sugar.md	糖（US & Mexico）
validation-rules.md	驗證規則與合理性檢查
failure-modes.md	失敗模式與緩解策略
</reference_index>

<workflows_index>

Workflow	Purpose
ingest.md	抓取解析單一或多個 WASDE 報告
backfill.md	批量回補歷史數據
validate.md	驗證數據一致性與修正追蹤
configure.md	配置商品範圍與輸出設定
</workflows_index>

<templates_index>

Template	Purpose
config.yaml	標準配置文件模板
us-balance-schema.yaml	US 供需表 schema
world-balance-schema.yaml	World 供需表 schema
</templates_index>

<scripts_index>

Script	Purpose
discover_releases.py	發現 WASDE 發布日期與 URL
fetch_report.py	下載 PDF/HTML 報告
parse_tables.py	解析表格提取數據
validate_data.py	執行驗證檢查
</scripts_index>

<examples_index> 範例輸出 (examples/)

文件	內容
corn_us_balance.json	美國玉米供需平衡表範例
wheat_world_balance.json	世界小麥供需平衡表範例
ingest_status_success.json	成功執行的狀態報告範例
backfill_result.json	批量回補作業結果範例
</examples_index>

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