@sixb/core 0.1.20 → 0.1.22

package/src/models/image/runtime.ts

@@ -0,0 +1,335 @@
+import { randomUUID } from "node:crypto"
+import { assertModelAccess } from "../../authorization"
+import type { BlobStorage, FileRef } from "../../blob-storage/types"
+import type { ExecutionContext } from "../../execution"
+import type { SixbRuntimeContext } from "../../runtime/types"
+import type { ModelCatalog } from "../catalog"
+import type { ModelCallEndEvent } from "../events"
+import type { AiModelCallRecorder } from "../execution/model-call-recorder"
+import type { ModelExecutionSession } from "../execution/session"
+import { prepareModelInputFile, readModelInputFile } from "../input-file"
+import { estimateModelCall, type ModelMoney } from "../pricing"
+import type { ModelPricingDimensions } from "../rate-card"
+import { assertImageModel } from "./catalog"
+import { ImageModelResponseError } from "./errors"
+import type {
+  ImageData,
+  ImageGenerateInput,
+  ImageModel,
+  ImageModelResponseMetadata,
+  ImageModelResult,
+  ImageModelsRuntime,
+  ImageReservationInput,
+} from "./types"
+
+interface PreparedRequest {
+  readonly prompt: string
+  readonly n: number
+  readonly size?: string
+  readonly aspectRatio?: string
+  readonly quality?: string
+  readonly style?: string
+  readonly seed?: number
+  readonly images: readonly { readonly file: FileRef; readonly mediaType: string }[]
+}
+
+export function createImageRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  catalog: ModelCatalog | undefined,
+  session: ModelExecutionSession,
+  blobs: BlobStorage | undefined
+): ImageModelsRuntime {
+  return {
+    async generate(input) {
+      assertModelAccess(runtime, execution, "models.image.generate")
+
+      const request = prepareRequest(input)
+      if (!blobs) {
+        throw new Error("[SixbModels] Image generation requires blob storage.")
+      }
+
+      const signal = session.signal(input.signal)
+      signal.throwIfAborted()
+
+      const binding = selectModel(catalog, input.model)
+      assertImageModel(binding)
+      assertRequestSupport(binding, request)
+
+      const accounting = await session.accounting()
+      accounting.assertHealthy()
+
+      const model = binding.resolve ? await binding.resolve() : binding
+      assertImageModel(model)
+      if (model.providerId !== binding.providerId || model.modelId !== binding.modelId) {
+        throw new TypeError(
+          "[SixbModels] Resolved image model identity does not match the selected model."
+        )
+      }
+      assertRequestSupport(model, request)
+
+      const images: ImageData[] = []
+      for (const image of request.images) {
+        signal.throwIfAborted()
+        images.push({
+          data: await readModelInputFile(blobs, image.file, signal),
+          mediaType: image.mediaType,
+        })
+      }
+      accounting.assertHealthy()
+
+      const dimensions = pricingDimensions(request)
+      const promptTokens = Math.ceil(new TextEncoder().encode(request.prompt).byteLength / 4)
+      const callId = `call_${randomUUID()}`
+      await accounting.admitCall({
+        callId,
+        providerId: model.providerId,
+        modelId: model.modelId,
+        modelKind: "image",
+        inputTokens:
+          images.length > 0
+            ? { status: "unavailable", reason: "nonTextInput" }
+            : { status: "estimated", tokens: promptTokens, method: "utf8BytesDividedByFour" },
+        outputTokenAllowance: 0,
+        reservationCost: estimateReservationCost(model, {
+          n: request.n,
+          promptTokens,
+          inputImages: images.length,
+          dimensions,
+        }),
+      })
+
+      let result: ImageModelResult
+      try {
+        signal.throwIfAborted()
+        result = await model.generate({
+          prompt: request.prompt,
+          n: request.n,
+          ...(request.size === undefined ? {} : { size: request.size }),
+          ...(request.aspectRatio === undefined ? {} : { aspectRatio: request.aspectRatio }),
+          ...(request.quality === undefined ? {} : { quality: request.quality }),
+          ...(request.style === undefined ? {} : { style: request.style }),
+          ...(request.seed === undefined ? {} : { seed: request.seed }),
+          images,
+          signal,
+        })
+      } catch (error) {
+        await recordImages(
+          accounting,
+          model,
+          callId,
+          error instanceof ImageModelResponseError ? error.metadata : {},
+          undefined,
+          dimensions
+        )
+        throw error
+      }
+
+      // A completed, billable reply must survive cancellation and image validation failures.
+      const returned = Array.isArray(result?.output?.images) ? result.output.images : undefined
+      const event = await recordImages(
+        accounting,
+        model,
+        callId,
+        result ?? {},
+        returned?.length,
+        dimensions
+      )
+      signal.throwIfAborted()
+      if (!returned?.length || !returned.every(isImageData) || !isWarnings(result.warnings)) {
+        throw new ImageModelResponseError(
+          "[SixbModels] Invalid image response.",
+          model.providerId,
+          model.modelId,
+          result ?? {}
+        )
+      }
+
+      const files: FileRef[] = []
+      for (const image of returned) {
+        files.push(
+          await blobs.put({
+            body: image.data,
+            expectedSizeBytes: image.data.byteLength,
+            mediaType: image.mediaType,
+            signal,
+          })
+        )
+      }
+      await accounting.recordFiles(callId, files)
+
+      return {
+        files,
+        warnings: [...(result.warnings ?? [])],
+        usage: event.usage,
+        cost: event.cost,
+        callId,
+      }
+    },
+  }
+}
+
+/** Validate and snapshot the caller's request before the first await. */
+function prepareRequest(input: ImageGenerateInput): PreparedRequest {
+  if (typeof input?.prompt !== "string" || !input.prompt.trim()) {
+    throw new TypeError("[SixbModels] Image generation requires a nonblank prompt.")
+  }
+  const n = input.n ?? 1
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw new TypeError("[SixbModels] Image count 'n' must be a positive safe integer.")
+  }
+  for (const field of ["size", "aspectRatio", "quality", "style"] as const) {
+    const value = input[field]
+    if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+      throw new TypeError(`[SixbModels] Image ${field} must be a nonblank string.`)
+    }
+  }
+  if (input.seed !== undefined && !Number.isSafeInteger(input.seed)) {
+    throw new TypeError("[SixbModels] Image seed must be a safe integer.")
+  }
+  if (input.images !== undefined && !Array.isArray(input.images)) {
+    throw new TypeError("[SixbModels] Reference images must be an array of FileRefs.")
+  }
+
+  return {
+    prompt: input.prompt,
+    n,
+    ...(input.size === undefined ? {} : { size: input.size }),
+    ...(input.aspectRatio === undefined ? {} : { aspectRatio: input.aspectRatio }),
+    ...(input.quality === undefined ? {} : { quality: input.quality }),
+    ...(input.style === undefined ? {} : { style: input.style }),
+    ...(input.seed === undefined ? {} : { seed: input.seed }),
+    images: (input.images ?? []).map((image) => prepareModelInputFile(image, "image")),
+  }
+}
+
+function selectModel(
+  catalog: ModelCatalog | undefined,
+  requested: ImageModel | undefined
+): ImageModel {
+  // A model the caller passes runs as given, listed or not; the catalog supplies the default.
+  const selected = requested ?? catalog?.image?.default.model
+  if (!selected) {
+    throw new Error(
+      "[SixbModels] Configure models.image in createSixb() or supply a model to generate()."
+    )
+  }
+
+  return selected
+}
+
+function assertRequestSupport(model: ImageModel, request: PreparedRequest): void {
+  const definition = model.definition
+  if (definition.maxImagesPerCall !== undefined && request.n > definition.maxImagesPerCall) {
+    throw new RangeError(
+      `[SixbModels] The selected model returns at most ${definition.maxImagesPerCall} images per call.`
+    )
+  }
+  for (const [field, list] of [
+    ["size", definition.sizes],
+    ["aspectRatio", definition.aspectRatios],
+    ["quality", definition.qualities],
+    ["style", definition.styles],
+  ] as const) {
+    const value = request[field]
+    if (value !== undefined && list && !list.includes(value)) {
+      throw new TypeError(
+        `[SixbModels] Image ${field} '${value}' is not supported by the selected model. Use one of: ${list.join(", ")}.`
+      )
+    }
+  }
+
+  if (request.images.length === 0) return
+  const accepted = definition.inputImages
+  if (!accepted) {
+    throw new TypeError("[SixbModels] The selected model does not accept reference images.")
+  }
+  if (request.images.length > accepted.maxCount) {
+    throw new RangeError(
+      `[SixbModels] The selected model accepts at most ${accepted.maxCount} reference images.`
+    )
+  }
+  for (const image of request.images) {
+    if (image.file.sizeBytes > accepted.maxBytes) {
+      throw new RangeError(
+        `[SixbModels] Reference image exceeds the model's ${accepted.maxBytes}-byte input limit.`
+      )
+    }
+    if (accepted.mediaTypes && !accepted.mediaTypes.includes(image.mediaType)) {
+      throw new TypeError(
+        `[SixbModels] Image media type '${image.mediaType}' is not supported by the selected model.`
+      )
+    }
+  }
+}
+
+function pricingDimensions(request: PreparedRequest): ModelPricingDimensions {
+  return {
+    ...(request.size === undefined ? {} : { size: request.size }),
+    ...(request.quality === undefined ? {} : { quality: request.quality }),
+    ...(request.style === undefined ? {} : { style: request.style }),
+  }
+}
+
+function estimateReservationCost(
+  model: ImageModel,
+  input: ImageReservationInput
+): ModelMoney | undefined {
+  try {
+    return model.costEstimator?.estimateReservation?.(input)
+  } catch {
+    // Optional pricing cannot bypass an enforced budget: admission fails closed without it.
+    return undefined
+  }
+}
+
+async function recordImages(
+  accounting: AiModelCallRecorder,
+  model: ImageModel,
+  callId: string,
+  metadata: ImageModelResponseMetadata,
+  returnedImages: number | undefined,
+  dimensions: ModelPricingDimensions
+): Promise<ModelCallEndEvent> {
+  // The images actually returned are the count that was billed, whatever the provider reports.
+  const usage = {
+    ...metadata.usage,
+    ...(returnedImages === undefined ? {} : { outputImages: returnedImages }),
+  }
+  const estimate = estimateModelCall(model, {
+    usage,
+    route: metadata.route,
+    responseModelId: metadata.responseModelId,
+    dimensions,
+  })
+  const event: ModelCallEndEvent = {
+    callId,
+    modelKind: "image",
+    providerId: model.providerId,
+    modelId: model.modelId,
+    responseId: metadata.providerIds?.responseId ?? callId,
+    providerIds: metadata.providerIds,
+    responseModelId: metadata.responseModelId,
+    usage,
+    cost: metadata.reportedCost ? { status: "reported", ...metadata.reportedCost } : estimate,
+    ...(metadata.reportedCost ? { estimate } : {}),
+    route: metadata.route,
+  }
+
+  await accounting.onModelCallEnd(event)
+  return event
+}
+
+function isImageData(value: unknown): value is ImageData {
+  const image = value as Partial<ImageData> | null
+  return (
+    image?.data instanceof Uint8Array &&
+    image.data.byteLength > 0 &&
+    typeof image.mediaType === "string" &&
+    /^image\/[a-z0-9.+-]+$/.test(image.mediaType)
+  )
+}
+
+function isWarnings(value: unknown): value is readonly string[] | undefined {
+  return value === undefined || (Array.isArray(value) && value.every((w) => typeof w === "string"))
+}

package/src/models/image/types.ts

@@ -0,0 +1,111 @@
+import type { FileRef } from "../../blob-storage/types"
+import type { ModelDefinition } from "../definitions"
+import type { ModelProviderIds, ModelRoute, ModelUsage } from "../events"
+import type { ModelCallCost, ModelCostEstimator, ModelMoney, ModelReportedCost } from "../pricing"
+import type { ModelPricingDimensions, ModelRateCard } from "../rate-card"
+
+/** Serializable facts about one image model. Omitted lists mean the provider publishes none. */
+export interface ImageModelDefinition extends ModelDefinition {
+  readonly kind: "image"
+  readonly maxImagesPerCall?: number
+  /** Accepted `size` values, such as `1024x1024` or `1K`. */
+  readonly sizes?: readonly string[]
+  readonly aspectRatios?: readonly string[]
+  readonly qualities?: readonly string[]
+  readonly styles?: readonly string[]
+  /** Reference images for edits; omitted when the model takes none. */
+  readonly inputImages?: {
+    readonly maxCount: number
+    /** Bounds memory consumption before a file is opened. Providers may impose lower limits. */
+    readonly maxBytes: number
+    readonly mediaTypes?: readonly string[]
+  }
+}
+
+/** Image bytes with the media type the provider resolved. */
+export interface ImageData {
+  readonly data: Uint8Array
+  readonly mediaType: string
+}
+
+export interface ImageModelRequest {
+  readonly prompt: string
+  readonly n: number
+  readonly size?: string
+  readonly aspectRatio?: string
+  readonly quality?: string
+  readonly style?: string
+  readonly seed?: number
+  readonly images: readonly ImageData[]
+  readonly signal?: AbortSignal
+}
+
+export interface ImageModelResponseMetadata {
+  readonly usage?: ModelUsage
+  readonly providerIds?: ModelProviderIds
+  readonly responseModelId?: string
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: ModelRoute
+}
+
+export interface ImageModelResult extends ImageModelResponseMetadata {
+  readonly output: { readonly images: readonly ImageData[] }
+  /** Provider notes about the request, such as a setting it ignored. */
+  readonly warnings?: readonly string[]
+}
+
+export interface ImageReservationInput {
+  readonly n: number
+  /** UTF-8 bytes of the prompt divided by four, rounded up. */
+  readonly promptTokens: number
+  readonly inputImages: number
+  readonly dimensions: ModelPricingDimensions
+}
+
+export interface ImageCostEstimator extends Pick<ModelCostEstimator, "estimate"> {
+  /** Return undefined if the request cannot be priced safely before inference. */
+  estimateReservation?(input: ImageReservationInput): ModelMoney | undefined
+}
+
+/** Provider binding. Resolving it may fetch metadata, but must never perform inference. */
+export interface ImageModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: ImageModelDefinition
+  readonly costEstimator?: ImageCostEstimator
+  /**
+   * The prices this binding bills by, for people and agents choosing a model. Pricing itself
+   * goes through costEstimator; absent when the price is unknown.
+   */
+  readonly rateCard?: ModelRateCard
+  resolve?(): Promise<ImageModel>
+  generate(request: ImageModelRequest): Promise<ImageModelResult>
+}
+
+export interface ImageGenerateInput {
+  readonly prompt: string
+  /** Defaults to 1. */
+  readonly n?: number
+  readonly size?: string
+  readonly aspectRatio?: string
+  readonly quality?: string
+  readonly style?: string
+  readonly seed?: number
+  /** Reference images for an edit or variation. */
+  readonly images?: readonly FileRef[]
+  readonly model?: ImageModel
+  readonly signal?: AbortSignal
+}
+
+export interface ImageGenerateResult {
+  /** Generated images, already written to blob storage. */
+  readonly files: readonly FileRef[]
+  readonly warnings: readonly string[]
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+  readonly callId: string
+}
+
+export interface ImageModelsRuntime {
+  generate(input: ImageGenerateInput): Promise<ImageGenerateResult>
+}

package/src/models/index.ts

@@ -4,14 +4,25 @@ export { assertJsonObject, assertJsonValue, isJsonObject, isJsonValue } from "..
 export type {
   AudioModelCatalog,
   AudioModelCatalogInput,
+  SpeechModelCatalog,
+  SpeechModelEntry,
   TranscriptionModelCatalog,
   TranscriptionModelEntry,
 } from "./audio/catalog"
-export { TranscriptionModelResponseError } from "./audio/errors"
+export { SpeechModelResponseError, TranscriptionModelResponseError } from "./audio/errors"
 export type {
   AudioModelsRuntime,
+  AudioSpeakInput,
+  AudioSpeakResult,
   AudioTranscribeInput,
   AudioTranscribeResult,
+  SpeechCostEstimator,
+  SpeechModel,
+  SpeechModelDefinition,
+  SpeechModelRequest,
+  SpeechModelResponseMetadata,
+  SpeechModelResult,
+  SpeechReservationInput,
   TranscriptionCostEstimator,
   TranscriptionModel,
   TranscriptionModelDefinition,
@@ -20,6 +31,7 @@ export type {
   TranscriptionModelResult,
   TranscriptionOutput,
 } from "./audio/types"
+export type { ModelCallFiles, ModelCallsRuntime } from "./calls"
 export type {
   EmbeddingModelCatalog,
   EmbeddingModelEntry,
@@ -27,6 +39,9 @@ export type {
   LanguageModelDefinitionCatalog,
   LanguageModelEntry,
   LanguageModelRef,
+  LanguageModelTier,
+  LanguageModelTierProbabilities,
+  LanguageModelTiers,
   ModelCatalog,
   ModelCatalogFor,
   ModelCatalogInput,
@@ -35,7 +50,7 @@ export type {
   RerankingModelCatalog,
   RerankingModelEntry,
 } from "./catalog"
-export { createModelCatalog } from "./catalog"
+export { createModelCatalog, LANGUAGE_MODEL_TIERS } from "./catalog"
 export type { DecisionModelCatalog, DecisionModelEntry } from "./decision/catalog"
 export { DecisionModelResponseError } from "./decision/errors"
 export type { DecisionAnswerSchema, DecisionOutputShape } from "./decision/output"
@@ -61,10 +76,11 @@ export type {
 } from "./decision/types"
 export type {
   LanguageModelDefinition,
+  LanguageModelLabel,
   ModelDefinition,
   ModelKind,
 } from "./definitions"
-export { defineLanguageModel } from "./definitions"
+export { defineLanguageModel, defineLanguageModelLabel } from "./definitions"
 export type {
   EmbeddingBatchLimits,
   EmbeddingModel,
@@ -102,6 +118,21 @@ export type {
   LanguageModelsRuntime,
   ModelsRuntime,
 } from "./generation-types"
+export type { ImageModelCatalog, ImageModelEntry } from "./image/catalog"
+export { ImageModelResponseError } from "./image/errors"
+export type {
+  ImageCostEstimator,
+  ImageData,
+  ImageGenerateInput,
+  ImageGenerateResult,
+  ImageModel,
+  ImageModelDefinition,
+  ImageModelRequest,
+  ImageModelResponseMetadata,
+  ImageModelResult,
+  ImageModelsRuntime,
+  ImageReservationInput,
+} from "./image/types"
 export type {
   LanguageModel,
   LanguageModelProvider,
@@ -147,10 +178,13 @@ export type {
 } from "./pricing"
 export { estimateModelReservation, rateModelCall } from "./pricing"
 export type {
-  LanguageModelRateCard,
+  ModelPriceVariant,
+  ModelPricingDimensions,
   ModelPricingTier,
+  ModelRateCard,
   ModelTokenPrice,
   ModelUnitPrice,
+  ModelVariantPrice,
 } from "./rate-card"
 export { defineModelRateCard } from "./rate-card"
 export type {

package/src/models/{audio/file.ts → input-file.ts}

@@ -1,24 +1,33 @@
 import { createHash } from "node:crypto"
-import type { BlobStorage, FileRef } from "../../blob-storage/types"
-import { isFileRef } from "../../blob-storage/validation"
+import type { BlobStorage, FileRef } from "../blob-storage/types"
+import { isFileRef } from "../blob-storage/validation"
 
 /** Snapshot caller-owned metadata before model resolution or storage introduces an await. */
-export function prepareTranscriptionFile(input: FileRef): { audio: FileRef; mediaType: string } {
+export function prepareModelInputFile(
+  input: FileRef,
+  type: "audio" | "image"
+): { file: FileRef; mediaType: string } {
   if (!isFileRef(input) || !Number.isSafeInteger(input.sizeBytes) || input.sizeBytes <= 0) {
-    throw new TypeError("[SixbModels] Transcription requires a nonempty FileRef.")
+    throw new TypeError(`[SixbModels] ${capitalize(type)} input must be a nonempty FileRef.`)
   }
 
-  const audio = { ...input }
-  const mediaType = audio.mediaType?.split(";", 1)[0]?.trim().toLowerCase()
-  if (!mediaType || !/^audio\/[a-z0-9.+-]+$/.test(mediaType)) {
-    throw new TypeError("[SixbModels] Audio FileRef must declare an audio mediaType.")
+  const file = { ...input }
+  const mediaType = file.mediaType?.split(";", 1)[0]?.trim().toLowerCase()
+  if (!mediaType || !new RegExp(`^${type}/[a-z0-9.+-]+$`).test(mediaType)) {
+    throw new TypeError(
+      `[SixbModels] ${capitalize(type)} FileRef must declare an ${type} mediaType.`
+    )
   }
 
-  return { audio, mediaType }
+  return { file, mediaType }
+}
+
+function capitalize(type: "audio" | "image"): string {
+  return type === "audio" ? "Audio" : "Image"
 }
 
 /** Read an already validated reference, bounded by its verified size and the model's limit. */
-export async function readTranscriptionFile(
+export async function readModelInputFile(
   storage: BlobStorage,
   file: FileRef,
   signal: AbortSignal
@@ -31,7 +40,7 @@ export async function readTranscriptionFile(
     info.digest !== file.digest ||
     info.sizeBytes !== file.sizeBytes
   ) {
-    throw new Error("[SixbModels] Audio reference does not match the stored file.")
+    throw new Error("[SixbModels] File reference does not match the stored file.")
   }
 
   const stream = await storage.open(file.blobId)
@@ -54,7 +63,7 @@ export async function readTranscriptionFile(
       signal.throwIfAborted()
       if (done) break
       if (!(value instanceof Uint8Array) || value.byteLength > bytes.byteLength - offset) {
-        throw new Error("[SixbModels] Audio stream exceeds its declared size.")
+        throw new Error("[SixbModels] File stream exceeds its declared size.")
       }
 
       bytes.set(value, offset)
@@ -63,7 +72,7 @@ export async function readTranscriptionFile(
     }
 
     if (offset !== file.sizeBytes || `sha256:${hash.digest("hex")}` !== file.digest) {
-      throw new Error("[SixbModels] Audio stream does not match its content-addressed reference.")
+      throw new Error("[SixbModels] File stream does not match its content-addressed reference.")
     }
 
     complete = true

package/src/models/language-model.ts

@@ -4,6 +4,7 @@ import type { LanguageModelDefinition } from "./definitions"
 import type { LanguageModelStreamEvent } from "./events"
 import type { ModelMessage } from "./messages"
 import type { ModelCostEstimator } from "./pricing"
+import type { ModelRateCard } from "./rate-card"
 
 export const MODEL_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const
 
@@ -83,12 +84,24 @@ export interface LanguageModel {
   readonly modelId: string
   readonly definition: LanguageModelDefinition
   readonly costEstimator?: ModelCostEstimator
+  /**
+   * The prices this binding bills by, for people and agents choosing a model. Pricing itself
+   * goes through costEstimator; absent when the price is unknown.
+   */
+  readonly rateCard?: ModelRateCard
   /**
    * Reasoning Sixb applies whenever this model runs without an explicit choice: chat turns, AI
    * workflow steps, subagents, and direct generation. Providers set it from their model options;
    * Sixb checks it against `definition.capabilities` at startup.
    */
   readonly defaultReasoning?: ModelReasoningLevel
+  /**
+   * Output limit the binding sets for every call, agent calls included. Unlike
+   * `definition.maxOutputTokens`, the most the model itself can produce, this is the developer's
+   * choice. Providers set it from their model options; Sixb checks it against that maximum at
+   * startup.
+   */
+  readonly maxOutputTokens?: number
   /**
    * Return an executable model pinned to operational metadata, preserving model identity.
    * `offline` requires a local snapshot without catalog I/O. Workers retain this model