@sixb/core 0.1.6 → 0.1.8

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.")
+  }
+}

package/src/models/rate-card.ts

@@ -0,0 +1,101 @@
+/** Decimal USD per million tokens. Strings keep provider prices exact. */
+export type ModelUnitPrice = string
+
+export interface ModelPricingTier {
+  readonly minTokens: number
+  readonly maxTokens?: number
+  readonly price: ModelUnitPrice
+}
+
+export type ModelTokenPrice =
+  | ModelUnitPrice
+  | { readonly default: ModelUnitPrice; readonly tiers: readonly ModelPricingTier[] }
+
+export interface LanguageModelRateCard {
+  readonly currency: "USD"
+  readonly unit: "million-tokens"
+  readonly input: ModelTokenPrice
+  readonly output: ModelTokenPrice
+  readonly cacheReadInput?: ModelTokenPrice
+  readonly cacheWriteInput?: ModelTokenPrice
+  readonly cacheWriteInput5m?: ModelTokenPrice
+  readonly cacheWriteInput1h?: ModelTokenPrice
+}
+
+/** Validate and snapshot provider-owned pricing independently of operational metadata. */
+export function defineModelRateCard(rateCard: LanguageModelRateCard): LanguageModelRateCard {
+  assertRecord(rateCard, "rate card")
+  if (rateCard.currency !== "USD" || rateCard.unit !== "million-tokens") {
+    throw new TypeError("[Sixb] Model rate cards must use USD per million tokens.")
+  }
+  return Object.freeze({
+    currency: "USD",
+    unit: "million-tokens",
+    input: tokenPrice(rateCard.input),
+    output: tokenPrice(rateCard.output),
+    ...(rateCard.cacheReadInput === undefined
+      ? {}
+      : { cacheReadInput: tokenPrice(rateCard.cacheReadInput) }),
+    ...(rateCard.cacheWriteInput === undefined
+      ? {}
+      : { cacheWriteInput: tokenPrice(rateCard.cacheWriteInput) }),
+    ...(rateCard.cacheWriteInput5m === undefined
+      ? {}
+      : { cacheWriteInput5m: tokenPrice(rateCard.cacheWriteInput5m) }),
+    ...(rateCard.cacheWriteInput1h === undefined
+      ? {}
+      : { cacheWriteInput1h: tokenPrice(rateCard.cacheWriteInput1h) }),
+  })
+}
+
+function tokenPrice(value: ModelTokenPrice): ModelTokenPrice {
+  if (typeof value === "string") return price(value)
+  assertRecord(value, "token price")
+  if (!Array.isArray(value.tiers)) throw new TypeError("[Sixb] Model price tiers must be an array.")
+  let previousMax = 0
+  return Object.freeze({
+    default: price(value.default),
+    tiers: Object.freeze(
+      value.tiers.map((tier, index) => {
+        assertRecord(tier, "price tier")
+        if (
+          typeof tier.minTokens !== "number" ||
+          !Number.isSafeInteger(tier.minTokens) ||
+          tier.minTokens < 0
+        ) {
+          throw new TypeError("[Sixb] Model price tier has an invalid minimum.")
+        }
+        if (index > 0 && tier.minTokens < previousMax) {
+          throw new TypeError("[Sixb] Model price tiers must be ordered and nonoverlapping.")
+        }
+        if (
+          tier.maxTokens !== undefined &&
+          (typeof tier.maxTokens !== "number" ||
+            !Number.isSafeInteger(tier.maxTokens) ||
+            tier.maxTokens <= tier.minTokens)
+        ) {
+          throw new TypeError("[Sixb] Model price tier has an invalid maximum.")
+        }
+        previousMax = tier.maxTokens ?? Number.POSITIVE_INFINITY
+        return Object.freeze({
+          minTokens: tier.minTokens,
+          ...(tier.maxTokens === undefined ? {} : { maxTokens: tier.maxTokens }),
+          price: price(tier.price),
+        })
+      })
+    ),
+  })
+}
+
+function price(value: unknown): string {
+  if (typeof value !== "string" || !/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
+    throw new TypeError("[Sixb] Model price must be a nonnegative decimal string.")
+  }
+  return value
+}
+
+function assertRecord(value: unknown, field: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`[Sixb] Model ${field} must be an object.`)
+  }
+}

package/src/models/tools.ts

@@ -0,0 +1,29 @@
+import type { JsonObject, JsonValue } from "../json"
+import type { ModelToolOutput } from "./messages"
+
+export interface ModelToolExecutionContext {
+  readonly signal: AbortSignal
+  readonly callId: string
+  readonly toolCallId: string
+}
+
+export interface ModelTool<TInput = unknown, TOutput extends JsonValue = JsonValue> {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: JsonObject
+  parseInput(value: unknown): TInput
+  execute(input: TInput, context: ModelToolExecutionContext): Promise<TOutput>
+  /** Project a durable output into provider-safe model content without changing the stored result. */
+  toModelOutput?(
+    output: TOutput,
+    context: ModelToolExecutionContext
+  ): ModelToolOutput | Promise<ModelToolOutput>
+  errorText(error: unknown): string
+}
+
+export interface ModelOutput<TOutput> {
+  readonly name: string
+  readonly description?: string
+  readonly schema: JsonObject
+  validate(value: unknown): TOutput
+}