@sixb/core 0.1.5 → 0.1.7

package/src/models/language-model.ts

@@ -0,0 +1,143 @@
+import type { JsonObject, ReadonlyJsonObject } from "../json"
+import type { LanguageModelDefinitionCatalog, ModelDefinitionCatalog } from "./catalog"
+import type { LanguageModelDefinition } from "./definitions"
+import type { LanguageModelStreamEvent } from "./events"
+import type { ModelMessage } from "./messages"
+import type { ModelCostEstimator } from "./pricing"
+
+export const MODEL_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const
+
+export type ModelReasoningEffort = (typeof MODEL_REASONING_EFFORTS)[number]
+
+export const MODEL_REASONING_LEVELS = [
+  "provider-default",
+  "none",
+  ...MODEL_REASONING_EFFORTS,
+] as const
+
+export type ModelReasoningLevel = (typeof MODEL_REASONING_LEVELS)[number]
+
+/** Exact provider-native reasoning budget, expressed in tokens. */
+export interface ModelReasoningBudget extends ReadonlyJsonObject {
+  readonly budgetTokens: number
+}
+
+/** Provider-neutral reasoning preference accepted by every language-model runtime. */
+export type ModelReasoning = ModelReasoningLevel | ModelReasoningBudget
+
+export interface ModelReasoningBudgetCapabilities {
+  readonly min?: number
+  readonly max?: number
+}
+
+/** Controls exposed by one concrete model offering through one provider. */
+export interface ModelReasoningCapabilities {
+  readonly canDisable?: boolean
+  readonly efforts?: readonly ModelReasoningEffort[]
+  readonly budgetTokens?: ModelReasoningBudgetCapabilities
+}
+
+export interface ModelCapabilities {
+  readonly inputMediaTypes?: readonly string[] | "any"
+  /** `undefined` is unknown, `false` is unsupported, and an object describes supported controls. */
+  readonly reasoning?: false | ModelReasoningCapabilities
+  readonly localTools?: boolean
+  readonly parallelToolCalls?: boolean
+  readonly nativeStructuredOutput?: boolean
+  readonly providerExecutedTools?: boolean
+}
+
+export interface ModelToolSpecification {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: JsonObject
+}
+
+export interface ModelResponseFormat {
+  readonly type: "json"
+  readonly name: string
+  readonly description?: string
+  readonly schema: JsonObject
+}
+
+export interface LanguageModelRequest {
+  readonly callId: string
+  readonly messages: readonly ModelMessage[]
+  readonly tools: readonly ModelToolSpecification[]
+  readonly reasoning?: ModelReasoning
+  /** Per-call output ceiling; providers must not exceed a stricter configured model limit. */
+  readonly maxOutputTokens?: number
+  /** Disable automatic prompt caching without overriding explicit provider configuration. */
+  readonly caching?: "auto" | "off"
+  readonly responseFormat?: ModelResponseFormat
+  readonly signal: AbortSignal
+}
+
+export interface LanguageModelStream {
+  readonly events: AsyncIterable<LanguageModelStreamEvent>
+}
+
+export interface LanguageModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: LanguageModelDefinition
+  readonly costEstimator?: ModelCostEstimator
+  /**
+   * Return an executable model pinned to operational metadata, preserving model identity.
+   * `offline` requires a local snapshot without catalog I/O. Workers retain this model
+   * for generation and compaction; later catalog refreshes must not change its capabilities/limits.
+   * Throw ModelCatalogUnavailableError for catalog transport/access failures to allow workers to
+   * retry with an offline snapshot. Invalid definitions and other resolver errors remain fatal.
+   */
+  resolve?(options?: { readonly offline?: boolean }): Promise<LanguageModel>
+  stream(request: LanguageModelRequest): Promise<LanguageModelStream>
+}
+
+/** The common callable provider shape. Provider packages may accept additional model options. */
+export interface ModelProvider<TCatalog extends ModelDefinitionCatalog = ModelDefinitionCatalog> {
+  readonly providerId: string
+  readonly catalog: TCatalog
+}
+
+export interface LanguageModelProvider extends ModelProvider<LanguageModelDefinitionCatalog> {
+  (modelId: string): LanguageModel
+}
+
+export function isModelReasoning(value: unknown): value is ModelReasoning {
+  if (typeof value === "string") {
+    return (MODEL_REASONING_LEVELS as readonly string[]).includes(value)
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  if (Object.keys(value).length !== 1) return false
+  const budgetTokens = (value as { readonly budgetTokens?: unknown }).budgetTokens
+  return typeof budgetTokens === "number" && Number.isSafeInteger(budgetTokens) && budgetTokens >= 0
+}
+
+/** Explain why a request cannot be represented by known model capabilities. Unknown is allowed. */
+export function modelReasoningSupportIssue(
+  capabilities: ModelCapabilities["reasoning"],
+  reasoning: unknown
+): string | undefined {
+  if (reasoning === undefined) return undefined
+  if (!isModelReasoning(reasoning)) return "the reasoning preference is invalid"
+  if (reasoning === "provider-default") return undefined
+  if (capabilities === undefined) return undefined
+  if (capabilities === false) return "reasoning is not supported"
+  if (reasoning === "none") {
+    return capabilities.canDisable === true ? undefined : "reasoning cannot be disabled"
+  }
+  if (typeof reasoning === "string") {
+    return capabilities.efforts?.includes(reasoning) === true
+      ? undefined
+      : `reasoning effort '${reasoning}' is not supported`
+  }
+  const budget = capabilities.budgetTokens
+  if (budget === undefined) return "reasoning token budgets are not supported"
+  if (budget.min !== undefined && reasoning.budgetTokens < budget.min) {
+    return `reasoning token budget must be at least ${budget.min}`
+  }
+  if (budget.max !== undefined && reasoning.budgetTokens > budget.max) {
+    return `reasoning token budget must not exceed ${budget.max}`
+  }
+  return undefined
+}

package/src/models/messages.ts

@@ -0,0 +1,78 @@
+import type { JsonValue } from "../json"
+
+/** Opaque, JSON-safe provider state. Each provider reads only its own key. */
+export type ProviderData = Readonly<Record<string, JsonValue>>
+
+interface ModelPartBase {
+  readonly providerData?: ProviderData
+}
+
+export interface ModelTextPart extends ModelPartBase {
+  readonly type: "text"
+  readonly text: string
+}
+
+export interface ModelReasoningPart extends ModelPartBase {
+  readonly type: "reasoning"
+  readonly text: string
+}
+
+export interface ModelFilePart extends ModelPartBase {
+  readonly type: "file"
+  readonly data: URL
+  readonly filename?: string
+  readonly mediaType: string
+}
+
+export interface ModelToolCallPart extends ModelPartBase {
+  readonly type: "tool-call"
+  readonly toolCallId: string
+  readonly toolName: string
+  readonly input: JsonValue
+  readonly providerExecuted?: boolean
+  readonly dynamic?: boolean
+}
+
+export type ModelToolOutput =
+  | { readonly type: "text"; readonly value: string }
+  | { readonly type: "json"; readonly value: JsonValue }
+  | { readonly type: "error-text"; readonly value: string }
+  | { readonly type: "error-json"; readonly value: JsonValue }
+
+export interface ModelToolResultPart extends ModelPartBase {
+  readonly type: "tool-result"
+  readonly toolCallId: string
+  readonly toolName: string
+  readonly output: ModelToolOutput
+  /** Original durable tool output when the model-facing output is a projection. */
+  readonly originalOutput?: JsonValue
+  readonly providerExecuted?: boolean
+  readonly dynamic?: boolean
+}
+
+/** Ordered replay state with no honest portable content representation. */
+export interface ModelProviderStatePart {
+  readonly type: "provider-state"
+  readonly providerId: string
+  readonly data: JsonValue
+}
+
+export type ModelAssistantPart =
+  | ModelTextPart
+  | ModelReasoningPart
+  | ModelToolCallPart
+  | ModelToolResultPart
+  | ModelProviderStatePart
+
+export type ModelMessage =
+  | {
+      readonly role: "system"
+      readonly content: string
+      readonly providerData?: ProviderData
+    }
+  | {
+      readonly role: "user"
+      readonly content: readonly (ModelTextPart | ModelFilePart)[]
+    }
+  | { readonly role: "assistant"; readonly content: readonly ModelAssistantPart[] }
+  | { readonly role: "tool"; readonly content: readonly ModelToolResultPart[] }

package/src/models/pricing.ts

@@ -0,0 +1,390 @@
+import type { ModelRoute, ModelUsage } from "./events"
+import type { LanguageModel } from "./language-model"
+import type { LanguageModelRateCard, ModelTokenPrice } from "./rate-card"
+
+/** Optional local financial enrichment cannot discard a completed, billable call. */
+export function estimateModelCall(
+  model: LanguageModel,
+  input: Parameters<ModelCostEstimator["estimate"]>[0]
+): ModelCostEstimate {
+  try {
+    return model.costEstimator?.estimate(input) ?? rateModelCall({ usage: input.usage })
+  } catch {
+    console.warn(
+      "[Sixb] Model cost estimation failed; preserving usage and available provider cost."
+    )
+    return { status: "unpriceable", reason: "missing-rate-card" }
+  }
+}
+
+export interface ModelMoney {
+  readonly currency: "USD"
+  /** Billionths of one currency unit, serialized as an integer string. */
+  readonly amountNanos: string
+}
+
+export interface ModelReportedCost {
+  readonly money: ModelMoney
+  readonly providerId?: string
+}
+
+/** A local estimate is never a provider-reported charge. No financial API is required to run. */
+export type ModelCostEstimate = Exclude<ModelCallCost, { status: "reported" }>
+
+export interface ModelCostEstimator {
+  /** Conservative token-cost reservation, including cache writes and pricing tiers.
+   * Return undefined when routing or non-token charges prevent a safe local estimate. */
+  estimateReservation?(input: {
+    readonly inputTokens: number
+    readonly outputTokens: number
+  }): ModelMoney | undefined
+
+  estimate(input: {
+    readonly usage: ModelUsage
+    readonly route?: ModelRoute
+    readonly responseModelId?: string
+  }): ModelCostEstimate
+}
+
+export type ModelCostMeter =
+  | "tokens.input.total"
+  | "tokens.input.uncached"
+  | "tokens.input.cacheRead"
+  | "tokens.input.cacheWrite"
+  | "tokens.input.cacheWrite5m"
+  | "tokens.input.cacheWrite1h"
+  | "tokens.output.total"
+
+export interface ModelCostComponent {
+  readonly meter: ModelCostMeter
+  readonly quantity: string
+  readonly rateAmountNanosPerMillion: string
+  readonly chargeAmountNanos: string
+}
+
+export type ModelCallCost =
+  | { readonly status: "reported"; readonly money: ModelMoney; readonly providerId?: string }
+  | {
+      readonly status: "rated"
+      readonly money: ModelMoney
+      readonly components: readonly ModelCostComponent[]
+    }
+  | {
+      readonly status: "unpriceable"
+      readonly reason: "missing-rate-card" | "missing-usage" | "inconsistent-usage"
+      readonly missingMeters?: readonly ModelCostMeter[]
+    }
+
+/** Reserve at the highest configured token rates, before cache usage and the final tier are known. */
+export function estimateModelReservation(input: {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly rateCard?: LanguageModelRateCard
+}): ModelMoney | undefined {
+  if (!input.rateCard) return undefined
+  if (![input.inputTokens, input.outputTokens].every((n) => Number.isSafeInteger(n) && n >= 0)) {
+    throw new TypeError(
+      "[Sixb] Model reservation token estimates must be nonnegative safe integers."
+    )
+  }
+  const maxRate = (prices: readonly (ModelTokenPrice | undefined)[]) => {
+    const rates = prices.flatMap((price) =>
+      price === undefined
+        ? []
+        : typeof price === "string"
+          ? [price]
+          : [price.default, ...price.tiers.map((tier) => tier.price)]
+    )
+    return rates.reduce((max, price) => {
+      const rate = decimalDollarsToNanos(price)
+      return rate > max ? rate : max
+    }, 0n)
+  }
+  const card = input.rateCard
+  const inputRate = maxRate([
+    card.input,
+    card.cacheReadInput,
+    card.cacheWriteInput,
+    card.cacheWriteInput5m,
+    card.cacheWriteInput1h,
+  ])
+  const outputRate = maxRate([card.output])
+  const charge = (tokens: number, rate: bigint) => (BigInt(tokens) * rate + 999_999n) / 1_000_000n
+  return {
+    currency: "USD",
+    amountNanos: (
+      charge(input.inputTokens, inputRate) + charge(input.outputTokens, outputRate)
+    ).toString(),
+  }
+}
+
+/** Prefer the provider's bill over rate-card estimates, then rate complete token meters locally. */
+export function rateModelCall(input: {
+  readonly usage: ModelUsage
+  readonly rateCard?: LanguageModelRateCard
+  readonly reported?: undefined
+}): ModelCostEstimate
+export function rateModelCall(input: {
+  readonly usage: ModelUsage
+  readonly rateCard?: LanguageModelRateCard
+  readonly reported?: ModelReportedCost
+}): ModelCallCost
+export function rateModelCall(input: {
+  readonly usage: ModelUsage
+  readonly rateCard?: LanguageModelRateCard
+  readonly reported?: ModelReportedCost
+}): ModelCallCost {
+  if (input.reported) {
+    assertAmountNanos(input.reported.money.amountNanos)
+    return {
+      status: "reported",
+      money: input.reported.money,
+      ...(input.reported.providerId === undefined ? {} : { providerId: input.reported.providerId }),
+    }
+  }
+  if (!input.rateCard) return { status: "unpriceable", reason: "missing-rate-card" }
+  const { usage, rateCard } = input
+  if (!validUsageCounters(usage)) {
+    return { status: "unpriceable", reason: "inconsistent-usage" }
+  }
+  if (usage.inputTokens === undefined || usage.outputTokens === undefined) {
+    return {
+      status: "unpriceable",
+      reason: "missing-usage",
+      missingMeters: [
+        ...(usage.inputTokens === undefined ? (["tokens.input.total"] as const) : []),
+        ...(usage.outputTokens === undefined ? (["tokens.output.total"] as const) : []),
+      ],
+    }
+  }
+
+  const partitioned = partitionInputUsage(usage, rateCard)
+  if (partitioned.status !== "rated") return partitioned
+
+  const components: ModelCostComponent[] = []
+  if (!partitioned.partitioned) {
+    components.push(
+      component("tokens.input.total", usage.inputTokens, rateCard.input, usage.inputTokens)
+    )
+  } else {
+    components.push(
+      component("tokens.input.uncached", partitioned.uncached, rateCard.input, usage.inputTokens)
+    )
+    if (partitioned.cacheRead !== undefined) {
+      components.push(
+        component(
+          "tokens.input.cacheRead",
+          partitioned.cacheRead,
+          rateCard.cacheReadInput!,
+          usage.inputTokens
+        )
+      )
+    }
+    if (partitioned.cacheWrite !== undefined) {
+      components.push(
+        component(
+          "tokens.input.cacheWrite",
+          partitioned.cacheWrite,
+          rateCard.cacheWriteInput!,
+          usage.inputTokens
+        )
+      )
+    }
+    if (partitioned.cacheWrite5m !== undefined) {
+      components.push(
+        component(
+          "tokens.input.cacheWrite5m",
+          partitioned.cacheWrite5m,
+          rateCard.cacheWriteInput5m ?? rateCard.cacheWriteInput!,
+          usage.inputTokens
+        )
+      )
+    }
+    if (partitioned.cacheWrite1h !== undefined) {
+      components.push(
+        component(
+          "tokens.input.cacheWrite1h",
+          partitioned.cacheWrite1h,
+          rateCard.cacheWriteInput1h ?? rateCard.cacheWriteInput!,
+          usage.inputTokens
+        )
+      )
+    }
+  }
+  components.push(
+    component("tokens.output.total", usage.outputTokens, rateCard.output, usage.inputTokens)
+  )
+  const total = components.reduce((sum, entry) => sum + BigInt(entry.chargeAmountNanos), 0n)
+  return {
+    status: "rated",
+    money: { currency: rateCard.currency, amountNanos: total.toString() },
+    components,
+  }
+}
+
+type PartitionResult =
+  | { readonly status: "rated"; readonly partitioned: false }
+  | {
+      readonly status: "rated"
+      readonly partitioned: true
+      readonly uncached: number
+      readonly cacheRead?: number
+      readonly cacheWrite?: number
+      readonly cacheWrite5m?: number
+      readonly cacheWrite1h?: number
+    }
+  | Extract<ModelCallCost, { status: "unpriceable" }>
+
+function partitionInputUsage(usage: ModelUsage, rateCard: LanguageModelRateCard): PartitionResult {
+  const hasSpecificWrites =
+    usage.cacheWrite5mInputTokens !== undefined || usage.cacheWrite1hInputTokens !== undefined
+  const cacheWriteSpecific =
+    (usage.cacheWrite5mInputTokens ?? 0) + (usage.cacheWrite1hInputTokens ?? 0)
+  if (
+    hasSpecificWrites &&
+    usage.cacheWriteInputTokens !== undefined &&
+    usage.cacheWriteInputTokens !== cacheWriteSpecific
+  ) {
+    return { status: "unpriceable", reason: "inconsistent-usage" }
+  }
+
+  const partitioned =
+    usage.uncachedInputTokens !== undefined ||
+    usage.cacheReadInputTokens !== undefined ||
+    usage.cacheWriteInputTokens !== undefined ||
+    hasSpecificWrites ||
+    rateCard.cacheReadInput !== undefined ||
+    rateCard.cacheWriteInput !== undefined ||
+    rateCard.cacheWriteInput5m !== undefined ||
+    rateCard.cacheWriteInput1h !== undefined
+  if (!partitioned) return { status: "rated", partitioned: false }
+
+  const cacheRead = usage.cacheReadInputTokens ?? 0
+  const totalWrite = usage.cacheWriteInputTokens ?? cacheWriteSpecific
+  if (usage.inputTokens !== undefined && cacheRead + totalWrite > usage.inputTokens) {
+    return { status: "unpriceable", reason: "inconsistent-usage" }
+  }
+
+  const missing: ModelCostMeter[] = []
+  if (usage.uncachedInputTokens === undefined) missing.push("tokens.input.uncached")
+  if (rateCard.cacheReadInput !== undefined && usage.cacheReadInputTokens === undefined) {
+    missing.push("tokens.input.cacheRead")
+  }
+  if (
+    rateCard.cacheWriteInput !== undefined &&
+    rateCard.cacheWriteInput5m === undefined &&
+    rateCard.cacheWriteInput1h === undefined &&
+    usage.cacheWriteInputTokens === undefined
+  ) {
+    missing.push("tokens.input.cacheWrite")
+  }
+  if (rateCard.cacheWriteInput5m !== undefined && usage.cacheWrite5mInputTokens === undefined) {
+    missing.push("tokens.input.cacheWrite5m")
+  }
+  if (rateCard.cacheWriteInput1h !== undefined && usage.cacheWrite1hInputTokens === undefined) {
+    missing.push("tokens.input.cacheWrite1h")
+  }
+  if (missing.length > 0) {
+    return { status: "unpriceable", reason: "missing-usage", missingMeters: missing }
+  }
+  if (cacheRead > 0 && rateCard.cacheReadInput === undefined) {
+    return {
+      status: "unpriceable",
+      reason: "missing-rate-card",
+      missingMeters: ["tokens.input.cacheRead"],
+    }
+  }
+  if (!hasSpecificWrites && totalWrite > 0 && rateCard.cacheWriteInput === undefined) {
+    return {
+      status: "unpriceable",
+      reason: "missing-rate-card",
+      missingMeters: ["tokens.input.cacheWrite"],
+    }
+  }
+  if (
+    (usage.cacheWrite5mInputTokens ?? 0) > 0 &&
+    rateCard.cacheWriteInput5m === undefined &&
+    rateCard.cacheWriteInput === undefined
+  ) {
+    return {
+      status: "unpriceable",
+      reason: "missing-rate-card",
+      missingMeters: ["tokens.input.cacheWrite5m"],
+    }
+  }
+  if (
+    (usage.cacheWrite1hInputTokens ?? 0) > 0 &&
+    rateCard.cacheWriteInput1h === undefined &&
+    rateCard.cacheWriteInput === undefined
+  ) {
+    return {
+      status: "unpriceable",
+      reason: "missing-rate-card",
+      missingMeters: ["tokens.input.cacheWrite1h"],
+    }
+  }
+
+  const uncached = usage.uncachedInputTokens!
+  if (uncached + cacheRead + totalWrite !== usage.inputTokens) {
+    return { status: "unpriceable", reason: "inconsistent-usage" }
+  }
+  return {
+    status: "rated",
+    partitioned: true,
+    uncached,
+    ...(rateCard.cacheReadInput === undefined ? {} : { cacheRead }),
+    ...(hasSpecificWrites
+      ? {
+          cacheWrite5m: usage.cacheWrite5mInputTokens ?? 0,
+          cacheWrite1h: usage.cacheWrite1hInputTokens ?? 0,
+        }
+      : rateCard.cacheWriteInput === undefined
+        ? {}
+        : { cacheWrite: totalWrite }),
+  }
+}
+
+function validUsageCounters(usage: ModelUsage): boolean {
+  return Object.entries(usage)
+    .filter(([key]) => key !== "raw")
+    .every(([, value]) => value === undefined || (Number.isSafeInteger(value) && value >= 0))
+}
+
+function component(
+  meter: ModelCostMeter,
+  quantity: number,
+  price: ModelTokenPrice,
+  tierTokens: number
+): ModelCostComponent {
+  const rate = decimalDollarsToNanos(resolvePrice(price, tierTokens))
+  const charge = (BigInt(quantity) * rate + 500_000n) / 1_000_000n
+  return {
+    meter,
+    quantity: quantity.toString(),
+    rateAmountNanosPerMillion: rate.toString(),
+    chargeAmountNanos: charge.toString(),
+  }
+}
+
+function resolvePrice(price: ModelTokenPrice, tokens: number): string {
+  if (typeof price === "string") return price
+  return (
+    price.tiers.find(
+      (tier) =>
+        tokens >= tier.minTokens && (tier.maxTokens === undefined || tokens < tier.maxTokens)
+    )?.price ?? price.default
+  )
+}
+
+function decimalDollarsToNanos(value: string): bigint {
+  const [whole = "0", fraction = ""] = value.split(".")
+  const nanos = fraction.slice(0, 9).padEnd(9, "0")
+  const roundUp = Number(fraction[9] ?? "0") >= 5
+  return BigInt(whole) * 1_000_000_000n + BigInt(nanos) + (roundUp ? 1n : 0n)
+}
+
+function assertAmountNanos(value: string): void {
+  if (!/^(?:0|[1-9]\d*)$/.test(value)) {
+    throw new TypeError("[Sixb] Provider-reported model cost must use nonnegative amountNanos.")
+  }
+}