Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
8.3 KB
Raw Blame
/**
 * Generic OpenAI-compatible LLM provider.
 *
 * Many providers (z.ai / ZhipuAI, Alibaba Cloud Model Studio / Bailian, and the
 * R6 additions openrouter/gemini/deepseek/groq/together/fireworks/mistral/xai/
 * cerebras/deepinfra/perplexity/moonshot/nebius/novita) expose an
 * OpenAI-compatible chat/completions API and differ only in their `baseURL`,
 * default model, and the string reported by `getProviderType()`. Rather than a
 * bespoke subclass per provider, this single parameterized class captures that
 * shape — adding a new OpenAI-compatible provider is now a single data entry in
 * `PROVIDERS` (`registryCore.ts`).
 *
 * PORTABILITY (R6 param audit): the base OpenAIProvider already sends only the
 * portable core — model + messages + tools + tool_choice + max_tokens +
 * temperature. It never emits the params the stricter third parties reject
 * (Groq: n>1 / logprobs / logit_bias; Cerebras: frequency_penalty /
 * presence_penalty), so nothing there needs trimming. The two remaining params
 * still need normalizing for the third-party arm:
 *   - temperature: the OpenAI-compatible range is [0,2], but Moonshot restricts
 *     it to [0,1]. We clamp to the provider's real ceiling ({@link
 *     temperatureCeiling}) — capping only what the provider would actually 400
 *     on, rather than silently degrading a valid [1,2] value on providers that
 *     accept it. (DeepSeek's reasoner ignores sampling params rather than
 *     erroring, so no clamp is needed to keep it happy.)
 *   - tool_choice: Moonshot rejects 'required', so for MOONSHOT ONLY we downgrade
 *     it to 'auto' (the model still sees the tools; we just don't force a call).
 *     Every other compat provider honors 'required' and passes it through — the
 *     downgrade is provider-gated so a forced-tool-call guarantee isn't silently
 *     weakened on providers that support it (incl. the pre-existing zai/bailian).
 * Native OpenAI (the base class) and Azure keep full fidelity — only this shared
 * third-party arm is conservative.
 */
import OpenAI from 'openai'
import { LlmErrorCode } from '../core/errors'
import type {
  CompletionResponse,
  ChatMessage as CoreChatMessage,
  ToolCompletionResponse,
  ToolDefinition,
} from '../core/types'
import type { ImageTransportOperation } from './imageInput'
import { OpenAIProvider } from './openai'
import type { LlmProvider } from './registryCore'
import type { ClassifiedError } from './types'

/**
 * Clamp/normalize call options to the portable subset every OpenAI-compatible
 * third party accepts (see class doc). `temperatureCeiling` is the provider's
 * upper bound (2 for the OpenAI-compatible default, 1 for Moonshot). Preserves
 * all other fields (max_tokens, signal, …) untouched.
 */
function toPortableOptions<T extends { temperature?: number; tool_choice?: string }>(
  options: T | undefined,
  temperatureCeiling: number,
  downgradeRequiredToolChoice: boolean
): T | undefined {
  if (!options) return options
  const next = { ...options }
  if (typeof next.temperature === 'number') {
    next.temperature = Math.min(temperatureCeiling, Math.max(0, next.temperature))
  }
  // Only providers that actually 400 on tool_choice:'required' get the downgrade
  // — otherwise we'd silently weaken a forced-tool-call guarantee (reachable via
  // a workflow step's toolChoice:'required') on the providers that honor it.
  if (downgradeRequiredToolChoice && next.tool_choice === 'required') {
    next.tool_choice = 'auto'
  }
  return next
}

/**
 * Provider-native error codes that mean "this model does not work for you right
 * now" (retired or inaccessible — ambiguous by design, spec 02 §3.1). z.ai uses
 * numeric codes; Bailian native slugs. Both compat-mode APIs surface them in
 * `error.code`.
 */
const MODEL_NOT_AVAILABLE_CODES = new Set(['1211', '1220', 'ModelNotFound', 'Model.AccessDenied'])

/** Provider-native billing/quota codes (z.ai 1113, Bailian Arrearage). */
const BILLING_CODES = new Set(['1113', 'Arrearage'])

export class OpenAICompatibleProvider extends OpenAIProvider {
  /** Compatibility and a configured URL do not establish an official API contract. */
  override getVisualDeliveryLimits(_operation: ImageTransportOperation): null {
    return null
  }
  /** Provider temperature upper bound — 1 for Moonshot, else the [0,2] default. */
  private readonly temperatureCeiling: number
  /**
   * Whether this provider rejects `tool_choice: 'required'`. Only Moonshot does;
   * every other OpenAI-compatible provider honors it, so the downgrade is
   * provider-gated (mirrors {@link temperatureCeiling}).
   */
  private readonly downgradesRequiredToolChoice: boolean

  constructor(
    // `id` is a provider id from the registry (a `LlmProvider`); it arrives typed
    // as `string` because `CoreProviderDescriptor.id` is `string`. Construction
    // only ever happens via `makeProvider` from registry descriptors, so the cast
    // in getProviderType() is sound.
    private cfg: { id: string; baseURL: string; defaultModel: string },
    apiKey: string,
    model?: string
  ) {
    // Thread cfg.defaultModel as the fallback. Without it, model=undefined would
    // fall through to OpenAIProvider's own default ('gpt-5.4-mini'), and this
    // provider would request a non-existent model against its baseURL.
    super(new OpenAI({ apiKey, baseURL: cfg.baseURL }), model ?? cfg.defaultModel)
    this.temperatureCeiling = cfg.id === 'moonshot' ? 1 : 2
    this.downgradesRequiredToolChoice = cfg.id === 'moonshot'
  }

  override getProviderType(): LlmProvider {
    return this.cfg.id as LlmProvider
  }

  /**
   * The OpenAI-compatible arm inherits the shared HTTP classifier from the base
   * class, but several third parties encode model-availability and billing in a
   * PROVIDER-NATIVE `error.code` that the raw HTTP status hides — most notably
   * billing arriving inside a 429 (which the base class would treat as a
   * retryable rate-limit and loop on). Intercept those codes first, then fall
   * through to the shared HTTP/unknown classification. (spec 02 §3.1)
   *
   * Recognised codes (open sets — unmatched codes fall through):
   *   - z.ai:    1211 / 1220 → model not available; 1113 → billing/quota.
   *   - Bailian: ModelNotFound / Model.AccessDenied → model not available;
   *              Arrearage → billing/quota.
   */
  override classifyError(err: unknown): ClassifiedError {
    const rawCode =
      (err as { error?: { code?: unknown }; code?: unknown })?.error?.code ??
      (err as { code?: unknown })?.code
    const providerCode = rawCode == null ? undefined : String(rawCode)
    if (providerCode) {
      const message =
        (err as { error?: { message?: string }; message?: string })?.error?.message ??
        (err as { message?: string })?.message ??
        'Unknown LLM error'
      const httpStatus =
        typeof (err as { status?: unknown })?.status === 'number'
          ? (err as { status: number }).status
          : undefined
      const mapped = MODEL_NOT_AVAILABLE_CODES.has(providerCode)
        ? LlmErrorCode.ModelNotAvailable
        : BILLING_CODES.has(providerCode)
          ? LlmErrorCode.InsufficientQuota
          : null
      if (mapped) return { code: mapped, retryable: false, message, httpStatus, providerCode }
    }
    return super.classifyError(err)
  }

  // Third-party OpenAI-compatible APIs use the portable legacy field. The
  // native OpenAI translation is intentionally not inherited for this arm.
  protected override usesMaxCompletionTokens(): boolean {
    return false
  }

  protected override supportsReasoningContent(): boolean {
    return this.cfg.id === 'zai'
  }

  override completeSingleTurn(
    messages: CoreChatMessage[],
    options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
  ): Promise<CompletionResponse> {
    return super.completeSingleTurn(
      messages,
      toPortableOptions(options, this.temperatureCeiling, this.downgradesRequiredToolChoice)
    )
  }

  override completeSingleTurnWithTools(
    messages: CoreChatMessage[],
    tools: ToolDefinition[],
    options?: {
      max_tokens?: number
      temperature?: number
      tool_choice?: string
      signal?: AbortSignal
      verifyImageInput?: boolean
    }
  ): Promise<ToolCompletionResponse> {
    return super.completeSingleTurnWithTools(
      messages,
      tools,
      toPortableOptions(options, this.temperatureCeiling, this.downgradesRequiredToolChoice)
    )
  }
}