kayadibi1/h1b-labor-map
GitHub: kayadibi1/h1b-labor-map
一个引文驱动的可复现联邦数据管道，整合多个美国政府数据源，将 H-1B 雇主担保行为与劳动力需求映射比对，帮助用户识别真实担保雇主并生成个性化排名。
Stars: 0 | Forks: 0
# 美国劳动力市场 × H-1B 担保地图
一个可复现、引文驱动的数据 pipeline，将美国劳动力市场需求与雇主的 H-1B 担保行为进行映射比对。它将 DOL LCA、USCIS 批准数据、BLS / OEWS、IPEDS、IRS 和 SEC 文件转化为一个可审计的排名视图，展示哪些雇主切实地在哪些大都会区为哪些职位提供担保。每一条数值规则都可以追溯到带有验证日期的 Federal Register / CFR 引文。完整规范位于 `labor_market_h1b_map_blueprint.md` 中；本 README 介绍操作说明。
**状态：** 已在真实的多 GB 联邦发布数据上完成端到端运行（Phase 0 数据源验证时间 2026-05-27）。数据验证采用的是 `ingest_dol.py` 中一旦出错即高调报错的逐 FY（财年）列映射器（当数据源 schema 发生偏移时，它会报出确切缺失的逻辑列名并停止运行），而不是正式的 schema 验证器。
## 该 pipeline 能解答的问题
1. **切实地说，哪些雇主会担保像我这样的人？**
不是原始的 LCA 数量——LCA 申请严重夸大了实际招聘情况。我们通过 USCIS Initial Approvals（即标题中提到的“新担保”信号）对其进行缩减；对于受配额限制（cap-subject）的雇主，我们还会通过**工资级别加权的抽签概率**（FY2027 及以后规则：Level IV = 4 个抽签名额，Level I = 1 个名额）进行缩减。
2. **我应该瞄准哪些不受配额限制（cap-exempt）的雇主？**
Cap-exempt 雇主（大学、附属非营利组织、非营利研究机构、政府研究机构）完全绕过抽签。对于非 STEM-CIP 申请人来说，这是最切合实际的主要途径；该 pipeline 将其作为一等（first-class）输出予以展示。
3. **我目标职位 × 大都会区哪里确实存在担保需求？**
4. **我应该避开哪些雇主？**（外包公司、低批准率的批量申请工厂、近期触发 WARN Act 裁员的公司。）
## 快速开始
```
# 安装固定的 dependencies（使用 uv；固定于 Python 3.11）
uv sync --extra dev
# 对环境进行 sanity check
uv run python -c "import polars, duckdb, rapidfuzz; print('env ok')"
# 查看 Phase 0 分支决策（CIP 驱动；默认为非 STEM）
uv run python run.py --stage verify
# 检查 / 编辑您的 profile，然后重新验证
notepad user_profile.yaml
uv run python run.py --stage verify
# Dry run 完整的 pipeline（无下载，无 transforms）
uv run python run.py --dry-run
# 完整运行（下载数 GB 的 DOL + USCIS 文件；请预留时间）
uv run python run.py
# 重新运行下个季度，跳过未更改的 sources
uv run python run.py --incremental
# 测试
uv run pytest -q
```
## Phase 0 分支决策（关键）
该 pipeline 会读取 `user_profile.yaml` 中的 `identity.cip_code`，并将其与实时的 DHS STEM-Designated Degree Program List（缓存在 `data/raw/sevp/stem_cip_list_2024-07-23.md` 中）进行比对。该分支决定了您拥有一次抽签机会（非 STEM，12个月 OPT）还是三次机会（STEM，共 36个月 OPT），进而决定 `cap_exempt_only` 是否默认为 TRUE。
**SAIS 相关的 CIP 编码：**
| CIP | 领域 | 是否为 STEM？ |
|---|---|---|
| **45.0603** | Econometrics and Quantitative Economics | 是 |
| **30.4901** | Mathematical Economics | 是 |
| **30.7001** | Data Science | 是 |
| 45.0601 | Economics, General | 否 |
| 45.0605 | International Economics | 否 |
| 45.0901 | International Relations（默认） | 否 |
| 45.0902 | National Security Policy Studies | 否 |
如果您获得的学位 CIP 不是 45.0901，请更新 `user_profile.yaml` 并重新运行 `python run.py --stage verify` 以查看新的分支。
## 架构
```
data/raw # untouched downloads, dated; sha256/ETag tracked
data/staging # cleaned, typed, SOC/NAICS/CBSA standardized parquet
data/marts # final joined fact table + 8 output views (parquet + csv)
data/manifest # phase0_findings.md, sources.json, employer review CSVs
src # ingest_*, entity_resolve, geo_normalize, join, scoring, views
tests # offline fixture-driven unit + smoke tests
config.yaml # pipeline-level rule values (dated + sourced)
user_profile.yaml # your CIP, SOC weights, metros, cap-exempt list, gates
run.py # orchestrator
Makefile # convenience targets
```
### 数据源模块
| 模块 | 数据源 | 备注 |
|---|---|---|
| `ingest_dol.py` | DOL OFLC LCA + PERM xlsx | 逐 FY 列映射器；遇到缺失的必需列时会大声报错 |
| `ingest_uscis.py` | USCIS H-1B Employer Data Hub | 区分 Initial 与 Continuing 的批准/拒绝数 |
| `ingest_bls.py` | BLS API v2 + OEWS 大都会区邮政编码 | OEWS 隐藏值保留为 NULL |
| `ingest_warn.py` | 州 WARN 门户网站（NY/MA/VA/DC + 框架） | 尽力抓取；记录失败日志 |
| `ingest_irs.py` | ProPublica Nonprofit Explorer | Cap-exempt 子类别证据 |
| `ingest_edgar.py` | SEC EDGAR company_tickers.json | 上市公司母公司 CIK |
| `ingest_ipeds.py` | DOE DAPIP 机构名单 | HIGHER_ED 高置信度标记 |
| `ingest_census.py` | OMB CBSA delineation 2023 | 地理标准化 |
### 转换 / 评分
| 模块 | 职责 |
|---|---|
| `entity_resolve.py` | 分层雇主名称解析器（标准化 → 精确匹配 → token-sort ≥ 95 → 人工审查 → 企业集团覆盖） |
| `geo_normalize.py` | 城市/州 → CBSA 编码（带有精选的 DC 大都会区快捷映射） |
| `cap_exempt.py` | 依据 8 CFR 214.2(h)(19)(iii)(C) 判定子类别 + 置信度 |
| `join.py` | 使用 DuckDB 将 LCA / USCIS / OEWS 关联至 `mart_fact.parquet` |
| `scoring.py` | 双轨制 cap-exempt vs cap-subject 真实度评分 + 个人得分 |
| `views.py` | 8 个输出视图 |
## 8 个输出视图（`data/marts/*.parquet` + `.csv`）
1. **`ranked_employers_capexempt`** — 按真实度排序的 Cap-exempt 担保雇主。
2. **`ranked_employers_capsubject`** — 按真实度排序的 Cap-subject 担保雇主（计入抽签权重因素）。
3. **`metro_heatmap`** — CBSA × SOC 的担保量和需求热度图。
4. **`role_trends`** — 2024 年规则变更前后的 SOC 趋势。
5. **`cap_exempt_targets`** — 按子类别划分的免抽签通道。
6. **`red_flags`** — 高 LCA 数量 + 低批准率 / 劳务派遣 / Level 1 批量申请工厂。
7. **`green_card_friendly_employers`** — 按 PERM 申请量排名（数据导入后）。
8. **`personal_top_targets`** — 基于个人得分加权，并根据您的门槛条件过滤。
9. **`timing_calendar`** — 每个雇主的运营外联时间窗口。
（核心排名是 `ranked_employers_*` / `personal_top_targets`；两者均遵循 `gates.min_evidence_tier`，因此小样本雇主绝不会意外排到顶部。）
## 担保真实度的计算方式
**Cap-exempt（无抽签）：**
```
realism_capex = initial_approval_rate
× min(1.0, initial_approvals / n_threshold_capexempt) # default n=3
× (1 - staffing_penalty)
× (1 - layoff_penalty)
```
**Cap-subject（适用抽签，FY2027 及以后受工资加权影响）：**
```
realism_capsub = initial_approval_rate
× Σ pct_level_L × lottery_rate_level_L # FY2027 weighted
× min(1.0, initial_approvals / n_threshold_capsubject) # default n=10
× (1 - staffing_penalty)
× (1 - layoff_penalty)
```
工资级别调整后的中选率（自 FY2027 起生效）位于 `config.yaml > rules.wage_level_adjusted_selection_rate_fy2027`：
| 级别 | 抽签名额 | 大致中选率 |
|---|---|---|
| I | 1 | 17% |
| II | 2 | 34% |
| III | 3 | 51% |
| IV | 4 | 68% |
（假定符合历史 Level 分布；每次季度运行时会根据真实的 DOL 数据重新计算。）
## 每季度重新运行
1. 执行 `git pull`（如果在版本控制下）以获取任何 blueprint 更新。
2. 重新运行 **Phase 0** 刷新数据源 URL + 规则数值：
uv run python run.py --stage verify
阅读 `data/manifest/phase0_findings.md` 并针对发生变化的任何内容更新 `config.yaml`
中的引文。
3. 以增量方式重新运行整个 pipeline：
uv run python run.py --incremental
4. 审查并清理待处理队列（每个只需几分钟）：
- `data/manifest/employer_matches_review.csv` — 新的模糊匹配项
- `data/manifest/geo_review.csv` — 新的未匹配地区
- `data/manifest/cap_exempt_review.csv` — 需人工审查的 cap-exempt 组织
## 当 DOL 更改 schema 时
`ingest_dol.py` 会根据真实的表头构建逐 FY 的列映射器。当 DOL
增加/删除列时：
1. pipeline 会大声报错，指出缺失的逻辑列名及其
实际读到的表头。
2. 将新的物理表头模式添加到
`src/ingest_dol.py` 的 `LOGICAL_COLUMNS` 中。
3. 重新运行。
逐 FY 的映射器会提交到 `data/manifest/dol_column_mappers/`，因此
历史记录是可审计的。
## 已知局限性
- **实时需求**：此版本中无法访问 Lightcast/Revelio。需求
基于 BLS 数据建模（存在 1–6 个月的滞后）。前瞻性声明带有
根据 `accuracy_guardrails` 设定的数据滞后标签。
- **WARN 覆盖范围**：此版本中只有 NY/MA/VA/DC 有可用的抓取器。
CA/TX/WA/NJ/IL/FL/GA 门户网站严重依赖 JS，需要针对各州编写 Playwright
抓取器（TODO）。在没有数据时会回退；pipeline 不会崩溃。
- **PERM 下游使用**：`ingest_dol.py` 可以导入 PERM 文件，但
join 目前只呈现 LCA 数据。在 PERM 阶段被接入 join 之前，
PERM 排名视图将输出空文件。
- **单一雇主的子公司链条**：企业集团覆盖文件
涵盖了 FAANG / 咨询公司 / 大型银行等层级。长尾子公司
会通过 token-sort 处理，可能需要手动添加审查条目。
## 许可证 / 数据条款
代码：MIT（见 `LICENSE`）。数据：所有主要数据源均为美国政府公共领域发布数据。WARN
公告、IPEDS 和 SEC EDGAR 不带任何使用限制。ProPublica
Nonprofit Explorer 要求使用礼貌的 User-Agent（在 `.env` 中设置
`PROPUBLICA_CONTACT_EMAIL`）。BLS API 需要一个免费的注册
密钥（在 `.env` 中设置 `BLS_API_KEY`）。
标签：DuckDB, ETL管道, Polars, 代码示例, 劳动力市场, 后端开发, 安全规则引擎, 数据分析, 数据工程, 逆向工具