Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

9.6 KB
Raw Blame
/**
 * Pure half of the model catalog: turns the models.dev API payload into the
 * small per-driver catalog Akeru keeps, and decides which models are current.
 *
 * `ModelCatalog.ts` fetches and caches; `scripts/sync-model-catalog.ts`
 * regenerates the bundled `model-catalog.json` with the same conversion.
 */
import type { ProviderDriverKind } from "@akeru/contracts";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";

import bundledCatalogJson from "./model-catalog.json" with { type: "json" };

export const MODELS_DEV_URL = "https://models.dev/api.json";

/** models.dev provider id for each driver kind the catalog covers. */
export const MODELS_DEV_PROVIDER_BY_DRIVER = {
  codex: "openai",
  claudeAgent: "anthropic",
  grok: "xai",
  kimi: "kimi-code-plan-global",
  opencodeGo: "opencode-go",
} as const satisfies Record<string, string>;

/**
 * Drivers whose older models move to the picker's legacy section. Kimi For
 * Coding and OpenCode Go plans list every model they serve as current.
 */
const DRIVERS_WITH_LEGACY: ReadonlySet<string> = new Set(["codex", "claudeAgent", "grok"]);

/** A family's newest model stays current while it is this close to the
 * provider's newest release. Measured against the newest release, not the
 * clock, so an old cache or bundle never demotes everything. */
const CURRENT_WINDOW_MS = 180 * 24 * 60 * 60 * 1000;

const CatalogModel = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  family: Schema.optionalKey(Schema.String),
  releaseDate: Schema.optionalKey(Schema.String),
  deprecated: Schema.optionalKey(Schema.Boolean),
  /** Reasoning effort levels the model accepts, in models.dev order. */
  efforts: Schema.optionalKey(Schema.Array(Schema.String)),
  /** True when the model offers a priority (Fast) service tier. */
  fast: Schema.optionalKey(Schema.Boolean),
});

export type CatalogModel = typeof CatalogModel.Type;

/** `version` gates breaking changes to the cached and bundled shape. */
export const ModelCatalogSchema = Schema.Struct({
  version: Schema.Literal(1),
  drivers: Schema.Record(Schema.String, Schema.Array(CatalogModel)),
});

export type ModelCatalogData = typeof ModelCatalogSchema.Type;

export const BUNDLED_MODEL_CATALOG: ModelCatalogData =
  Schema.decodeUnknownSync(ModelCatalogSchema)(bundledCatalogJson);

/** The slice of a models.dev model entry the catalog reads. Unknown keys are ignored. */
const ModelsDevModel = Schema.Struct({
  id: Schema.String,
  name: Schema.optionalKey(Schema.String),
  family: Schema.optionalKey(Schema.String),
  release_date: Schema.optionalKey(Schema.String),
  status: Schema.optionalKey(Schema.String),
  tool_call: Schema.optionalKey(Schema.Boolean),
  reasoning_options: Schema.optionalKey(
    Schema.Array(
      Schema.Struct({
        type: Schema.String,
        values: Schema.optionalKey(Schema.Array(Schema.String)),
      }),
    ),
  ),
  modalities: Schema.optionalKey(
    Schema.Struct({ output: Schema.optionalKey(Schema.Array(Schema.String)) }),
  ),
  experimental: Schema.optionalKey(
    Schema.Struct({
      modes: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
    }),
  ),
});

type ModelsDevModel = typeof ModelsDevModel.Type;

const ModelsDevProvider = Schema.Struct({
  models: Schema.Record(Schema.String, Schema.Unknown),
});

const decodeModelsDevModel = Schema.decodeUnknownOption(ModelsDevModel);

const decodeModelsDevProvider = Schema.decodeUnknownOption(ModelsDevProvider);

/** The models.dev payload: provider entries keyed by provider id. Each entry
 * and model is decoded on its own so one malformed record cannot sink the rest. */
export const ModelsDevPayload = Schema.Record(Schema.String, Schema.Unknown);

export type ModelsDevPayload = typeof ModelsDevPayload.Type;

/** Whether a driver can run this models.dev entry as a coding agent model. */
function isUsable(driver: string, model: ModelsDevModel): boolean {
  if (model.tool_call !== true) return false;

  if ((model.modalities?.output ?? ["text"]).some((output) => output !== "text")) return false;

  // Dated Anthropic snapshots duplicate their undated alias.
  if (driver === "claudeAgent" && /-\d{8}$/.test(model.id)) return false;

  if (driver === "codex") {
    // ChatGPT sign-in serves the GPT reasoning models. The Pro and nano tiers
    // are API-only, and non-reasoning models do not run in the Codex harness.
    const efforts = model.reasoning_options?.find((option) => option.type === "effort");

    return (
      model.id.startsWith("gpt-") &&
      !/-(pro|nano)$/.test(model.family ?? "") &&
      !/-(pro|nano)(-|$)/.test(model.id) &&
      efforts !== undefined
    );
  }

  return true;
}

function toCatalogModel(model: ModelsDevModel): CatalogModel {
  const efforts = model.reasoning_options?.find((option) => option.type === "effort")?.values;

  return {
    id: model.id,
    name: model.name?.trim() || model.id,
    ...(model.family ? { family: model.family } : {}),
    ...(model.release_date ? { releaseDate: model.release_date } : {}),
    ...(model.status === "deprecated" ? { deprecated: true } : {}),
    ...(efforts && efforts.length > 0 ? { efforts } : {}),
    ...(model.experimental?.modes?.fast !== undefined ? { fast: true } : {}),
  };
}

const releaseMs = (model: CatalogModel) => Date.parse(model.releaseDate ?? "") || 0;

/** Newest release first; ties keep a stable id order. */
const byNewest = (left: CatalogModel, right: CatalogModel) =>
  releaseMs(right) - releaseMs(left) || left.id.localeCompare(right.id);

/**
 * Converts the models.dev payload into the catalog. Returns null when the
 * payload holds no usable model for any covered driver, so a broken or
 * reshaped upstream response never replaces a good catalog.
 */
export function catalogFromModelsDev(providers: ModelsDevPayload): ModelCatalogData | null {
  const drivers: Record<string, ReadonlyArray<CatalogModel>> = {};

  for (const [driver, providerId] of Object.entries(MODELS_DEV_PROVIDER_BY_DRIVER)) {
    const provider = Option.getOrUndefined(decodeModelsDevProvider(providers[providerId]));

    if (provider === undefined) continue;

    const models = Object.values(provider.models).flatMap((raw) => {
      const decoded = Option.getOrUndefined(decodeModelsDevModel(raw));

      return decoded !== undefined && isUsable(driver, decoded) ? [toCatalogModel(decoded)] : [];
    });

    if (models.length > 0) drivers[driver] = models.toSorted(byNewest);
  }

  return Object.keys(drivers).length > 0 ? { version: 1, drivers } : null;
}

/**
 * Combines a fresh catalog with the previous one: a driver missing from the
 * fresh payload keeps its previous models instead of losing its list.
 */
export function mergeCatalogs(
  previous: ModelCatalogData,
  next: ModelCatalogData,
): ModelCatalogData {
  return { version: 1, drivers: { ...previous.drivers, ...next.drivers } };
}

/**
 * Combines the bundled catalog with a cached one. The cache usually wins, but
 * an app update can ship a bundle generated after the cache was fetched; a
 * driver whose bundled list has a newer release than its cached list uses the
 * bundled list, so offline users still see the models the update added.
 */
export function preferNewerLists(
  bundled: ModelCatalogData,
  cached: ModelCatalogData,
): ModelCatalogData {
  const newestRelease = (models: ReadonlyArray<CatalogModel> | undefined) =>
    Math.max(0, ...(models ?? []).map(releaseMs));

  const drivers = { ...bundled.drivers, ...cached.drivers };

  for (const [driver, models] of Object.entries(bundled.drivers)) {
    if (newestRelease(models) > newestRelease(cached.drivers[driver])) drivers[driver] = models;
  }

  return { version: 1, drivers };
}

/** Catalog models for a driver, newest first. Empty for drivers the catalog does not cover. */
export function catalogModelsFor(
  catalog: ModelCatalogData,
  driver: ProviderDriverKind,
): ReadonlyArray<CatalogModel> {
  return catalog.drivers[driver] ?? [];
}

/**
 * Model ids that belong in the picker's main section, or null when the driver
 * has no legacy concept. Deprecated models are never current. For drivers with
 * a legacy section, only the newest model of each family stays current, and
 * only while its release is recent relative to the provider's newest model.
 * Undated models stay current.
 */
export function currentModelIds(
  catalog: ModelCatalogData,
  driver: ProviderDriverKind,
): ReadonlySet<string> | null {
  const models = catalogModelsFor(catalog, driver).filter((model) => !model.deprecated);

  if (!DRIVERS_WITH_LEGACY.has(driver)) {
    return catalog.drivers[driver] ? new Set(models.map((model) => model.id)) : null;
  }

  if (!catalog.drivers[driver]) return null;

  if (models.length === 0) return new Set();
  const newest = Math.max(...models.map(releaseMs));
  const newestByFamily = new Map<string, CatalogModel>();

  for (const model of models.toSorted(byNewest)) {
    const family = model.family ?? model.id;

    if (!newestByFamily.has(family)) newestByFamily.set(family, model);
  }

  // An undated model cannot be placed against its family or the window, so it
  // stays current rather than landing in legacy the moment it appears.
  return new Set([
    ...[...newestByFamily.values()].flatMap((model) =>
      newest - releaseMs(model) <= CURRENT_WINDOW_MS ? [model.id] : [],
    ),
    ...models.flatMap((model) => (releaseMs(model) === 0 ? [model.id] : [])),
  ]);
}

/** Maps models.dev effort names onto the levels the Mastra harness accepts. */
export function harnessEffortLevels(efforts: ReadonlyArray<string>): string[] {
  return [
    ...new Set(
      efforts.flatMap((effort) =>
        effort === "none"
          ? ["off"]
          : ["low", "medium", "high", "xhigh", "max"].includes(effort)
            ? [effort]
            : [],
      ),
    ),
  ];
}