Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
| Kind | Reads | Add a source by |
|---|---|---|
| `plugins/openapi` | An OpenAPI spec per release, diffed with `core/diff/` and turned into events by `core/normalize/` | An `adapter.Adapter` in `plugins/openapi/adapter/` (latest tag, fetch a tag's spec; `Versions` to list every release) and a `plugin.RegisterProvider` block |
| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`new-plugin` doesn't scaffold this reader yet) |
| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement: Markdown or Markdoc), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`new-plugin` doesn't scaffold this reader yet) |
| `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` |
| `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` |
| `plugins/catalog` | A provider's own structured list of what it offers: a command catalog kept as one JSON file per command in its repo, read at each release tag and compared for commands that disappeared entirely | A `catalog.Commands` (repo, directory, release tag pattern); a catalog of another shape is a new reader type in the package |
Expand Down
78 changes: 78 additions & 0 deletions plugins/notices/google_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
package notices

import (
"os"
"strings"
"testing"

"github.com/patch-it-dev/patch-it-plugins/core/kit/kittest"
"github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire"
)

// section is the saved page from start up to end (to the end of the page
// when end is ""), as a page of its own.
func section(t *testing.T, file, start, end string) string {
t.Helper()
b, err := os.ReadFile(file)
if err != nil {
t.Fatal(err)
}
s := string(b)
i := strings.Index(s, start)
if i < 0 {
t.Fatalf("%s: the saved page's shape changed", file)
}
if end == "" {
return s[i:]
}
j := strings.Index(s[i+1:], end)
if j < 0 {
t.Fatalf("%s: the saved page's shape changed", file)
}
return s[i : i+1+j]
}

// readGoogle is a first read of page, served as content, through the kind.
func readGoogle(t *testing.T, page retire.Page, content string) int {
t.Helper()
f := t.TempDir() + "/page"
if err := os.WriteFile(f, []byte(content), 0o644); err != nil {
t.Fatal(err)
}
saved := kittest.Pages{page.URL: f}
return len(kittest.Page(t, kittest.Env(t, saved), Plugin{Page: page, Archiver: &kittest.Archive{T: t, Pages: saved}}))
}

// The pinned drop test for the Gemini API page: the Gemini 4 models (no
// shutdown date announced) and the managed agents, whose deprecated table
// has real dates but names agents, not models, next to the two Gemini 3
// models shut down already. Only those two are events; the agents' table
// renamed to "Model" would give two more, so the header is what keeps it
// out.
func TestGeminiDropsModelsWithNoDateAndAgents(t *testing.T) {
const file = "retire/testdata/gemini-deprecations.md"
current := section(t, file, "## Gemini 4 models", "## Gemini 3 models")
retired := section(t, file, "### Deprecated models {% id=\"gemini-3-deprecated-models\" %}", "## Gemini 2.5 Pro models")
agents := section(t, file, "## Managed agents", "")
if n := readGoogle(t, retire.Gemini, current+retired+agents); n != 2 {
t.Errorf("%d events, want the 2 shut-down Gemini 3 models only", n)
}
if _, err := retire.Parse(retire.Gemini.Format.Pipes([]byte(agents)), retire.Gemini.Keep); err == nil {
t.Error("the agents' tables read as retirements")
}
asModels := strings.ReplaceAll(agents, " * Agent\n", " * Model\n")
if rs, err := retire.Parse(retire.Gemini.Format.Pipes([]byte(asModels)), retire.Gemini.Keep); err != nil || len(rs) != 2 {
t.Errorf("the agents' table with a Model header: %d, %v; the drop proves nothing", len(rs), err)
}
}

// Google's Gemini dates are the earliest a model may go: the description
// says so.
func TestGeminiDatesAreTheEarliest(t *testing.T) {
saved := kittest.Pages{retire.Gemini.URL: "retire/testdata/gemini-deprecations.md"}
for _, e := range kittest.Page(t, kittest.Env(t, saved), Plugin{Page: retire.Gemini, Archiver: &kittest.Archive{T: t, Pages: saved}}) {
if !strings.Contains(e.Description, "the earliest date Google gives") {
t.Fatalf("%s: %q", e.Subject.Name, e.Description)
}
}
}
6 changes: 6 additions & 0 deletions plugins/notices/notices.go
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,12 @@ func init() {
Watches: "Generative AI model deprecations on Vertex AI",
URLs: []string{"https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml"},
Plugin: Plugin{Page: feed.VertexAIModels, Archiver: kit.Wayback{}},
}, {
ID: "gemini-models", Layer: plugin.LayerAIModels, Page: "providers/google-gemini-models.md",
Watches: "Gemini API model shutdown dates (the earliest Google gives) and their replacements, from Google's own deprecations table",
URLs: []string{"https://ai.google.dev/gemini-api/docs/deprecations", "https://aistudio.google.com/docs/deprecations"},
Packages: []string{"pypi:google-genai", "npm:@google/genai"},
Plugin: Plugin{Page: retire.Gemini, Archiver: kit.Wayback{}},
}},
})
plugin.RegisterProvider(plugin.Provider{
Expand Down
71 changes: 71 additions & 0 deletions plugins/notices/retire/formats.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
package retire

import (
"regexp"
"strings"
)

var (
// markdocCell is one cell of a Markdoc table: " * `gemini-2.0-flash`".
markdocCell = regexp.MustCompile(`^\s*\* ?(.*)$`)
markdocHeading = regexp.MustCompile(`^(#+ .*?)\s*(\{%.*%\})?\s*$`)
)

// markdocPipes reads a Markdoc page's tables ({% table %}, a "* cell" per
// line, rows split by "---", the first row the header) into pipe tables,
// each under the heading above it. Nothing else on the page is kept.
func markdocPipes(page []byte) []byte {
var out []string
var rows [][]string
var cur []string
in := false
flush := func() {
if len(cur) > 0 {
rows = append(rows, cur)
cur = nil
}
}
for _, line := range strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") {
t := strings.TrimSpace(line)
switch {
case !in && strings.HasPrefix(t, "#"):
if m := markdocHeading.FindStringSubmatch(t); m != nil {
out = append(out, m[1])
}
case !in && t == "{% table %}":
in, rows, cur = true, nil, nil
case in && t == "{% /table %}":
flush()
out = append(out, pipeTable(rows)...)
in = false
case in && t == "---":
flush()
case in && strings.HasPrefix(t, "*"):
cur = append(cur, strings.TrimSpace(markdocCell.FindStringSubmatch(line)[1]))
case in && t != "" && len(cur) > 0:
// A cell's text continued on the next line.
cur[len(cur)-1] += " " + t
}
}
return []byte(strings.Join(out, "\n") + "\n")
}

// pipeTable writes rows (the first the header) as a Markdown pipe table,
// escaping a pipe inside a cell.
func pipeTable(rows [][]string) []string {
if len(rows) == 0 {
return nil
}
line := func(cells []string) string {
esc := make([]string, len(cells))
for i, c := range cells {
esc[i] = strings.ReplaceAll(c, "|", `\|`)
}
return "| " + strings.Join(esc, " | ") + " |"
}
out := []string{"", line(rows[0]), "|" + strings.Repeat(" --- |", len(rows[0]))}
for _, r := range rows[1:] {
out = append(out, line(r))
}
return append(out, "")
}
2 changes: 1 addition & 1 deletion plugins/notices/retire/notices.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ func (p Page) PageURL() string { return p.URL }

// Find reads every retirement on the page.
func (p Page) Find(page []byte) (kit.Notices, error) {
rs, err := Parse(page, p.Keep)
rs, err := Parse(p.Format.Pipes(page), p.Keep)
return Retirements(rs), err
}

Expand Down
27 changes: 26 additions & 1 deletion plugins/notices/retire/providers.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
package retire

import "strings"
import (
"regexp"
"strings"
)

// OpenAI's deprecations page (checked 2026-10-13). Its tables cover every
// kind of model; these events are for the text models the Chat Completions
Expand Down Expand Up @@ -46,3 +49,25 @@ func openAIText(name string) bool {
}
return false
}

// googleModel is a model id as code sends it, nothing around it: a cell
// with a footnote mark ("textembedding-gecko@003 *") isn't read.
var googleModel = regexp.MustCompile(`^[a-z0-9][a-z0-9.@_-]*$`)

// Gemini is the Gemini API's deprecations page (ai.google.dev, served by
// aistudio.google.com as markdown, checked 2026-11-21): one Markdoc table per
// model family, | Model | Release date | Shutdown date | Recommended
// replacement |, current models with "No shutdown date announced", shut-down
// ones under "Deprecated models". Every model there is one code names in a
// request (text, image, video, audio, embedding: all through the same SDK);
// the managed agents' tables name an agent, not a model, and are skipped.
// Google says its dates are the earliest a model may be shut down.
var Gemini = Page{
API: "google/gemini-models",
Provider: "google",
Vendor: "Google",
URL: "https://aistudio.google.com/docs/deprecations",
Format: FormatMarkdoc,
Keep: googleModel.MatchString,
Earliest: true,
}
88 changes: 64 additions & 24 deletions plugins/notices/retire/retire.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,15 @@
// OpenAPI differ. There is no spec to diff, only the provider's own table of
// shutdown date, model and named replacement, so this reads the table.
//
// Both providers serve the page as markdown at its URL plus ".md" (checked
// 2026-10-13), and both write each announcement as a table whose first column
// is the date the model stops working. The event cites a Wayback Machine
// snapshot of that markdown (kit/), never the live page: the contract
// requires a source that can't change under the event.
// A page is a Markdown pipe table (OpenAI's and Anthropic's pages, served as
// markdown at their URL plus ".md", checked 2026-10-13), a Markdoc table
// (Google's Gemini API page, {% table %} with one "* cell" per line, checked
// 2026-11-21), read into pipe rows first, with its headings, so one parser
// reads every page. A table is a retirement
// table when it has a shutdown or retirement date column, a model column and
// a replacement column, in any order. The event cites a Wayback Machine
// snapshot of the page (kit/), never the live page: the contract requires a
// source that can't change under the event.
package retire

import (
Expand All @@ -25,12 +29,27 @@ type Page struct {
API string // the source id the events carry: "openai/models"
Provider string // the model subject's provider: "openai"
Vendor string // for sentences: "OpenAI"
URL string // the page as markdown
URL string // the page, as markdown
// Format is how the page writes its tables: Markdown pipe tables (the
// default), Markdoc or HTML.
Format Format
// Keep says whether a model name belongs to this source: the operations
// above take text models, not image, audio or embedding ones.
Keep func(name string) bool
// Earliest says the page's dates are the earliest a model may be shut
// down, not the day it is (Google's Gemini API page): the description
// says so.
Earliest bool
}

// Format is how a page writes its tables.
type Format string

const (
FormatMarkdown Format = ""
FormatMarkdoc Format = "markdoc"
)

// Retirement is one model name the provider stops serving on Date, with the
// replacement it names. An alias gets its own Retirement, with the row it
// came from.
Expand All @@ -47,6 +66,16 @@ var (
ticked = regexp.MustCompile("`([^`]+)`")
)

// Pipes is the page's tables as Markdown pipe tables, each under the
// heading above it: the page itself when it's Markdown.
func (f Format) Pipes(page []byte) []byte {
switch f {
case FormatMarkdoc:
return markdocPipes(page)
}
return page
}

var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"}

// Parse reads every retirement table on the page. A model listed more than
Expand All @@ -57,6 +86,7 @@ var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"}
// points at a model that no longer works.
func Parse(page []byte, keep func(string) bool) ([]Retirement, error) {
lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n")
headerAt := 0
var out []Retirement
seen := map[string]bool{}
heading := ""
Expand All @@ -67,23 +97,31 @@ func Parse(page []byte, keep func(string) bool) ([]Retirement, error) {
continue
}
header := cells(line)
if len(header) < 3 || !dateHeader.MatchString(header[0]) {
when := -1
for c, h := range header {
if dateHeader.MatchString(h) {
when = c
break
}
}
if len(header) < 3 || when < 0 {
continue
}
model, repl := column(header, "model"), column(header, "replacement", "substitute")
if model < 0 || repl < 0 {
continue // an endpoint ("System") or a training-price table: no model to replace
model, repl := column(header, "model"), column(header, "replacement", "substitute", "upgrade")
if model < 0 || repl < 0 || model == repl {
continue // an endpoint ("System"), an agent or a training-price table: no model to replace
}
headerAt = i
i++ // the |---| row
for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") {
i++
row := strings.TrimSpace(lines[i])
c := cells(row)
if len(c) <= model || len(c) <= repl {
if len(c) <= model || len(c) <= repl || len(c) <= when {
return nil, fmt.Errorf("a short row under %q: %s", heading, row)
}
names := ticked.FindAllStringSubmatch(c[model], -1)
date, err := parseDate(c[0])
date, err := parseDate(c[when])
if err != nil {
// "To be announced": not a retirement yet, and the newer word on
// these names, so an older row's date for them doesn't count.
Expand All @@ -92,7 +130,7 @@ func Parse(page []byte, keep func(string) bool) ([]Retirement, error) {
}
continue
}
excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n")
excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerAt]), row}, "\n")
for _, m := range names {
name := m[1]
if seen[name] || !keep(name) {
Expand All @@ -110,14 +148,6 @@ func Parse(page []byte, keep func(string) bool) ([]Retirement, error) {
return out, nil
}

// headerLine walks back from a row to its table's header.
func headerLine(lines []string, i int) int {
for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") {
i--
}
return i
}

// follow replaces a replacement that is itself retired with its own
// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is
// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra.
Expand Down Expand Up @@ -173,8 +203,8 @@ func cells(row string) []string {
}

func column(header []string, words ...string) int {
for i, h := range header {
for _, w := range words {
for _, w := range words {
for i, h := range header {
if strings.Contains(strings.ToLower(h), w) {
return i
}
Expand Down Expand Up @@ -211,7 +241,7 @@ func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.E
ChangeType: event.ChangeTypeBreaking,
Breaking: true,
Subject: subject,
Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor),
Description: describe(p, r),
MigrationHint: h,
SourceURL: sourceURL,
SourceExcerpt: r.Excerpt,
Expand All @@ -227,6 +257,13 @@ func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.E
return events, errs
}

func describe(p Page, r Retirement) string {
if p.Earliest {
return fmt.Sprintf("Model %q can be shut down from %s, the earliest date %s gives: %s requests naming it fail once it is.", r.Model, r.Date, p.Vendor, p.Vendor)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: for some rows this sentence is wrong. gemini-2.5-pro, gemini-2.5-flash and gemini-embedding-2-preview don't fail on their date. Google says requests to them "will automatically route to" the replacement and are billed at its rates. The event is still worth emitting, since behaviour and price change, and the hint already quotes the routing note. But "requests naming it fail once it is" isn't true for those three. A softer wording such as "…: Google stops serving it under that name from then" would be correct for every row.

}
return fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor)
}

// replacement is the one model the provider names, when its replacement cell
// is exactly one model name: not none, not several, not a model with a
// setting (`gpt-5.6-sol` (`reasoning.mode: pro`)). The patch-it client opens
Expand All @@ -242,6 +279,9 @@ func replacement(cell string) string {

func hint(vendor string, r Retirement) string {
repl := strings.TrimSpace(r.Replacement)
if repl == "" {
return fmt.Sprintf("%s names no replacement model.", vendor)
}
if First(repl) == "" {
return fmt.Sprintf("%s names no replacement model: %s", vendor, repl)
}
Expand Down
Loading
Loading