@exvio/os-backend-core 0.4.0

package/src/ai/errors.ts

@@ -0,0 +1,114 @@
+import type { AIOperation, AIProviderName } from './types.ts'
+
+export type AIErrorCode =
+  | 'not_configured'
+  | 'missing_tenant'
+  | 'invalid_config'
+  | 'unknown_provider'
+  | 'unsupported_operation'
+  | 'invalid_request'
+  | 'authentication'
+  | 'permission_denied'
+  | 'rate_limited'
+  | 'timeout'
+  | 'aborted'
+  | 'network'
+  | 'endpoint_not_allowed'
+  | 'content_filtered'
+  | 'invalid_response'
+  | 'provider_error'
+
+export interface AIErrorOptions {
+  readonly code: AIErrorCode
+  readonly message: string
+  readonly provider?: AIProviderName
+  readonly model?: string
+  readonly operation?: AIOperation
+  readonly status?: number
+  readonly retryable?: boolean
+  /** Accepted for call-site compatibility but deliberately never retained. */
+  readonly cause?: unknown
+}
+
+/** A stable, secret-free error envelope shared by every provider. */
+export class AIError extends Error {
+  readonly code: AIErrorCode
+  readonly provider?: AIProviderName
+  readonly model?: string
+  readonly operation?: AIOperation
+  readonly status?: number
+  readonly retryable: boolean
+
+  constructor(options: AIErrorOptions) {
+    // Provider/network errors can contain Authorization headers, prompts, or
+    // response bodies. The public error envelope never keeps the raw cause.
+    super(options.message)
+    this.name = 'AIError'
+    this.code = options.code
+    this.provider = options.provider
+    this.model = options.model
+    this.operation = options.operation
+    this.status = options.status
+    this.retryable = options.retryable ?? false
+  }
+}
+
+export interface AIErrorContext {
+  readonly provider?: AIProviderName
+  readonly model?: string
+  readonly operation?: AIOperation
+}
+
+/** Map an HTTP status without retaining response bodies, headers, or credentials. */
+export function aiErrorFromHttpStatus(status: number, context: AIErrorContext = {}): AIError {
+  if (status === 401) {
+    return new AIError({ ...context, status, code: 'authentication', message: 'AI provider authentication failed' })
+  }
+  if (status === 403) {
+    return new AIError({ ...context, status, code: 'permission_denied', message: 'AI provider denied the request' })
+  }
+  if (status === 408 || status === 504) {
+    return new AIError({ ...context, status, code: 'timeout', message: 'AI provider request timed out', retryable: true })
+  }
+  if (status === 429) {
+    return new AIError({ ...context, status, code: 'rate_limited', message: 'AI provider rate limit exceeded', retryable: true })
+  }
+  if (status === 500 || status === 502 || status === 503 || status === 504) {
+    return new AIError({ ...context, status, code: 'provider_error', message: 'AI provider is temporarily unavailable', retryable: true })
+  }
+  return new AIError({ ...context, status, code: 'provider_error', message: 'AI provider rejected the request' })
+}
+
+export function unsupportedAIProviderOperation(
+  provider: AIProviderName,
+  operation: AIOperation,
+  model?: string,
+): AIError {
+  return new AIError({
+    code: 'unsupported_operation',
+    message: `AI provider "${provider}" does not support ${operation}`,
+    provider,
+    model,
+    operation,
+  })
+}
+
+export function toAIError(error: unknown, context: AIErrorContext = {}): AIError {
+  if (error instanceof AIError) return error
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    return new AIError({ ...context, code: 'aborted', message: 'AI request was aborted', cause: error })
+  }
+  if (error instanceof Error && error.name === 'AbortError') {
+    return new AIError({ ...context, code: 'aborted', message: 'AI request was aborted', cause: error })
+  }
+  return new AIError({
+    ...context,
+    code: 'provider_error',
+    message: 'AI provider request failed',
+    cause: error,
+  })
+}
+
+export function isRetryableAIError(error: unknown): error is AIError {
+  return error instanceof AIError && error.retryable
+}

package/src/ai/index.ts

@@ -0,0 +1,27 @@
+export { createAIClient } from './client.ts'
+export {
+  createAIProviderRegistry,
+  withAIProvider,
+  type AIProviderRegistry,
+} from './registry.ts'
+export {
+  createAIObjectPrompt,
+  parseAIConfig,
+  parseAIJSON,
+  parseAIObject,
+  validateAIObject,
+} from './schema.ts'
+export {
+  AIError,
+  aiErrorFromHttpStatus,
+  isRetryableAIError,
+  toAIError,
+  unsupportedAIProviderOperation,
+} from './errors.ts'
+export type * from './errors.ts'
+export type * from './types.ts'
+export * from './pricing.ts'
+export {
+  assertActiveAIModelId,
+  replacementForRetiredAIModelId,
+} from './model-policy.ts'

package/src/ai/model-policy.ts

@@ -0,0 +1,27 @@
+import { AIError } from './errors.ts'
+
+const RETIRED_MODEL_REPLACEMENTS: Readonly<Record<string, string>> = Object.freeze({
+  'deepseek-chat': 'deepseek-v4-flash',
+  'deepseek-reasoner': 'deepseek-v4-flash',
+  'gemini-3.1-flash-lite-preview': 'gemini-3.1-flash-lite',
+})
+
+/**
+ * Return the canonical replacement used by forward data migrations.
+ * Runtime requests must never be rewritten silently; call
+ * `assertActiveAIModelId` at configuration boundaries instead.
+ */
+export function replacementForRetiredAIModelId(model: string): string | undefined {
+  return RETIRED_MODEL_REPLACEMENTS[model.trim()]
+}
+
+/** Reject model identifiers that built-in providers no longer serve. */
+export function assertActiveAIModelId(model: string): void {
+  const normalized = model.trim()
+  if (replacementForRetiredAIModelId(normalized) === undefined) return
+  throw new AIError({
+    code: 'invalid_config',
+    message: 'AI model identifier is retired',
+    model: normalized,
+  })
+}

package/src/ai/pricing.ts

@@ -0,0 +1,158 @@
+import type { AIModel, AIUsage } from './types.ts'
+
+export interface AIPriceRate {
+  /** USD per one million uncached input tokens. */
+  readonly inputPerMillionUsd: number
+  /** USD per one million output tokens. */
+  readonly outputPerMillionUsd: number
+  /** Falls back to inputPerMillionUsd when the provider has no cache rate. */
+  readonly cachedInputPerMillionUsd?: number
+  /** Falls back to inputPerMillionUsd when the provider reports cache misses. */
+  readonly cacheMissInputPerMillionUsd?: number
+}
+
+export interface AIPriceEntry {
+  readonly provider: string
+  readonly model: string
+  readonly version: string
+  readonly effectiveFrom: string
+  readonly effectiveTo?: string
+  readonly rate: AIPriceRate
+}
+
+export interface AIPriceCatalog {
+  resolve(model: AIModel, at?: Date): AIPriceEntry | null
+}
+
+export interface AICostResult {
+  readonly currency: 'USD'
+  readonly amount: string
+  readonly catalogVersion: string
+  readonly effectiveFrom: string
+}
+
+/**
+ * Builds an immutable, date-aware price catalogue. Rates deliberately come
+ * from the consumer/operations layer: provider prices change independently of
+ * this package and must be versioned instead of silently rewritten in code.
+ */
+export function createPriceCatalog(entries: readonly AIPriceEntry[]): AIPriceCatalog {
+  const snapshot = entries.map((entry) => {
+    assertRate(entry)
+    const from = parseDate(entry.effectiveFrom, 'effectiveFrom')
+    const to = entry.effectiveTo === undefined
+      ? Number.POSITIVE_INFINITY
+      : parseDate(entry.effectiveTo, 'effectiveTo')
+    if (to <= from) throw new TypeError('AI price effectiveTo must be after effectiveFrom')
+    return { entry: Object.freeze({ ...entry, rate: Object.freeze({ ...entry.rate }) }), from, to }
+  })
+
+  return Object.freeze({
+    resolve(model: AIModel, at = new Date()): AIPriceEntry | null {
+      const instant = at.getTime()
+      if (!Number.isFinite(instant)) throw new TypeError('AI price lookup date is invalid')
+      const matches = snapshot
+        .filter(({ entry, from, to }) => (
+          entry.provider === model.provider && entry.model === model.model && instant >= from && instant < to
+        ))
+        .sort((a, b) => b.from - a.from)
+      return matches[0]?.entry ?? null
+    },
+  })
+}
+
+/** Unknown models return null, never a misleading zero-cost value. */
+export function calculateCostUsd(
+  model: AIModel,
+  usage: AIUsage | null,
+  catalog: AIPriceCatalog,
+  at = new Date(),
+): AICostResult | null {
+  if (!usage) return null
+  assertUsage(usage)
+  const price = catalog.resolve(model, at)
+  if (!price) return null
+
+  const input = tokenCount(usage.inputTokens)
+  const output = tokenCount(usage.outputTokens)
+  const cached = Math.min(input, tokenCount(usage.cachedInputTokens))
+  const reportedMiss = usage.cacheMissInputTokens === undefined
+    ? input - cached
+    : Math.min(input - cached, tokenCount(usage.cacheMissInputTokens))
+  const unclassified = Math.max(0, input - cached - reportedMiss)
+
+  const rate = price.rate
+  const inputCost = (
+    cached * (rate.cachedInputPerMillionUsd ?? rate.inputPerMillionUsd)
+    + reportedMiss * (rate.cacheMissInputPerMillionUsd ?? rate.inputPerMillionUsd)
+    + unclassified * rate.inputPerMillionUsd
+  ) / 1_000_000
+  const outputCost = (output * rate.outputPerMillionUsd) / 1_000_000
+
+  return {
+    currency: 'USD',
+    amount: (inputCost + outputCost).toFixed(9),
+    catalogVersion: price.version,
+    effectiveFrom: price.effectiveFrom,
+  }
+}
+
+function tokenCount(value: number | undefined): number {
+  return Number.isSafeInteger(value) && (value ?? -1) >= 0 ? value! : 0
+}
+
+function assertRate(entry: AIPriceEntry): void {
+  if (!entry.provider || !entry.model || !entry.version) {
+    throw new TypeError('AI price entry requires provider, model, and version')
+  }
+  if (!isPlainRecord(entry.rate)) throw new TypeError('AI price rate must be an object')
+  assertRateValue(entry.rate.inputPerMillionUsd)
+  assertRateValue(entry.rate.outputPerMillionUsd)
+  if (entry.rate.cachedInputPerMillionUsd !== undefined) assertRateValue(entry.rate.cachedInputPerMillionUsd)
+  if (entry.rate.cacheMissInputPerMillionUsd !== undefined) assertRateValue(entry.rate.cacheMissInputPerMillionUsd)
+}
+
+function assertRateValue(value: unknown): asserts value is number {
+  if (!Number.isFinite(value) || (value as number) < 0) {
+    throw new TypeError('AI price rates must be finite and non-negative')
+  }
+}
+
+function assertUsage(usage: AIUsage): void {
+  for (const value of [usage.inputTokens, usage.outputTokens, usage.totalTokens]) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new TypeError('AI usage token counts must be non-negative safe integers')
+    }
+  }
+  for (const value of [
+    usage.cachedInputTokens,
+    usage.cacheMissInputTokens,
+    usage.reasoningTokens,
+  ]) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+      throw new TypeError('AI usage token counts must be non-negative safe integers')
+    }
+  }
+  const cached = usage.cachedInputTokens ?? 0
+  const missed = usage.cacheMissInputTokens ?? 0
+  if (
+    usage.totalTokens < usage.inputTokens + usage.outputTokens
+    || cached > usage.inputTokens
+    || missed > usage.inputTokens
+    || cached + missed > usage.inputTokens
+  ) {
+    throw new TypeError('AI cache token counts cannot exceed input tokens')
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function parseDate(value: string, field: string): number {
+  const parsed = Date.parse(value)
+  if (!Number.isFinite(parsed)) throw new TypeError(`AI price ${field} must be an ISO date`)
+  return parsed
+}

package/src/ai/providers/deepseek.ts

@@ -0,0 +1,61 @@
+import { AIError } from '../errors.ts'
+import type { AIProviderFactory, AIProviderFactoryContext } from '../types.ts'
+import { OpenAICompatibleProvider } from './openai-compatible.ts'
+
+/** Official DeepSeek chat-completions endpoint. */
+export const DEEPSEEK_DEFAULT_ENDPOINT = 'https://api.deepseek.com/chat/completions'
+
+/**
+ * Current non-legacy default for consumer configuration and migrations.
+ *
+ * Runtime requests still carry an explicit provider/model pair; the provider
+ * never infers a model from a prefix or silently replaces a requested model.
+ */
+export const DEEPSEEK_DEFAULT_MODEL = 'deepseek-v4-flash'
+
+function buildDeepSeekProvider(context: AIProviderFactoryContext): OpenAICompatibleProvider {
+  const apiKey = context.config.apiKey?.trim()
+  if (!apiKey) {
+    throw new AIError({
+      code: 'not_configured',
+      message: 'DeepSeek API key is not configured',
+      provider: context.name,
+    })
+  }
+
+  return new OpenAICompatibleProvider({
+    name: context.name,
+    apiKey,
+    endpoint: context.config.endpoint ?? context.config.baseUrl ?? DEEPSEEK_DEFAULT_ENDPOINT,
+    fetch: context.fetch,
+    // DeepSeek's public chat-completions endpoint does not accept image/file
+    // content. Keep it fail-closed and route multimodal lanes elsewhere.
+    capabilities: { content: false, object: false, embedding: false },
+    // V4 generation models otherwise default to reasoning mode, which can
+    // consume the output budget before returning visible content. Callers may
+    // explicitly opt back in with disableThinking:false.
+    disableThinkingByDefault: isDeepSeekV4,
+  })
+}
+
+Object.defineProperty(buildDeepSeekProvider, 'defaultEndpoint', {
+  value: DEEPSEEK_DEFAULT_ENDPOINT,
+  enumerable: true,
+  writable: false,
+  configurable: false,
+})
+export const deepseekProviderFactory: AIProviderFactory = Object.freeze(buildDeepSeekProvider)
+
+/** Convenient constructor for a registry entry. */
+export function createDeepSeekProvider(): AIProviderFactory {
+  return deepseekProviderFactory
+}
+
+/** Named consistently with other built-in provider factory constructors. */
+export function createDeepSeekProviderFactory(): AIProviderFactory {
+  return deepseekProviderFactory
+}
+
+function isDeepSeekV4(model: string): boolean {
+  return /^deepseek-v[4-9](?:[-_.]|$)/i.test(model)
+}