@sixb/core 0.1.7 → 0.1.9

package/src/models/execution.ts

@@ -0,0 +1,207 @@
+import { runModelLoop } from "../agents/model-loop"
+import { assertProviderAccess } from "../authorization"
+import type { ExecutionContext } from "../execution"
+import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ModelCatalog } from "./catalog"
+import { ModelProviderError, ModelStreamError, UnsupportedModelFeatureError } from "./errors"
+import type { ModelCallEndEvent } from "./events"
+import { type ModelExecutionAttempt, registerModelExecutionBinding } from "./execution/binding"
+import { requireAccountingCapabilities } from "./execution/model-call-accounting"
+import { aiModelCallOutputTokenAllowance } from "./execution/model-call-admission"
+import { createAiModelCallLimitController } from "./execution/model-call-limits"
+import { AiModelCallRecorder } from "./execution/model-call-recorder"
+import { enqueueAiModelCallRecovery } from "./execution/recovery-queue"
+import type {
+  InferLanguageModelOutput,
+  LanguageModelGenerateInput,
+  LanguageModelGenerateResult,
+  LanguageModelOutputShape,
+  ModelsRuntime,
+} from "./generation-types"
+import { modelReasoningSupportIssue } from "./language-model"
+import type { ModelMessage } from "./messages"
+import { languageModelOutput } from "./output"
+import { resolveLanguageModel } from "./resolve"
+
+export function createModelsRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  catalog: ModelCatalog | undefined
+): ModelsRuntime {
+  let binding: ModelExecutionAttempt | undefined
+  let recorder: Promise<AiModelCallRecorder> | undefined
+
+  async function createRecorder(): Promise<AiModelCallRecorder> {
+    const storage = {
+      ...requireAccountingCapabilities(runtime.storage),
+      transaction: runtime.storage.transaction.bind(runtime.storage),
+    }
+    if (!binding) {
+      throw new Error(
+        "[SixbModels] Generation requires a bound request or worker execution attempt."
+      )
+    }
+    const { requesterGroupIds } = await ensureExecutionRecord(
+      runtime.storage.executions,
+      executionRecordInputFromRuntime({
+        execution,
+        runtimeAuthorization: runtime.runtimeAuthorization,
+      })
+    )
+    return new AiModelCallRecorder({
+      storage,
+      projectId: runtime.projectId,
+      executionId: execution.id,
+      attempt: binding.attempt,
+      requesterGroupIds,
+      limits: createAiModelCallLimitController({
+        storage,
+        projectId: runtime.projectId,
+        requestedBy: execution.requestedBy,
+        requesterGroupIds,
+      }),
+      recoverAiModelCall: (input) => enqueueAiModelCallRecovery(runtime.queues.agents, input),
+    })
+  }
+
+  function generate<const TShape extends LanguageModelOutputShape | undefined = undefined>(
+    input: LanguageModelGenerateInput<TShape>
+  ): Promise<
+    LanguageModelGenerateResult<
+      TShape extends LanguageModelOutputShape ? InferLanguageModelOutput<TShape> : string
+    >
+  >
+  async function generate(
+    input: LanguageModelGenerateInput<LanguageModelOutputShape | undefined>
+  ): Promise<LanguageModelGenerateResult<unknown>> {
+    assertProviderAccess(runtime, execution, "models.language.generate")
+    const messages = generationMessages(input)
+    if (!binding) {
+      throw new Error(
+        "[SixbModels] Generation requires a bound request or worker execution attempt."
+      )
+    }
+    const signal = input.signal ? AbortSignal.any([binding.signal, input.signal]) : binding.signal
+    signal.throwIfAborted()
+    const selected = input.model
+      ? catalog
+        ? catalog.language.getByRef({
+            provider: input.model.providerId,
+            modelId: input.model.modelId,
+          })?.model
+        : input.model
+      : catalog?.language.default.model
+    if (!selected) {
+      throw new Error(
+        input.model
+          ? `[SixbModels] Model '${input.model.providerId}/${input.model.modelId}' is not configured in models.language.`
+          : "[SixbModels] Configure models.language in createSixb() or supply a model to generate()."
+      )
+    }
+    const output =
+      input.output === undefined
+        ? undefined
+        : languageModelOutput(input.output, runtime.ontology.getValueTypesById())
+    const model = await resolveLanguageModel(selected)
+    const reasoningIssue = modelReasoningSupportIssue(
+      model.definition.capabilities.reasoning,
+      input.reasoning
+    )
+    if (reasoningIssue) throw new UnsupportedModelFeatureError(`[SixbModels] ${reasoningIssue}.`)
+    if (output && model.definition.capabilities.nativeStructuredOutput === false) {
+      throw new UnsupportedModelFeatureError(
+        "[SixbModels] Model does not support native structured output."
+      )
+    }
+    const maxOutputTokens = Math.min(
+      aiModelCallOutputTokenAllowance(input.maxOutputTokens ?? model.definition.maxOutputTokens),
+      model.definition.maxOutputTokens ?? Infinity
+    )
+    if (typeof input.reasoning === "object" && input.reasoning.budgetTokens >= maxOutputTokens) {
+      throw new TypeError("[SixbModels] Output allowance must exceed the reasoning token budget.")
+    }
+    recorder ??= createRecorder()
+    const accounting = await recorder
+    accounting.assertHealthy()
+    signal.throwIfAborted()
+    let event: ModelCallEndEvent | undefined
+    const options = {
+      model: accounting.wrapModel(model),
+      messages,
+      maxSteps: 1,
+      rejectLocalToolCalls: true,
+      maxOutputTokens,
+      reasoning: input.reasoning,
+      caching: input.caching,
+      signal,
+      onModelCallEnd: async (completed: ModelCallEndEvent) => {
+        await accounting.onModelCallEnd(completed)
+        event = completed
+      },
+    }
+    const result = output ? await runModelLoop({ ...options, output }) : await runModelLoop(options)
+    if (result.status === "aborted") {
+      signal.throwIfAborted()
+      throw new DOMException("Model generation aborted", "AbortError")
+    }
+    if (result.finishReason === "error" || result.finishReason === "content-filter") {
+      throw new ModelProviderError(
+        `[SixbModels] Generation ended with '${result.finishReason}'.`,
+        model.providerId,
+        model.modelId
+      )
+    }
+    if (!event)
+      throw new ModelStreamError("[SixbModels] Generation completed without accounting metadata.")
+    return {
+      output: result.output,
+      usage: event.usage,
+      cost: event.cost,
+      callId: event.callId,
+      finishReason: result.finishReason,
+    }
+  }
+
+  const models: ModelsRuntime = {
+    language: { generate },
+  }
+  registerModelExecutionBinding(models, (input) => {
+    binding = { attempt: input.attempt, signal: input.signal }
+  })
+  return models
+}
+
+function generationMessages(
+  input: LanguageModelGenerateInput<LanguageModelOutputShape | undefined>
+): readonly ModelMessage[] {
+  if ((input.prompt === undefined) === (input.messages === undefined)) {
+    throw new TypeError("[SixbModels] Supply exactly one of prompt or messages.")
+  }
+  if (input.prompt !== undefined && typeof input.prompt !== "string") {
+    throw new TypeError("[SixbModels] prompt must be a string.")
+  }
+  if (input.messages !== undefined && !Array.isArray(input.messages)) {
+    throw new TypeError("[SixbModels] messages must be an array.")
+  }
+  if (input.instructions !== undefined && typeof input.instructions !== "string") {
+    throw new TypeError("[SixbModels] instructions must be a string.")
+  }
+  if (
+    input.maxOutputTokens !== undefined &&
+    (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens <= 0)
+  ) {
+    throw new TypeError("[SixbModels] maxOutputTokens must be a positive safe integer.")
+  }
+  if (input.caching !== undefined && input.caching !== "auto" && input.caching !== "off") {
+    throw new TypeError("[SixbModels] caching must be 'auto' or 'off'.")
+  }
+  return [
+    ...(input.instructions === undefined
+      ? []
+      : [{ role: "system" as const, content: input.instructions }]),
+    ...(input.prompt !== undefined
+      ? [{ role: "user" as const, content: [{ type: "text" as const, text: input.prompt }] }]
+      : (input.messages ?? [])),
+  ]
+}

package/src/models/generation-types.ts

@@ -0,0 +1,50 @@
+import type { InferSchemaOrRef, SchemaOrRef } from "../ontology"
+import type { ModelFinishReason, ModelUsage } from "./events"
+import type { LanguageModel, ModelReasoning } from "./language-model"
+import type { ModelMessage } from "./messages"
+import type { ModelCallCost } from "./pricing"
+
+export type LanguageModelOutputShape = Readonly<Record<string, SchemaOrRef>>
+
+export type InferLanguageModelOutput<TShape extends LanguageModelOutputShape> =
+  string extends keyof TShape
+    ? Record<string, unknown>
+    : { -readonly [K in keyof TShape]: InferSchemaOrRef<TShape[K]> }
+
+export type LanguageModelGenerateInput<
+  TShape extends LanguageModelOutputShape | undefined = undefined,
+> = {
+  readonly instructions?: string
+  readonly model?: LanguageModel
+  readonly output?: TShape
+  readonly maxOutputTokens?: number
+  readonly reasoning?: ModelReasoning
+  readonly caching?: "auto" | "off"
+  readonly signal?: AbortSignal
+} & (undefined extends TShape ? unknown : { readonly output: TShape }) &
+  (
+    | { readonly prompt: string; readonly messages?: never }
+    | { readonly messages: readonly ModelMessage[]; readonly prompt?: never }
+  )
+
+export interface LanguageModelGenerateResult<TOutput = string> {
+  readonly output: TOutput
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+  readonly finishReason: ModelFinishReason
+  readonly callId: string
+}
+
+export interface LanguageModelsRuntime {
+  generate<const TShape extends LanguageModelOutputShape | undefined = undefined>(
+    input: LanguageModelGenerateInput<TShape>
+  ): Promise<
+    LanguageModelGenerateResult<
+      TShape extends LanguageModelOutputShape ? InferLanguageModelOutput<TShape> : string
+    >
+  >
+}
+
+export interface ModelsRuntime {
+  readonly language: LanguageModelsRuntime
+}

package/src/models/index.ts

@@ -35,6 +35,14 @@ export type {
   ModelUsage,
 } from "./events"
 export { normalizeModelProviderIds } from "./events"
+export type {
+  InferLanguageModelOutput,
+  LanguageModelGenerateInput,
+  LanguageModelGenerateResult,
+  LanguageModelOutputShape,
+  LanguageModelsRuntime,
+  ModelsRuntime,
+} from "./generation-types"
 export type {
   LanguageModel,
   LanguageModelProvider,

package/src/models/language-model.ts

@@ -43,6 +43,7 @@ export interface ModelCapabilities {
   readonly reasoning?: false | ModelReasoningCapabilities
   readonly localTools?: boolean
   readonly parallelToolCalls?: boolean
+  /** `undefined` is unknown, not an assertion that schema-constrained output is unsupported. */
   readonly nativeStructuredOutput?: boolean
   readonly providerExecutedTools?: boolean
 }
@@ -90,6 +91,8 @@ export interface LanguageModel {
    * retry with an offline snapshot. Invalid definitions and other resolver errors remain fatal.
    */
   resolve?(options?: { readonly offline?: boolean }): Promise<LanguageModel>
+  /** Validate known output constraints without inference. Success does not certify endpoint support. */
+  validateResponseFormat?(format: ModelResponseFormat): void | Promise<void>
   stream(request: LanguageModelRequest): Promise<LanguageModelStream>
 }
 

package/src/models/output.ts

@@ -0,0 +1,45 @@
+import { assertJsonObject } from "../json"
+import { schemaRecordToJsonSchema } from "../ontology/json-schema"
+import { isObjectRefSchema, validateSchemaOrRefValue } from "../ontology/refs"
+import type { ValueType } from "../ontology/types"
+import { isRecord } from "../ontology/validation"
+import { coerceSchemaValueToTyped, normalizeSchemaValue } from "../ontology/validation/normalize"
+import type { LanguageModelOutputShape } from "./generation-types"
+import type { ModelOutput } from "./tools"
+
+export function languageModelOutput(
+  shape: LanguageModelOutputShape,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): ModelOutput<Record<string, unknown>> {
+  if (!isRecord(shape)) throw new TypeError("[SixbModels] output must be a Sixb schema record.")
+  const schema = schemaRecordToJsonSchema({ shape, valueTypesById })
+  assertJsonObject(schema, "model output schema")
+  return {
+    name: "sixb_output",
+    schema,
+    validate(value) {
+      if (!isRecord(value)) throw new TypeError("[SixbModels] Output must be an object.")
+      for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(shape, key)) {
+          throw new TypeError(`[SixbModels] Unknown output field '${key}'.`)
+        }
+      }
+      return Object.fromEntries(
+        Object.entries(shape).map(([key, field]) => {
+          if (!Object.hasOwn(value, key)) {
+            throw new TypeError(`[SixbModels] Missing output field '${key}'.`)
+          }
+          validateSchemaOrRefValue(field, value[key], `output.${key}`, valueTypesById)
+          const output = isObjectRefSchema(field)
+            ? value[key]
+            : coerceSchemaValueToTyped(
+                field,
+                normalizeSchemaValue(field, value[key], `output.${key}`, valueTypesById),
+                valueTypesById
+              )
+          return [key, output]
+        })
+      )
+    },
+  }
+}

package/src/models/resolve.ts

@@ -0,0 +1,27 @@
+import { defineLanguageModel } from "./definitions"
+import { ModelCatalogUnavailableError } from "./errors"
+import type { LanguageModel } from "./language-model"
+
+/** Pin operational metadata once, falling back offline only when the catalog is unavailable. */
+export async function resolveLanguageModel(binding: LanguageModel): Promise<LanguageModel> {
+  const offline =
+    binding.definition.contextWindow !== undefined ||
+    binding.definition.maxInputTokens !== undefined
+  let model: LanguageModel
+  try {
+    model = (await binding.resolve?.({ offline })) ?? binding
+  } catch (cause) {
+    if (offline || !(cause instanceof ModelCatalogUnavailableError)) throw cause
+    model = (await binding.resolve?.({ offline: true })) ?? binding
+  }
+  const definition = defineLanguageModel(model.definition)
+  if (
+    definition.providerId !== binding.providerId ||
+    definition.modelId !== binding.modelId ||
+    model.providerId !== binding.providerId ||
+    model.modelId !== binding.modelId
+  ) {
+    throw new TypeError("[SixbModels] Resolved model identity does not match the selected model.")
+  }
+  return model
+}