From bb4a697b9818ba65e54bee02edd4442691e4cccc Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Fri, 27 Feb 2026 01:58:29 +0800 Subject: [PATCH] docs: sync english README.md with high-end quant trading focus --- README.md | 312 ++++++++++++++++++------------------------------------ 1 file changed, 101 insertions(+), 211 deletions(-) diff --git a/README.md b/README.md index cbc5d8e4..a3427354 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,64 @@ -# ๐ŸŒก๏ธ PolyWeather: Real-time Weather Query & Analysis Bot +# ๐ŸŒก๏ธ PolyWeather: Quantitative Weather Trading & AI Command Center -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 with **model consensus scoring** and **entry timing signals** in plain language. +![Banner Placeholder: Futuristic Weather Trading System] -## ๐Ÿš€ Quick Start +PolyWeather is not just a simple weather bot. It is an **institutional-grade weather quantitative trading assistant** designed for prediction markets like **Polymarket** and other weather derivatives. By connecting directly to global aviation weather stations (METAR) without CDN caching, integrating our Dynamic Ensemble Blending (DEB) model, extracting real-time micro-climate features, and stripping away human emotion via the massive LLaMA 70B AI model, it provides you with rapid, objective, and lethal trading signals. -### Requirements +--- -- **Python 3.11+** -- Dependencies: `pip install -r requirements.txt` -- **Environment Variables**: Set `TELEGRAM_BOT_TOKEN` in `.env` (required). Optionally set `METEOBLUE_API_KEY` for London high-precision forecasts. +## ๐Ÿš€ Core Features Matrix -### VPS Deployment (Recommended) +### 1. ๐Ÿง  Proprietary Moat: Dynamic Ensemble Blending (DEB) -**First-time setup:** +Traditional weather bots simply calculate rigid averages out of numerical models like ECMWF and GFS. PolyWeather introduces a **dynamic tracking and backtesting algorithm**: + +- **Adaptive Weight Evolution**: By looking back at the Mean Absolute Error (MAE) of each model over the past 7-14 days at specific airports (e.g., EsenboฤŸa Airport in Ankara), the system actively penalizes and rewards the 5 major NWP models (ECMWF, GFS, ICON, GEM, JMA) per query. +- **High-Concurrency Thread-Safe Database**: Built on an underlying memory singleton cache and system-level file locks (`fcntl Lock`), PolyWeather guarantees 0 disk I/O bottlenecks and microsecond response timesโ€”even when bombarded by 500+ users checking the weather at the exact same millisecond. + +### 2. ๐Ÿค– AI Trading Veteran (Groq AI Agent) + +The system no longer outputs boring templates. We feed all **complex thermodynamic parameters** (wind direction/speed matrix, cooling inertia, rounding resistance) into LLaMA 3.3 70B via the lightning-fast Groq API: + +- **๐ŸงŠ Forced Objectivity**: With strict logical constraints built into the prompt, the AI accurately evaluates scenarios like "15kt cold northerly winds at 3 PM, coupled with radiation dropping below 50W/mยฒ" and immediately calls "Dead market: peak passed, bets frozen." +- **๐ŸŽฏ Quantitative Confidence Scoring**: It outputs a 1-10 confidence score with strong guidance. High confidence means an "immediate signal to build positions," whereas low confidence warns of a chaotic market full of wind/rain uncertainties. + +### 3. โฑ๏ธ Absolute Live Dominance (Zero-Cache METAR Extraction) + +In the meat grinder of Polymarket weather settlements, **a 1-minute delay can mean a 100% loss of your principal**. + +- PolyWeather forces anti-cache dynamic timestamps on every single API call, bypassing all proxy network (CDN) stagnant cache pools. +- It doesn't just extract "how many degrees it is now." It analyzes the exact decimal point for Settlement Risk (including the deadly X.5 Wunderground roundup boundaries). + +### 4. ๐Ÿ“ˆ High-Frequency Data Mining Foundation + +Built-in `fetch_history.py` native spider system. + +- One click to pull down hundreds of thousands of rows of hourly historical physics sandbox feature matrices (over 10 dimensions including humidity, shortwave radiation, surface pressure) for any global benchmark city across the past 3-5 years. +- Infinite ammunition ready for our next-generation XGBoost / LightGBM Machine Learning Model Output Statistics (MOS) calibration. + +--- + +## โšก Deployment & Operations + +### Environment Architecture + +- **Core Engine**: Python 3.11+ (Strict Compliance) +- **Dependency Stack**: `pip install -r requirements.txt` +- **Volume Mounts**: Minimal configuration. Just register your `TELEGRAM_BOT_TOKEN` and `GROQ_API_KEY` inside `.env` to summon the AI. + +### Recommended 1-Click VPS Production Launch + +**Step 1: Build & Register** ```bash git clone https://github.com/yangyuan-zhen/PolyWeather.git cd PolyWeather pip install -r requirements.txt -cp .env.example .env # Edit .env with your Token and API Keys +cp .env.example .env # Be sure to insert your secure API keys ``` -**Create one-click update script (run once):** +**Step 2: Daemon Updater Assembly** +Set up an automated keep-alive script to integrate updates, conflict-resolution, and hot-swaps all in one push: ```bash cat > ~/update.sh << 'EOF' @@ -32,233 +69,86 @@ 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!" +nohup python3 bot_listener.py > bot.log 2>&1 & +echo "โœ… PolyWeather Quant Terminal up and loaded with the latest modules!" EOF chmod +x ~/update.sh ``` -**Daily updates (after each code push):** +**Daily Operations Command (Push & Play):** ```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. +> One command to wipe Git conflicts, execute warm/cold reboots, and clean logs. --- -## ๐Ÿค– Telegram Bot Commands +## ๐Ÿ•น๏ธ Telegram Command Center -| Command | Description | Usage | -| :------------- | :--------------------- | :--------------------------------------------- | -| `/city [name]` | **Query City Weather** | Get detailed forecasts, METAR & trend analysis | -| `/id` | **Get Chat ID** | Retrieve your current Telegram Chat ID | -| `/help` | **Help** | Display all available commands | +| Tactical Command | Trigger Action | Module Feedback | +| :------------------ | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/city [City Code]` | **Reconnaissance** | Initiates full-dimension weather sweep. Returns DEB-weighted forecast, METAR tracking, rounding risk warnings, and AI quantitative trading conclusion. | +| `/id` | **Identity Ping** | Maps the current comm channel (Chat ID). | +| `/help` | **Terminal Manual** | Pulls the latest command set. | -### Supported Cities +### Target Arenas -| 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) | โ€” | +From low-risk setups in the Middle East/Africa to high-latency slippage arenas in North America, PolyWeather embeds precise airport deviation models (Risk Profiles): +`lon`(London EGLC), `par`(Paris LFPG), `ank`(Ankara LTAC), `nyc`(New York KLGA), `chi`(Chicago KORD), `ba`(Buenos Aires SAEZ)... and more. -### Example - -``` -/city ๅทด้ปŽ -/city london -/city par -``` +> **Fire Examples:** +> `/city Paris` +> `/city london` +> `/city ba` --- -## โœจ Key Features - -### 1. ๐Ÿ›๏ธ Multi-Source Data Fusion - -| Source | Role | Coverage | Strength | -| :---------------------- | :---------------------- | :-------------- | :-------------------------------------------------------------------------- | -| **Multi-Model (5 NWP)** | **Consensus Scoring** | Global | ECMWF, GFS, ICON, GEM, JMA โ€” 5 fully independent NWP models via Open-Meteo | -| **Open-Meteo** | Base Forecast | Global | 72h hourly curves, sunrise/sunset, **sunshine duration**, **shortwave radiation** | -| **Open-Meteo Ensemble** | **Uncertainty Range** | Global | 51-member ensemble: median, P10, P90 spread for confidence assessment | -| **Meteoblue (MB)** | Precision Consensus | London Only | Multi-model aggregation; excellent for microclimates | -| **METAR** | **Settlement Standard** | Global Airports | Polymarket settlement source; real-time airport observations | -| **NWS** | Official (US) | US Only | US National Weather Service high-fidelity forecasts | -| **MGM** | Observations (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall | - -> โš ๏ธ **All NWP model queries use airport coordinates** (matching METAR station), not city center. This eliminates systematic bias between forecast and settlement locations. - -**Open-Meteo API Architecture**: Three API calls go through the same platform, each serving a different purpose: - -``` - Open-Meteo (API Platform) - โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ โ”‚ โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ /forecast โ”‚ โ”‚ โ”‚ /forecast โ”‚ - โ”‚ (default) โ”‚ โ”‚ โ”‚ ?models=... โ”‚ - โ”‚ = best_matchโ”‚ โ”‚ โ”‚ = multi-modelโ”‚ - โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ โ”‚ โ”‚ - โ–ผ โ”‚ โ–ผ - Auto-selects best โ”‚ Returns each model - model (โ‰ˆ ECMWF) โ”‚ ECMWF / GFS / ICON - โ†’ Hourly curves โ”‚ GEM / JMA - โ†’ Sunrise/sunset โ”‚ โ†’ Consensus scoring - โ†’ Sunshine/radiation โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ /ensemble โ”‚ - โ”‚ 51 members โ”‚ - โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ–ผ - Median / P10 / P90 - โ†’ Uncertainty range -``` - -> ๐Ÿ’ก The OM default forecast is essentially **one of the 5 models** (auto-selected), so it is **excluded from consensus scoring** to avoid double-counting. - -### 2. โšก Ultra-Fresh Data (Zero-Cache) - -- **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. - -### 3. ๐ŸŽฏ Multi-Model Consensus Scoring - -The bot queries **5 independent NWP models** (ECMWF, GFS, ICON, GEM, JMA) to rate forecast agreement: - -| Level | Condition (ยฐC / ยฐF) | Meaning | -|:---|:---|:---| -| ๐ŸŽฏ **High** | Spread โ‰ค 0.8ยฐC / 1.5ยฐF | All 5 models converge โ€” high confidence, low risk | -| โš–๏ธ **Medium** | Spread โ‰ค 1.5ยฐC / 3.0ยฐF | Minor disagreement โ€” moderate confidence | -| โš ๏ธ **Low** | Spread > 1.5ยฐC / 3.0ยฐF | Major divergence โ€” high uncertainty, wait for more data | - -Primary models: **ECMWF IFS** (Europe), **GFS** (US NOAA), **ICON** (Germany DWD), **GEM** (Canada), **JMA** (Japan). Plus Meteoblue (London) and NWS (US) when available. Ensemble median is excluded to avoid double-counting. - -### 4. ๐Ÿ“Š Ensemble Forecast Spread (NEW) - -Fetches 51-member ensemble forecasts from Open-Meteo to quantify prediction uncertainty: - -> ๐Ÿ“Š **Ensemble**: Median 10.8ยฐC, 90% range [9.5ยฐC - 12.1ยฐC], spread 2.6ยฐ. - -A tight range = high confidence in the forecast. A wide range = the atmosphere is chaotic, higher risk. - -**Deterministic vs Ensemble Divergence Detection**: When the OM deterministic forecast exceeds the ensemble P90 or falls below P10, the bot flags it. If actual observations later verify the forecast, the warning upgrades to a โœ… **Forecast Verified** message. - -### 5. โฐ Entry Timing Signal (NEW) - -A composite score combining three factors to advise on betting timing: - -| Factor | Score | -|:---|:---| -| Peak already passed | +3 | -| โ‰ค 2h to peak | +2 | -| โ‰ค 4h to peak | +1 | -| Model consensus: High | +2 | -| Model consensus: Medium | +1 | -| Actual โ‰ˆ Forecast (gap โ‰ค 0.5ยฐ) | +2 | -| Actual close to Forecast (gap โ‰ค 1.5ยฐ) | +1 | - -| Total โ‰ฅ | Signal | Advice | -|:---|:---|:---| -| 5 | โฐ **Ideal** | Low uncertainty โ€” good to bet | -| 3 | โฐ **Good** | Consider small positions | -| 2 | โฐ **Cautious** | Keep observing | -| <2 | โฐ **Not Recommended** | High uncertainty โ€” wait | - -### 6. ๐Ÿง  Smart Trend Analysis (Plain Language) - -The bot generates human-readable insights automatically: - -- **๐Ÿšจ 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`). -- **โ˜€๏ธ Weather Condition Summary**: Synthesizes METAR phenomena + cloud cover into a single glanceable icon + text (e.g., `โ›… Partly Cloudy`). -- **๐ŸŒค๏ธ Solar Radiation Analysis**: Tracks cumulative shortwave radiation vs. daily total; warns when clouds severely block sunlight. -- **๐ŸŒ™ Warm Advection Detection**: Identifies when peak temperature occurred during zero-radiation hours (e.g., 3 AM), proving the high was driven by warm air mass rather than solar heating. - -### 7. ๐Ÿ“Š Risk Profiling - -Every city has a data bias risk profile based on airport-to-city-center distance: - -- ๐Ÿ”ด **High Risk**: Seoul (48.8km), Chicago (25.3km) โ€” large bias expected -- ๐ŸŸก **Medium Risk**: Ankara (24.5km), Paris (25.2km), Dallas, Buenos Aires โ€” systematic bias -- ๐ŸŸข **Low Risk**: London (12.7km), Wellington (5.1km) โ€” reliable data - -### 8. ๐ŸŒ… Enhanced Display - -- **Sunrise/Sunset + Sunshine Hours**: `๐ŸŒ… 07:34 | ๐ŸŒ‡ 18:29 | โ˜€๏ธ 9.9h` -- **Weather Condition at a Glance**: `โœˆ๏ธ ๅฎžๆต‹ (METAR): 9ยฐC | โ›… Partly Cloudy | 15:00` -- **WU Settlement Preview**: Shows the Wunderground-rounded value for settlement reference. - ---- - -## ๐Ÿ—๏ธ System Architecture +## ๐Ÿ—๏ธ System Architecture Anatomy ```mermaid graph TD - User[/Telegram User/] --> Bot[bot_listener.py] - Bot --> Collector[WeatherDataCollector] + classDef ai fill:#f9f,stroke:#333,stroke-width:2px; + classDef core fill:#bbf,stroke:#333,stroke-width:2px; + classDef data fill:#dfd,stroke:#333,stroke-width:1px; - subgraph "Data Engine" - Collector --> MM[Multi-Model API
ECMWF/GFS/ICON/GEM/JMA] - Collector --> OM[Open-Meteo Forecast] - Collector --> ENS[Open-Meteo Ensemble] - Collector --> MB[Meteoblue API] - Collector --> NOAA[METAR / NOAA] - Collector --> MGM[MGM Observations] - Collector --> NWS[US NWS API] + User[Telegram / Signal Receiver] -->|Trigger Scan| Bot[bot_listener.py Core Scheduler]:::core + + subgraph Heterogeneous Data Parsing + Bot --> Collector[WeatherDataCollector] + Collector --> OM[Open-Meteo Archive/Live]:::data + Collector --> MM[Multi-Model Predictors]:::data + Collector --> METAR[Air Traffic Control Raw Logs]:::data end - Collector --> Processing[Consensus Scoring & Trend Analysis] - Processing --> Bot - Bot --> Response[/Betting Snapshot with Entry Signal/] + subgraph Computation & Circuit Breakers + Collector --> DEB[DEB Dynamic Weighting]:::core + DEB --> DB[(daily_records JSON DB
Thread-Safe)] + Collector --> Logic[Rounding Analysis / Cooldown] + end + + subgraph AI Metric Generation + DEB --> AIAnalyzer[Groq/LLaMA Cognitive Model]:::ai + Logic --> AIAnalyzer + METAR --> AIAnalyzer + end + + AIAnalyzer -->|Generates: Spread+Logic+Confidence| Bot + Bot -->|Assembles High-Dimensional Slice| User ``` -- **Logic Decoupling**: `weather_sources.py` handles data fetching & parsing; `bot_listener.py` handles analysis & rendering. -- **City Config**: `city_risk_profiles.py` contains all METAR station mappings and risk assessments. -- **Multi-Model Consensus**: 5 independent NWP models (ECMWF, GFS, ICON, GEM, JMA) for robust consensus scoring. -- **Ensemble Integration**: 51-member ensemble provides P10/P90 uncertainty bands and divergence detection. -- **Airport-Aligned Coordinates**: All NWP queries target METAR station coordinates, not city centers. +--- + +## ๐ŸŽฏ Trader's Playbook + +As a Commander of PolyWeather, etch these rules into your DNA: + +1. ๐Ÿงฌ **Trust the DEB Baseline**: Instead of blindly believing an extreme forecast from ECMWF or GFS, stare at the `DEB Blended Forecast` on line one. It is the system's re-calibrated truth, forged after absorbing the punishing MAE beating those models took over the past 7 days. +2. ๐ŸŽฏ **Respect the AI Confidence Red Line**: If the AI returns a `Confidence: โ‰ค 4/10`, it means the model's delay is clashing heavily with real-time airport headwinds. **Chop your gambling hands off immediately.** You are in a high-risk chaotic zone. +3. โš–๏ธ **Fear the X.5 Rounding Abyss**: Polymarket weather settles on integer values (rounded via Wunderground logic). When the terminal blinks `โš–๏ธ Settlement Boundary... crossed the rounding line`, this is where liquidity dries up and slippage becomes most predatory. +4. ๐ŸŒ™ **Identify False Positives (Warm Advection radar)**: If the temperature ignores the sun and spikes during a low-radiation night, the system triggers a `๐ŸŒ™ Warm Advection Anomaly`. This mechanism frequently hands you the golden "LONG" signal (shattering the original forecast's ceiling) exactly when the rest of the market is betting NO. --- -## ๐ŸŽฏ Betting Strategy Tips - -1. **Check Model Consensus**: The ๐ŸŽฏ/โš–๏ธ/โš ๏ธ rating tells you immediately if the forecast is reliable. -2. **Use the Entry Signal**: Wait for โฐ **Ideal** or **Good** timing before placing bets. Don't bet early when uncertainty is high. -3. **Watch Ensemble Spread**: A tight 90% band (< 2ยฐ) means model confidence is high โ€” this is where edges live. -4. **Watch the Peak Window**: Use `/city` frequently during predicted peak hours. -5. **Settlement Priority**: Settlement is always based on **METAR** data, rounded to integer via Wunderground. -6. **Geographic Risk**: Pay attention to bias warnings, especially for high-risk cities like Seoul and Chicago. -7. **Solar Radiation Clues**: If the bot reports "warm advection driven" ๐ŸŒ™, the temperature was pushed by warm air, not sunlight โ€” this pattern often breaks model predictions. -8. **Wind Conflicts**: When METAR and MGM show opposite wind directions, expect temperature volatility. - ---- - -_Last updated: 2026-02-22_ +_The weather changes. Our edge remains. | Updated 2026_