llm-sunset 0.1.0__tar.gz

llm_sunset-0.1.0/LICENSE

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

llm_sunset-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: llm-sunset
+Version: 0.1.0
+Summary: Find AI model IDs in your code that are deprecated or about to be shut down (OpenAI, Anthropic, Gemini, Azure, Groq, Cohere, xAI).
+Author: llm-sunset contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Ashveil1/llm-sunset
+Project-URL: Issues, https://github.com/Ashveil1/llm-sunset/issues
+Keywords: llm,openai,anthropic,gemini,deprecation,linter,ci,ai,model-retirement
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🌅 llm-sunset
+
+**Your app is about to break because an AI provider is shutting down the model it uses. `llm-sunset` tells you before it happens.**
+
+OpenAI, Anthropic, Google, Groq, Cohere and xAI retire models constantly, often with only a few months' notice. The model ID sits hard-coded in some config file and nobody notices until production starts returning `404 model_not_found`.
+
+`llm-sunset` scans your code, finds every AI model ID, and checks it against a daily-updated list of official deprecation notices.
+
+```console
+$ llm-sunset
+app/llm.py:12:23     error    OpenAI model 'gpt-4o-2024-05-13' retires 2026-10-23 (16 days left); replace with: gpt-5.6-sol
+app/summarize.py:8:11  error  OpenAI model 'gpt-3.5-turbo' retires 2026-10-23 (16 days left); replace with: gpt-5.6-terra
+config/models.yaml:3:8 error  Anthropic model 'claude-2.0' RETIRED on 2025-07-21 (443 days ago); replace with: claude-opus-4-8
+worker/.env:2:7        warning Anthropic model 'claude-sonnet-4-5-20250929' retires 2026-11-30 (54 days left)
+
+4 finding(s): 3 error(s), 1 warning(s)
+```
+
+- **Zero dependencies.** Pure Python standard library, Python 3.8+.
+- **Works offline.** Ships with a bundled snapshot; uses live data when it can reach it.
+- **No API keys, and your code never leaves your machine.** It only downloads a public JSON file.
+- **CI-ready.** Comes with a GitHub Action, a pre-commit hook, SARIF output for GitHub code scanning, JSON and Markdown.
+- **Low noise.** It matches exact model IDs (so `gpt-4o-mini` is not reported as `gpt-4o`, and `gpt-4.1` is not reported as `gpt-4`) and skips prose docs, lockfiles and `node_modules`.
+
+## Install
+
+```bash
+pipx install llm-sunset     # or: pip install llm-sunset / uvx llm-sunset
+```
+
+## Usage
+
+```bash
+llm-sunset                          # scan current directory
+llm-sunset src/ config/             # scan specific paths
+llm-sunset --provider openai        # only OpenAI notices (repeatable)
+llm-sunset --fail-within 30         # only fail on models retiring within 30 days
+llm-sunset --format json            # also: markdown, sarif, github
+llm-sunset info gpt-4o-2024-05-13   # look up a model
+llm-sunset upcoming --days 90       # every shutdown in the next 90 days
+```
+
+**Exit code** is `1` if any model is already retired or retires within `--fail-within` days (default 90). Use `--no-fail` to only report.
+
+**Ignoring things:** put `llm-sunset: ignore` in a comment on a line, or `llm-sunset: ignore-file` anywhere in a file. Use `--exclude 'tests/*'` for paths. Markdown/RST/TXT files are skipped unless you pass `--include-docs`.
+
+**Azure, Vertex AI and Bedrock** publish their own retirement dates for models they resell, which often differ from the original provider's dates. To avoid false alarms these are off by default. Turn them on with `--provider azure` or `--provider all`.
+
+## GitHub Action
+
+```yaml
+# .github/workflows/llm-sunset.yml
+name: llm-sunset
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 8 * * 1"   # also re-check weekly: deprecations are announced while your code sits still
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Ashveil1/llm-sunset@v0
+        with:
+          fail-within: 60          # optional
+          # provider: "openai anthropic"
+          # exclude: "tests/*"
+```
+
+Findings appear as inline annotations on the PR, along with a summary table on the run page.
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/Ashveil1/llm-sunset
+    rev: v0.1.0
+    hooks:
+      - id: llm-sunset
+```
+
+## GitHub code scanning (SARIF)
+
+```yaml
+      - run: pipx run llm-sunset --format sarif --no-fail > llm-sunset.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: llm-sunset.sarif
+```
+
+## Where the data comes from
+
+Deprecation data comes from [deprecations.info](https://deprecations.info) ([source](https://github.com/deprecations/deprecations-rss), MIT). It scrapes the official deprecation pages of OpenAI, Anthropic, Google Gemini and Vertex AI, AWS Bedrock, Azure AI Foundry, Cohere, Groq and xAI every day. `llm-sunset` caches it for 24 hours in `~/.cache/llm-sunset/` and falls back to a bundled snapshot that is refreshed weekly.
+
+If you find a missing or wrong entry, please report it upstream at deprecations-rss. For false positives or negatives in matching, open an issue here.
+
+## Support the project
+
+If `llm-sunset` saved you from a production outage, please consider [sponsoring](https://github.com/sponsors/Ashveil1) ❤️
+
+## License
+
+MIT

llm_sunset-0.1.0/README.md

@@ -0,0 +1,104 @@
+# 🌅 llm-sunset
+
+**Your app is about to break because an AI provider is shutting down the model it uses. `llm-sunset` tells you before it happens.**
+
+OpenAI, Anthropic, Google, Groq, Cohere and xAI retire models constantly, often with only a few months' notice. The model ID sits hard-coded in some config file and nobody notices until production starts returning `404 model_not_found`.
+
+`llm-sunset` scans your code, finds every AI model ID, and checks it against a daily-updated list of official deprecation notices.
+
+```console
+$ llm-sunset
+app/llm.py:12:23     error    OpenAI model 'gpt-4o-2024-05-13' retires 2026-10-23 (16 days left); replace with: gpt-5.6-sol
+app/summarize.py:8:11  error  OpenAI model 'gpt-3.5-turbo' retires 2026-10-23 (16 days left); replace with: gpt-5.6-terra
+config/models.yaml:3:8 error  Anthropic model 'claude-2.0' RETIRED on 2025-07-21 (443 days ago); replace with: claude-opus-4-8
+worker/.env:2:7        warning Anthropic model 'claude-sonnet-4-5-20250929' retires 2026-11-30 (54 days left)
+
+4 finding(s): 3 error(s), 1 warning(s)
+```
+
+- **Zero dependencies.** Pure Python standard library, Python 3.8+.
+- **Works offline.** Ships with a bundled snapshot; uses live data when it can reach it.
+- **No API keys, and your code never leaves your machine.** It only downloads a public JSON file.
+- **CI-ready.** Comes with a GitHub Action, a pre-commit hook, SARIF output for GitHub code scanning, JSON and Markdown.
+- **Low noise.** It matches exact model IDs (so `gpt-4o-mini` is not reported as `gpt-4o`, and `gpt-4.1` is not reported as `gpt-4`) and skips prose docs, lockfiles and `node_modules`.
+
+## Install
+
+```bash
+pipx install llm-sunset     # or: pip install llm-sunset / uvx llm-sunset
+```
+
+## Usage
+
+```bash
+llm-sunset                          # scan current directory
+llm-sunset src/ config/             # scan specific paths
+llm-sunset --provider openai        # only OpenAI notices (repeatable)
+llm-sunset --fail-within 30         # only fail on models retiring within 30 days
+llm-sunset --format json            # also: markdown, sarif, github
+llm-sunset info gpt-4o-2024-05-13   # look up a model
+llm-sunset upcoming --days 90       # every shutdown in the next 90 days
+```
+
+**Exit code** is `1` if any model is already retired or retires within `--fail-within` days (default 90). Use `--no-fail` to only report.
+
+**Ignoring things:** put `llm-sunset: ignore` in a comment on a line, or `llm-sunset: ignore-file` anywhere in a file. Use `--exclude 'tests/*'` for paths. Markdown/RST/TXT files are skipped unless you pass `--include-docs`.
+
+**Azure, Vertex AI and Bedrock** publish their own retirement dates for models they resell, which often differ from the original provider's dates. To avoid false alarms these are off by default. Turn them on with `--provider azure` or `--provider all`.
+
+## GitHub Action
+
+```yaml
+# .github/workflows/llm-sunset.yml
+name: llm-sunset
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 8 * * 1"   # also re-check weekly: deprecations are announced while your code sits still
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Ashveil1/llm-sunset@v0
+        with:
+          fail-within: 60          # optional
+          # provider: "openai anthropic"
+          # exclude: "tests/*"
+```
+
+Findings appear as inline annotations on the PR, along with a summary table on the run page.
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/Ashveil1/llm-sunset
+    rev: v0.1.0
+    hooks:
+      - id: llm-sunset
+```
+
+## GitHub code scanning (SARIF)
+
+```yaml
+      - run: pipx run llm-sunset --format sarif --no-fail > llm-sunset.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: llm-sunset.sarif
+```
+
+## Where the data comes from
+
+Deprecation data comes from [deprecations.info](https://deprecations.info) ([source](https://github.com/deprecations/deprecations-rss), MIT). It scrapes the official deprecation pages of OpenAI, Anthropic, Google Gemini and Vertex AI, AWS Bedrock, Azure AI Foundry, Cohere, Groq and xAI every day. `llm-sunset` caches it for 24 hours in `~/.cache/llm-sunset/` and falls back to a bundled snapshot that is refreshed weekly.
+
+If you find a missing or wrong entry, please report it upstream at deprecations-rss. For false positives or negatives in matching, open an issue here.
+
+## Support the project
+
+If `llm-sunset` saved you from a production outage, please consider [sponsoring](https://github.com/sponsors/Ashveil1) ❤️
+
+## License
+
+MIT

llm_sunset-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llm-sunset"
+dynamic = ["version"]
+description = "Find AI model IDs in your code that are deprecated or about to be shut down (OpenAI, Anthropic, Gemini, Azure, Groq, Cohere, xAI)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "llm-sunset contributors" }]
+keywords = ["llm", "openai", "anthropic", "gemini", "deprecation", "linter", "ci", "ai", "model-retirement"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.scripts]
+llm-sunset = "llm_sunset.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Ashveil1/llm-sunset"
+Issues = "https://github.com/Ashveil1/llm-sunset/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "llm_sunset.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+llm_sunset = ["snapshot.json"]

llm_sunset-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llm_sunset-0.1.0/src/llm_sunset/__init__.py

@@ -0,0 +1,3 @@
+"""llm-sunset: find deprecated and soon-to-be-retired AI model IDs in your code."""
+
+__version__ = "0.1.0"

llm_sunset-0.1.0/src/llm_sunset/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

llm_sunset-0.1.0/src/llm_sunset/cli.py

@@ -0,0 +1,171 @@
+"""Command line interface for llm-sunset."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import date
+from typing import List, Optional
+
+from . import __version__, report
+from .data import load
+from .scanner import Matcher, scan
+
+EPILOG = """examples:
+  llm-sunset                         scan the current directory
+  llm-sunset src/ config/            scan specific paths
+  llm-sunset --provider openai       only check OpenAI deprecations
+  llm-sunset --format sarif > out.sarif
+  llm-sunset info gpt-4o-2024-05-13  look up a single model
+  llm-sunset upcoming --days 90      list every shutdown in the next 90 days
+
+Ignore a line with a comment containing:  llm-sunset: ignore
+Ignore a whole file with:                  llm-sunset: ignore-file
+"""
+
+
+def _today(value: Optional[str]) -> date:
+    return date.fromisoformat(value) if value else date.today()
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--provider", action="append", metavar="NAME",
+                   help="only consider this provider (repeatable; e.g. openai, anthropic, google, azure, groq). "
+                        "Default: all direct providers; Azure/Vertex/Bedrock need an explicit "
+                        "--provider (or --provider all)")
+    p.add_argument("--offline", action="store_true", help="don't fetch live data; use cache or bundled snapshot")
+    p.add_argument("--data-file", metavar="PATH", help="use a local deprecations JSON file")
+    p.add_argument("--today", metavar="YYYY-MM-DD", help=argparse.SUPPRESS)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="llm-sunset",
+        description="Find AI model IDs in your code that are deprecated or about to be shut down.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--version", action="version", version=f"llm-sunset {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    s = sub.add_parser("scan", help="scan files (default command)")
+    s.add_argument("paths", nargs="*", default=["."])
+    s.add_argument("--format", choices=["text", "json", "markdown", "sarif", "github"], default="text")
+    s.add_argument("--fail-within", type=int, default=90, metavar="DAYS",
+                   help="treat models retiring within DAYS as errors (default: 90)")
+    s.add_argument("--warn-within", type=int, default=365, metavar="DAYS",
+                   help="hide models retiring more than DAYS from now (default: 365, -1 = show all)")
+    s.add_argument("--no-fail", action="store_true", help="always exit 0")
+    s.add_argument("--exclude", action="append", default=[], metavar="GLOB", help="exclude paths (repeatable)")
+    s.add_argument("--include-docs", action="store_true", help="also scan .md/.rst/.txt files")
+    _common(s)
+
+    i = sub.add_parser("info", help="show deprecation info for model IDs")
+    i.add_argument("models", nargs="+")
+    _common(i)
+
+    u = sub.add_parser("upcoming", help="list upcoming shutdowns")
+    u.add_argument("--days", type=int, default=180, help="look ahead this many days (default: 180)")
+    _common(u)
+    return p
+
+
+def cmd_scan(a: argparse.Namespace) -> int:
+    today = _today(a.today)
+    deps, source = load(offline=a.offline, data_file=a.data_file)
+    findings = scan(a.paths, Matcher(deps, a.provider), exclude=a.exclude, include_docs=a.include_docs)
+    if a.warn_within >= 0:
+        findings = [
+            f for f in findings
+            if f.deprecation.days_left(today) is None or f.deprecation.days_left(today) <= a.warn_within
+        ]
+
+    if a.format == "json":
+        print(report.render_json(findings, today, a.fail_within, source))
+    elif a.format == "markdown":
+        print(report.render_markdown(findings, today, a.fail_within, source))
+    elif a.format == "sarif":
+        print(report.render_sarif(findings, today, a.fail_within))
+    elif a.format == "github":
+        out = report.render_github(findings, today, a.fail_within)
+        if out:
+            print(out)
+        print(report.render_text(findings, today, a.fail_within, source))
+        summary = os.environ.get("GITHUB_STEP_SUMMARY")
+        if summary:
+            with open(summary, "a", encoding="utf-8") as fh:
+                fh.write(report.render_markdown(findings, today, a.fail_within, source) + "\n")
+    else:
+        print(report.render_text(findings, today, a.fail_within, source))
+
+    if a.no_fail:
+        return 0
+    return 1 if any(report.severity(f, today, a.fail_within) == "error" for f in findings) else 0
+
+
+def cmd_info(a: argparse.Namespace) -> int:
+    today = _today(a.today)
+    deps, source = load(offline=a.offline, data_file=a.data_file)
+    matcher = Matcher(deps, a.provider)
+    status = 0
+    for model in a.models:
+        hits = matcher.by_id.get(model, [])
+        if not hits:
+            print(f"{model}: no deprecation notice found")
+            continue
+        status = 1
+        for d in hits:
+            left = d.days_left(today)
+            if left is None:
+                when = "deprecated, no shutdown date announced"
+            elif left <= 0:
+                when = f"RETIRED on {d.shutdown_date}"
+            else:
+                when = f"retires {d.shutdown_date} ({left} days left)"
+            print(f"{model} [{d.provider}]: {when}")
+            if d.replacements:
+                print(f"    replace with: {', '.join(d.replacements)}")
+            if d.url:
+                print(f"    source: {d.url}")
+    print(f"(data: {source})", file=sys.stderr)
+    return status
+
+
+def cmd_upcoming(a: argparse.Namespace) -> int:
+    today = _today(a.today)
+    deps, source = load(offline=a.offline, data_file=a.data_file)
+    matcher = Matcher(deps, a.provider)
+    rows = []
+    for items in matcher.by_id.values():
+        for d in items:
+            left = d.days_left(today)
+            if left is not None and 0 < left <= a.days:
+                rows.append((d.shutdown_date, d))
+    rows.sort(key=lambda r: (r[0], r[1].provider, r[1].model_id))
+    if not rows:
+        print(f"No shutdowns in the next {a.days} days.")
+    for when, d in rows:
+        repl = f"  -> {', '.join(d.replacements)}" if d.replacements else ""
+        print(f"{when}  {d.provider:<14} {d.model_id}{repl}")
+    print(f"(data: {source})", file=sys.stderr)
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    known = {"scan", "info", "upcoming", "-h", "--help", "--version"}
+    if not argv or argv[0] not in known:
+        argv = ["scan"] + argv
+    a = build_parser().parse_args(argv)
+    handler = {"scan": cmd_scan, "info": cmd_info, "upcoming": cmd_upcoming}[a.command]
+    try:
+        return handler(a)
+    except BrokenPipeError:
+        return 0
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

llm_sunset-0.1.0/src/llm_sunset/data.py

@@ -0,0 +1,139 @@
+"""Load the AI model deprecation dataset.
+
+Data comes from https://deprecations.info (MIT licensed, refreshed daily by
+https://github.com/deprecations/deprecations-rss). We try, in order:
+
+1. a fresh local cache (< 24h old)
+2. the live feed
+3. a stale local cache
+4. the snapshot bundled with this package (works fully offline)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+FEED_URLS = (
+    "https://deprecations.info/v1/deprecations.json",
+    "https://raw.githubusercontent.com/deprecations/deprecations-rss/main/data.json",
+)
+CACHE_TTL_SECONDS = 24 * 60 * 60
+SNAPSHOT_PATH = Path(__file__).with_name("snapshot.json")
+
+
+@dataclass(frozen=True)
+class Deprecation:
+    provider: str
+    model_id: str
+    shutdown_date: Optional[date]
+    deprecation_date: Optional[date]
+    replacements: Tuple[str, ...] = field(default_factory=tuple)
+    url: str = ""
+
+    def days_left(self, today: date) -> Optional[int]:
+        if self.shutdown_date is None:
+            return None
+        return (self.shutdown_date - today).days
+
+
+def _parse_date(value: object) -> Optional[date]:
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        return date.fromisoformat(value[:10])
+    except ValueError:
+        return None
+
+
+def cache_path() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(Path.home(), ".cache")
+    return Path(base) / "llm-sunset" / "deprecations.json"
+
+
+def _download(timeout: float) -> Optional[list]:
+    for url in FEED_URLS:
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "llm-sunset"})
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+            if isinstance(data, list) and data:
+                return data
+        except Exception:
+            continue
+    return None
+
+
+def _read_json(path: Path) -> Optional[list]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else None
+    except Exception:
+        return None
+
+
+def load_raw(offline: bool = False, data_file: Optional[str] = None, timeout: float = 10.0) -> Tuple[list, str]:
+    """Return (records, source_description)."""
+    if data_file:
+        data = _read_json(Path(data_file))
+        if data is None:
+            raise SystemExit(f"llm-sunset: could not read data file {data_file}")
+        return data, data_file
+
+    cache = cache_path()
+    if not offline:
+        fresh = cache.exists() and time.time() - cache.stat().st_mtime < CACHE_TTL_SECONDS
+        if fresh:
+            data = _read_json(cache)
+            if data:
+                return data, "cache"
+        data = _download(timeout)
+        if data:
+            try:
+                cache.parent.mkdir(parents=True, exist_ok=True)
+                cache.write_text(json.dumps(data), encoding="utf-8")
+            except OSError:
+                pass
+            return data, "live"
+        data = _read_json(cache)
+        if data:
+            return data, "cache (stale)"
+
+    data = _read_json(SNAPSHOT_PATH)
+    if not data:
+        raise SystemExit("llm-sunset: bundled snapshot missing and feed unreachable")
+    return data, "bundled snapshot"
+
+
+def normalize(records: Iterable[dict]) -> List[Deprecation]:
+    """Turn raw records into Deprecation objects, one per (provider, model_id)."""
+    best: Dict[Tuple[str, str], Tuple[str, Deprecation]] = {}
+    for r in records:
+        model_id = (r.get("model_id") or "").strip()
+        provider = (r.get("provider") or "Unknown").strip()
+        if not model_id:
+            continue
+        dep = Deprecation(
+            provider=provider,
+            model_id=model_id,
+            shutdown_date=_parse_date(r.get("shutdown_date")),
+            deprecation_date=_parse_date(r.get("deprecation_date")),
+            replacements=tuple(x for x in (r.get("replacement_models") or []) if isinstance(x, str)),
+            url=r.get("url") or "",
+        )
+        key = (provider, model_id)
+        seen = r.get("last_observed") or r.get("announcement_date") or ""
+        if key not in best or seen >= best[key][0]:
+            best[key] = (seen, dep)
+    return [d for _, d in best.values()]
+
+
+def load(offline: bool = False, data_file: Optional[str] = None) -> Tuple[List[Deprecation], str]:
+    raw, source = load_raw(offline=offline, data_file=data_file)
+    return normalize(raw), source