gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive update of all documentation - Paris, wind analysis, VPS deploy, supported cities table

Browse Source
This commit is contained in:
AmandaloveYang
2026-02-18 09:49:40 +08:00
parent 3f4f31d24b
commit d533bd5b21
3 changed files with 173 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MARKET_DISCOVERY.md
+3
View File
@@ -1,5 +1,8 @@
# Polymarket Weather Market Discovery Technical Documentation # Polymarket Weather Market Discovery Technical Documentation
> ⚠️ **Current Status: Suspended**
> The automated market discovery and monitoring engine described here has been commented out in `run.py`. The system currently operates in "passive query mode" — weather analysis is only triggered by the `/city` command.
This document explains the technical implementation of how PolyWeather identifies and tracks weather markets on Polymarket. This document explains the technical implementation of how PolyWeather identifies and tracks weather markets on Polymarket.
## 1. Data Sources ## 1. Data Sources
README.md
+106 -42
View File
@@ -1,6 +1,6 @@
# 🌡️ PolyWeather: Real-time Weather Query & Analysis Bot # 🌡️ PolyWeather: Real-time Weather Query & Analysis Bot
An intelligent weather information bot designed to provide ultra-fast, live meteorological data, high-fidelity forecasts, and smart trend analysis. Built for speed and accuracy, it bypasses network caching to deliver the most up-to-date reports from global weather stations. An intelligent weather bot for prediction markets and professional weather betting. Fetches ultra-fresh data directly from global weather stations, bypassing CDN caches, and provides automated trend analysis in plain language.
## 🚀 Quick Start ## 🚀 Quick Start
@@ -8,19 +8,53 @@ An intelligent weather information bot designed to provide ultra-fast, live mete
- **Python 3.11+** - **Python 3.11+**
- Dependencies: `pip install -r requirements.txt` - Dependencies: `pip install -r requirements.txt`
- **Environment**: Configure `METEOBLUE_API_KEY` in `.env` to enable high-precision London forecasts. - **Environment Variables**: Set `TELEGRAM_BOT_TOKEN` in `.env` (required). Optionally set `METEOBLUE_API_KEY` for London high-precision forecasts.
### Running Locally (Windows/Linux) ### VPS Deployment (Recommended)
**First-time setup:**
```bash ```bash
# Windows git clone https://github.com/yangyuan-zhen/PolyWeather.git
py -3.11 run.py cd PolyWeather
pip install -r requirements.txt
# Linux/VPS cp .env.example .env # Edit .env with your Token and API Keys
python3 run.py
``` ```
_Note: The system is currently in **Weather Query Mode**. Legacy active market monitoring and automated trading modules are suspended._ **Create one-click update script (run once):**
```bash
cat > ~/update.sh << 'EOF'
#!/bin/bash
cd ~/PolyWeather
git fetch origin
git reset --hard origin/main
pkill -f run.py
pkill -f bot_listener.py
sleep 1
nohup python3 run.py > bot.log 2>&1 &
echo "✅ Updated and restarted!"
EOF
chmod +x ~/update.sh
```
**Daily updates (after each code push):**
```bash
~/update.sh
```
> One command: pull latest code → kill old process → start new process. No branch conflict handling needed.
### Local Development (Windows)
```bash
py -3.11 run.py
```
> Local machine is for editing code and Git push only. IDE import errors are expected (dependencies not installed locally) and do not affect VPS operation.
_Note: The system is currently in **Weather Query Mode**. Legacy market monitoring and automated trading modules are suspended._
--- ---
@@ -32,50 +66,75 @@ _Note: The system is currently in **Weather Query Mode**. Legacy active market m
| `/id` | **Get Chat ID** | Retrieve your current Telegram Chat ID | | `/id` | **Get Chat ID** | Retrieve your current Telegram Chat ID |
| `/help` | **Help** | Display all available commands | | `/help` | **Help** | Display all available commands |
### Supported Cities
| City | Aliases | METAR Station | Extra Sources |
|:---|:---|:---|:---|
| London | `lon`, `伦敦` | EGLC (City Airport) | Meteoblue |
| Paris | `par`, `巴黎` | LFPG (Charles de Gaulle) | — |
| Ankara | `ank`, `安卡拉` | LTAC (Esenboğa) | MGM |
| New York | `nyc`, `ny`, `纽约` | KLGA (LaGuardia) | NWS |
| Chicago | `chi`, `芝加哥` | KORD (O'Hare) | NWS |
| Dallas | `dal`, `达拉斯` | KDAL (Love Field) | NWS |
| Miami | `mia`, `迈阿密` | KMIA (International) | NWS |
| Atlanta | `atl`, `亚特兰大` | KATL (Hartsfield-Jackson) | NWS |
| Seattle | `sea`, `西雅图` | KSEA (Sea-Tac) | NWS |
| Toronto | `tor`, `多伦多` | CYYZ (Pearson) | — |
| Seoul | `sel`, `首尔` | RKSI (Incheon) | — |
| Buenos Aires | `ba`, `布宜诺斯艾利斯` | SAEZ (Ezeiza) | — |
| Wellington | `wel`, `惠灵顿` | NZWN (Wellington) | — |
### Example
```
/city 巴黎
/city london
/city par
```
--- ---
## ✨ Key Features ## ✨ Key Features
### 1. 🏛️ Multi-Source Data Fusion (High-Fidelity) ### 1. 🏛️ Multi-Source Data Fusion
The bot aggregates data from multiple authoritative sources, layered by reliability:
| Source | Role | Coverage | Strength | | Source | Role | Coverage | Strength |
| :----------------- | :---------------------- | :-------------- | :--------------------------------------------------------------------------------- | | :----------------- | :---------------------- | :-------------- | :--------------------------------------------------------------------------------- |
| **Open-Meteo** | Base Forecast | Global | Provides detailed 72-hour temperature curves for all cities. | | **Open-Meteo** | Base Forecast | Global | 72-hour hourly temperature curves, sunrise/sunset times |
| **Meteoblue (MB)** | **Precision Consensus** | London Only | **Traders' choice**. Aggregates multiple models; excellent for microclimates. | | **Meteoblue (MB)** | **Precision Consensus** | London Only | Multi-model aggregation; excellent for microclimates |
| **METAR** | **Settlement Standard** | Global Airports | The absolute truth for Polymarket settlement; real-time station data. | | **METAR** | **Settlement Standard** | Global Airports | Polymarket settlement source; real-time airport observations |
| **NWS** | Official (US) | US Only | High-fidelity forecasts for US cities, critical for extreme weather events. | | **NWS** | Official (US) | US Only | US National Weather Service high-fidelity forecasts |
| **MGM** | Official (Turkey) | Ankara | Direct access to Turkish State Meteorological Service for local official accuracy. | | **MGM** | Official (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall |
### 2. ⚡ Ultra-Fresh Data (Cache-Busting) ### 2. ⚡ Ultra-Fresh Data (Zero-Cache)
To counter second-by-second variations in weather betting, we implemented **Zero-Cache Technology**: - **Dynamic Timestamps**: Every API request includes a unique token to force servers to bypass CDN caches.
- **MGM Real-time Sync**: Specialized header camouflaging and timezone correction for Turkish API.
- **Micro-timestamp Tokens**: Every request includes a dynamic token to force servers to bypass CDN caches. ### 3. 🧠 Smart Trend Analysis (Plain Language)
- **MGM Real-time Sync**: Specialized header camouflaging to bypass local Turkish API anti-crawling for Ankara.
### 3. ⏱️ Automated Trend Analysis The bot generates human-readable insights automatically:
The bot doesn't just fetch data; it interprets it: - **🚨 Forecast Breakthrough Alerts**: Detects when METAR observed max exceeds all forecast highs.
- **⏱️ Peak Window Prediction**: Identifies the exact hours when today's high is expected.
- **🌬️ Wind Direction Cross-Validation**: Compares METAR and MGM wind data; alerts on conflicts (>90° difference).
- **☁️ Cloud Impact Analysis**: Evaluates cloud cover's effect on warming potential.
- **📉 Pressure Analysis**: Low pressure indicates warm/moist air passage.
- **🌧️ Rain Detection**: Cross-validates METAR weather codes with actual rainfall data to avoid false positives.
- **📊 Max Temperature Time Tracking**: Shows exactly when the daily high was recorded (e.g., `最高: 12°C @14:20`).
- **Peak Window Prediction**: Automatically identifies the timeframe when today's record is most likely to be hit. ### 4. 📊 Risk Profiling
- **Risk Profiling**: Assigns risk levels based on geographic traits (e.g., Ankara high-altitude swings, London coastal microclimates).
- **Source Attribution**: Every data point is clearly labeled ([MGM], [METAR], [MB]) to help you weigh the data.
### 4. 📊 Smart Max-Temp Tracking Every city has a data bias risk profile based on airport-to-city-center distance:
Optimized for Polymarket settlement logic: - 🔴 **High Risk**: Seoul (48.8km), Chicago (25.3km) — large bias expected
- 🟡 **Medium Risk**: Ankara (24.5km), Paris (25.2km), Dallas, Buenos Aires — systematic bias
- **Local Day Filtering**: Uses city UTC offsets to strictly count observations after 00:00 local time. - 🟢 **Low Risk**: London (12.7km), Wellington (5.1km) — reliable data
- **Multi-dimension Monitoring**: Includes "Feels Like" temperatures and 24h precipitation to assist in nuanced trade decisions.
--- ---
## 🏗️ System Architecture ## 🏗️ System Architecture
PolyWeather uses a **Lightweight, Plugin-based** architecture for millisecond responses.
```mermaid ```mermaid
graph TD graph TD
User[/Telegram User/] --> Bot[bot_listener.py] User[/Telegram User/] --> Bot[bot_listener.py]
@@ -83,25 +142,30 @@ graph TD
subgraph "Data Engine" subgraph "Data Engine"
Collector --> OM[Open-Meteo API] Collector --> OM[Open-Meteo API]
Collector --> MB[Meteoblue Weather API] Collector --> MB[Meteoblue API]
Collector --> NOAA[METAR Data Center] Collector --> NOAA[METAR / NOAA]
Collector --> MGM[Turkish MGM API] Collector --> MGM[Turkish MGM API]
Collector --> NWS[US NWS API] Collector --> NWS[US NWS API]
end end
Collector --> Processing[Smart Analysis & Formatting] Collector --> Processing[Smart Analysis & Formatting]
Processing --> Bot Processing --> Bot
Bot --> Reponse[/Compact Betting Snapshot/] Bot --> Response[/Compact Betting Snapshot/]
``` ```
- **Logic Decoupling**: `weather_sources.py` handles parsing; `bot_listener.py` handles rendering. - **Logic Decoupling**: `weather_sources.py` handles data fetching & parsing; `bot_listener.py` handles analysis & rendering.
- **Legacy Modules**: `main.py` contains the old automated trading engine. Focus has shifted to "assisted manual decision-making." - **City Config**: `city_risk_profiles.py` contains all METAR station mappings and risk assessments.
--- ---
## 🎯 Betting Strategy Tips ## 🎯 Betting Strategy Tips
1. **Check Consensus**: Compare Open-Meteo and Meteoblue (MB). Consensus usually implies higher probability. 1. **Check Consensus**: Compare Open-Meteo, Meteoblue (MB), and NWS/MGM forecasts.
2. **Watch the Peak**: Use `/city` frequently during predicted peak windows to catch momentum. 2. **Watch the Peak Window**: Use `/city` frequently during predicted peak hours.
3. **Weighting Hierarchy**: Settlement is **METAR**; high-accuracy trend is **MB** (London); Official (NWS/MGM) is the "anchor." 3. **Settlement Priority**: Settlement is always based on **METAR** data.
4. **Geographic Risk**: Pay close attention to cities where "Bias will significantly amplify." 4. **Geographic Risk**: Pay attention to bias warnings, especially for high-risk cities.
5. **Wind Conflicts**: When METAR and MGM show opposite wind directions, expect temperature volatility.
---
_Last updated: 2026-02-18_
README_ZH.md
+64 -39
View File
@@ -1,6 +1,6 @@
# 🌡️ PolyWeather: 实时天气查询与分析机器人 # 🌡️ PolyWeather: 实时天气查询与分析机器人
一个智能天气信息机器人，专为提供超快、实时的气象数据、高保真预报和智能趋势分析而设计。通过绕过网络缓存，直接从全球气象站获取最新数据。 专为预测市场和天气博弈设计的智能天气机器人。通过绕过 CDN 缓存直接从全球气象站获取最新数据，并提供通俗易懂的自动趋势分析。
## 🚀 快速开始 ## 🚀 快速开始
@@ -8,7 +8,7 @@
- **Python 3.11+** - **Python 3.11+**
- 依赖安装: `pip install -r requirements.txt` - 依赖安装: `pip install -r requirements.txt`
- **环境变量**: 需在 `.env` 中配置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。 - **环境变量**: 在 `.env` 中设置 `TELEGRAM_BOT_TOKEN`（必需）。可选设置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。
### VPS 部署 (推荐) ### VPS 部署 (推荐)
@@ -52,7 +52,7 @@ chmod +x ~/update.sh
py -3.11 run.py py -3.11 run.py
``` ```
> 本地笔记本**不需要安装 Python**，只用来编辑代码和 Git 推送。IDE 的 import 报错是因为本地没装依赖，不影响 VPS 运行。 > 本地笔记本**不需要安装依赖**，只用来编辑代码和 Git 推送。IDE 的 import 报错是因为本地没装依赖，不影响 VPS 运行。
_注意：系统当前处于 **天气查询模式**。主动市场监控和自动交易模块已暂停。_ _注意：系统当前处于 **天气查询模式**。主动市场监控和自动交易模块已暂停。_
@@ -66,56 +66,76 @@ _注意：系统当前处于 **天气查询模式**。主动市场监控和自
| `/id` | **获取 Chat ID** | 获取当前 Telegram 聊天 ID | | `/id` | **获取 Chat ID** | 获取当前 Telegram 聊天 ID |
| `/help` | **帮助** | 显示所有可用指令 | | `/help` | **帮助** | 显示所有可用指令 |
### /city 指令示例 ### 支持的城市
| 城市 | 缩写/别名 | METAR 机场 | 额外数据源 |
|:---|:---|:---|:---|
| 伦敦 London | `lon`, `伦敦` | EGLC (City Airport) | Meteoblue |
| 巴黎 Paris | `par`, `巴黎` | LFPG (Charles de Gaulle) | — |
| 安卡拉 Ankara | `ank`, `安卡拉` | LTAC (Esenboğa) | MGM |
| 纽约 New York | `nyc`, `ny`, `纽约` | KLGA (LaGuardia) | NWS |
| 芝加哥 Chicago | `chi`, `芝加哥` | KORD (O'Hare) | NWS |
| 达拉斯 Dallas | `dal`, `达拉斯` | KDAL (Love Field) | NWS |
| 迈阿密 Miami | `mia`, `迈阿密` | KMIA (International) | NWS |
| 亚特兰大 Atlanta | `atl`, `亚特兰大` | KATL (Hartsfield-Jackson) | NWS |
| 西雅图 Seattle | `sea`, `西雅图` | KSEA (Sea-Tac) | NWS |
| 多伦多 Toronto | `tor`, `多伦多` | CYYZ (Pearson) | — |
| 首尔 Seoul | `sel`, `首尔` | RKSI (Incheon) | — |
| 布宜诺斯艾利斯 Buenos Aires | `ba`, `布宜诺斯艾利斯` | SAEZ (Ezeiza) | — |
| 惠灵顿 Wellington | `wel`, `惠灵顿` | NZWN (Wellington) | — |
### 使用示例
``` ```
/city 伦敦 /city 巴黎
/city london
/city par
``` ```
--- ---
## ✨ 核心功能 ## ✨ 核心功能
### 1. 🏛️ 多源数据融合 (Multi-Source Fusion) ### 1. 🏛️ 多源数据融合
机器人聚合了全球最权威的几个数据源，并按权重进行分层： | 数据源 | 数据角色 | 覆盖范围 | 优势 |
| :----------------- | :------------- | :--------- | :--------------------------------------------------- |
| **Open-Meteo** | 基础预测 | 全球 | 72 小时逐小时温度曲线、日出日落时间 |
| **Meteoblue (MB)** | **高精度共识** | 仅限伦敦 | 聚合多家模型，对微气候处理极佳 |
| **METAR** | **结算标准** | 全球机场 | Polymarket 结算参考的绝对真理，实时机场观测 |
| **NWS** | 官方预测(美) | 仅限美国 | 美国国家气象局高精度预报 |
| **MGM** | 官方预测(土) | 仅限安卡拉 | 土耳其气象局：气压、云量、体感温度、24h 降水 |
| 数据源 | 数据角色 | 覆盖范围 | 优势 | ### 2. ⚡ 超新鲜数据 (零缓存)
| :----------------- | :------------- | :--------- | :----------------------------------------------- |
| **Open-Meteo** | 基础预测 | 全球 | 提供所有城市的 72 小时精细化温度曲线 |
| **Meteoblue (MB)** | **高精度共识** | 仅限伦敦 | **交易员首选**。聚合多家模型，对微气候处理极佳 |
| **METAR** | **结算标准** | 全球机场 | Polymarket 结算参考的绝对真理，实时机场观测 |
| **NWS** | 官方预测(美) | 仅限美国 | 美国国家气象局，对美国城市的极端天气预判准确 |
| **MGM** | 官方预测(土) | 仅限安卡拉 | 土耳其气象局，提供安卡拉 Esenboğa 机场的官方数据 |
### 2. ⚡ 超新鲜数据 (Cache-Busting) - **动态时间戳**：每个 API 请求都附带唯一令牌，强制服务器绕过 CDN 缓存。
为了应对气象博弈中秒级的变化，我们实现了 **0 缓存技术**：
- **微秒级令牌**：每个 API 请求都附带动态时间戳，强制气象服务器绕过 CDN 缓存返回最新值。
- **MGM 实时同步**：针对土耳其 MGM API 做了专门的 Header 伪装和时区校正。 - **MGM 实时同步**：针对土耳其 MGM API 做了专门的 Header 伪装和时区校正。
### 3. ⏱️ 自动态势分析 ### 3. 🧠 智能趋势分析（通俗语言）
机器人不仅仅搬运数据，它还会进行逻辑加工： 机器人自动生成人类可读的分析洞察：
- **峰值时刻预测**：自动计算今天气温最高点出现的概率窗口（如：14:00 - 15:00）。 - **🚨 预报击穿预警**：当 METAR 实测最高温超过所有预报时自动警报。
- **风险等级 (Risk-Profile)**：根据地理特征（如安卡拉的高原温差、伦敦的近海微气候）自动分配风险等级。 - **⏱️ 峰值时段预测**：精确预测当日最高温出现的时间窗口。
- **数据溯源**：报表明确标注每个数字的来源（[MGM], [METAR], [MB]）。 - **🌬️ 风向交叉验证**：同时对比 METAR 和 MGM 风向数据，差异超 90° 自动告警。
- **🍃 风速分析**：标注风速并结合风向判断对温度的影响。
- **☁️ 云层遮挡分析**：评估云量对升温潜力的影响（晴天/多云/阴天）。
- **📉 气压分析**：低气压意味着暖湿气流过境，有利升温。
- **🌧️ 降雨检测**：交叉验证 METAR 天气代码和实际降水量，避免误报。
- **📊 最高温时间追踪**：精确显示每日最高温出现的时间（如 `最高: 12°C @14:20`）。
### 4. 📊 智能最高温追踪 ### 4. 📊 风险等级
针对 Polymarket 的结算逻辑进行优化： 每个城市都有基于机场-市区距离的数据偏差风险档案：
- **当地日历日过滤**：基于城市 UTC 偏移，严格统计当地时间 00:00 之后的实测最高温。 - 🔴 **高危**：首尔 (48.8km)、芝加哥 (25.3km) — 偏差大
- **多维度监测**：集成体感温度 (`feels_like`) 和 24h 累计降雨量，辅助多维度判断。 - 🟡 **中危**：安卡拉 (24.5km)、巴黎 (25.2km)、达拉斯、布宜诺斯艾利斯 — 有系统偏差
- 🟢 **低危**：伦敦 (12.7km)、惠灵顿 (5.1km) — 数据靠谱
--- ---
## 🏗️ 系统架构 ## 🏗️ 系统架构
本项目采用 **“轻量化、插件式”** 架构，旨在实现毫秒级响应。
```mermaid ```mermaid
graph TD graph TD
User[/Telegram User/] --> Bot[bot_listener.py] User[/Telegram User/] --> Bot[bot_listener.py]
@@ -123,25 +143,30 @@ graph TD
subgraph "Data Engine" subgraph "Data Engine"
Collector --> OM[Open-Meteo API] Collector --> OM[Open-Meteo API]
Collector --> MB[Meteoblue Weather API] Collector --> MB[Meteoblue API]
Collector --> NOAA[METAR Data Center] Collector --> NOAA[METAR / NOAA]
Collector --> MGM[Turkish MGM API] Collector --> MGM[Turkish MGM API]
Collector --> NWS[US NWS API] Collector --> NWS[US NWS API]
end end
Collector --> Processing[智能分析 & 格式化] Collector --> Processing[智能分析 & 格式化]
Processing --> Bot Processing --> Bot
Bot --> Reponse[/精简版博弈快照/] Bot --> Response[/天气分析快照/]
``` ```
- **逻辑解耦**：`weather_sources.py` 负责外部数据的解析；`bot_listener.py` 负责消息模板渲染。 - **逻辑解耦**：`weather_sources.py` 负责数据获取与解析；`bot_listener.py` 负责分析与渲染。
- **遗留模块说明**：项目根目录下的 `main.py` 包含旧版本的自动交易引擎。目前重心在“手动辅助决策”，如需开启请查阅 [MARKET_DISCOVERY_ZH.md](./MARKET_DISCOVERY_ZH.md)。 - **城市配置**：`city_risk_profiles.py` 包含所有 METAR 机场映射和风险评估。
--- ---
## 🎯 博弈策略提示 ## 🎯 博弈策略提示
1. **检查模型共识**：查看 Open-Meteo 和 Meteoblue (MB) 是否达成共识。 1. **检查模型共识**：对比 Open-Meteo、Meteoblue (MB) 和 NWS/MGM 的预报。
2. **关注峰值窗口**：在预测的峰值时段多次使用 `/city` 刷新。 2. **关注峰值窗口**：在预测的峰值时段频繁使用 `/city` 刷新。
3. **数据权重优先级**：结算以 **METAR** 为准，趋势预测以 **MB** 为准（仅限伦敦）。 3. **结算优先级**：结算永远以 **METAR** 数据为准。
4. **地理风险评估**：重点关注提示中的“偏差会显著放大”警告（如安卡拉、伦敦）。 4. **地理风险**：重点关注高危城市的偏差警告。
5. **风向冲突**：METAR 和 MGM 风向相反时，温度波动风险增大。
---
_最后更新: 2026-02-18_