# CAISO SP15 OASIS MCP

把 [CAISO OASIS](https://www.caiso.com/systems-applications/portals-applications/open-access-same-time-information-system-oasis) 上和 SP15 有关的日前电价、南部边界、影子价格下到本地 SQLite，再用 MCP 查询。给同组的人训练模型用。数据是 CAISO 的公开披露，这个仓库只提供下载和查询。

在线接口大约只保留 **39 个月**。默认从 `2023-08-01` 同步到太平洋时区的今天。2016 年以后、超出 39 个月的电价在 [Historical OASIS Data Downloader](https://oasis-bulk.caiso.com/)，要自己的 AWS 账号，下载流量由下载方付。本工具不会去连那个桶。

## SP15 在这里指什么

| 名称 | OASIS 里的名字 | 说明 |
| --- | --- | --- |
| SP15 日前电价 | `TH_SP15_GEN-APND` | 枢纽电价，含 LMP、MCC、MCE、MCL、MGHG |
| 南部负荷电价 | `DLAP_SCE-APND`、`DLAP_SDGE-APND`、`DLAP_VEA-APND` | SCE、SDG&E、Valley Electric |
| 南部辅助服务 | `AS_SP26` | 现货里没有叫 SP15 的辅助服务区。Path 26 以南就是这个区 |
| Path 26 | Midway–Vincent 500kV | SP15 和 ZP26 之间的运行边界，影子价格标成 `sp15` |
| Path 15 | Gates–Midway 一带 | 枢纽名字的来源，影子价格标成 `path15`，默认和 SP15 一起返回 |

南部联络线包括 Palo Verde、Delaney、Hassayampa、North Gila、Blythe、Eldorado、Mead、Marketplace、Adelanto、IPP DC、Victorville、Sylmar、IID、VEA、Silver Peak 和 CFE。Malin、NOB、COI、Tracy 这些北部断面没有收进来。完整名单在 `list_catalog`。

`region_tag` 是按约束名字做的地名分类，原始名字原样保存。`query_shadow_prices` 的 `region=all` 可以看到当天披露的全部日前支路约束，不只有南部。

影子价格只在**绑定**的小时出现。空值不是 0 美元。

方向 `I` 是进口到 CAISO，`E` 是从 CAISO 出口。OASIS 把 `OTC_MW` 标成 Hourly TTC，把 `TTC_MW` 标成 Seasonal TTC。`useage_mw` 沿用他们的拼写，意思是未安排的输电权容量。

## 安装

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m sp15_oasis sync
```

第一次同步大约要几十分钟。请求之间停 7 秒，这是为了待在 CAISO 的可接受使用范围里。不要把 `--sleep` 改小，也不要几个人同时对 OASIS 做全量同步。一个人同步完，把 `data/sp15.sqlite` 拷给别人即可。

每天补数再跑一次同一条命令。已经结束的历史块会跳过，只刷新还包含今天的那一块。

只补某一张表：

```bash
.venv/bin/python -m sp15_oasis sync --dataset dam_lmp
.venv/bin/python -m sp15_oasis status
```

数据库在 `data/sp15.sqlite`，不进 Git。换路径用环境变量 `SP15_DB`。

## 接到 Cursor

把下面放进 Cursor 的 MCP 配置，路径改成自己的克隆目录。改完后重载 MCP。

```json
{
  "mcpServers": {
    "caiso-sp15": {
      "command": "/ABS/PATH/TO/repo/.venv/bin/python",
      "args": ["-m", "sp15_oasis"],
      "env": { "SP15_ROOT": "/ABS/PATH/TO/repo" }
    }
  }
}
```

服务走 stdio，只在本机查询本地库，不会把 OASIS 再包成一个公开网站。

从零安装、同步和接到 Cursor 见 [MCP使用指南](MCP使用指南.md)。字段中文名、OASIS 原名和单位见 [数据指标对照表](数据指标对照表.md)。

每天 01:15（这台电脑的本地时间）自动补当天已经发布的数据。没采全会在这台 Mac 上弹通知，并持续补到 02:00：

```bash
./scripts/install-daily-sync.sh
```

## 工具

- `list_catalog`：节点、联络线、单位、库里有多少天
- `dataset_coverage`：每张表的起止运行日和同步进度
- `query_dam_prices`：日前电价，美元/MWh
- `query_ancillary`：AS_SP26 日前价格（美元/MW）或需求（MW）
- `query_tie_atc`：南部联络线日前 ATC，MW
- `query_tie_usage`：南部联络线日前 TTC、OTC、计划潮流、TRM
- `query_shadow_prices`：日前支路/诺模图或联络线约束影子价格
- `training_panel`：一小时一行的训练表
- `query_sql`：一条只读 SELECT

日期都是运行日 `YYYY-MM-DD`，含首尾。`training_panel` 一次最多 5000 小时，用 `offset` 翻页。

导出整段训练表：

```bash
.venv/bin/python -m sp15_oasis export \
  --start 2024-01-01 --end 2024-12-31 \
  --out data/sp15_2024.csv
```

`data/*.csv` 被 git 忽略。

主干联络线列是 Palo Verde、Eldorado、Mead、IPP DC–Adelanto、North Gila、Blythe、Sylmar、CFE。`ties=ALL` 会把目录里的南部联络线都摊开。列名 `_i` 是进口，`_e` 是出口，`_atc` 是可用容量，`_ene` 是计划净交换。

## 报表

全部来自 `https://oasis.caiso.com/oasisapi/SingleZip`，市场都是 DAM。

| 本地表 | OASIS 报表 | 内容 |
| --- | --- | --- |
| `dam_lmp` | `PRC_LMP` v12 | 四个节点的日前电价和分量 |
| `as_price` | `PRC_AS` v12 | AS_SP26 出清价 |
| `as_requirement` | `AS_REQ` v1 | AS_SP26 需求 |
| `tie_atc` | `TRNS_ATC` v1 | 南部联络线 ATC |
| `tie_usage` | `TRNS_USAGE` v1 | 南部联络线容量和计划潮流 |
| `intertie_shadow` | `PRC_CNSTR` v1 | 联络线约束影子价格，南部打了 `sp15_related` |
| `nomogram_shadow` | `PRC_NOMOGRAM` v1 | 支路和诺模图影子价格，带 `region_tag` |

如果以后从批量站点拿到同样表头的 CSV，可以叠进已有的库：

```bash
.venv/bin/python -m sp15_oasis import-csv dam_lmp /path/to/PRC_LMP.csv
```

## 测试

```bash
.venv/bin/python -m unittest discover -s tests -v
```

测试不访问 OASIS。