Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

16.4 KB
Raw Blame
/**
 * Search filtering and grouping-by-provider for the models page (pure functions, easy to
 * unit test): grouping uses the entry's **provider field** directly ((provider, model_id) is
 * the entry's unique key, with no `<provider>/<id>` concatenation anywhere in the pipeline).
 * A provider not in the catalog list is a **user-defined group**: each
 * forms its own group, keeping its original value, with OpenAI protocol semantics (env
 * fallback OPENAI_*), sorted by name and appended after custom. Matches model_id /
 * display name / provider / vendor name case-insensitively; built-in group order follows
 * the MODEL_PROVIDERS definition. Empty groups aren't returned, except the custom group,
 * which is always shown when there's no search query (rendered even when empty, to host
 * the generic "add model" entry point).
 *
 * That automatic sequence is the DEFAULT, not the last word: every entry point takes an
 * optional `groupOrder` — the user's dragged arrangement, stored per Project by
 * model-group-order.ts — and applies it to the assembled group list. An empty order is
 * the identity, so a profile that has never dragged a group sees exactly the catalog
 * order. Storage stays out of this module: the caller loads the array and passes it in.
 */
import { MODEL_PROVIDERS, catalogEntryFor, offPeakAt } from "@adelie/core/model-catalog";
import type { ModelProviderInfo, OffPeakDiscount } from "@adelie/core/model-catalog";

import { orderModelGroups } from "./model-group-order";

/** Paired model reference (same shape as the server DTO's ModelRefDto; a model is always referenced as (provider, modelId)). */
export interface ModelRefValue {
  provider: string;
  modelId: string;
}

/** Paired-reference equality (the sole comparison standard; either side missing counts as unequal). */
export function sameModelRef(
  a: ModelRefValue | null | undefined,
  b: ModelRefValue | null | undefined,
): boolean {
  return !!a && !!b && a.provider === b.provider && a.modelId === b.modelId;
}

/** Minimal row shape needed for grouping/filtering (models-page's RowState and the DTO's ModelInfo are both supersets of this). */
export interface ModelRowLike {
  /** Vendor id (entry field): a value not in the catalog list is a user-defined group, forming its own group while keeping its original value. */
  provider: string;
  /** Upstream model id (i.e. the stored model_id). */
  modelId: string;
  displayName?: string;
  /**
   * The row's running promotion, as the models endpoint reports it: a fraction off the stored
   * price, which is the list price (0.5 = half price). The server keeps it apart from the config
   * file and applies it when it prices usage. Absent when the row has none.
   */
  discount?: number;
}

/** Synthesized vendor info for a user-defined group: OpenAI protocol semantics (env fallback OPENAI_*), no external links or gateway endpoint. */
export function userProviderInfo(id: string): ModelProviderInfo {
  return { id, label: id, envKey: "OPENAI_API_KEY", envBaseUrlKey: "OPENAI_BASE_URL" };
}

/** Case-insensitive match against model_id / display name / raw provider value / vendor display name; empty query always matches. */
export function matchesQuery(row: ModelRowLike, query: string): boolean {
  const q = query.trim().toLowerCase();
  if (!q) return true;
  const provider = MODEL_PROVIDERS.find((p) => p.id === row.provider);
  return (
    row.modelId.toLowerCase().includes(q) ||
    (row.displayName ?? "").toLowerCase().includes(q) ||
    row.provider.toLowerCase().includes(q) ||
    (provider?.label ?? "").toLowerCase().includes(q)
  );
}

/** The user-defined group ids present in `rows` (anything not in the catalog list), sorted by name. */
function userGroupIds(rows: readonly ModelRowLike[]): string[] {
  return [
    ...new Set(rows.map((r) => r.provider).filter((p) => !MODEL_PROVIDERS.some((k) => k.id === p))),
  ].sort();
}

/**
 * Every group key the library can show, in its automatic order: the built-in providers in
 * MODEL_PROVIDERS order — **including the ones holding no models**, which groupModelRows
 * drops from the render — then the user-defined groups. This is the sequence a group drop
 * is committed against, so a group that happens to be empty today keeps its catalog place
 * instead of arriving as a newcomer the first time a model is added to it.
 */
export function allGroupKeys(rows: readonly ModelRowLike[]): string[] {
  return [...MODEL_PROVIDERS.map((p) => p.id), ...userGroupIds(rows)];
}

export interface ProviderGroup<T extends ModelRowLike> {
  provider: ModelProviderInfo;
  rows: T[];
}

/**
 * Filter + group by vendor; rows within a group keep their original order. Built-in groups
 * follow MODEL_PROVIDERS order (the custom group is returned even when empty, when there's
 * no search query); user-defined groups each form their own group, sorted by name and
 * appended after custom.
 *
 * `groupOrder` then rearranges that list: groups it names take its order, groups it does
 * not keep their automatic order and TRAIL (orderModelGroups — a group the user just
 * created appears where the control that created it sits, at the bottom of the page).
 * Reordering happens before empty groups are dropped, so a stored key for a group holding
 * no models costs nothing and is not visible.
 */
export function groupModelRows<T extends ModelRowLike>(
  rows: T[],
  query: string,
  groupOrder: readonly string[] = [],
): ProviderGroup<T>[] {
  const searching = query.trim() !== "";
  const filtered = rows.filter((r) => matchesQuery(r, query));
  const builtin = MODEL_PROVIDERS.map((provider) => ({
    provider,
    rows: filtered.filter((r) => r.provider === provider.id),
  }));
  const extras = userGroupIds(filtered).map((id) => ({
    provider: userProviderInfo(id),
    rows: filtered.filter((r) => r.provider === id),
  }));
  const ordered = orderModelGroups([...builtin, ...extras], (g) => g.provider.id, groupOrder);
  return ordered.filter((g) => g.rows.length > 0 || (!searching && g.provider.id === "custom"));
}

/**
 * Flattens the library grouping into one ordered list (the chat model picker uses this):
 * rows ordered exactly as the model page shows them — built-in provider groups in
 * MODEL_PROVIDERS order (custom last), then user-defined groups, with `groupOrder` applied
 * on top; in-group row order preserved. Passing the page's stored order here is what keeps
 * "exactly as the model page shows them" true once a user has dragged their groups.
 */
export function orderModelsLikeLibrary<T extends ModelRowLike>(
  rows: T[],
  groupOrder: readonly string[] = [],
): T[] {
  return groupModelRows(rows, "", groupOrder).flatMap((g) => g.rows);
}

/**
 * Row shape for the configured-key filter: adds the read-only credential display and the masked
 * env-fallback preview (the DTO's ModelInfo is a superset).
 */
export interface ModelCredentialRowLike extends ModelRowLike {
  credential?: { apiKeyMasked?: string };
  /**
   * Masked preview of the env-fallback value: the server emits it only for a variable that
   * currently holds a non-empty value, so its presence is proof the environment can authenticate
   * this entry.
   */
  envKeyMasked?: string;
}

/**
 * Whether the model has an API key behind it — the single rule shared by the model library, the
 * chat model picker and the chat credential guide: a stored (masked) key **or** a masked env
 * fallback, since a user who exported the variable has configured the key just as deliberately as
 * one who typed it into the dialog. `envKey` is only the NAME of that variable and says nothing
 * about whether it is set, so it never counts on its own.
 */
export function hasConfiguredKey(m: ModelCredentialRowLike): boolean {
  return !!m.credential?.apiKeyMasked || !!m.envKeyMasked;
}

/**
 * Free model detection (drives the light-yellow "Free" badge on the model card and in the
 * chat model picker): the entry carries explicit pricing and all three buckets are 0 — covers the
 * catalog's :free variants and the openrouter/free router — while unpriced models (no pricing
 * at all, costs merely unknown) stay unbadged. Accepts the DTO's numeric pricing buckets or
 * the model page's string-typed edit fields ("" = unpriced).
 */
export function isFreeModel(
  pricing:
    | { cacheRead: number | string; cacheWrite: number | string; output: number | string }
    | undefined,
): boolean {
  if (!pricing) return false;
  return [pricing.cacheRead, pricing.cacheWrite, pricing.output].every((b) =>
    typeof b === "string" ? b.trim() !== "" && Number(b) === 0 : b === 0,
  );
}

/**
 * The three price buckets as the page carries them: the DTO's numbers, or the model page's
 * string-typed edit fields ("" = unpriced) — the same pair of shapes isFreeModel accepts.
 */
export interface PricingBucketsLike {
  cacheRead?: number | string;
  cacheWrite?: number | string;
  output?: number | string;
}

/** The discount decoration for one model card, and the price it makes the row cost right now. */
export interface DiscountedPrice {
  /**
   * Whole-percent saving off the list price, as the badge shows it (50 for a half-price row). A
   * promotion and a live off-peak tier combine into one figure: 20% off, then half of the rest,
   * is 60.
   */
  percent: number;
  /**
   * What the seller bills for this row right now, in USD per million tokens — the figure the
   * card prints: the stored list price less the running promotion and, while the off-peak tier
   * is live, less its rate as well.
   */
  billed: BucketPrices;
  /**
   * When the saving is the time-of-day tier alone, the peak windows of the row's own schedule —
   * the hours it bills at list price instead — so the badge can explain when the rate applies.
   * Absent otherwise: a row that also runs a promotion is explained as the promotion.
   */
  peak?: PeakWindows;
}

/**
 * A schedule's peak windows reduced to the parts a sentence about them needs. Each dictionary
 * spells this one digest in its own words, so the explanation follows the schedule a row
 * actually declares; the catalog carries more than one vendor's windows. Both name the zone as
 * Beijing time: every catalog schedule is written in UTC+8, which the catalog's tests pin.
 */
export interface PeakWindows {
  /**
   * The ISO weekdays the windows fall on (1 = Monday … 7 = Sunday), as inclusive runs of
   * consecutive days: `[[1, 5]]` is Monday to Friday.
   */
  days: Array<[number, number]>;
  /** The runs cover the whole week, so the windows recur daily. */
  everyDay: boolean;
  /** The windows on those days, as whole-hour `[start, end)` pairs in Beijing time. */
  hours: OffPeakDiscount["peakHours"];
}

/** The digest of one schedule's peak windows (see PeakWindows). */
export function peakWindows(schedule: OffPeakDiscount): PeakWindows {
  const days: Array<[number, number]> = [];
  for (const day of schedule.peakDays) {
    const run = days.at(-1);
    if (run !== undefined && run[1] === day - 1) run[1] = day;
    else days.push([day, day]);
  }
  return {
    days,
    everyDay: days.length === 1 && days[0]![0] === 1 && days[0]![1] === 7,
    hours: schedule.peakHours,
  };
}

/** The three price buckets in USD per million tokens, in the numeric shape the DTO carries. */
export interface BucketPrices {
  cacheRead: number;
  cacheWrite: number;
  output: number;
}

/** One bucket as a finite number, or undefined for an unpriced ("" / absent) field. */
function bucketValue(v: number | string | undefined): number | undefined {
  if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
  if (v === undefined || v.trim() === "") return undefined;
  const n = Number(v);
  return Number.isFinite(n) ? n : undefined;
}

/**
 * `value` as a fraction off a price, or undefined when it is not one. Only (0, 1) says anything:
 * a badge built from a value outside that range reads as `-0%`, as `-100%` beside a "Free" tag,
 * or as `--20%`.
 */
export function fractionOff(value: number | undefined): number | undefined {
  return value !== undefined && value > 0 && value < 1 ? value : undefined;
}

/**
 * A price as the row's running promotion bills it: every bucket less `discount`, or `pricing`
 * itself when there is no promotion. Stored prices are list prices, so anything estimating what
 * usage costs from them has to take off the promotion the server takes off when it records that
 * cost. A time-of-day tier is not applied here.
 */
export function promotedPricing(
  pricing: BucketPrices | undefined,
  discount: number | undefined,
): BucketPrices | undefined {
  const promotion = fractionOff(discount);
  if (pricing === undefined || promotion === undefined) return pricing;
  return {
    cacheRead: pricing.cacheRead * (1 - promotion),
    cacheWrite: pricing.cacheWrite * (1 - promotion),
    output: pricing.output * (1 - promotion),
  };
}

/**
 * The discount decoration for one model row, or undefined for a row billed at its stored price.
 *
 * The stored price is always the list price, and two things can take something off it:
 *
 * - A **promotion** is the row's `discount`, which the server keeps apart from the config file:
 *   presets are seeded and synced with the catalog's, a platform sync writes the platform's, and
 *   a save that changes the row's price clears it. Keeping it true to the price stored beside
 *   it is the server's job, so it is taken as given here.
 * - An **off-peak tier** comes from the catalog entry's schedule. It changes twice a day, so
 *   nothing stores it: the reduction is applied here, against `now`, and inside the peak windows
 *   the row is simply at list price. It applies only while the stored price is still exactly the
 *   catalog's peak price. Prices are editable, and a hand-typed number has nothing to do with the
 *   seller's peak price — halving it would invent a saving the user is not getting.
 *
 * When both apply, the two reductions multiply.
 */
export function discountedPrice(
  row: ModelRowLike & PricingBucketsLike,
  now: Date = new Date(),
): DiscountedPrice | undefined {
  const cacheRead = bucketValue(row.cacheRead);
  const cacheWrite = bucketValue(row.cacheWrite);
  const output = bucketValue(row.output);
  // An unpriced row has no price to take anything off.
  if (cacheRead === undefined || cacheWrite === undefined || output === undefined) return undefined;
  const promotion = fractionOff(row.discount) ?? 0;
  const entry = catalogEntryFor(row.provider, row.modelId);
  const schedule = entry?.offPeakDiscount;
  const peak = entry?.pricing;
  const tier =
    schedule !== undefined &&
    peak !== undefined &&
    cacheRead === peak.cache_read &&
    cacheWrite === peak.cache_write &&
    output === peak.output &&
    offPeakAt(schedule, now)
      ? (fractionOff(schedule.rate) ?? 0)
      : 0;
  if (promotion === 0 && tier === 0) return undefined;
  const off = (v: number): number => Math.round(v * (1 - promotion) * (1 - tier) * 1e6) / 1e6;
  return {
    percent: Math.round((promotion + tier - promotion * tier) * 100),
    billed: { cacheRead: off(cacheRead), cacheWrite: off(cacheWrite), output: off(output) },
    ...(schedule !== undefined && tier > 0 && promotion === 0
      ? { peak: peakWindows(schedule) }
      : {}),
  };
}

export interface VisibleChatModelsOptions {
  /** true = list every model (the dropdown's expanded "show all" state). */
  showAll: boolean;
  query: string;
  /** Currently selected model: always visible even without a configured key (the active choice must never be invisible). */
  selected?: ModelRefValue | null;
  /** Project default model: always visible even without a configured key. */
  defaultModel?: ModelRefValue | null;
  /** The models page's stored group order; omitted = the catalog's automatic order. */
  groupOrder?: readonly string[];
}

/**
 * Candidate list for the chat model picker: library order → keep only models with a key
 * (hasConfiguredKey: stored or env-backed; plus the selected and the default model, unless
 * showAll) → the query then filters whatever is visible. When NO model has a key, the filter
 * degrades to showAll (everything listed), so the picker is never uselessly empty.
 */
export function visibleChatModels<T extends ModelCredentialRowLike>(
  models: T[],
  { showAll, query, selected, defaultModel, groupOrder }: VisibleChatModelsOptions,
): T[] {
  const ordered = orderModelsLikeLibrary(models, groupOrder);
  const keep =
    showAll || !ordered.some(hasConfiguredKey)
      ? ordered
      : ordered.filter(
          (m) => hasConfiguredKey(m) || sameModelRef(m, selected) || sameModelRef(m, defaultModel),
        );
  return keep.filter((m) => matchesQuery(m, query));
}