windguru 0.2.0__py3-none-any.whl

guru/__init__.py

@@ -0,0 +1,28 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from guru.models.blend import BestForecast, BlendWeight
+from guru.models.forecast import Forecast, ForecastHour, Spot
+from guru.search.blend import get_best_forecast
+from guru.search.forecast import get_forecast
+from guru.search.near import spots_near
+from guru.search.spots import get_spot, resolve_spot, search_spots
+
+try:
+    __version__ = version("windguru")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.2.0"
+
+__all__ = [
+    "BestForecast",
+    "BlendWeight",
+    "Forecast",
+    "ForecastHour",
+    "Spot",
+    "get_best_forecast",
+    "get_forecast",
+    "get_spot",
+    "resolve_spot",
+    "search_spots",
+    "spots_near",
+    "__version__",
+]

guru/cli/__init__.py

@@ -0,0 +1,3 @@
+from guru.cli.main import app, cli
+
+__all__ = ["app", "cli"]

guru/cli/console.py

@@ -0,0 +1,3 @@
+from rich.console import Console
+
+console = Console()

guru/cli/errors.py

@@ -0,0 +1,34 @@
+"""CLI emit / fail helpers (stdout JSON + Rich)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import typer
+
+from guru.cli.console import console
+from guru.core.envelope import error_payload, success_payload
+from guru.core.errors import classify_error
+
+
+def emit_json(data: Any) -> None:
+    """Write JSON to stdout (success or pre-built envelope)."""
+    sys.stdout.write(json.dumps(data, default=str) + "\n")
+
+
+def print_ok(data: Any) -> None:
+    """Emit a success envelope."""
+    emit_json(success_payload(data))
+
+
+def fail(exc: BaseException, *, as_json: bool) -> None:
+    """Print error (JSON or Rich) and exit with a stable code."""
+    classified = classify_error(exc)
+    code = 2 if classified.retryable else 1
+    if as_json:
+        emit_json(error_payload(exc))
+        raise typer.Exit(code) from exc
+    console.print(f"[red]{exc}[/red]")
+    raise typer.Exit(code) from exc

guru/cli/main.py

@@ -0,0 +1,209 @@
+"""Typer CLI — agent-friendly Windguru client (fli-style)."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from guru import __version__
+from guru.cli.console import console
+from guru.cli.errors import fail, print_ok
+from guru.cli.render import (
+    print_best,
+    print_forecast,
+    print_models_table,
+    print_near_table,
+    print_spots_table,
+)
+from guru.core.envelope import ERROR_SCHEMA, dump_model
+from guru.core.instruct import instruct_payload
+from guru.models.aliases import list_models
+from guru.search.blend import get_best_forecast
+from guru.search.exceptions import GuruError
+from guru.search.forecast import get_forecast
+from guru.search.near import spots_near
+from guru.search.spots import resolve_spot, search_spots
+
+_CATCH = (GuruError, ValueError, OSError)
+
+app = typer.Typer(
+    name="guru",
+    help=(
+        "Windguru CLI for humans and AI agents. "
+        "Prefer `guru best <spot> --json` (WINDGURU_DEFAULT top 3). "
+        "Run `guru instruct --json` for the agent recipe."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.command("version")
+def version_cmd(
+    as_json: bool = typer.Option(False, "--json", help="Machine-readable envelope"),
+) -> None:
+    if as_json:
+        print_ok({"version": __version__})
+    else:
+        console.print(__version__)
+
+
+@app.command("instruct")
+def instruct_cmd(
+    as_json: bool = typer.Option(True, "--json/--no-json", help="JSON recipe (default on)"),
+) -> None:
+    """Explain the free WINDGURU_DEFAULT → top-3 workflow for agents."""
+    payload = instruct_payload()
+    if as_json:
+        print_ok(payload)
+        return
+    console.print(payload["summary"])
+    for step in payload["steps"]:
+        console.print(f"{step['step']}. {step['action']}: {step['detail']}")
+        if step.get("command"):
+            console.print(f"   [cyan]{step['command']}[/cyan]")
+
+
+@app.command("spots")
+def spots_cmd(
+    query: str = typer.Argument(..., help="Spot name search"),
+    limit: int = typer.Option(20, "--limit", "-n"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Search Windguru spots by name (live API)."""
+    try:
+        spots = search_spots(query, limit=limit)
+    except _CATCH as exc:
+        fail(exc, as_json=as_json)
+    if as_json:
+        print_ok([dump_model(s) for s in spots])
+        return
+    print_spots_table(spots, title=f"Spots matching {query!r}")
+
+
+@app.command("near")
+def near_cmd(
+    lat: float = typer.Option(..., "--lat", help="Latitude"),
+    lon: float = typer.Option(..., "--lon", help="Longitude"),
+    radius: float = typer.Option(50.0, "--radius", help="Search radius km"),
+    limit: int = typer.Option(20, "--limit", "-n"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Named spots near a point (free map markers — not PRO click-forecast)."""
+    try:
+        spots = spots_near(lat, lon, radius_km=radius, limit=limit)
+    except _CATCH as exc:
+        fail(exc, as_json=as_json)
+    if as_json:
+        print_ok([dump_model(s) for s in spots])
+        return
+    print_near_table(spots, lat=lat, lon=lon, radius=radius)
+
+
+@app.command("best")
+def best_cmd(
+    spot: str = typer.Argument(..., help="Spot id or unique name"),
+    top: int = typer.Option(3, "--top", help="How many WINDGURU_DEFAULT models to keep"),
+    hours: int = typer.Option(
+        48, "--hours", "-H", help="Max forecast steps to return per model"
+    ),
+    pick: int | None = typer.Option(None, "--pick", help="Disambiguate by spot id"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """WINDGURU DEFAULT Tune → top models by weight → those forecasts."""
+    try:
+        resolved = resolve_spot(spot, pick=pick)
+        best = get_best_forecast(resolved.id, top=top, hours=hours)
+    except _CATCH as exc:
+        fail(exc, as_json=as_json)
+    if as_json:
+        print_ok(dump_model(best))
+        return
+    print_best(best)
+
+
+@app.command("forecast")
+def forecast_cmd(
+    spot: str = typer.Argument(..., help="Spot id or unique name"),
+    model: str = typer.Option("gfs", "--model", "-m", help="Model alias or id"),
+    hours: int = typer.Option(
+        48, "--hours", "-H", help="Max forecast steps to return"
+    ),
+    pick: int | None = typer.Option(None, "--pick", help="Disambiguate by spot id"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Single-model forecast (escape hatch; prefer `guru best`)."""
+    try:
+        resolved = resolve_spot(spot, pick=pick)
+        fc = get_forecast(resolved.id, model=model, hours=hours)
+    except _CATCH as exc:
+        fail(exc, as_json=as_json)
+    if as_json:
+        print_ok(dump_model(fc))
+        return
+    print_forecast(fc)
+
+
+@app.command("models")
+def models_cmd(
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """List known model aliases (extend from live captures)."""
+    rows = list_models()
+    if as_json:
+        print_ok(rows)
+        return
+    print_models_table(rows)  # type: ignore[arg-type]
+
+
+@app.command("schema")
+def schema_cmd(
+    name: str = typer.Argument("forecast", help="spot | forecast | best | error | instruct"),
+) -> None:
+    """Dump JSON Schema for agent payloads."""
+    from guru.models.blend import BestForecast
+    from guru.models.forecast import Forecast, Spot
+
+    schemas = {
+        "spot": Spot.model_json_schema(),
+        "forecast": Forecast.model_json_schema(),
+        "best": BestForecast.model_json_schema(),
+        "instruct": {"type": "object", "description": "see guru instruct --json"},
+        "error": ERROR_SCHEMA,
+    }
+    key = name.lower().strip()
+    if key not in schemas:
+        fail(
+            ValueError(f"Unknown schema {name!r}. Choose: {', '.join(sorted(schemas))}"),
+            as_json=True,
+        )
+    print_ok({"name": key, "schema": schemas[key]})
+
+
+@app.command("doctor")
+def doctor_cmd(
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Env + version sanity check (no live Windguru call)."""
+    info = {
+        "version": __version__,
+        "GURU_TIMEOUT": os.environ.get("GURU_TIMEOUT", "30"),
+        "GURU_IMPERSONATE": os.environ.get("GURU_IMPERSONATE", "chrome"),
+        "models": list_models(),
+    }
+    if as_json:
+        print_ok(info)
+        return
+    console.print(f"guru {__version__}")
+    console.print(f"GURU_TIMEOUT={info['GURU_TIMEOUT']}")
+    console.print(f"GURU_IMPERSONATE={info['GURU_IMPERSONATE']}")
+    console.print(f"{len(info['models'])} known model aliases")
+
+
+def cli() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    cli()

guru/cli/render.py

@@ -0,0 +1,88 @@
+"""Rich human-readable tables."""
+
+from __future__ import annotations
+
+from rich.table import Table
+
+from guru.cli.console import console
+from guru.models.blend import BestForecast
+from guru.models.forecast import Forecast, Spot, wind_dir_cardinal
+
+
+def print_spots_table(spots: list[Spot], *, title: str) -> None:
+    table = Table(title=title)
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Country")
+    table.add_column("Nick")
+    for s in spots:
+        table.add_row(str(s.id), s.name, s.country or "", s.nickname or "")
+    console.print(table)
+
+
+def print_near_table(spots: list[Spot], *, lat: float, lon: float, radius: float) -> None:
+    table = Table(title=f"Spots within {radius:g} km of {lat:g},{lon:g}")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Lat")
+    table.add_column("Lon")
+    for s in spots:
+        lat_s = f"{s.lat:.4f}" if s.lat is not None else ""
+        lon_s = f"{s.lon:.4f}" if s.lon is not None else ""
+        table.add_row(str(s.id), s.name, lat_s, lon_s)
+    console.print(table)
+
+
+def print_models_table(rows: list[dict[str, object]]) -> None:
+    table = Table(title="Models")
+    table.add_column("ID")
+    table.add_column("Primary")
+    table.add_column("Aliases")
+    for row in rows:
+        aliases = row.get("aliases") or []
+        alias_s = ", ".join(str(a) for a in aliases)  # type: ignore[arg-type]
+        table.add_row(str(row["id"]), str(row["primary"]), alias_s)
+    console.print(table)
+
+
+def print_best(best: BestForecast) -> None:
+    console.print(
+        f"[bold]{best.spot.name}[/bold] · preset {best.preset} · top {len(best.models)}"
+    )
+    table = Table(title="WINDGURU DEFAULT weights")
+    table.add_column("#")
+    table.add_column("Model")
+    table.add_column("ID")
+    table.add_column("%", justify="right")
+    for m in best.models:
+        table.add_row(str(m.rank), m.name, str(m.id_model), f"{m.weight_pct:.1f}")
+    console.print(table)
+    for fc in best.forecasts:
+        print_forecast(fc)
+
+
+def print_forecast(fc: Forecast) -> None:
+    title = f"{fc.spot.name} · {fc.model} ({fc.model_id})"
+    if fc.init:
+        title += f" · init {fc.init.strftime('%Y-%m-%d %HZ')}"
+    table = Table(title=title)
+    table.add_column("UTC", style="dim")
+    table.add_column("kt", justify="right")
+    table.add_column("Gust", justify="right")
+    table.add_column("Dir")
+    table.add_column("°C", justify="right")
+    table.add_column("mm", justify="right")
+    for row in fc.hours:
+        table.add_row(
+            row.time.strftime("%a %d %H:%M"),
+            _fmt(row.wind_kn, 1),
+            _fmt(row.gust_kn, 1),
+            f"{wind_dir_cardinal(row.wind_dir_deg)} {_fmt(row.wind_dir_deg, 0)}".strip(),
+            _fmt(row.temp_c, 1),
+            _fmt(row.precip_mm, 1),
+        )
+    console.print(table)
+
+
+def _fmt(v: float | None, digits: int) -> str:
+    return "-" if v is None else f"{v:.{digits}f}"

guru/core/__init__.py

@@ -0,0 +1,22 @@
+"""Shared core utilities (CLI + MCP)."""
+
+from guru.core.envelope import (
+    API_VERSION,
+    ERROR_SCHEMA,
+    dump_model,
+    error_payload,
+    success_payload,
+)
+from guru.core.errors import ErrorClassification, classify_error
+from guru.core.instruct import instruct_payload
+
+__all__ = [
+    "API_VERSION",
+    "ERROR_SCHEMA",
+    "ErrorClassification",
+    "classify_error",
+    "dump_model",
+    "error_payload",
+    "instruct_payload",
+    "success_payload",
+]

guru/core/envelope.py

@@ -0,0 +1,45 @@
+"""Shared JSON envelope for CLI and MCP (fli-style agent contract)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from guru.core.errors import classify_error
+from guru.search.exceptions import GuruAmbiguousError
+
+API_VERSION = 1
+
+ERROR_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "ok": {"const": False},
+        "api_version": {"type": "integer"},
+        "error": {"type": "string"},
+        "error_type": {"type": "string"},
+        "retryable": {"type": "boolean"},
+        "http_status": {"type": "integer"},
+        "candidates": {"type": "array"},
+    },
+}
+
+
+def success_payload(data: Any) -> dict[str, Any]:
+    return {"ok": True, "api_version": API_VERSION, "data": data}
+
+
+def error_payload(exc: BaseException) -> dict[str, Any]:
+    classified = classify_error(exc)
+    payload: dict[str, Any] = {
+        "ok": False,
+        "api_version": API_VERSION,
+        "error": str(exc),
+        **classified.as_fields(),
+    }
+    if isinstance(exc, GuruAmbiguousError):
+        payload["candidates"] = [c.model_dump(mode="json") for c in exc.candidates]
+    return payload
+
+
+def dump_model(model: Any) -> Any:
+    """Pydantic model → JSON-ready dict."""
+    return model.model_dump(mode="json")

guru/core/errors.py

@@ -0,0 +1,60 @@
+"""Shared error classification for CLI and MCP (fli-style)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from guru.search.exceptions import (
+    GuruAmbiguousError,
+    GuruError,
+    GuruHTTPError,
+    GuruNotFoundError,
+    GuruParseError,
+)
+
+_RETRYABLE_HTTP = {429}
+
+
+@dataclass(frozen=True)
+class ErrorClassification:
+    error_type: str
+    retryable: bool
+    http_status: int | None = None
+
+    def as_fields(self) -> dict[str, Any]:
+        fields: dict[str, Any] = {
+            "error_type": self.error_type,
+            "retryable": self.retryable,
+        }
+        if self.http_status is not None:
+            fields["http_status"] = self.http_status
+        return fields
+
+
+def classify_error(exc: BaseException) -> ErrorClassification:
+    """Map an exception to a stable ``error_type`` + ``retryable`` pair."""
+    if isinstance(exc, GuruAmbiguousError):
+        return ErrorClassification("ambiguous", retryable=False)
+    if isinstance(exc, GuruNotFoundError):
+        return ErrorClassification("not_found", retryable=False)
+    if isinstance(exc, GuruParseError):
+        return ErrorClassification("parse_error", retryable=False)
+    if isinstance(exc, GuruHTTPError):
+        status = getattr(exc, "status_code", None)
+        retryable = status is not None and (status in _RETRYABLE_HTTP or status >= 500)
+        return ErrorClassification("http_error", retryable=retryable, http_status=status)
+    if isinstance(exc, TimeoutError):
+        return ErrorClassification("timeout", retryable=True)
+    if isinstance(exc, ConnectionError | OSError):
+        return ErrorClassification("connection_error", retryable=True)
+    if isinstance(exc, ValueError):
+        return ErrorClassification("validation_error", retryable=False)
+    if isinstance(exc, GuruError):
+        return ErrorClassification("search_error", retryable=False)
+    msg = str(exc).lower()
+    if "timeout" in msg:
+        return ErrorClassification("timeout", retryable=True)
+    if "429" in msg or "rate" in msg:
+        return ErrorClassification("rate_limited", retryable=True, http_status=429)
+    return ErrorClassification("unexpected_error", retryable=False)

guru/core/instruct.py

@@ -0,0 +1,66 @@
+"""Agent recipe text (CLI ``instruct`` + MCP)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+INSTRUCT_STEPS: list[dict[str, Any]] = [
+    {
+        "step": 1,
+        "action": "search_spots",
+        "command": 'guru spots "<name>" --json',
+        "detail": (
+            "Search named Windguru spots. If multiple matches, pick an id "
+            "(do not guess)."
+        ),
+    },
+    {
+        "step": 2,
+        "action": "near_spots",
+        "command": "guru near --lat <lat> --lon <lon> --json",
+        "detail": (
+            "Or find free named spots near coordinates (map markers). "
+            "Never use PRO lat/lon click-forecast."
+        ),
+    },
+    {
+        "step": 3,
+        "action": "best_forecast",
+        "command": "guru best <id_spot> --json",
+        "detail": (
+            "Uses Tune preset WINDGURU_DEFAULT only: compute model weights "
+            "(resolution × freshness × preference), keep top 3, fetch those forecasts."
+        ),
+    },
+    {
+        "step": 4,
+        "action": "ignore_rest",
+        "command": None,
+        "detail": (
+            "Ignore lower-weighted models unless the user asks for a specific "
+            "model via guru forecast -m."
+        ),
+    },
+]
+
+INSTRUCT_SUMMARY = (
+    "For any place: resolve a named Windguru spot, then run guru best. "
+    "Always WINDGURU_DEFAULT Tune; trust only the top 3 models by weight. "
+    "Do not scrape windguru.cz HTML or the map canvas. Do not require PRO."
+)
+
+
+def instruct_payload() -> dict[str, Any]:
+    return {
+        "summary": INSTRUCT_SUMMARY,
+        "preset": "WINDGURU_DEFAULT",
+        "top_models": 3,
+        "steps": INSTRUCT_STEPS,
+        "examples": [
+            'guru spots "castelldefels" --json',
+            "guru best 201 --json",
+            'guru spots "De Slufter" --json',
+            "guru best 48309 -H 24 --json",
+            "guru near --lat 51.9 --lon 4.1 --radius 40 --json",
+        ],
+    }

guru/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP package."""

guru/mcp/_entry.py

@@ -0,0 +1,31 @@
+"""MCP console-script entry points."""
+
+from __future__ import annotations
+
+import sys
+
+
+def run() -> None:
+    try:
+        from guru.mcp.server import mcp
+    except ModuleNotFoundError:
+        print(
+            "MCP dependencies are not installed.\n"
+            "Install them with:  pip install 'windguru[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    mcp.run()
+
+
+def run_http() -> None:
+    try:
+        from guru.mcp.server import mcp
+    except ModuleNotFoundError:
+        print(
+            "MCP dependencies are not installed.\n"
+            "Install them with:  pip install 'windguru[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    mcp.run(transport="http", host="127.0.0.1", port=8000)