feat: manage import models and recover interrupted runs (#99)

Author: HarryRandall

apps/web/.env.example

@@ -20,8 +20,7 @@ SUPABASE_SECRET_KEY=
 # OpenRouter extraction
 OPENROUTER_API_KEY=
 
-# Allowed models. Select the active model in admin.
-COURSEMAP_OPENROUTER_MODELS=google/gemini-3.1-flash-lite,qwen/qwen3-32b,google/gemini-2.5-flash-lite
+# Models and pricing are managed in the admin dashboard and stored in the database.
 
 # Background imports through Vercel Queues
 COURSEMAP_QUEUE_IMPORTS_ENABLED=false

apps/web/app/api/admin/academic-structure-imports/route.ts

@@ -1,3 +1,4 @@
+import { loadImportModelSetting } from "@/lib/admin/settings";
 import { canManageCatalogueImports } from "@/lib/auth/viewer";
 import { recordAcademicStructureImportDispatch } from "@/lib/structure-import/import-store";
 import {
@@ -93,7 +94,11 @@ async function startQueuedImport(request: Request) {
 
   let input;
   try {
-    input = parseAcademicStructureImportRequest(body);
+    const setting = await loadImportModelSetting();
+    if (setting.error) return jsonError(setting.error, 503);
+    input = parseAcademicStructureImportRequest(body, setting.model);
+    if (!setting.options.includes(input.requestedModel))
+      return jsonError("Choose an enabled import model.", 400);
   } catch (error) {
     return jsonError(
       error instanceof AcademicStructureImportRequestError
@@ -345,3 +350,29 @@ export async function PATCH(request: Request) {
     );
   }
 }
+
+export async function DELETE(request: Request) {
+  if (!(await canManageCatalogueImports())) {
+    return jsonError("Import permission is required.", 403);
+  }
+  let runId: string;
+  try {
+    runId = parseReconciliationRequest(await request.json());
+  } catch {
+    return jsonError(
+      "A valid academic structure import run ID is required.",
+      400,
+    );
+  }
+  const supabase = await createClient();
+  const { error } = await supabase.rpc("cancel_academic_structure_import", {
+    p_run_id: runId,
+  });
+  if (error) {
+    return jsonError(
+      "The import run could not be stopped.",
+      error.code === "42501" ? 403 : error.code === "P0002" ? 404 : 500,
+    );
+  }
+  return Response.json({ runId, status: "stopped" });
+}

apps/web/app/api/admin/course-imports/route.ts

@@ -1,3 +1,4 @@
+import { loadImportModelSetting } from "@/lib/admin/settings";
 import { canManageCourseImports } from "@/lib/auth/viewer";
 import { recordCourseImportDispatch } from "@/lib/course-import/import-store";
 import {
@@ -74,7 +75,11 @@ async function startQueuedImport(request: Request) {
 
   let input;
   try {
-    input = parseCourseImportRequest(body);
+    const setting = await loadImportModelSetting();
+    if (setting.error) return jsonError(setting.error, 503);
+    input = parseCourseImportRequest(body, setting.model);
+    if (!setting.options.includes(input.requestedModel))
+      return jsonError("Choose an enabled import model.", 400);
   } catch (error) {
     return jsonError(
       error instanceof CourseImportRequestError

apps/web/lib/admin/import-model.ts

@@ -0,0 +1,36 @@
+export type ImportModel = {
+  id: string;
+  name: string;
+  provider: string;
+  enabled: boolean;
+  visible: boolean;
+  input_usd_per_million: number | null;
+  output_usd_per_million: number | null;
+  pricing_updated_at: string | null;
+};
+
+export const ESTIMATED_IMPORT_INPUT_TOKENS = 10_000;
+export const ESTIMATED_IMPORT_OUTPUT_TOKENS = 2_000;
+
+export function estimatedImportCost(model: ImportModel) {
+  if (
+    model.input_usd_per_million === null ||
+    model.output_usd_per_million === null
+  )
+    return null;
+  return (
+    (model.input_usd_per_million * ESTIMATED_IMPORT_INPUT_TOKENS +
+      model.output_usd_per_million * ESTIMATED_IMPORT_OUTPUT_TOKENS) /
+    1_000_000
+  );
+}
+
+export function formatImportPrice(usd: number | null) {
+  if (usd === null || !Number.isFinite(usd) || usd < 0) return "—";
+  if (usd === 0) return "$0";
+  if (usd < 0.01) {
+    const cents = usd * 100;
+    return cents < 0.001 ? "<0.001¢" : `${Number(cents.toFixed(3))}¢`;
+  }
+  return `$${usd.toFixed(2)}`;
+}

apps/web/lib/admin/model-catalogue.ts

@@ -0,0 +1,49 @@
+import { assertOpenRouterModel } from "@/lib/course-import/openrouter";
+import type { ImportModel } from "@/lib/admin/import-model";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tokenRate(value: unknown) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const rate = Number(value) * 1_000_000;
+  return Number.isFinite(rate) && rate >= 0 && rate < 1_000_000 ? rate : null;
+}
+
+export function readCatalogueModel(
+  payload: unknown,
+  requested: string,
+): ImportModel {
+  const id = assertOpenRouterModel(requested);
+  if (!isRecord(payload) || !Array.isArray(payload.data))
+    throw new Error("The model catalogue could not be read.");
+  const model = payload.data.find(
+    (item: unknown) => isRecord(item) && item.id === id,
+  );
+  if (!isRecord(model) || typeof model.name !== "string")
+    throw new Error("The model was not found in OpenRouter's catalogue.");
+  const pricing = isRecord(model.pricing) ? model.pricing : {};
+  const [provider, ...name] = model.name.split(": ");
+  return {
+    id,
+    name: (name.join(": ") || model.name).slice(0, 160),
+    provider: (name.length ? provider : id.split("/")[0]!).slice(0, 80),
+    enabled: true,
+    visible: true,
+    input_usd_per_million: tokenRate(pricing.prompt),
+    output_usd_per_million: tokenRate(pricing.completion),
+    pricing_updated_at: new Date().toISOString(),
+  };
+}
+
+export async function fetchCatalogueModel(id: string) {
+  assertOpenRouterModel(id);
+  const response = await fetch("https://openrouter.ai/api/v1/models", {
+    cache: "no-store",
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok)
+    throw new Error("OpenRouter's model catalogue is unavailable.");
+  return readCatalogueModel(await response.json(), id);
+}

apps/web/lib/admin/settings-actions.ts

@@ -2,61 +2,180 @@
 
 import { revalidatePath } from "next/cache";
 import { canManageCourseImports } from "@/lib/auth/viewer";
-import { configuredOpenRouterModels } from "@/lib/course-import/openrouter";
 import { createClient } from "@/lib/supabase/server";
 import { IMPORT_MODEL_SETTING_KEY } from "@/lib/admin/settings";
+import { fetchCatalogueModel } from "@/lib/admin/model-catalogue";
+import { assertOpenRouterModel } from "@/lib/course-import/openrouter";
 
 export type ImportModelActionResult = {
   ok: boolean;
   model: string;
   message: string;
 };
 
-/**
- * Set the model every subsequent import run requests. Rejecting models the
- * deployment does not allow keeps this in step with the queue's own check
- * rather than deferring the failure to a run that has already started.
- */
+function refreshImportPages() {
+  revalidatePath("/admin", "layout");
+}
+
 export async function setImportModel(
   model: string,
 ): Promise<ImportModelActionResult> {
-  const requested = model.trim().toLowerCase();
-  if (!configuredOpenRouterModels().includes(requested)) {
+  if (!(await canManageCourseImports()))
+    return {
+      ok: false,
+      model,
+      message: "Import management permission is required.",
+    };
+  try {
+    const requested = assertOpenRouterModel(model);
+    const supabase = await createClient();
+    const { error } = await supabase
+      .from("app_settings")
+      .upsert(
+        { key: IMPORT_MODEL_SETTING_KEY, value: requested },
+        { onConflict: "key" },
+      );
+    if (error)
+      return {
+        ok: false,
+        model,
+        message:
+          "The default model could not be saved. Choose an enabled model.",
+      };
+    refreshImportPages();
+    return {
+      ok: true,
+      model: requested,
+      message: "The default import model was updated.",
+    };
+  } catch {
     return {
       ok: false,
       model,
-      message: "Choose a model this deployment is configured to call.",
+      message: "The default model could not be saved.",
     };
   }
+}
 
-  if (!(await canManageCourseImports())) {
+export async function saveImportModel(
+  model: string,
+  refreshOnly = false,
+): Promise<ImportModelActionResult> {
+  if (!(await canManageCourseImports()))
     return {
       ok: false,
       model,
       message: "Import management permission is required.",
     };
+  try {
+    const entry = await fetchCatalogueModel(model);
+    const supabase = await createClient();
+    const { enabled, visible, ...pricing } = entry;
+    const { error } = refreshOnly
+      ? await supabase
+          .from("import_models")
+          .update(pricing)
+          .eq("id", entry.id)
+          .eq("enabled", true)
+          .select("id")
+          .single()
+      : await supabase
+          .from("import_models")
+          .upsert({ ...pricing, enabled, visible });
+    if (error)
+      return { ok: false, model, message: "The model could not be saved." };
+    refreshImportPages();
+    return {
+      ok: true,
+      model: entry.id,
+      message: "The model and its pricing were saved.",
+    };
+  } catch {
+    return {
+      ok: false,
+      model,
+      message:
+        "The model could not be loaded from OpenRouter. Check its identifier and try again.",
+    };
   }
+}
 
+export async function removeImportModel(
+  model: string,
+): Promise<ImportModelActionResult> {
+  if (!(await canManageCourseImports()))
+    return {
+      ok: false,
+      model,
+      message: "Import management permission is required.",
+    };
   try {
     const supabase = await createClient();
-    const { error } = await supabase
-      .from("app_settings")
-      .upsert(
-        { key: IMPORT_MODEL_SETTING_KEY, value: requested },
-        { onConflict: "key" },
-      );
-    if (error) {
-      return { ok: false, model, message: "The model could not be saved." };
-    }
+    const { data, error } = await supabase
+      .from("import_models")
+      .update({ enabled: false })
+      .eq("id", assertOpenRouterModel(model))
+      .select("id")
+      .single();
+    if (error || !data)
+      return {
+        ok: false,
+        model,
+        message:
+          "The model could not be removed. Choose another default first.",
+      };
+    refreshImportPages();
+    return {
+      ok: true,
+      model,
+      message: "The model was removed from future imports.",
+    };
   } catch {
-    return { ok: false, model, message: "The model could not be saved." };
+    return { ok: false, model, message: "The model could not be removed." };
   }
+}
 
-  revalidatePath("/admin");
-  revalidatePath("/admin/dashboard");
-  return {
-    ok: true,
-    model: requested,
-    message: `Imports now use ${requested}.`,
-  };
+export async function setImportModelVisibility(
+  model: string,
+  visible: boolean,
+): Promise<ImportModelActionResult> {
+  if (!(await canManageCourseImports()))
+    return {
+      ok: false,
+      model,
+      message: "Import management permission is required.",
+    };
+  try {
+    if (typeof visible !== "boolean")
+      throw new Error("The visibility is invalid.");
+    const supabase = await createClient();
+    const { data, error } = await supabase
+      .from("import_models")
+      .update({ visible })
+      .eq("id", assertOpenRouterModel(model))
+      .eq("enabled", true)
+      .select("id")
+      .single();
+    if (error || !data)
+      return {
+        ok: false,
+        model,
+        message:
+          "The model visibility could not be changed. Choose another default before hiding it.",
+      };
+    refreshImportPages();
+    return {
+      ok: true,
+      model,
+      message: visible
+        ? "The model is available for selection."
+        : "The model is hidden from selection.",
+    };
+  } catch {
+    return {
+      ok: false,
+      model,
+      message: "The model visibility could not be changed.",
+    };
+  }
 }