plugin-ai-api 1.1.0 → 1.1.2

package/src/server/utils/responses-stream.ts

@@ -0,0 +1,384 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { OpenAIUsage } from './openai-format';
+import {
+  chatResultToResponse,
+  createResponseOutputMessage,
+  createResponseReasoningItem,
+  extractReasoningText,
+  extractResponseIncompleteReason,
+  extractResponseOutputText,
+  extractResponseServiceTier,
+  generateResponseItemId,
+  responseIncompleteReason,
+  responseUsageFromOpenAIUsage,
+  type ResponseFunctionToolCall,
+  type ResponseObject,
+  type ResponseOutputMessage,
+  type ResponseOutputText,
+  type ResponseReasoningItem,
+} from './responses-format';
+
+export interface ResponseStreamEvent {
+  type: string;
+  sequence_number: number;
+  [key: string]: unknown;
+}
+
+interface ToolCallState {
+  outputIndex: number;
+  item: ResponseFunctionToolCall;
+}
+
+export interface ResponseStreamState {
+  id: string;
+  model: string;
+  requestBody: Record<string, unknown>;
+  createdAt: number;
+  sequenceNumber: number;
+  nextOutputIndex: number;
+  textItem?: { outputIndex: number; item: ResponseOutputMessage; text: string };
+  reasoningItem?: { outputIndex: number; item: ResponseReasoningItem; text: string };
+  toolCalls: Map<number, ToolCallState>;
+  usage?: OpenAIUsage;
+  finishReason?: string;
+  serviceTier?: ResponseObject['service_tier'];
+}
+
+function event(state: ResponseStreamState, value: Record<string, unknown> & { type: string }): ResponseStreamEvent {
+  return { ...value, sequence_number: state.sequenceNumber++ };
+}
+
+export function createResponseStreamState(
+  id: string,
+  model: string,
+  requestBody: Record<string, unknown>,
+): ResponseStreamState {
+  return {
+    id,
+    model,
+    requestBody,
+    createdAt: Math.floor(Date.now() / 1000),
+    sequenceNumber: 0,
+    nextOutputIndex: 0,
+    toolCalls: new Map(),
+  };
+}
+
+function responseSnapshot(state: ResponseStreamState, status: ResponseObject['status']): ResponseObject {
+  const content = state.textItem?.text ?? '';
+  const reasoningText = state.reasoningItem?.text;
+  const toolCalls = [...state.toolCalls.values()].map(({ item }) => ({
+    id: item.call_id,
+    type: 'function' as const,
+    function: { name: item.name, arguments: item.arguments },
+  }));
+  const response = chatResultToResponse({
+    id: state.id,
+    model: state.model,
+    content,
+    reasoningText,
+    usage: state.usage,
+    toolCalls,
+    finishReason: state.finishReason,
+    serviceTier: state.serviceTier,
+    requestBody: state.requestBody,
+    status,
+  });
+
+  // Preserve the stable item IDs and the provider emission order clients saw in earlier events.
+  const indexedOutput: Array<{ index: number; item: ResponseObject['output'][number] }> = [];
+  if (state.reasoningItem) {
+    indexedOutput.push({
+      index: state.reasoningItem.outputIndex,
+      item: {
+        ...state.reasoningItem.item,
+        status: status === 'in_progress' ? 'in_progress' : status === 'failed' ? 'incomplete' : 'completed',
+      },
+    });
+  }
+  if (state.textItem) {
+    indexedOutput.push({
+      index: state.textItem.outputIndex,
+      item: {
+        ...state.textItem.item,
+        status:
+          status === 'in_progress'
+            ? 'in_progress'
+            : status === 'failed' || responseIncompleteReason(state.finishReason)
+              ? 'incomplete'
+              : 'completed',
+        content: state.textItem.text ? [{ type: 'output_text', text: state.textItem.text, annotations: [] }] : [],
+      },
+    });
+  }
+  for (const { item, outputIndex } of state.toolCalls.values()) {
+    indexedOutput.push({
+      index: outputIndex,
+      item: {
+        ...item,
+        status: status === 'in_progress' ? 'in_progress' : status === 'failed' ? 'incomplete' : 'completed',
+      },
+    });
+  }
+  const output = indexedOutput.sort((left, right) => left.index - right.index).map(({ item }) => item);
+  response.created_at = state.createdAt;
+  response.output = output;
+  response.output_text = content;
+  response.usage = responseUsageFromOpenAIUsage(state.usage);
+  return response;
+}
+
+export function createResponseStartEvents(state: ResponseStreamState): ResponseStreamEvent[] {
+  return [
+    event(state, { type: 'response.created', response: responseSnapshot(state, 'in_progress') }),
+    event(state, { type: 'response.in_progress', response: responseSnapshot(state, 'in_progress') }),
+  ];
+}
+
+function ensureTextItem(state: ResponseStreamState): ResponseStreamEvent[] {
+  if (state.textItem) return [];
+  const outputIndex = state.nextOutputIndex++;
+  const item = createResponseOutputMessage('', 'in_progress', generateResponseItemId('msg'));
+  state.textItem = { outputIndex, item, text: '' };
+  const part: ResponseOutputText = { type: 'output_text', text: '', annotations: [] };
+  return [
+    event(state, { type: 'response.output_item.added', output_index: outputIndex, item }),
+    event(state, {
+      type: 'response.content_part.added',
+      item_id: item.id,
+      output_index: outputIndex,
+      content_index: 0,
+      part,
+    }),
+  ];
+}
+
+function ensureReasoningItem(state: ResponseStreamState): ResponseStreamEvent[] {
+  if (state.reasoningItem) return [];
+  const outputIndex = state.nextOutputIndex++;
+  const item = createResponseReasoningItem('');
+  item.status = 'in_progress';
+  state.reasoningItem = { outputIndex, item, text: '' };
+  return [
+    event(state, { type: 'response.output_item.added', output_index: outputIndex, item }),
+    event(state, {
+      type: 'response.content_part.added',
+      item_id: item.id,
+      output_index: outputIndex,
+      content_index: 0,
+      part: { type: 'reasoning_text', text: '' },
+    }),
+  ];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function appendToolCallChunks(state: ResponseStreamState, value: unknown): ResponseStreamEvent[] {
+  if (!Array.isArray(value)) return [];
+  const events: ResponseStreamEvent[] = [];
+  for (const [fallbackIndex, raw] of value.entries()) {
+    if (!isRecord(raw)) continue;
+    const index = typeof raw.index === 'number' ? raw.index : fallbackIndex;
+    const functionValue = isRecord(raw.function) ? raw.function : undefined;
+    const id = typeof raw.id === 'string' ? raw.id : undefined;
+    const name =
+      typeof raw.name === 'string'
+        ? raw.name
+        : typeof functionValue?.name === 'string'
+          ? functionValue.name
+          : undefined;
+    const argumentsDelta =
+      typeof raw.args === 'string'
+        ? raw.args
+        : typeof functionValue?.arguments === 'string'
+          ? functionValue.arguments
+          : raw.args === undefined
+            ? ''
+            : JSON.stringify(raw.args);
+
+    let call = state.toolCalls.get(index);
+    if (!call) {
+      const callId = id ?? generateResponseItemId('fc');
+      const item: ResponseFunctionToolCall = {
+        id: generateResponseItemId('fc'),
+        type: 'function_call',
+        status: 'in_progress',
+        call_id: callId,
+        name: name ?? '',
+        arguments: '',
+      };
+      call = { outputIndex: state.nextOutputIndex++, item };
+      state.toolCalls.set(index, call);
+      events.push(event(state, { type: 'response.output_item.added', output_index: call.outputIndex, item }));
+    }
+    if (name) call.item.name = name;
+    // Provider chunks may carry the real call id only in a later delta — keep it in sync so
+    // tool results submitted against the streamed id match the stored item.
+    if (id) call.item.call_id = id;
+    if (argumentsDelta) {
+      call.item.arguments += argumentsDelta;
+      events.push(
+        event(state, {
+          type: 'response.function_call_arguments.delta',
+          item_id: call.item.id,
+          output_index: call.outputIndex,
+          delta: argumentsDelta,
+        }),
+      );
+    }
+  }
+  return events;
+}
+
+export function appendResponseStreamChunk(state: ResponseStreamState, chunk: unknown): ResponseStreamEvent[] {
+  if (!isRecord(chunk)) return [];
+  const events: ResponseStreamEvent[] = [];
+  const reasoningDelta = extractReasoningText(chunk);
+  if (reasoningDelta) {
+    events.push(...ensureReasoningItem(state));
+    const reasoning = state.reasoningItem as NonNullable<ResponseStreamState['reasoningItem']>;
+    reasoning.text += reasoningDelta;
+    reasoning.item.content = [{ type: 'reasoning_text', text: reasoning.text }];
+    events.push(
+      event(state, {
+        type: 'response.reasoning_text.delta',
+        item_id: reasoning.item.id,
+        output_index: reasoning.outputIndex,
+        content_index: 0,
+        delta: reasoningDelta,
+      }),
+    );
+  }
+
+  const content = extractResponseOutputText(chunk);
+  if (content) {
+    events.push(...ensureTextItem(state));
+    const text = state.textItem as NonNullable<ResponseStreamState['textItem']>;
+    text.text += content;
+    text.item.content = [{ type: 'output_text', text: text.text, annotations: [] }];
+    events.push(
+      event(state, {
+        type: 'response.output_text.delta',
+        item_id: text.item.id,
+        output_index: text.outputIndex,
+        content_index: 0,
+        delta: content,
+        logprobs: [],
+      }),
+    );
+  }
+
+  events.push(...appendToolCallChunks(state, chunk.tool_call_chunks));
+  const finishReason = [chunk.response_metadata, chunk.additional_kwargs]
+    .filter(isRecord)
+    .map((metadata) => metadata.finish_reason)
+    .find((candidate): candidate is string => typeof candidate === 'string' && candidate.length > 0);
+  const incompleteReason = extractResponseIncompleteReason(chunk);
+  if (finishReason || incompleteReason) state.finishReason = finishReason ?? incompleteReason;
+  state.serviceTier = state.serviceTier ?? extractResponseServiceTier(chunk);
+  return events;
+}
+
+export function setResponseStreamUsage(state: ResponseStreamState, usage: OpenAIUsage | undefined): void {
+  if (usage) state.usage = usage;
+}
+
+export function finalizeResponseStream(state: ResponseStreamState): ResponseStreamEvent[] {
+  const events: ResponseStreamEvent[] = [];
+  const incompleteReason = responseIncompleteReason(state.finishReason);
+  if (state.reasoningItem) {
+    const { item, outputIndex, text } = state.reasoningItem;
+    item.status = 'completed';
+    events.push(
+      event(state, {
+        type: 'response.reasoning_text.done',
+        item_id: item.id,
+        output_index: outputIndex,
+        content_index: 0,
+        text,
+      }),
+      event(state, {
+        type: 'response.content_part.done',
+        item_id: item.id,
+        output_index: outputIndex,
+        content_index: 0,
+        part: { type: 'reasoning_text', text },
+      }),
+      event(state, { type: 'response.output_item.done', output_index: outputIndex, item }),
+    );
+  }
+  if (state.textItem) {
+    const { item, outputIndex, text } = state.textItem;
+    item.status = incompleteReason ? 'incomplete' : 'completed';
+    const part: ResponseOutputText = { type: 'output_text', text, annotations: [] };
+    item.content = [part];
+    events.push(
+      event(state, {
+        type: 'response.output_text.done',
+        item_id: item.id,
+        output_index: outputIndex,
+        content_index: 0,
+        text,
+        logprobs: [],
+      }),
+      event(state, {
+        type: 'response.content_part.done',
+        item_id: item.id,
+        output_index: outputIndex,
+        content_index: 0,
+        part,
+      }),
+      event(state, { type: 'response.output_item.done', output_index: outputIndex, item }),
+    );
+  }
+  for (const { item, outputIndex } of state.toolCalls.values()) {
+    item.status = 'completed';
+    events.push(
+      event(state, {
+        type: 'response.function_call_arguments.done',
+        item_id: item.id,
+        output_index: outputIndex,
+        name: item.name,
+        arguments: item.arguments,
+      }),
+      event(state, { type: 'response.output_item.done', output_index: outputIndex, item }),
+    );
+  }
+  const response = responseSnapshot(state, incompleteReason ? 'incomplete' : 'completed');
+  events.push(
+    event(state, { type: response.status === 'incomplete' ? 'response.incomplete' : 'response.completed', response }),
+  );
+  return events;
+}
+
+export function createResponseErrorEvent(
+  state: ResponseStreamState,
+  error: { message: string; code?: string },
+): ResponseStreamEvent {
+  return event(state, {
+    type: 'error',
+    code: error.code ?? 'server_error',
+    message: error.message,
+    param: null,
+  });
+}
+
+export function createResponseFailedEvent(
+  state: ResponseStreamState,
+  error: { message: string; code?: string },
+): ResponseStreamEvent {
+  const response = responseSnapshot(state, 'failed');
+  response.error = { code: error.code ?? 'server_error', message: error.message };
+  response.completed_at = null;
+  return event(state, { type: 'response.failed', response });
+}

package/src/server/utils/virtual-models.ts

@@ -0,0 +1,320 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Context } from '@nocobase/actions';
+import type { Model } from '@nocobase/database';
+import { toOpenAIError } from './openai-format';
+import { resolveModelReference } from './resolve-service';
+import { AiApiAccessScope, isModelAllowed, isServiceAllowed, resolveUserAccessScope } from './user-permissions';
+import { getAiApiConfig } from './request-cache';
+
+/**
+ * Virtual-model routing ("auto" and admin-defined aliases).
+ *
+ * A virtual alias resolves to a concrete `service/modelId` purely from the
+ * request's structural shape — never from prompt semantics (that is the
+ * deliberately deferred LLM-classifier path). The resolver walks an ordered
+ * bucket of candidates and picks the FIRST model the caller is permitted to
+ * use; when none is usable it falls back to the configured `fallbackModel`.
+ *
+ * Security invariant: a candidate is only returned when it passes the caller's
+ * usage-group scope (isServiceAllowed + isModelAllowed), so an alias can never
+ * widen access beyond what the user could call directly.
+ */
+
+export interface VirtualModel {
+  name: string;
+  mode: VirtualModelMode;
+  fallbackModel: string;
+  visionModels?: string[];
+  toolModels?: string[];
+  reasoningModels?: string[];
+  cheapModels?: string[];
+  generalModels?: string[];
+  enabled?: boolean;
+}
+
+export type VirtualModelMode = 'chat' | 'embedding';
+
+export interface VirtualResolution {
+  status: 'resolved';
+  /** The alias the client asked for, e.g. "auto". */
+  virtualModel: string;
+  /** Why this bucket was chosen — recorded for audit. */
+  reason: 'vision' | 'tools' | 'structured_output' | 'reasoning' | 'cheap' | 'general' | 'fallback';
+  /** The resolved concrete service + modelId, ready for the existing pipeline. */
+  resolved: { service: Model; modelId: string };
+}
+
+export interface UnavailableVirtualModel {
+  status: 'unavailable';
+  virtualModel: string;
+  reason: 'mode_mismatch' | 'no_permitted_model' | 'permission_check_failed';
+  configuredMode: VirtualModelMode;
+  requestedMode: VirtualModelMode;
+}
+
+export type VirtualModelLookup = VirtualResolution | UnavailableVirtualModel;
+
+interface RequestSignals {
+  hasImage: boolean;
+  hasTools: boolean;
+  wantsStructuredOutput: boolean;
+  wantsReasoning: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function contentHasImage(content: unknown): boolean {
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => {
+    if (!isRecord(block)) return false;
+    if (block.type === 'image_url') return true;
+    if (block.type === 'file') return true;
+    if (block.type === 'file_url') return true;
+    return false;
+  });
+}
+
+/** Extract the structural signals that decide the routing bucket. */
+export function detectRequestSignals(body: Record<string, unknown>): RequestSignals {
+  const messages = Array.isArray(body.messages) ? body.messages : [];
+  const hasImage = messages.some((msg) => isRecord(msg) && contentHasImage(msg.content));
+  const hasTools = Array.isArray(body.tools) && body.tools.length > 0;
+  const rf = body.response_format;
+  const wantsStructuredOutput = isRecord(rf) && (rf.type === 'json_object' || rf.type === 'json_schema');
+  const wantsReasoning =
+    (Object.hasOwn(body, 'reasoning') && body.reasoning !== undefined && body.reasoning !== null) ||
+    (Object.hasOwn(body, 'reasoning_effort') && body.reasoning_effort !== undefined && body.reasoning_effort !== null);
+  return { hasImage, hasTools, wantsStructuredOutput, wantsReasoning };
+}
+
+function valueOf<T>(model: unknown, key: string): T | undefined {
+  if (!model) return undefined;
+  if (typeof (model as { get?: unknown }).get === 'function') {
+    return (model as { get: (k: string) => unknown }).get(key) as T | undefined;
+  }
+  return (model as Record<string, unknown>)[key] as T | undefined;
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string' && v.length > 0) : [];
+}
+
+function toVirtualModel(row: unknown, fallbackName = ''): VirtualModel {
+  return {
+    name: String(valueOf(row, 'name') ?? fallbackName),
+    mode: valueOf<string>(row, 'mode') === 'embedding' ? 'embedding' : 'chat',
+    fallbackModel: String(valueOf(row, 'fallbackModel') ?? ''),
+    visionModels: stringList(valueOf(row, 'visionModels')),
+    toolModels: stringList(valueOf(row, 'toolModels')),
+    reasoningModels: stringList(valueOf(row, 'reasoningModels')),
+    cheapModels: stringList(valueOf(row, 'cheapModels')),
+    generalModels: stringList(valueOf(row, 'generalModels')),
+    enabled: valueOf<boolean>(row, 'enabled'),
+  };
+}
+
+async function loadVirtualModel(ctx: Context, name: string): Promise<VirtualModel | null> {
+  const row = await ctx.db.getRepository('aiApiVirtualModels').findOne({ filter: { name, enabled: true } });
+  return row ? toVirtualModel(row, name) : null;
+}
+
+/**
+ * Derive an ordered bucket from aiApiModelMetadata when the admin left the
+ * explicit list empty: enabled rows matching the capability, ascending sortOrder.
+ */
+async function deriveBucket(ctx: Context, capability: 'vision' | 'tool' | 'reasoning' | 'general'): Promise<string[]> {
+  const repo = ctx.db.getRepository('aiApiModelMetadata');
+  const filter: Record<string, unknown> = { enabled: true };
+  if (capability === 'vision') filter.supportsVision = true;
+  else if (capability === 'tool') filter.supportsToolCalling = true;
+  else if (capability === 'reasoning') filter.reasoningTier = 'reasoning';
+  // The general bucket is a catch-all for requests with no capability signal. It intentionally
+  // includes every enabled model (any reasoningTier) so a general request can be served by
+  // whatever the admin ranked first via sortOrder.
+  else filter.reasoningTier = { $in: ['general', 'cheap', 'reasoning'] };
+
+  const rows = await repo.find({ filter, sort: 'sortOrder', pageSize: 200 });
+  const list = (rows as unknown[]).map((row) => {
+    const service = valueOf<string>(row, 'llmService');
+    const model = valueOf<string>(row, 'model');
+    return service && model ? `${service}/${model}` : '';
+  });
+  return list.filter(Boolean);
+}
+
+async function bucketFor(
+  ctx: Context,
+  vm: VirtualModel,
+  signals: RequestSignals,
+): Promise<{ reason: VirtualResolution['reason']; candidates: string[] }> {
+  const explicit = (list: string[] | undefined) => (list && list.length ? list : null);
+  if (signals.hasImage) {
+    return { reason: 'vision', candidates: explicit(vm.visionModels) ?? (await deriveBucket(ctx, 'vision')) };
+  }
+  if (signals.hasTools) {
+    return { reason: 'tools', candidates: explicit(vm.toolModels) ?? (await deriveBucket(ctx, 'tool')) };
+  }
+  if (signals.wantsReasoning) {
+    return { reason: 'reasoning', candidates: explicit(vm.reasoningModels) ?? (await deriveBucket(ctx, 'reasoning')) };
+  }
+  if (signals.wantsStructuredOutput) {
+    return {
+      reason: 'structured_output',
+      candidates: explicit(vm.generalModels) ?? (await deriveBucket(ctx, 'general')),
+    };
+  }
+  // Default to the cheapest bucket the admin configured; fall back to general.
+  const cheap = explicit(vm.cheapModels);
+  if (cheap) return { reason: 'cheap', candidates: cheap };
+  return { reason: 'general', candidates: explicit(vm.generalModels) ?? (await deriveBucket(ctx, 'general')) };
+}
+
+/**
+ * Resolve a virtual alias to a concrete model for the current caller.
+ * Returns null when the alias does not exist or is disabled (caller then falls
+ * through to the normal model resolution).
+ */
+export async function resolveVirtualModel(
+  ctx: Context,
+  alias: string,
+  body: Record<string, unknown>,
+  requestedMode: VirtualModelMode,
+): Promise<VirtualModelLookup | null> {
+  const vm = await loadVirtualModel(ctx, alias);
+  if (!vm) return null;
+  if (vm.mode !== requestedMode) {
+    return {
+      status: 'unavailable',
+      virtualModel: alias,
+      reason: 'mode_mismatch',
+      configuredMode: vm.mode,
+      requestedMode,
+    };
+  }
+
+  const config = await getAiApiConfig(ctx);
+  const globalServices = valueOf<unknown>(config, 'enabledLlmServices') ?? [];
+  const scope = await resolveUserAccessScope(ctx);
+  if (scope.lookupFailed) {
+    return {
+      status: 'unavailable',
+      virtualModel: alias,
+      reason: 'permission_check_failed',
+      configuredMode: vm.mode,
+      requestedMode,
+    };
+  }
+  const usable = (service: Model, modelId: string) =>
+    valueOf<boolean>(service, 'enabled') !== false &&
+    isServiceAllowed(scope, globalServices, {
+      name: valueOf<string>(service, 'name'),
+      title: valueOf<string>(service, 'title'),
+    }) &&
+    isModelAllowed(scope, `${valueOf<string>(service, 'name')}/${modelId}`);
+
+  // Embedding requests have none of the chat capability signals below. Their
+  // alias is therefore a stable endpoint-family name for the configured fallback.
+  if (requestedMode === 'embedding') {
+    const fallback = await resolveModelReference(ctx, vm.fallbackModel);
+    if (fallback && usable(fallback.service, fallback.modelId)) {
+      return { status: 'resolved', virtualModel: alias, reason: 'fallback', resolved: fallback };
+    }
+    return {
+      status: 'unavailable',
+      virtualModel: alias,
+      reason: 'no_permitted_model',
+      configuredMode: vm.mode,
+      requestedMode,
+    };
+  }
+  const signals = detectRequestSignals(body);
+  const { reason, candidates } = await bucketFor(ctx, vm, signals);
+
+  for (const candidate of candidates) {
+    const resolved = await resolveModelReference(ctx, candidate);
+    if (resolved && usable(resolved.service, resolved.modelId)) {
+      return { status: 'resolved', virtualModel: alias, reason, resolved };
+    }
+  }
+
+  const fallback = await resolveModelReference(ctx, vm.fallbackModel);
+  if (fallback && usable(fallback.service, fallback.modelId)) {
+    return { status: 'resolved', virtualModel: alias, reason: 'fallback', resolved: fallback };
+  }
+  return {
+    status: 'unavailable',
+    virtualModel: alias,
+    reason: 'no_permitted_model',
+    configuredMode: vm.mode,
+    requestedMode,
+  };
+}
+
+/** Return aliases whose required fallback model is accessible to the caller. */
+export async function listAccessibleVirtualModels(
+  ctx: Context,
+  scope: AiApiAccessScope,
+  globalServices: unknown,
+): Promise<VirtualModel[]> {
+  const rows = await ctx.db.getRepository('aiApiVirtualModels').find({ filter: { enabled: true } });
+  const accessible: VirtualModel[] = [];
+
+  for (const row of rows as unknown[]) {
+    const vm = toVirtualModel(row);
+    if (!vm.fallbackModel) continue;
+    const resolved = await resolveModelReference(ctx, vm.fallbackModel);
+    if (!resolved || valueOf<boolean>(resolved.service, 'enabled') === false) continue;
+    const service = {
+      name: valueOf<string>(resolved.service, 'name'),
+      title: valueOf<string>(resolved.service, 'title'),
+    };
+    if (
+      isServiceAllowed(scope, globalServices, service) &&
+      isModelAllowed(scope, `${service.name}/${resolved.modelId}`)
+    ) {
+      accessible.push(vm);
+    }
+  }
+
+  return accessible;
+}
+
+export function respondVirtualModelUnavailable(ctx: Context, result: UnavailableVirtualModel): void {
+  if (result.reason === 'permission_check_failed') {
+    ctx.status = 503;
+    ctx.body = toOpenAIError(
+      503,
+      'Unable to verify LLM permissions for this user. Please retry shortly.',
+      'service_unavailable',
+      'permission_check_failed',
+    );
+    return;
+  }
+  if (result.reason === 'mode_mismatch') {
+    ctx.status = 404;
+    ctx.body = toOpenAIError(
+      404,
+      `Virtual model '${result.virtualModel}' serves ${result.configuredMode} requests and cannot be used for ${result.requestedMode} requests.`,
+      'invalid_request_error',
+      'model_not_found',
+    );
+    return;
+  }
+  ctx.status = 403;
+  ctx.body = toOpenAIError(
+    403,
+    `No model behind virtual alias '${result.virtualModel}' is available to this user. Use GET /v1/models to see available models.`,
+    'permission_denied',
+    'model_not_available',
+  );
+}