windguru 0.2.0__tar.gz

windguru-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          pip install -e ".[dev,mcp]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q -m "not live"

windguru-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+
+# Editors / OS
+.venv/
+venv/
+.idea/
+.vscode/
+.DS_Store
+
+# Local capture dumps (keep fixtures/ tracked intentionally)
+/tmp/
+*.har

windguru-0.2.0/AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md — how to extend `guru`
+
+You are working on **guru**: a Windguru CLI/library/MCP reverse-engineered the same way [`fli`](https://github.com/punitarani/fli) reverse-engineers Google Flights.
+
+## Calling guru from an agent
+
+```bash
+pipx install 'windguru[mcp]'
+guru instruct --json
+guru spots "<place>" --json          # or: guru near --lat --lon --json
+guru best <id_spot> --json           # WINDGURU_DEFAULT → top 3 forecasts
+```
+
+- Prefer **`best` / `best_forecast`**, not raw GFS.
+- Preset is always **WINDGURU_DEFAULT** (only adaptive Tune preset we support).
+- On `error_type: ambiguous`, pick from `candidates` — never silent first-match.
+- Envelope: `ok`, `api_version`, `error_type`, `retryable` (shared CLI + MCP).
+- Do **not** scrape HTML, Tune jBox, or MapLibre. Do **not** require PRO.
+
+## Hard rule: clone methods from fli
+
+**Strongly prefer copying patterns from fli over inventing new ones.**
+
+Keep a local checkout of fli (`git clone https://github.com/punitarani/fli /tmp/fli-ref`) and **read their search client before changing ours**.
+
+| fli | guru | Copy this idea |
+|-----|------|----------------|
+| `fli/search/client.py` | `guru/search/client.py` | `curl_cffi` impersonation, retries, env timeouts |
+| `fli/core/errors.py` | `guru/core/errors.py` | Shared CLI/MCP `error_type` vocabulary |
+| capture scripts + fixtures | `scripts/capture_fixtures.py` + `fixtures/` | Browser Network → fixture → offline parser tests |
+| `fli/cli/` | `guru/cli/` | Typer + Rich + `--json` |
+| `fli/mcp/` | `guru/mcp/` | FastMCP STDIO + HTTP |
+| `fli/models/` | `guru/models/` | Pydantic only — no I/O |
+| `_tfs` migration when signed RPC broke | `docs/WIRE.md` SPA `rundef` form | When simple `forecast` dies, use page-derived params |
+
+## Reverse-engineering workflow (required)
+
+1. Open the spot in **Cursor browser** (`https://www.windguru.cz/201`).
+2. CDP / Network: list requests matching `iapi.php`.
+3. Note host (`.cz` vs `.net`), `q=`, and params (`id_spot`, `id_model`, `rundef`, `opt=simplemap`, …).
+4. Reproduce with `curl_cffi` + **Referer**.
+5. Dump fixture → parser test → update `docs/WIRE.md`.
+
+**Never HTML-scrape the forecast table or Tune UI** as the primary path.
+
+## Product shape
+
+```text
+pipx install windguru
+guru spots <query>
+guru near --lat Y --lon X
+guru best <id|name> [--top 3] [--hours N] [--json]
+guru-mcp
+```
+
+## Do / don’t
+
+- **Do** extend `MODELS` from live Network captures.
+- **Do** keep free vs PRO failures explicit (PRO is out of core).
+- **Do** stay polite on rate limits.
+- **Don’t** commit cookies / PRO passwords / private nicknames as defaults.
+- **Don’t** ship a worldwide spot dump in the wheel (live `near` / `spots` only).
+- **Don’t** depend on `life-research` — this repo is public and clean-slate.
+
+## Engineering standards
+
+Keep and follow (do not delete):
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar
+
+## Dev commands
+
+```bash
+pipx install -e ".[dev,mcp]"
+# or: source .venv/bin/activate && pip install -e ".[dev,mcp]"
+guru spots "foster city"
+guru best 201 -H 12 --json
+pytest -q
+pytest -m live
+ruff check .
+```

windguru-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berend Gort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

windguru-0.2.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: windguru
+Version: 0.2.0
+Summary: Windguru CLI, MCP server, and Python library — reverse-engineered forecast access (fli-style)
+Project-URL: Homepage, https://github.com/berendgort/guru
+Project-URL: Repository, https://github.com/berendgort/guru
+Project-URL: Issues, https://github.com/berendgort/guru/issues
+Author-email: Berend Gort <berend.gort@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,forecast,kitesurf,mcp,weather,wind,windguru
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: rich>=13.8.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: typer>=0.15.1
+Provides-Extra: all
+Requires-Dist: fastmcp>=3.2; extra == 'all'
+Requires-Dist: mcp>=1.2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.8.4; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.2; extra == 'mcp'
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# guru
+
+Windguru **CLI + MCP + Python library**. Same idea as [`fli`](https://github.com/punitarani/fli): reverse-engineered JSON, zero HTML scraping, agent-first.
+
+> Free only — named spots + WINDGURU DEFAULT Tune top-3. No PRO lat/lon click-forecast.
+
+## Install
+
+```bash
+# CLI (recommended)
+pipx install windguru
+
+# CLI + MCP server
+pipx install 'windguru[mcp]'
+
+guru --help
+guru instruct --json
+```
+
+Until the PyPI release is live, install from GitHub:
+
+```bash
+pipx install 'windguru @ git+https://github.com/berendgort/guru.git'
+pipx install 'windguru[mcp] @ git+https://github.com/berendgort/guru.git'
+```
+
+PyPI name **`windguru`**, command **`guru`**, MCP **`guru-mcp`**.
+
+Or with pip:
+
+```bash
+pip install windguru
+pip install 'windguru[mcp]'
+```
+
+## MCP Server
+
+```bash
+pipx install 'windguru[mcp]'
+
+# STDIO (Cursor / Claude Desktop)
+guru-mcp
+
+# HTTP (streamable)
+guru-mcp-http  # http://127.0.0.1:8000/mcp/
+```
+
+### Connecting to Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "guru": {
+      "command": "guru-mcp"
+    }
+  }
+}
+```
+
+> Tip: if the binary is not on PATH, use the full path from `which guru-mcp`
+> (often `~/.local/bin/guru-mcp`).
+
+### MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `instruct` | Agent recipe (WINDGURU_DEFAULT → top 3) |
+| `search_spots` | Named spot search |
+| `near_spots` | Free map markers near lat/lon |
+| `resolve_spot` | Name/id → spot (`ambiguous` + candidates) |
+| `best_forecast` | Tune weights → top models → forecasts |
+| `get_forecast` | Single-model escape hatch |
+| `list_models` | Known aliases |
+
+## Agent recipe
+
+```bash
+guru instruct --json
+guru spots "castelldefels" --json
+guru best 201 --json
+guru near --lat 51.9 --lon 4.1 --json
+guru best 48309 -H 24 --json   # De Slufter
+```
+
+`guru best` always uses **WINDGURU_DEFAULT** Tune weights and returns the **top 3** models + forecasts. Prefer that over raw GFS.
+
+JSON envelope: `{"ok": true|false, "api_version": 1, "data"|error fields}`. Shared `error_type` / `retryable` with MCP.
+
+## CLI
+
+| Command | Role |
+|---------|------|
+| `guru instruct` | Teach agents the workflow |
+| `guru spots <q>` | Name search |
+| `guru near --lat --lon` | Free map markers near a point |
+| `guru best <spot>` | WINDGURU_DEFAULT → top 3 → forecasts |
+| `guru forecast <spot> -m gfs` | Single model |
+| `guru models` / `schema` / `doctor` | Discoverability |
+
+Ambiguous names fail with `error_type: ambiguous` + `candidates` (pass numeric id or `--pick`).
+
+## Library
+
+```python
+from guru import search_spots, get_best_forecast, spots_near
+
+spots = search_spots("castelldefels")
+best = get_best_forecast(201, top=3, hours=24)
+print(best.models[0].name, best.models[0].weight_pct)
+print(best.forecasts[0].hours[0].wind_kn)
+```
+
+## Architecture
+
+| Layer | Path | Role |
+|-------|------|------|
+| Core | `guru/core/` | Shared envelope, errors, instruct recipe |
+| CLI | `guru/cli/` | Typer + Rich + `--json` (thin over core) |
+| MCP | `guru/mcp/` | FastMCP over core (no CLI imports) |
+| Search | `guru/search/` | HTTP (`curl_cffi`), blend_math, near, forecast |
+| Models | `guru/models/` | Pydantic + aliases only |
+| Wire | [`docs/WIRE.md`](docs/WIRE.md) | Captured `iapi.php` |
+| MCP | [`docs/mcp.md`](docs/mcp.md) | `guru-mcp` setup + tools |
+
+Read [`AGENTS.md`](AGENTS.md) before extending. Capture Network → fixtures → tests.
+
+Engineering standards (kept in-repo):
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar (layers, size caps, pure core)
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar (one writer, clocks, contracts)
+
+## Disclaimer
+
+Unofficial. Not affiliated with Windguru. Personal / research use; respect ToS and rate limits.
+
+## License
+
+MIT

windguru-0.2.0/README.md

@@ -0,0 +1,138 @@
+# guru
+
+Windguru **CLI + MCP + Python library**. Same idea as [`fli`](https://github.com/punitarani/fli): reverse-engineered JSON, zero HTML scraping, agent-first.
+
+> Free only — named spots + WINDGURU DEFAULT Tune top-3. No PRO lat/lon click-forecast.
+
+## Install
+
+```bash
+# CLI (recommended)
+pipx install windguru
+
+# CLI + MCP server
+pipx install 'windguru[mcp]'
+
+guru --help
+guru instruct --json
+```
+
+Until the PyPI release is live, install from GitHub:
+
+```bash
+pipx install 'windguru @ git+https://github.com/berendgort/guru.git'
+pipx install 'windguru[mcp] @ git+https://github.com/berendgort/guru.git'
+```
+
+PyPI name **`windguru`**, command **`guru`**, MCP **`guru-mcp`**.
+
+Or with pip:
+
+```bash
+pip install windguru
+pip install 'windguru[mcp]'
+```
+
+## MCP Server
+
+```bash
+pipx install 'windguru[mcp]'
+
+# STDIO (Cursor / Claude Desktop)
+guru-mcp
+
+# HTTP (streamable)
+guru-mcp-http  # http://127.0.0.1:8000/mcp/
+```
+
+### Connecting to Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "guru": {
+      "command": "guru-mcp"
+    }
+  }
+}
+```
+
+> Tip: if the binary is not on PATH, use the full path from `which guru-mcp`
+> (often `~/.local/bin/guru-mcp`).
+
+### MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `instruct` | Agent recipe (WINDGURU_DEFAULT → top 3) |
+| `search_spots` | Named spot search |
+| `near_spots` | Free map markers near lat/lon |
+| `resolve_spot` | Name/id → spot (`ambiguous` + candidates) |
+| `best_forecast` | Tune weights → top models → forecasts |
+| `get_forecast` | Single-model escape hatch |
+| `list_models` | Known aliases |
+
+## Agent recipe
+
+```bash
+guru instruct --json
+guru spots "castelldefels" --json
+guru best 201 --json
+guru near --lat 51.9 --lon 4.1 --json
+guru best 48309 -H 24 --json   # De Slufter
+```
+
+`guru best` always uses **WINDGURU_DEFAULT** Tune weights and returns the **top 3** models + forecasts. Prefer that over raw GFS.
+
+JSON envelope: `{"ok": true|false, "api_version": 1, "data"|error fields}`. Shared `error_type` / `retryable` with MCP.
+
+## CLI
+
+| Command | Role |
+|---------|------|
+| `guru instruct` | Teach agents the workflow |
+| `guru spots <q>` | Name search |
+| `guru near --lat --lon` | Free map markers near a point |
+| `guru best <spot>` | WINDGURU_DEFAULT → top 3 → forecasts |
+| `guru forecast <spot> -m gfs` | Single model |
+| `guru models` / `schema` / `doctor` | Discoverability |
+
+Ambiguous names fail with `error_type: ambiguous` + `candidates` (pass numeric id or `--pick`).
+
+## Library
+
+```python
+from guru import search_spots, get_best_forecast, spots_near
+
+spots = search_spots("castelldefels")
+best = get_best_forecast(201, top=3, hours=24)
+print(best.models[0].name, best.models[0].weight_pct)
+print(best.forecasts[0].hours[0].wind_kn)
+```
+
+## Architecture
+
+| Layer | Path | Role |
+|-------|------|------|
+| Core | `guru/core/` | Shared envelope, errors, instruct recipe |
+| CLI | `guru/cli/` | Typer + Rich + `--json` (thin over core) |
+| MCP | `guru/mcp/` | FastMCP over core (no CLI imports) |
+| Search | `guru/search/` | HTTP (`curl_cffi`), blend_math, near, forecast |
+| Models | `guru/models/` | Pydantic + aliases only |
+| Wire | [`docs/WIRE.md`](docs/WIRE.md) | Captured `iapi.php` |
+| MCP | [`docs/mcp.md`](docs/mcp.md) | `guru-mcp` setup + tools |
+
+Read [`AGENTS.md`](AGENTS.md) before extending. Capture Network → fixtures → tests.
+
+Engineering standards (kept in-repo):
+
+- [`docs/code_quality.md`](docs/code_quality.md) — Korotkevich / Tourist bar (layers, size caps, pure core)
+- [`docs/data_engineering_standards.md`](docs/data_engineering_standards.md) — Gray / Stonebraker bar (one writer, clocks, contracts)
+
+## Disclaimer
+
+Unofficial. Not affiliated with Windguru. Personal / research use; respect ToS and rate limits.
+
+## License
+
+MIT

windguru-0.2.0/docs/WIRE.md

@@ -0,0 +1,103 @@
+# Wire — Windguru `iapi.php`
+
+Public JSON the SPA uses. Drive these endpoints with `curl_cffi` + **Referer**. Never scrape HTML, Tune jBox, or MapLibre.
+
+Captured 2026-09-22 (Castelldefels `201`, De Slufter `48309`). Fixtures under `fixtures/`.
+
+## Hosts
+
+| Base | Use |
+|------|-----|
+| `https://www.windguru.cz/int/iapi.php` | Search, simplemap, `forecast_spot`, `forecast`, `model_info_full` |
+| `https://www.windguru.net/int/iapi.php` | SPA `forecast` with `rundef` + `cache_index` (fallback) |
+
+| Call | Referer |
+|------|---------|
+| search / model_info | `https://www.windguru.cz/` |
+| spot / forecast | `https://www.windguru.cz/{id_spot}` |
+| simplemap | `https://www.windguru.cz/map/spot/` |
+
+## Queries (free)
+
+### `q=search_spots&search=…`
+
+```json
+{ "count": N, "spots": [{ "id_spot", "spotname", "country", "nickname?" }] }
+```
+
+Name search only — no lat/lon. CLI: `guru spots`.
+
+### `q=spots&opt=simplemap&WGCACHEABLE=1800`
+
+Same markers as the [spot map](https://www.windguru.cz/map/spot/):
+
+```json
+{ "count": N, "spots": [[id_spot, spotname, lat, lon], ...] }
+```
+
+~10k rows worldwide. CLI: `guru near --lat --lon`. No PRO.
+
+### `q=forecast_spot&id_spot=…`
+
+| Path | Content |
+|------|---------|
+| `spots["{id}"]` | name, lat/lon/alt, **`models`** (id_model list for that spot) |
+| `tabs[0].blend` | **WINDGURU DEFAULT** (`id_blend_settings: 1`): `res_sensitivity`, `init_sensitivity`, `model_koef` |
+| `tabs[0].id_model_arr` | per-model `rundef`, `cache_index`, `initstr` |
+
+### `q=model_info_full`
+
+Keyed by id string. Fields used by blend: `model_name`, `resolution`, `initstamp`, `priority`, `wave`, `virtual`.
+
+### `q=forecast&id_spot=…&id_model=…`
+
+Top-level + `fcst` parallel arrays (**knots**): `hours`, `WINDSPD`, `GUST`, `WINDDIR`, `TMP`/`TMPE`, `APCP`/`APCP1`, `TCDC`, `RH`, `initstamp`.
+
+Also returns `wgmodel` (resolution_real, initstamp) when needed for debugging.
+
+### SPA fallback (if simple `forecast` dies)
+
+```
+GET …/windguru.net/int/iapi.php?q=forecast
+  &id_model=3&rundef=…&id_spot=201&WGCACHEABLE=21600&cache_index=…
+```
+
+Same lesson as fli `_tfs`: params from `forecast_spot` tab rows.
+
+## WINDGURU DEFAULT weights
+
+Port of SPA `di.calcSortByWeights` → `guru/search/blend.py`.
+
+```
+res_w[id]  = normalize( resolution ** (-2 * res_sensitivity) )
+init_w[id] = normalize( ai(init_sensitivity, age_h) )
+wgt_raw    = res_w * init_w * model_koef[id]
+weight     = wgt_raw / Σ wgt_raw
+
+ai(s, age) = max(0, 100*(age+4)^(-0.5*s) - 3*s*age)
+age_h      = (max_initstamp - initstamp) / 3600
+normalize  = scale so mean≈1, cap individual ≤1.5
+```
+
+Skip `wave`, `virtual`, and id `100` (WG Mix table). Sort weight desc, then `priority` asc. Product: **top 3**.
+
+## Agent path
+
+`spots` | `near` → `best` (preset locked) → ignore lower models.
+
+## Fixtures
+
+| File | Source |
+|------|--------|
+| `search_castelldefels.json` | `search_spots` |
+| `forecast_spot_201.json` | Castelldefels |
+| `forecast_spot_48309.json` | De Slufter |
+| `model_info_full.json` | live catalog |
+| `forecast_201_gfs.json` | GFS sample |
+| `spots_simplemap_nl.json` | NL bbox subset of simplemap |
+
+Refresh: `python scripts/capture_fixtures.py`
+
+## Rate limits
+
+Unknown. Retries via tenacity; prefer `WGCACHEABLE` on simplemap. Be polite.