shearline 1.0.0__tar.gz

shearline-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backshear LLC
+
+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.

shearline-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: shearline
+Version: 1.0.0
+Summary: Analyst-grade US severe-weather tools for AI agents over MCP: warning polygons with IBW tags, SPC outlooks, RAP point environments, MRMS hail/rotation, storm reports, and a composite threat brief.
+Keywords: mcp,weather,severe-weather,meteorology,nws,spc,mrms,radar,ai-agents
+Author: Backshear LLC
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Dist: boto3>=1.43.27
+Requires-Dist: cfgrib>=0.9.15.1
+Requires-Dist: eccodeslib>=2.47.1.20
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: metpy>=1.7.1
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: shapely>=2.1.2
+Requires-Dist: xarray>=2026.4.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/lostnumber07/shearline
+Project-URL: Repository, https://github.com/lostnumber07/shearline
+Project-URL: Issues, https://github.com/lostnumber07/shearline/issues
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.lostnumber07/shearline -->
+
+# SHEARLINE
+
+**The severe-weather analyst your agent doesn't have.** SHEARLINE is a free, MIT-licensed MCP server that gives AI agents analyst-grade US severe-weather tools: live warning polygons with Impact-Based Warning tags, SPC convective outlooks, RAP-derived point environments (CAPE/shear/SRH/STP computed with MetPy), MRMS radar-derived hail and rotation products, ground-truth storm reports, and a composite threat brief that synthesizes all of it. A dozen weather MCPs already wrap the basic forecast API; SHEARLINE deliberately skips everything they do and ships only what requires radar meteorology to expose correctly.
+
+> **Informational only. Not a substitute for official NWS warnings.** Every tool repeats this, because it matters: when weather threatens, follow official warnings from weather.gov and local authorities.
+
+## Tools
+
+| Tool | What it returns |
+| --- | --- |
+| `get_active_warnings(lat, lon, radius_km=40)` | Active tornado/severe-thunderstorm/flash-flood warning polygons with IBW tags (max hail size, max gust, tornado detection/damage threat), parsed storm motion, expirations, and whether the exact point is inside a polygon. Watches listed separately. |
+| `get_spc_outlook(lat, lon, day=1)` | SPC categorical risk (TSTM→HIGH) at the point plus tornado/hail/wind probabilities and significant-severe flags, days 1–3, with interpretation calibrated to the category. |
+| `get_point_environment(lat, lon)` | Latest RAP 13-km analysis profile computed with MetPy: MLCAPE/MUCAPE/CINs, LCL, 0–1/0–6 km shear, 0–1/0–3 km SRH, Bunkers motion, effective inflow layer, effective SRH/shear, SCP, and significant-tornado parameter — interpreted like an analyst (pulse vs. cool-season high-shear vs. classic supercell parameter space). |
+| `get_mrms_severe(lat, lon, radius_km=40)` | MRMS maxima within radius: 60-min MESH (hail, inches and mm), low-level and mid-level rotation tracks (azimuthal shear), VIL, composite reflectivity — each with valid time and distance/bearing of the max. |
+| `get_storm_reports(lat, lon, radius_km=80, hours=6)` | Normalized Local Storm Reports: type, magnitude with units, time, location, distance/bearing, remarks. |
+| `get_threat_brief(lat, lon)` | The showpiece: runs everything above concurrently and synthesizes a threat level (none/marginal/elevated/significant/extreme) **with stated logic**, hazards ranked, environment summary, nearest storm signature, and a recommended attention window. |
+| `get_radar_snapshot(lat, lon)` | Nearest WSR-88D's latest Level 2 volume metadata: VCP (scan strategy), max reflectivity with range/azimuth, coarse echo-top estimate. |
+
+Every tool returns structured JSON with `data` (numeric fields, units stated), `interpretation` (plain-language analyst sentences), `degraded` (which upstream sources failed, if any — partial data instead of errors), and the safety `disclaimer`.
+
+## Example: threat brief during a real outbreak
+
+Real output from 2026-06-10, point inside an active tornado warning in northern Missouri:
+
+```json
+{
+  "threat_level": "extreme",
+  "threat_logic": [
+    "Tornado Warning in effect at the point, corroborated by confirmed tornado reports nearby — treat as an immediate life-safety situation.",
+    "Severe Thunderstorm Warning at the point tagged 'Considerable' (hail to 1.75\", gusts to 60 mph).",
+    "Significant-tornado parameter of 4.0 with storms ongoing — environment strongly supports tornadic supercells.",
+    "MRMS MESH of 2.3\" hail within radius in the last hour.",
+    "Intense rotation track (azimuthal shear 0.013 /s) nearby in the last hour.",
+    "6 tornado report(s) near the point in the report window."
+  ],
+  "hazards_ranked": [
+    {"hazard": "tornado", "level": "extreme"},
+    {"hazard": "hail", "level": "extreme"},
+    {"hazard": "damaging_wind", "level": "extreme"},
+    {"hazard": "flash_flood", "level": "moderate"}
+  ],
+  "nearest_storm_signature": {
+    "signature": "composite reflectivity", "value": "58.5 dBZ",
+    "distance_km": 18.0, "direction": "ENE", "valid_utc": "2026-06-10T22:14Z"
+  },
+  "attention_window": {"window": "now", "until_utc": "2026-06-10T21:00:00-05:00"}
+}
+```
+
+And the same tool for a quiet coastal Maine point reads as confidently quiet — not as an error: `"threat_level": "none"` with the environment numbers shown so the agent can see *why* it's quiet.
+
+## Install
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/). No API keys — every data source is public and anonymous.
+
+**Claude Code:**
+
+```sh
+claude mcp add shearline -- uvx --from git+https://github.com/lostnumber07/shearline shearline
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shearline": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/lostnumber07/shearline", "shearline"]
+    }
+  }
+}
+```
+
+(Once published to PyPI, `uvx shearline` alone works.)
+
+**Streamable HTTP** (for remote/agent-platform use):
+
+```sh
+uvx --from git+https://github.com/lostnumber07/shearline shearline --http --port 8741
+# serves at http://127.0.0.1:8741/mcp
+```
+
+## Why these tools
+
+A forecast API tells you it might rain. None of the questions that matter on a severe weather day — *is this storm rotating, how big is the hail, is the environment loaded for tornadoes, am I inside the polygon* — are answerable from a forecast endpoint. They require the warning's IBW tags, radar-derived products, and a real sounding:
+
+- **Warnings with IBW tags, not just warning text.** A base-tier Severe Thunderstorm Warning and one tagged `DESTRUCTIVE` with 80 mph gusts are different planning problems. SHEARLINE parses the machine-readable tags (max hail size, max gust, tornado detection/damage threat) and the storm-motion vector, and does the point-in-polygon test for you.
+- **The environment, computed honestly.** CAPE without shear is a pulse-storm day; shear without CAPE is wind-driven rain. SHEARLINE pulls the current RAP analysis profile and computes the discriminating quantities with MetPy — including the effective inflow layer, effective SRH/shear, SCP, and STP — because high-CAPE/low-shear, low-CAPE/high-shear, and classic supercell parameter spaces produce very different hazards, and the interpretation says which one you're in.
+- **MRMS, because warnings lag storms.** MESH tells you what hail a storm has *already* produced; rotation tracks show where mesocyclones have tracked in the last hour — both on a ~2-minute cadence from the national radar mosaic, often ahead of the next warning update.
+- **LSRs, because radar isn't ground truth.** Spotter reports confirm what's actually reaching the ground.
+- **One brief that reasons across all of it.** The threat level is rule-based with the triggered rules quoted back, so an agent can audit the logic instead of trusting a vibe.
+
+## Data sources (all public, no keys)
+
+- Warnings: [api.weather.gov](https://www.weather.gov/documentation/services-web-api) (NWS)
+- Outlooks: [Storm Prediction Center](https://www.spc.noaa.gov/) public GeoJSON
+- Point environment: [NOMADS](https://nomads.ncep.noaa.gov/) RAP grib filter, derived with [MetPy](https://unidata.github.io/MetPy/)
+- MRMS: [NOAA MRMS on AWS Open Data](https://registry.opendata.aws/noaa-mrms-pds/)
+- Storm reports: [Iowa Environmental Mesonet](https://mesonet.agron.iastate.edu/) LSR service
+- NEXRAD Level 2: [Unidata on AWS Open Data](https://registry.opendata.aws/noaa-nexrad/)
+
+Coverage is **continental US only** — out-of-bounds coordinates are rejected with a clear error. Upstream fetches are cached (warnings 60 s, MRMS 120 s, LSRs 300 s, outlooks/RAP 30 min) and degrade gracefully: if one source is down, you get partial data plus a `degraded` field, never a bare exception.
+
+## Development
+
+```sh
+git clone https://github.com/lostnumber07/shearline && cd shearline
+uv sync
+uv run pytest          # offline test suite against recorded fixtures
+uv run ruff check .
+uv run shearline       # stdio
+uv run python scripts/smoke.py   # live smoke test, both transports
+```
+
+## License
+
+MIT © Backshear LLC. Weather data is produced by NOAA/NWS and other public services; this project is not affiliated with or endorsed by NOAA.

shearline-1.0.0/README.md

@@ -0,0 +1,120 @@
+<!-- mcp-name: io.github.lostnumber07/shearline -->
+
+# SHEARLINE
+
+**The severe-weather analyst your agent doesn't have.** SHEARLINE is a free, MIT-licensed MCP server that gives AI agents analyst-grade US severe-weather tools: live warning polygons with Impact-Based Warning tags, SPC convective outlooks, RAP-derived point environments (CAPE/shear/SRH/STP computed with MetPy), MRMS radar-derived hail and rotation products, ground-truth storm reports, and a composite threat brief that synthesizes all of it. A dozen weather MCPs already wrap the basic forecast API; SHEARLINE deliberately skips everything they do and ships only what requires radar meteorology to expose correctly.
+
+> **Informational only. Not a substitute for official NWS warnings.** Every tool repeats this, because it matters: when weather threatens, follow official warnings from weather.gov and local authorities.
+
+## Tools
+
+| Tool | What it returns |
+| --- | --- |
+| `get_active_warnings(lat, lon, radius_km=40)` | Active tornado/severe-thunderstorm/flash-flood warning polygons with IBW tags (max hail size, max gust, tornado detection/damage threat), parsed storm motion, expirations, and whether the exact point is inside a polygon. Watches listed separately. |
+| `get_spc_outlook(lat, lon, day=1)` | SPC categorical risk (TSTM→HIGH) at the point plus tornado/hail/wind probabilities and significant-severe flags, days 1–3, with interpretation calibrated to the category. |
+| `get_point_environment(lat, lon)` | Latest RAP 13-km analysis profile computed with MetPy: MLCAPE/MUCAPE/CINs, LCL, 0–1/0–6 km shear, 0–1/0–3 km SRH, Bunkers motion, effective inflow layer, effective SRH/shear, SCP, and significant-tornado parameter — interpreted like an analyst (pulse vs. cool-season high-shear vs. classic supercell parameter space). |
+| `get_mrms_severe(lat, lon, radius_km=40)` | MRMS maxima within radius: 60-min MESH (hail, inches and mm), low-level and mid-level rotation tracks (azimuthal shear), VIL, composite reflectivity — each with valid time and distance/bearing of the max. |
+| `get_storm_reports(lat, lon, radius_km=80, hours=6)` | Normalized Local Storm Reports: type, magnitude with units, time, location, distance/bearing, remarks. |
+| `get_threat_brief(lat, lon)` | The showpiece: runs everything above concurrently and synthesizes a threat level (none/marginal/elevated/significant/extreme) **with stated logic**, hazards ranked, environment summary, nearest storm signature, and a recommended attention window. |
+| `get_radar_snapshot(lat, lon)` | Nearest WSR-88D's latest Level 2 volume metadata: VCP (scan strategy), max reflectivity with range/azimuth, coarse echo-top estimate. |
+
+Every tool returns structured JSON with `data` (numeric fields, units stated), `interpretation` (plain-language analyst sentences), `degraded` (which upstream sources failed, if any — partial data instead of errors), and the safety `disclaimer`.
+
+## Example: threat brief during a real outbreak
+
+Real output from 2026-06-10, point inside an active tornado warning in northern Missouri:
+
+```json
+{
+  "threat_level": "extreme",
+  "threat_logic": [
+    "Tornado Warning in effect at the point, corroborated by confirmed tornado reports nearby — treat as an immediate life-safety situation.",
+    "Severe Thunderstorm Warning at the point tagged 'Considerable' (hail to 1.75\", gusts to 60 mph).",
+    "Significant-tornado parameter of 4.0 with storms ongoing — environment strongly supports tornadic supercells.",
+    "MRMS MESH of 2.3\" hail within radius in the last hour.",
+    "Intense rotation track (azimuthal shear 0.013 /s) nearby in the last hour.",
+    "6 tornado report(s) near the point in the report window."
+  ],
+  "hazards_ranked": [
+    {"hazard": "tornado", "level": "extreme"},
+    {"hazard": "hail", "level": "extreme"},
+    {"hazard": "damaging_wind", "level": "extreme"},
+    {"hazard": "flash_flood", "level": "moderate"}
+  ],
+  "nearest_storm_signature": {
+    "signature": "composite reflectivity", "value": "58.5 dBZ",
+    "distance_km": 18.0, "direction": "ENE", "valid_utc": "2026-06-10T22:14Z"
+  },
+  "attention_window": {"window": "now", "until_utc": "2026-06-10T21:00:00-05:00"}
+}
+```
+
+And the same tool for a quiet coastal Maine point reads as confidently quiet — not as an error: `"threat_level": "none"` with the environment numbers shown so the agent can see *why* it's quiet.
+
+## Install
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/). No API keys — every data source is public and anonymous.
+
+**Claude Code:**
+
+```sh
+claude mcp add shearline -- uvx --from git+https://github.com/lostnumber07/shearline shearline
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shearline": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/lostnumber07/shearline", "shearline"]
+    }
+  }
+}
+```
+
+(Once published to PyPI, `uvx shearline` alone works.)
+
+**Streamable HTTP** (for remote/agent-platform use):
+
+```sh
+uvx --from git+https://github.com/lostnumber07/shearline shearline --http --port 8741
+# serves at http://127.0.0.1:8741/mcp
+```
+
+## Why these tools
+
+A forecast API tells you it might rain. None of the questions that matter on a severe weather day — *is this storm rotating, how big is the hail, is the environment loaded for tornadoes, am I inside the polygon* — are answerable from a forecast endpoint. They require the warning's IBW tags, radar-derived products, and a real sounding:
+
+- **Warnings with IBW tags, not just warning text.** A base-tier Severe Thunderstorm Warning and one tagged `DESTRUCTIVE` with 80 mph gusts are different planning problems. SHEARLINE parses the machine-readable tags (max hail size, max gust, tornado detection/damage threat) and the storm-motion vector, and does the point-in-polygon test for you.
+- **The environment, computed honestly.** CAPE without shear is a pulse-storm day; shear without CAPE is wind-driven rain. SHEARLINE pulls the current RAP analysis profile and computes the discriminating quantities with MetPy — including the effective inflow layer, effective SRH/shear, SCP, and STP — because high-CAPE/low-shear, low-CAPE/high-shear, and classic supercell parameter spaces produce very different hazards, and the interpretation says which one you're in.
+- **MRMS, because warnings lag storms.** MESH tells you what hail a storm has *already* produced; rotation tracks show where mesocyclones have tracked in the last hour — both on a ~2-minute cadence from the national radar mosaic, often ahead of the next warning update.
+- **LSRs, because radar isn't ground truth.** Spotter reports confirm what's actually reaching the ground.
+- **One brief that reasons across all of it.** The threat level is rule-based with the triggered rules quoted back, so an agent can audit the logic instead of trusting a vibe.
+
+## Data sources (all public, no keys)
+
+- Warnings: [api.weather.gov](https://www.weather.gov/documentation/services-web-api) (NWS)
+- Outlooks: [Storm Prediction Center](https://www.spc.noaa.gov/) public GeoJSON
+- Point environment: [NOMADS](https://nomads.ncep.noaa.gov/) RAP grib filter, derived with [MetPy](https://unidata.github.io/MetPy/)
+- MRMS: [NOAA MRMS on AWS Open Data](https://registry.opendata.aws/noaa-mrms-pds/)
+- Storm reports: [Iowa Environmental Mesonet](https://mesonet.agron.iastate.edu/) LSR service
+- NEXRAD Level 2: [Unidata on AWS Open Data](https://registry.opendata.aws/noaa-nexrad/)
+
+Coverage is **continental US only** — out-of-bounds coordinates are rejected with a clear error. Upstream fetches are cached (warnings 60 s, MRMS 120 s, LSRs 300 s, outlooks/RAP 30 min) and degrade gracefully: if one source is down, you get partial data plus a `degraded` field, never a bare exception.
+
+## Development
+
+```sh
+git clone https://github.com/lostnumber07/shearline && cd shearline
+uv sync
+uv run pytest          # offline test suite against recorded fixtures
+uv run ruff check .
+uv run shearline       # stdio
+uv run python scripts/smoke.py   # live smoke test, both transports
+```
+
+## License
+
+MIT © Backshear LLC. Weather data is produced by NOAA/NWS and other public services; this project is not affiliated with or endorsed by NOAA.

shearline-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "shearline"
+version = "1.0.0"
+description = "Analyst-grade US severe-weather tools for AI agents over MCP: warning polygons with IBW tags, SPC outlooks, RAP point environments, MRMS hail/rotation, storm reports, and a composite threat brief."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Backshear LLC" }]
+requires-python = ">=3.12"
+keywords = ["mcp", "weather", "severe-weather", "meteorology", "nws", "spc", "mrms", "radar", "ai-agents"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "boto3>=1.43.27",
+    "cfgrib>=0.9.15.1",
+    "eccodeslib>=2.47.1.20",
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.27.2",
+    "metpy>=1.7.1",
+    "numpy>=2.4.6",
+    "pydantic>=2.13.4",
+    "shapely>=2.1.2",
+    "xarray>=2026.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lostnumber07/shearline"
+Repository = "https://github.com/lostnumber07/shearline"
+Issues = "https://github.com/lostnumber07/shearline/issues"
+
+[project.scripts]
+shearline = "shearline.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.20,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "respx>=0.23.1",
+    "ruff>=0.15.16",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]

shearline-1.0.0/src/shearline/__init__.py

@@ -0,0 +1,3 @@
+"""SHEARLINE — analyst-grade US severe-weather tools for AI agents over MCP."""
+
+__version__ = "1.0.0"

shearline-1.0.0/src/shearline/bounds.py

@@ -0,0 +1,24 @@
+"""CONUS bounds enforcement (invariant 2)."""
+
+CONUS_LAT_MIN = 24.0
+CONUS_LAT_MAX = 50.0
+CONUS_LON_MIN = -125.5
+CONUS_LON_MAX = -66.5
+
+
+class OutOfBoundsError(ValueError):
+    """Raised when coordinates fall outside the continental United States."""
+
+
+def check_conus(lat: float, lon: float) -> None:
+    if not isinstance(lat, (int, float)) or not isinstance(lon, (int, float)):
+        raise OutOfBoundsError("Latitude and longitude must be numbers.")
+    if not (CONUS_LAT_MIN <= lat <= CONUS_LAT_MAX) or not (
+        CONUS_LON_MIN <= lon <= CONUS_LON_MAX
+    ):
+        raise OutOfBoundsError(
+            f"Point ({lat}, {lon}) is outside the continental United States. "
+            f"SHEARLINE covers CONUS only (lat {CONUS_LAT_MIN} to {CONUS_LAT_MAX}, "
+            f"lon {CONUS_LON_MIN} to {CONUS_LON_MAX}). Longitude west of the prime "
+            "meridian must be negative, e.g. Oklahoma City is lon=-97.5."
+        )

shearline-1.0.0/src/shearline/cache.py

@@ -0,0 +1,71 @@
+"""In-memory TTL cache for upstream fetches.
+
+Every upstream request goes through this cache so repeat tool calls within a
+product's freshness window never re-hit NOAA servers (invariant 5). Expired
+entries are evicted on access and on every insert, so a long-running server
+does not pin stale multi-MB payloads (NEXRAD volumes, RAP subsets, rotating
+MRMS sample keys) indefinitely.
+"""
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+# TTLs in seconds (invariant 5)
+TTL_ALERTS = 60
+TTL_MRMS = 120
+TTL_LSR = 300
+TTL_OUTLOOK = 1800
+TTL_RAP = 1800
+
+
+class TTLCache:
+    """Async-safe cache with per-key locks so concurrent callers of the same
+    key trigger exactly one upstream fetch (no thundering herd)."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, tuple[float, Any]] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    def _lock_for(self, key: str) -> asyncio.Lock:
+        lock = self._locks.get(key)
+        if lock is None:
+            lock = self._locks.setdefault(key, asyncio.Lock())
+        return lock
+
+    def _sweep(self) -> None:
+        now = time.monotonic()
+        for key in [k for k, (exp, _) in self._entries.items() if exp <= now]:
+            self._entries.pop(key, None)
+            lock = self._locks.get(key)
+            if lock is not None and not lock.locked():
+                self._locks.pop(key, None)
+
+    async def get_or_fetch(
+        self, key: str, ttl: float, fetch: Callable[[], Awaitable[Any]]
+    ) -> Any:
+        hit = self._entries.get(key)
+        if hit is not None:
+            if hit[0] > time.monotonic():
+                return hit[1]
+            self._entries.pop(key, None)
+        async with self._lock_for(key):
+            hit = self._entries.get(key)
+            if hit is not None and hit[0] > time.monotonic():
+                return hit[1]
+            value = await fetch()
+            self._entries[key] = (time.monotonic() + ttl, value)
+            self._sweep()
+            return value
+
+    def put(self, key: str, ttl: float, value: Any) -> None:
+        self._entries[key] = (time.monotonic() + ttl, value)
+        self._sweep()
+
+    def clear(self) -> None:
+        self._entries.clear()
+        self._locks.clear()
+
+
+CACHE = TTLCache()