a model you still call retires in under 90 days

"""Turn OpenAI shutdown dates into a migration schedule, ordered by urgency.

Read only. GET requests and nothing else: the models list needs a project key
set to Read Only, and the optional traffic join needs an organization admin key
because usage belongs to the organization rather than to a project. The repair
is printed, never performed.
"""
import argparse
import datetime as dt
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("openai_model_retirement_window")

API = "https://api.openai.com/v1"

FLAGGED = ("urgent", "due", "expired", "unreadable-date")


def parse_day(value):
    """Read a shutdown_date into a date, or None when it cannot be read."""
    raw = str(value or "").strip()
    if not raw:
        return None
    try:
        return dt.date.fromisoformat(raw.split("T")[0])
    except ValueError:
        return None


def traffic_note(requests_30d):
    """How the traffic column is described, including when there is none.

    None means the admin key was not supplied, which is different from zero and
    has to read differently, or an unmeasured id looks like an unused one.
    """
    if requests_30d is None:
        return ("traffic unknown: no admin key, so this is ordered by date "
                "alone")
    if requests_30d == 0:
        return ("no requests in the last 30 days, so this is probably a string "
                "in a config file or a monthly job rather than live traffic")
    return "%d request(s) in the last 30 days" % (requests_30d,)


def plan(model, today, window_days=90, urgent_within=30, requests_30d=None):
    """Classify one models-list entry into a place in the migration schedule.

    Pure, and both thresholds are arguments: the right window is however long a
    model change takes to evaluate and roll out where you work, and that is not
    a constant this script gets to choose. Returns (state, detail).
    """
    raw = model.get("shutdown_date")
    if raw is None or str(raw).strip() == "":
        return ("unscheduled",
                "no shutdown date published today. Re-read the field rather "
                "than trusting this answer for a quarter.")

    day = parse_day(raw)
    if day is None:
        return ("unreadable-date",
                "shutdown_date is %r, which this script will not guess at."
                % (raw,))

    days = (day - today).days
    note = traffic_note(requests_30d)
    if days < 0:
        return ("expired",
                "shut down %d day(s) ago on %s. This is past planning; calls "
                "naming it are already failing. %s"
                % (-days, day.isoformat(), note))
    if days <= urgent_within:
        return ("urgent",
                "%d day(s) left, shutting down %s. Under %d days is scheduling "
                "work now, not next cycle. %s"
                % (days, day.isoformat(), urgent_within, note))
    if days <= window_days:
        return ("due",
                "%d day(s) left, shutting down %s. Inside the %d day window. %s"
                % (days, day.isoformat(), window_days, note))
    return ("later",
            "%d day(s) left, shutting down %s. Outside the window; nothing to "
            "do yet. %s" % (days, day.isoformat(), note))


def get(session, path, **params):
    r = session.get(API + path, params=params, timeout=60)
    if r.status_code in (401, 403):
        raise SystemExit("%d from OpenAI on %s: check the key, and that an "
                         "organization admin key is used for /organization/*"
                         % (r.status_code, path))
    r.raise_for_status()
    return r.json()


def usage_by_model(admin_key, days):
    """Sum num_model_requests per model over the window.

    Needs an organization admin key: the usage endpoints reject project keys
    outright. Returns {} when no key was given, which the caller reports as
    unknown rather than as zero.
    """
    if not admin_key:
        return {}
    session = requests.Session()
    session.headers.update({"Authorization": "Bearer " + admin_key})
    start = int((dt.datetime.now(dt.timezone.utc)
                 - dt.timedelta(days=days)).timestamp())
    totals = {}
    params = {"start_time": start, "bucket_width": "1d",
              "group_by[]": "model", "limit": 31}
    while True:
        page = get(session, "/organization/usage/completions", **params)
        for bucket in page.get("data", []):
            for row in bucket.get("results", []):
                name = row.get("model")
                if name:
                    totals[name] = totals.get(name, 0) + int(
                        row.get("num_model_requests") or 0)
        if not page.get("has_more"):
            break
        params["page"] = page.get("next_page")
        if not params["page"]:
            break
    return totals


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--window", type=int, default=90,
                    help="days ahead to treat as inside the migration window")
    ap.add_argument("--urgent-within", type=int, default=30,
                    help="days ahead that count as urgent rather than due")
    ap.add_argument("--usage-days", type=int, default=30,
                    help="days of usage to sum when an admin key is available")
    args = ap.parse_args()

    key = os.environ.get("OPENAI_API_KEY")
    if not key:
        log.error("set OPENAI_API_KEY (a project key set to Read Only)")
        return 2
    admin = os.environ.get("OPENAI_ADMIN_KEY")
    if not admin:
        log.warning("OPENAI_ADMIN_KEY is not set: the report will be ordered by "
                    "date alone, with no idea which ids carry traffic")

    session = requests.Session()
    session.headers.update({"Authorization": "Bearer " + key})
    models = get(session, "/models").get("data", [])
    dated = [m for m in models if str(m.get("shutdown_date") or "").strip()]

    totals = usage_by_model(admin, args.usage_days)

    rows = []
    today = dt.date.today()
    for model in dated:
        model_id = str(model.get("id") or "?")
        seen = totals.get(model_id) if admin else None
        if admin and seen is None:
            seen = 0
        state, detail = plan(model, today, args.window, args.urgent_within, seen)
        rows.append((parse_day(model.get("shutdown_date")) or dt.date.max,
                     -(seen or 0), state, model_id, detail))

    flagged = 0
    for _day, _neg, state, model_id, detail in sorted(rows):
        line = "%-14s %s  %s" % (state, model_id, detail)
        if state in FLAGGED:
            flagged += 1
            log.warning(line)
            log.warning("  repair: pin the successor from the deprecations page, "
                        "then re-run this against the new id so its own date is "
                        "on the calendar before it is a surprise")
        else:
            log.info(line)

    log.info("%d dated model(s), %d inside a %d day window",
             len(dated), flagged, args.window)
    return 1 if flagged else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Turn OpenAI shutdown dates into a migration schedule, ordered by urgency.
 *
 * Read only. GET requests and nothing else: the models list needs a project key
 * set to Read Only, and the optional traffic join needs an organization admin
 * key. The repair is printed, never performed.
 */
const API = 'https://api.openai.com/v1';
const DAY = 86400000;
const FLAGGED = ['urgent', 'due', 'expired', 'unreadable-date'];

/** Read a shutdown_date into a UTC date, or null when it cannot be read. */
export function parseDay(value) {
  const raw = String(value ?? '').trim().split('T')[0];
  if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) return null;
  const ms = Date.parse(`${raw}T00:00:00Z`);
  return Number.isNaN(ms) ? null : new Date(ms);
}

/**
 * How the traffic column is described, including when there is none. null means
 * the admin key was not supplied, which is different from zero and has to read
 * differently, or an unmeasured id looks like an unused one.
 */
export function trafficNote(requests30d) {
  if (requests30d === null || requests30d === undefined) {
    return 'traffic unknown: no admin key, so this is ordered by date alone';
  }
  if (requests30d === 0) {
    return 'no requests in the last 30 days, so this is probably a string in a ' +
           'config file or a monthly job rather than live traffic';
  }
  return `${requests30d} request(s) in the last 30 days`;
}

/**
 * Classify one models-list entry into a place in the migration schedule. Pure,
 * and both thresholds are arguments: the right window is however long a model
 * change takes to evaluate and roll out where you work. Returns [state, detail].
 */
export function plan(model, today, windowDays = 90, urgentWithin = 30,
                     requests30d = null) {
  const raw = model.shutdown_date;
  if (raw === null || raw === undefined || String(raw).trim() === '') {
    return ['unscheduled',
      'no shutdown date published today. Re-read the field rather than ' +
      'trusting this answer for a quarter.'];
  }

  const day = parseDay(raw);
  if (day === null) {
    return ['unreadable-date',
      `shutdown_date is ${JSON.stringify(raw)}, which this script will not guess at.`];
  }

  const iso = day.toISOString().slice(0, 10);
  const days = Math.round((day.getTime() - today.getTime()) / DAY);
  const note = trafficNote(requests30d);
  if (days < 0) {
    return ['expired',
      `shut down ${-days} day(s) ago on ${iso}. This is past planning; calls ` +
      `naming it are already failing. ${note}`];
  }
  if (days <= urgentWithin) {
    return ['urgent',
      `${days} day(s) left, shutting down ${iso}. Under ${urgentWithin} days is ` +
      `scheduling work now, not next cycle. ${note}`];
  }
  if (days <= windowDays) {
    return ['due',
      `${days} day(s) left, shutting down ${iso}. Inside the ${windowDays} day ` +
      `window. ${note}`];
  }
  return ['later',
    `${days} day(s) left, shutting down ${iso}. Outside the window; nothing to ` +
    `do yet. ${note}`];
}

async function get(key, path, params = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from OpenAI on ${path}: check the key, and ` +
      'that an organization admin key is used for /organization/*');
  }
  if (!res.ok) throw new Error(`${res.status} from ${path}`);
  return res.json();
}

export async function usageByModel(adminKey, days) {
  if (!adminKey) return new Map();
  const start = Math.floor((Date.now() - days * DAY) / 1000);
  const totals = new Map();
  const params = { start_time: start, bucket_width: '1d',
                   'group_by[]': 'model', limit: 31 };
  for (;;) {
    const page = await get(adminKey, '/organization/usage/completions', params);
    for (const bucket of page.data ?? []) {
      for (const row of bucket.results ?? []) {
        if (!row.model) continue;
        totals.set(row.model,
          (totals.get(row.model) ?? 0) + Number(row.num_model_requests ?? 0));
      }
    }
    if (!page.has_more || !page.next_page) break;
    params.page = page.next_page;
  }
  return totals;
}

async function main() {
  const key = process.env.OPENAI_API_KEY;
  if (!key) {
    console.error('set OPENAI_API_KEY (a project key set to Read Only)');
    process.exitCode = 2;
    return;
  }
  const admin = process.env.OPENAI_ADMIN_KEY;
  if (!admin) {
    console.warn('OPENAI_ADMIN_KEY is not set: the report will be ordered by ' +
                 'date alone, with no idea which ids carry traffic');
  }

  const arg = (name, fallback) => Number(process.argv.includes(name)
    ? process.argv[process.argv.indexOf(name) + 1] : fallback) || fallback;
  const windowDays = arg('--window', 90);
  const urgentWithin = arg('--urgent-within', 30);
  const usageDays = arg('--usage-days', 30);

  const { data = [] } = await get(key, '/models');
  const dated = data.filter((m) => String(m.shutdown_date ?? '').trim() !== '');
  const totals = await usageByModel(admin, usageDays);

  const today = new Date(`${new Date().toISOString().slice(0, 10)}T00:00:00Z`);
  const rows = dated.map((model) => {
    const modelId = String(model.id ?? '?');
    const seen = admin ? (totals.get(modelId) ?? 0) : null;
    const [state, detail] = plan(model, today, windowDays, urgentWithin, seen);
    const day = parseDay(model.shutdown_date);
    return { sort: day ? day.getTime() : Infinity, seen: seen ?? 0,
             state, modelId, detail };
  }).sort((a, b) => a.sort - b.sort || b.seen - a.seen);

  let flagged = 0;
  for (const row of rows) {
    const line = `${row.state.padEnd(14)} ${row.modelId}  ${row.detail}`;
    if (FLAGGED.includes(row.state)) {
      flagged += 1;
      console.warn(line);
      console.warn('  repair: pin the successor from the deprecations page, then ' +
        're-run this against the new id so its own date is on the calendar ' +
        'before it is a surprise');
    } else {
      console.log(line);
    }
  }

  console.log(`${dated.length} dated model(s), ${flagged} inside a ${windowDays} day window`);
  process.exitCode = flagged ? 1 : 0;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing key, and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

import datetime as dt

from openai_model_retirement_window import plan, traffic_note

TODAY = dt.date(2026, 8, 30)


def dated(day, model_id="gpt-5-2025-08-07"):
    return {"id": model_id, "shutdown_date": day}


def test_a_date_inside_the_window_is_due():
    state, detail = plan(dated("2026-11-15"), TODAY)
    assert state == "due"
    assert "77 day(s) left" in detail


def test_a_date_under_a_month_out_is_urgent_not_merely_due():
    state, detail = plan(dated("2026-09-20"), TODAY)
    assert state == "urgent"
    assert "not next cycle" in detail


def test_a_date_beyond_the_window_is_left_alone():
    assert plan(dated("2027-06-01"), TODAY)[0] == "later"


def test_the_window_and_the_urgency_line_are_both_arguments():
    model = dated("2026-11-15")
    assert plan(model, TODAY)[0] == "due"
    assert plan(model, TODAY, window_days=30)[0] == "later"
    assert plan(model, TODAY, window_days=90, urgent_within=120)[0] == "urgent"


def test_a_date_already_passed_is_out_of_scope_for_planning():
    state, detail = plan(dated("2026-07-01"), TODAY)
    assert state == "expired"
    assert "already failing" in detail


def test_no_date_is_unscheduled_rather_than_safe():
    state, detail = plan({"id": "gpt-5.6-sol"}, TODAY)
    assert state == "unscheduled"
    assert "Re-read" in detail
    assert plan({"id": "x", "shutdown_date": "Q4"}, TODAY)[0] == "unreadable-date"


def test_unmeasured_traffic_and_zero_traffic_do_not_read_the_same():
    assert "no admin key" in traffic_note(None)
    assert "config file" in traffic_note(0)
    assert "4000000 request(s)" in traffic_note(4000000)
    assert "config file" in plan(dated("2026-09-20"), TODAY, requests_30d=0)[1]
    assert "no admin key" in plan(dated("2026-09-20"), TODAY)[1]

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { plan, trafficNote } from './openai-model-retirement-window.mjs';

const TODAY = new Date('2026-08-30T00:00:00Z');
const dated = (day, id = 'gpt-5-2025-08-07') => ({ id, shutdown_date: day });

test('a date inside the window is due', () => {
  const [state, detail] = plan(dated('2026-11-15'), TODAY);
  assert.equal(state, 'due');
  assert.match(detail, /77 day\(s\) left/);
});

test('a date under a month out is urgent, not merely due', () => {
  const [state, detail] = plan(dated('2026-09-20'), TODAY);
  assert.equal(state, 'urgent');
  assert.match(detail, /not next cycle/);
});

test('a date beyond the window is left alone', () => {
  assert.equal(plan(dated('2027-06-01'), TODAY)[0], 'later');
});

test('the window and the urgency line are both arguments', () => {
  const model = dated('2026-11-15');
  assert.equal(plan(model, TODAY)[0], 'due');
  assert.equal(plan(model, TODAY, 30)[0], 'later');
  assert.equal(plan(model, TODAY, 90, 120)[0], 'urgent');
});

test('a date already passed is out of scope for planning', () => {
  const [state, detail] = plan(dated('2026-07-01'), TODAY);
  assert.equal(state, 'expired');
  assert.match(detail, /already failing/);
});

test('no date is unscheduled rather than safe', () => {
  const [state, detail] = plan({ id: 'gpt-5.6-sol' }, TODAY);
  assert.equal(state, 'unscheduled');
  assert.match(detail, /Re-read/);
  assert.equal(plan({ id: 'x', shutdown_date: 'Q4' }, TODAY)[0], 'unreadable-date');
});

test('unmeasured traffic and zero traffic do not read the same', () => {
  assert.match(trafficNote(null), /no admin key/);
  assert.match(trafficNote(0), /config file/);
  assert.match(trafficNote(4000000), /4000000 request\(s\)/);
  assert.match(plan(dated('2026-09-20'), TODAY, 90, 30, 0)[1], /config file/);
  assert.match(plan(dated('2026-09-20'), TODAY)[1], /no admin key/);
});