forcingkit 0.1.0__py3-none-any.whl

forcingkit_serve/routers/bathymetry.py

@@ -0,0 +1,241 @@
+import hashlib
+import httpx
+import logging
+from pathlib import Path
+from fastapi import APIRouter, Query, HTTPException
+from fastapi.responses import StreamingResponse, FileResponse
+from starlette.background import BackgroundTask
+from pydantic import BaseModel
+from forcingkit import settings
+
+router = APIRouter(prefix="/api/v1/bathymetry", tags=["bathymetry"])
+logger = logging.getLogger(__name__)
+
+
+async def stream_remote_file(url: str):
+    """
+    Passthrough proxy stream for local topobathykit setups to prevent local disk double-caching.
+    Large timeout applied because fusing geospatial data can take 5+ minutes.
+    """
+    client = httpx.AsyncClient()
+    request = client.build_request("GET", url, timeout=3600.0)
+    response = await client.send(request, stream=True)
+
+    if response.status_code != 200:
+        await response.aread()
+        await response.aclose()
+        await client.aclose()
+        raise HTTPException(
+            status_code=response.status_code,
+            detail=f"topobathykit Error: {response.text}",
+        )
+
+    async def cleanup():
+        await response.aclose()
+        await client.aclose()
+
+    return StreamingResponse(
+        response.aiter_raw(),
+        media_type="application/zip",
+        background=BackgroundTask(cleanup),
+    )
+
+
+@router.get("/fuse")
+async def fuse_bathymetry(
+    west: float = Query(..., description="Bounding box west (lon)"),
+    south: float = Query(..., description="Bounding box south (lat)"),
+    east: float = Query(..., description="Bounding box east (lon)"),
+    north: float = Query(..., description="Bounding box north (lat)"),
+    resolution: float = Query(10.0, description="Output resolution in meters"),
+    format: str = Query("zarr", description="Output format: geotiff or zarr"),
+):
+    """
+    Smart proxy for topobathykit that retrieves fused topography.
+    If topobathykit is on a remote cluster, this caches the zipped output locally
+    in forcingkit so future identical runs bypass the network.
+    """
+    topobathy_url = settings.env("TOPOBATHYKIT_URL", "http://localhost:9595").rstrip(
+        "/"
+    )
+    target_url = f"{topobathy_url}/fuse?west={west}&south={south}&east={east}&north={north}&resolution={resolution}&format={format}"
+
+    is_local = (
+        "localhost" in topobathy_url
+        or "127.0.0.1" in topobathy_url
+        or "0.0.0.0" in topobathy_url
+    )
+
+    if is_local:
+        logger.info(
+            f"topobathykit is local ({topobathy_url}). Streaming directly to avoid disk duplication."
+        )
+        try:
+            return await stream_remote_file(target_url)
+        except httpx.ConnectError:
+            raise HTTPException(
+                status_code=502,
+                detail=f"topobathykit is unreachable at {topobathy_url}. Please ensure the service is running on port 9595.",
+            )
+        except httpx.ReadTimeout:
+            raise HTTPException(
+                status_code=504,
+                detail=f"topobathykit at {topobathy_url} timed out during fusion.",
+            )
+
+    # --- IF REMOTE, Cache Strategy is Engaged ---
+    logger.info(
+        f"topobathykit is remote ({topobathy_url}). Entering proxy-cache routine."
+    )
+    cache_dir = Path(settings.cache_dir()).expanduser() / "bathymetry"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # Predictable cache key
+    key_str = f"{west},{south},{east},{north}_{resolution}_{format}"
+    cache_key = hashlib.md5(key_str.encode()).hexdigest()
+    cache_path = cache_dir / f"fused_proxy_{cache_key}.zip"
+
+    if cache_path.exists():
+        logger.info(f"Serving topography from local cache: {cache_path}")
+        return FileResponse(
+            path=cache_path,
+            media_type="application/zip",
+            filename=f"fused_{cache_key}.zip",
+        )
+
+    # Download and cache it
+    logger.info(
+        f"Cache miss. Fetching from remote topobathykit and writing to {cache_path}..."
+    )
+    try:
+        async with httpx.AsyncClient(timeout=3600.0) as client:
+            async with client.stream("GET", target_url) as response:
+                if response.status_code != 200:
+                    text = await response.aread()
+                    raise HTTPException(
+                        status_code=response.status_code,
+                        detail=f"topobathykit Error: {text.decode('utf-8')}",
+                    )
+
+                # Stream directly to disk
+                with open(cache_path, "wb") as f_out:
+                    async for chunk in response.aiter_bytes(chunk_size=8192):
+                        f_out.write(chunk)
+
+    except Exception as e:
+        if cache_path.exists():
+            cache_path.unlink()
+        raise HTTPException(status_code=500, detail=f"Proxy stream failed: {str(e)}")
+
+    logger.info(f"Successfully cached and serving: {cache_path}")
+    return FileResponse(
+        path=cache_path, media_type="application/zip", filename=f"fused_{cache_key}.zip"
+    )
+
+
+class FusionRequest(BaseModel):
+    bbox: list[float]
+    resolution: float = 30.0
+    format: str = "zarr"
+    policy_name: str | None = None
+    policy_yaml: str | None = None
+
+
+@router.post("/fuse")
+async def fuse_bathymetry_post(request: FusionRequest):
+    topobathy_url = settings.env("TOPOBATHYKIT_URL", "http://localhost:9595").rstrip(
+        "/"
+    )
+    target_url = f"{topobathy_url}/fuse"
+    is_local = (
+        "localhost" in topobathy_url
+        or "127.0.0.1" in topobathy_url
+        or "0.0.0.0" in topobathy_url
+    )
+    if is_local:
+        client = httpx.AsyncClient()
+        req = client.build_request(
+            "POST", target_url, timeout=3600.0, json=request.model_dump()
+        )
+        try:
+            response = await client.send(req, stream=True)
+        except httpx.ConnectError:
+            raise HTTPException(
+                status_code=502,
+                detail=f"topobathykit is unreachable at {topobathy_url}. Please ensure the service is running on port 9595.",
+            )
+        except httpx.ReadTimeout:
+            raise HTTPException(
+                status_code=504,
+                detail=f"topobathykit at {topobathy_url} timed out during fusion.",
+            )
+
+        if response.status_code != 200:
+            text = await response.aread()
+            await response.aclose()
+            await client.aclose()
+            raise HTTPException(
+                status_code=response.status_code,
+                detail=f"topobathykit Error: {text.decode('utf-8')}",
+            )
+
+        async def cleanup():
+            await response.aclose()
+            await client.aclose()
+
+        return StreamingResponse(
+            response.aiter_raw(),
+            media_type="application/zip",
+            background=BackgroundTask(cleanup),
+        )
+
+    logger.info(
+        f"topobathykit is remote ({topobathy_url}). Entering proxy-cache routine."
+    )
+    cache_dir = Path(settings.cache_dir()).expanduser() / "bathymetry"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # Include policy in cache key
+    policy_hash = "default"
+    if request.policy_yaml:
+        policy_hash = hashlib.md5(request.policy_yaml.encode()).hexdigest()
+    elif request.policy_name:
+        policy_hash = request.policy_name
+
+    key_str = f"{request.bbox}_{request.resolution}_{request.format}_{policy_hash}"
+    cache_key = hashlib.md5(key_str.encode()).hexdigest()
+    cache_path = cache_dir / f"fused_proxy_{cache_key}.zip"
+
+    if cache_path.exists():
+        logger.info(f"Serving topography from local cache: {cache_path}")
+        return FileResponse(
+            path=cache_path,
+            media_type="application/zip",
+            filename=f"fused_{cache_key}.zip",
+        )
+
+    logger.info(
+        f"Cache miss. Fetching from remote topobathykit and writing to {cache_path}..."
+    )
+    try:
+        async with httpx.AsyncClient(timeout=3600.0) as client:
+            async with client.stream(
+                "POST", target_url, json=request.model_dump()
+            ) as response:
+                if response.status_code != 200:
+                    text = await response.aread()
+                    raise HTTPException(
+                        status_code=response.status_code,
+                        detail=f"topobathykit Error: {text.decode('utf-8')}",
+                    )
+                with open(cache_path, "wb") as f_out:
+                    async for chunk in response.aiter_bytes(chunk_size=8192):
+                        f_out.write(chunk)
+    except Exception as e:
+        if cache_path.exists():
+            cache_path.unlink()
+        raise HTTPException(status_code=500, detail=f"Proxy stream failed: {str(e)}")
+
+    return FileResponse(
+        path=cache_path, media_type="application/zip", filename=f"fused_{cache_key}.zip"
+    )

forcingkit_serve/routers/plotly_api.py

@@ -0,0 +1,150 @@
+from fastapi import APIRouter, Query, HTTPException, Response
+import os
+from pathlib import Path
+import logging
+import json
+import numpy as np
+import xarray as xr
+from forcingkit import settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Cache View Data"])
+
+
+@router.get("/api/v1/cache/data")
+async def get_dataset_data(
+    dataset_id: str = Query(..., description="ID of the dataset"),
+    ext: str = Query(..., description="Extension"),
+    var_name: str = Query(..., description="Variable query"),
+    time_idx: str = Query("0", description="Time step index OR 'all'"),
+    lod: int = Query(0, description="Level of Detail stride (0=auto)"),
+):
+    cache_dir = Path(settings.cache_dir()).expanduser()
+    full_path = os.path.join(
+        cache_dir, f"{dataset_id}.zarr" if ext == "zarr" else f"{dataset_id}.{ext}"
+    )
+
+    if not os.path.exists(full_path):
+        raise HTTPException(status_code=404, detail="Dataset not found")
+
+    try:
+        ds = (
+            xr.open_zarr(full_path)
+            if ext == "zarr"
+            else xr.open_dataset(
+                full_path, engine="cfgrib" if ext == "grib" else "netcdf4"
+            )
+        )
+        if var_name not in ds.variables:
+            raise HTTPException(status_code=404, detail="Variable not found")
+
+        data_var = ds[var_name]
+
+        # Dimensions
+        slice_opts = {}
+        fetch_all_time = time_idx == "all"
+
+        for time_cand in ["time", "valid_time", "step", "ocean_time"]:
+            if time_cand in data_var.dims:
+                if not fetch_all_time:
+                    idx = int(time_idx)
+                    slice_opts[time_cand] = min(idx, ds.sizes[time_cand] - 1)
+
+        for z_name in ["depth", "zC", "level", "s_rho", "surface", "siglay", "siglev"]:
+            if z_name in data_var.dims and z_name not in slice_opts:
+                slice_opts[z_name] = (
+                    -1 if z_name in ("s_rho", "siglay", "siglev") else 0
+                )
+
+        valid_opts = {k: v for k, v in slice_opts.items() if k in data_var.dims}
+        da = data_var.isel(valid_opts)
+
+        # Smart sub-sampling
+        y_name = next(
+            (
+                str(d)
+                for d in da.dims
+                if "lat" in str(d) or "eta" in str(d) or str(d) == "y"
+            ),
+            None,
+        )
+        x_name = next(
+            (
+                str(d)
+                for d in da.dims
+                if "lon" in str(d) or "xi" in str(d) or str(d) == "x"
+            ),
+            None,
+        )
+
+        actual_stride = 1
+        if lod > 0:
+            actual_stride = lod
+        else:
+            # Auto compute stride based on spatial coords
+            if y_name and x_name:
+                max_dim = max(da.sizes[y_name], da.sizes[x_name])
+            else:
+                max_dim = max(da.shape)
+            if max_dim > 200:
+                actual_stride = int(np.ceil(max_dim / 200.0))
+
+        if actual_stride > 1:
+            slice_dict = {}
+            if y_name:
+                slice_dict[y_name] = slice(None, None, actual_stride)
+            if x_name:
+                slice_dict[x_name] = slice(None, None, actual_stride)
+            if slice_dict:
+                da = da.isel(slice_dict)
+            else:
+                # Fallback if no specific x/y dimension detected
+                spatial_dims = [
+                    d
+                    for d in da.dims
+                    if d
+                    not in [
+                        "time",
+                        "valid_time",
+                        "step",
+                        "ocean_time",
+                        "depth",
+                        "zC",
+                        "level",
+                        "s_rho",
+                        "surface",
+                        "siglay",
+                        "siglev",
+                    ]
+                ]
+                da = da.isel(
+                    {d: slice(None, None, actual_stride) for d in spatial_dims}
+                )
+
+        array = da.values
+
+        # Replace NaNs with None for JSON
+        arr = np.asarray(array)
+        masked = np.where(np.isnan(arr), None, arr).tolist()  # type: ignore
+
+        y_vals = (
+            ds[y_name].isel({y_name: slice(None, None, actual_stride)}).values.tolist()
+            if y_name and y_name in ds.coords
+            else None
+        )
+        x_vals = (
+            ds[x_name].isel({x_name: slice(None, None, actual_stride)}).values.tolist()
+            if x_name and x_name in ds.coords
+            else None
+        )
+
+        return Response(
+            content=json.dumps(
+                {"z": masked, "x": x_vals, "y": y_vals, "cube": fetch_all_time}
+            ),
+            media_type="application/json",
+        )
+
+    except Exception as e:
+        logger.error(f"Plotly data prep failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

forcingkit_serve/routers/removed.py

@@ -0,0 +1,86 @@
+"""Stubs for the routes removed on 2026-10-05.
+
+Each answers 410 Gone with the endpoint that replaces it, so a client still calling one learns
+where to go instead of meeting a bare 404. The response carries `Deprecation` (RFC 9745) and
+`Sunset` (RFC 8594) headers, both at the removal date, and `Link` headers to the notes at
+forcingkit.docs.lhzn.io (docs/source/removed_endpoints.rst). The next release drops this module and its `include_router`.
+"""
+
+import logging
+from datetime import datetime, timezone
+from email.utils import format_datetime
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger("forcingkit_serve")
+
+REMOVED_ON = datetime(2026, 10, 5, tzinfo=timezone.utc)
+DOCS_URL = "https://forcingkit.docs.lhzn.io/removed_endpoints.html"
+
+_PARENT = (
+    "POST /api/v1/obc: the parent ocean on true z (schema z-v2); its first record is the "
+    "initial condition"
+)
+_ATMOSPHERE = (
+    "POST /api/v1/atmosphere: the HRRR surface atmosphere (schema hrrr-atm-v1), including "
+    "10 m wind"
+)
+
+# (method, path) -> replacement
+REMOVED_ROUTES: dict[tuple[str, str], str] = {
+    ("POST", "/api/v1/ic/generate"): _PARENT,
+    ("POST", "/api/v1/ic/regrid"): _PARENT,
+    ("POST", "/api/v1/ic/cache"): "POST /api/v1/obc/cache",
+    ("POST", "/api/v1/ic/predict-donor"): "POST /api/v1/obc/predict-donor",
+    ("GET", "/api/v1/ic/download/{zarr_id}"): "GET /api/v1/obc/download/{zarr_id}",
+    ("POST", "/api/v1/bc/generate"): _ATMOSPHERE,
+    ("POST", "/api/v1/bc/cache"): _ATMOSPHERE + " (its response carries the store id)",
+    ("POST", "/api/v1/bc/predict-donor"): (
+        "none: the atmosphere is HRRR from 2014-07-30; earlier runs use ERA5 through "
+        "NumericalEarth in the model"
+    ),
+    (
+        "GET",
+        "/api/v1/bc/download/{zarr_id}",
+    ): "GET /api/v1/atmosphere/download/{zarr_id}",
+    ("POST", "/api/v1/harmonics"): (
+        "POST /api/v1/tide for observed water level, or the `zeta` variable of the "
+        "/api/v1/obc parent store"
+    ),
+    ("GET", "/api/v2/coupled-boundaries/{region}"): "POST /api/v1/obc",
+}
+
+router = APIRouter(tags=["Removed"])
+
+
+def _gone(method: str, path: str, replacement: str):
+    async def handler() -> JSONResponse:
+        logger.warning(f"Removed endpoint called: {method} {path}; use {replacement}")
+        return JSONResponse(
+            status_code=410,
+            content={
+                "status": "gone",
+                "detail": f"{method} {path} was removed on {REMOVED_ON.date().isoformat()}.",
+                "replacement": replacement,
+                "docs": DOCS_URL,
+            },
+            headers={
+                "Deprecation": f"@{int(REMOVED_ON.timestamp())}",
+                "Sunset": format_datetime(REMOVED_ON, usegmt=True),
+                "Link": f'<{DOCS_URL}>; rel="deprecation", <{DOCS_URL}>; rel="sunset"',
+            },
+        )
+
+    return handler
+
+
+for (_method, _path), _replacement in REMOVED_ROUTES.items():
+    router.add_api_route(
+        _path,
+        _gone(_method, _path, _replacement),
+        methods=[_method],
+        status_code=410,
+        deprecated=True,
+        summary=f"Removed on {REMOVED_ON.date().isoformat()}; use {_replacement.split(':')[0]}",
+    )