modelbump 0.1.0__py3-none-any.whl

modelbump/registry/data/openai.yaml

@@ -0,0 +1,384 @@
+# Copied from the source page. Scope: models called through text-generation or
+# embedding APIs; audio, realtime, image, video, moderation and fine-tuning
+# entries are left out (see docs/architecture/registry.md).
+# `announced` is the date of the page section; `shutdown` is its shutdown date.
+# `replacement` is what the page recommends TODAY (see ADR 0006).
+# When a model appears in more than one section, the newest section is the
+# current plan and older ones go under `superseded` (see ADR 0007).
+provider: openai
+source_url: https://developers.openai.com/api/docs/deprecations
+retrieved: 2026-10-08
+models:
+  - id: gpt-5.3-codex
+    announced: 2026-10-01
+    shutdown: 2027-04-01
+    replacement: gpt-6-sol
+  - id: gpt-5.4-nano
+    announced: 2026-10-01
+    shutdown: 2027-04-01
+    replacement: gpt-6-luna
+  - id: gpt-5.1
+    announced: 2026-10-01
+    shutdown: 2027-04-01
+    replacement: gpt-6-sol
+  - id: gpt-5.4-cyber
+    announced: 2026-09-11
+    shutdown: 2026-10-01
+    notes: "Page recommends the most capable cyber model available to you."
+  - id: gpt-5-2025-08-07
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-sol
+  - id: gpt-5-mini-2025-08-07
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-terra
+  - id: gpt-5-nano-2025-08-07
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-luna
+  - id: gpt-5-pro-2025-10-06
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-sol
+    notes: "Replacement uses reasoning.mode pro."
+  - id: o3-2025-04-16
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-sol
+  - id: o3-pro-2025-06-10
+    announced: 2026-06-11
+    shutdown: 2026-12-11
+    replacement: gpt-5.6-sol
+    notes: "Replacement uses reasoning.mode pro."
+  - id: gpt-5.2-chat-latest
+    announced: 2026-05-08
+    shutdown: 2026-08-10
+    replacement: gpt-5.6-sol
+  - id: gpt-5.3-chat-latest
+    announced: 2026-05-08
+    shutdown: 2026-08-10
+    replacement: gpt-5.6-sol
+  - id: gpt-3.5-turbo-0125
+    aliases: [gpt-3.5-turbo]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-terra
+  - id: gpt-4-0613
+    aliases: [gpt-4, gpt-4-0613-completions, gpt-4-completions]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+  - id: gpt-4-1106-preview
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+    notes: "Rescheduled: first set to shut down on 2026-03-26."
+    superseded:
+      - announced: 2025-09-26
+        shutdown: 2026-03-26
+  - id: gpt-4-turbo-2024-04-09
+    aliases: [gpt-4-turbo, gpt-4-turbo-completions]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+  - id: gpt-4.1-nano-2025-04-14
+    aliases: [gpt-4.1-nano]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-luna
+  - id: gpt-4o-2024-05-13
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+  - id: o1-2024-12-17
+    aliases: [o1]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+  - id: o1-pro-2025-03-19
+    aliases: [o1-pro]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+    notes: "Replacement uses reasoning.mode pro."
+  - id: o3-mini-2025-01-31
+    aliases: [o3-mini]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-sol
+  - id: o4-mini-2025-04-16
+    aliases: [o4-mini]
+    announced: 2026-04-22
+    shutdown: 2026-10-23
+    replacement: gpt-5.6-terra
+  - id: computer-use-preview-2025-03-11
+    aliases: [computer-use-preview]
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-terra
+  - id: gpt-4o-mini-search-preview-2025-03-11
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-terra
+  - id: gpt-4o-search-preview-2025-03-11
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-terra
+  - id: gpt-5-chat-latest
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5-codex
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5.1-chat-latest
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5.1-codex
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5.1-codex-max
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5.1-codex-mini
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-terra
+  - id: o3-deep-research-2025-06-26
+    aliases: [o3-deep-research]
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: o4-mini-deep-research-2025-06-26
+    aliases: [o4-mini-deep-research]
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: gpt-5.2-codex
+    announced: 2026-04-22
+    shutdown: 2026-07-23
+    replacement: gpt-5.6-sol
+  - id: chatgpt-4o-latest
+    announced: 2025-11-18
+    shutdown: 2026-02-17
+    replacement: gpt-5.1-chat-latest
+  - id: codex-mini-latest
+    announced: 2025-11-17
+    shutdown: 2026-02-12
+    replacement: gpt-5-codex-mini
+  - id: gpt-3.5-turbo-instruct
+    announced: 2025-09-26
+    shutdown: 2026-09-28
+    replacement: gpt-5.6-terra
+  - id: babbage-002
+    announced: 2025-09-26
+    shutdown: 2026-09-28
+    replacement: gpt-5.6-terra
+  - id: davinci-002
+    announced: 2025-09-26
+    shutdown: 2026-09-28
+    replacement: gpt-5.6-terra
+  - id: gpt-3.5-turbo-1106
+    announced: 2025-09-26
+    shutdown: 2026-09-28
+    replacement: gpt-5.6-terra
+  - id: gpt-4-0314
+    announced: 2025-09-26
+    shutdown: 2026-03-26
+    replacement: gpt-5
+    notes: "Rescheduled: first announced on 2023-06-13 with shutdown at earliest 2024-06-13. Page recommends gpt-5 or gpt-4.1."
+    superseded:
+      - announced: 2023-06-13
+        shutdown: 2024-06-13
+        shutdown_is_earliest: true
+  - id: gpt-4-0125-preview
+    aliases: [gpt-4-turbo-preview, gpt-4-turbo-preview-completions]
+    announced: 2025-09-26
+    shutdown: 2026-03-26
+    replacement: gpt-5
+    notes: "Page recommends gpt-5 or gpt-4.1."
+  - id: o1-preview
+    announced: 2025-04-28
+    shutdown: 2025-07-28
+    replacement: o3
+  - id: o1-mini
+    announced: 2025-04-28
+    shutdown: 2025-10-27
+    replacement: o4-mini
+  - id: gpt-4.5-preview
+    announced: 2025-04-14
+    shutdown: 2025-07-14
+    replacement: gpt-4.1
+  - id: gpt-4-32k
+    announced: 2024-06-06
+    shutdown: 2025-06-06
+    replacement: gpt-4o
+  - id: gpt-4-32k-0613
+    announced: 2024-06-06
+    shutdown: 2025-06-06
+    replacement: gpt-4o
+  - id: gpt-4-32k-0314
+    announced: 2024-06-06
+    shutdown: 2025-06-06
+    replacement: gpt-4o
+    notes: "Also listed in the 2023-06-13 section with the same shutdown date."
+    superseded:
+      - announced: 2023-06-13
+        shutdown: 2025-06-06
+  - id: gpt-4-vision-preview
+    announced: 2024-06-06
+    shutdown: 2024-12-06
+    replacement: gpt-4o
+  - id: gpt-4-1106-vision-preview
+    announced: 2024-06-06
+    shutdown: 2024-12-06
+    replacement: gpt-4o
+  - id: gpt-3.5-turbo-0613
+    announced: 2023-11-06
+    shutdown: 2024-09-13
+    replacement: gpt-3.5-turbo
+  - id: gpt-3.5-turbo-16k-0613
+    announced: 2023-11-06
+    shutdown: 2024-09-13
+    replacement: gpt-3.5-turbo
+  - id: text-ada-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: text-babbage-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: text-curie-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: text-davinci-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: text-davinci-002
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: text-davinci-003
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+  - id: ada
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: babbage-002
+  - id: babbage
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: babbage-002
+  - id: curie
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: davinci-002
+  - id: davinci
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: davinci-002
+  - id: code-davinci-002
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-3.5-turbo-instruct
+    notes: "Rescheduled: the 2023-03-20 section lists a 2023-03-23 shutdown."
+    superseded:
+      - announced: 2023-03-20
+        shutdown: 2023-03-23
+  - id: text-davinci-edit-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-4o
+  - id: code-davinci-edit-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: gpt-4o
+  - id: text-similarity-ada-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-ada-doc-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-ada-query-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: code-search-ada-code-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: code-search-ada-text-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-similarity-babbage-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-babbage-doc-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-babbage-query-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: code-search-babbage-code-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: code-search-babbage-text-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-similarity-curie-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-curie-doc-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-curie-query-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-similarity-davinci-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-davinci-doc-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: text-search-davinci-query-001
+    announced: 2023-07-06
+    shutdown: 2024-01-04
+    replacement: text-embedding-3-small
+  - id: gpt-3.5-turbo-0301
+    announced: 2023-06-13
+    shutdown: 2024-09-13
+    replacement: gpt-3.5-turbo
+  - id: code-davinci-001
+    announced: 2023-03-20
+    shutdown: 2023-03-23
+    replacement: gpt-4o
+  - id: code-cushman-002
+    announced: 2023-03-20
+    shutdown: 2023-03-23
+    replacement: gpt-4o
+  - id: code-cushman-001
+    announced: 2023-03-20
+    shutdown: 2023-03-23
+    replacement: gpt-4o

modelbump/registry/loader.py

@@ -0,0 +1,59 @@
+"""Load the retirement data files and look models up by ID."""
+
+from collections.abc import Iterable, Iterator
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+import yaml
+
+from modelbump.registry.models import Provider, ProviderFile, RetiredModel
+
+
+class DuplicateModelError(ValueError):
+    """Raised when the same model ID appears in more than one entry."""
+
+
+def load_provider_file(path: Traversable) -> ProviderFile:
+    """Read and validate one YAML data file."""
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return ProviderFile.model_validate(data)
+
+
+class Registry:
+    """All known retirements, indexed by every model ID and alias."""
+
+    def __init__(self, sources: Iterable[ProviderFile]) -> None:
+        self._sources = tuple(sources)
+        self._by_id: dict[str, tuple[Provider, RetiredModel]] = {}
+        for source in self._sources:
+            for model in source.models:
+                for model_id in model.all_ids():
+                    if model_id in self._by_id:
+                        raise DuplicateModelError(f"{model_id} appears more than once")
+                    self._by_id[model_id] = (source.provider, model)
+
+    @property
+    def sources(self) -> tuple[ProviderFile, ...]:
+        """The data files this registry was built from."""
+        return self._sources
+
+    def get(self, model_id: str) -> tuple[Provider, RetiredModel] | None:
+        """Return the provider and entry for ``model_id``, or None if unknown."""
+        return self._by_id.get(model_id)
+
+    def __iter__(self) -> Iterator[tuple[Provider, RetiredModel]]:
+        for source in self._sources:
+            for model in source.models:
+                yield source.provider, model
+
+    def __len__(self) -> int:
+        return sum(len(source.models) for source in self._sources)
+
+
+def load_registry() -> Registry:
+    """Load every data file shipped inside the package."""
+    data_dir = files("modelbump.registry") / "data"
+    paths = sorted(
+        (p for p in data_dir.iterdir() if p.name.endswith(".yaml")), key=lambda p: p.name
+    )
+    return Registry(load_provider_file(p) for p in paths)

modelbump/registry/models.py

@@ -0,0 +1,111 @@
+"""Data model for the retirement registry.
+
+Every field is checked when a data file is loaded, so a typo in a YAML file
+fails the tests instead of silently producing wrong warnings later.
+"""
+
+from datetime import date
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+
+class Provider(StrEnum):
+    """LLM providers whose retirements we track."""
+
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    OPENAI = "openai"
+
+
+class Status(StrEnum):
+    """Where a model is in its life cycle on a given day."""
+
+    ACTIVE = "active"
+    DEPRECATED = "deprecated"
+    RETIRED = "retired"
+
+
+class EarlierPlan(BaseModel):
+    """A retirement plan the provider announced and later replaced."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    announced: date | None = None
+    shutdown: date
+    shutdown_is_earliest: bool = False
+
+
+class RetiredModel(BaseModel):
+    """One model version that a provider has announced it will shut down."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str = Field(min_length=1, description="Model ID exactly as used in API calls.")
+    aliases: tuple[str, ...] = Field(
+        default=(), description="Other IDs that point to this same model."
+    )
+    announced: date | None = Field(
+        default=None, description="Day the provider announced the deprecation."
+    )
+    shutdown: date = Field(description="Day API calls to this model stop working.")
+    shutdown_is_earliest: bool = Field(
+        default=False,
+        description="True when the source only promises the shutdown no sooner than this day.",
+    )
+    replacement: str | None = Field(
+        default=None,
+        description="Replacement the source page recommended on the day we retrieved it.",
+    )
+    superseded: tuple[EarlierPlan, ...] = Field(
+        default=(), description="Earlier retirement plans for this model, oldest first."
+    )
+    notes: str | None = None
+
+    @model_validator(mode="after")
+    def _check_consistency(self) -> Self:
+        if self.announced is not None and self.shutdown < self.announced:
+            raise ValueError(f"{self.id}: shutdown {self.shutdown} is before announced")
+        ids = self.all_ids()
+        if len(set(ids)) != len(ids):
+            raise ValueError(f"{self.id}: an alias repeats the id or another alias")
+        if self.replacement in ids:
+            raise ValueError(f"{self.id}: replacement cannot be the model itself")
+        for plan in self.superseded:
+            if (
+                plan.announced is not None
+                and self.announced is not None
+                and plan.announced >= self.announced
+            ):
+                raise ValueError(
+                    f"{self.id}: a superseded plan must be announced before the current one"
+                )
+        return self
+
+    def all_ids(self) -> tuple[str, ...]:
+        """Return the main ID followed by every alias."""
+        return (self.id, *self.aliases)
+
+    def status_on(self, day: date) -> Status:
+        """Return the model's status on ``day``, using the current plan.
+
+        A model is retired from its shutdown day onwards, and deprecated from
+        the announcement day until then.
+        """
+        if day >= self.shutdown:
+            return Status.RETIRED
+        if self.announced is not None and day >= self.announced:
+            return Status.DEPRECATED
+        return Status.ACTIVE
+
+
+class ProviderFile(BaseModel):
+    """The contents of one ``data/<provider>.yaml`` file."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    provider: Provider
+    source_url: HttpUrl = Field(description="Page the data was copied from.")
+    retrieved: date = Field(description="Day we last checked the data against the source.")
+    models: tuple[RetiredModel, ...] = Field(min_length=1)

modelbump/scanner/__init__.py

@@ -0,0 +1,26 @@
+"""Scanner: find the LLM model IDs a repository depends on (ADR 0023)."""
+
+from modelbump.scanner.context import Context, Place, places
+from modelbump.scanner.files import iter_source_files, read_source
+from modelbump.scanner.ids import IdMatch, ModelIdFinder
+from modelbump.scanner.resolve import resolve
+from modelbump.scanner.scan import Finding, ScanResult, scan_path
+from modelbump.scanner.severity import DEFAULT_SOON_DAYS, Assessment, Severity, assess
+
+__all__ = [
+    "DEFAULT_SOON_DAYS",
+    "Assessment",
+    "Context",
+    "Finding",
+    "IdMatch",
+    "ModelIdFinder",
+    "Place",
+    "ScanResult",
+    "Severity",
+    "assess",
+    "iter_source_files",
+    "places",
+    "read_source",
+    "resolve",
+    "scan_path",
+]