@sixb/core 0.1.11 → 0.1.12

package/src/models/catalog.ts

@@ -1,17 +1,32 @@
 import { RuntimeError } from "../runtime/errors"
+import { indexModelBindings } from "./catalog-index"
+import { createDecisionCatalog, type DecisionModelCatalog } from "./decision/catalog"
+import type { DecisionModel } from "./decision/types"
 import {
   defineLanguageModel,
   type LanguageModelDefinition,
   type ModelDefinition,
 } from "./definitions"
+import { assertEmbeddingModel, type EmbeddingModel } from "./embedding-model"
 import type { LanguageModel } from "./language-model"
 
-/** Stable identity of one configured language-model binding. */
-export interface LanguageModelRef {
+/** Stable identity of a configured provider binding. */
+export interface ModelRef {
   readonly provider: string
   readonly modelId: string
 }
 
+export type LanguageModelRef = ModelRef
+
+export interface EmbeddingModelEntry extends ModelRef {
+  readonly model: EmbeddingModel
+}
+
+export interface EmbeddingModelCatalog {
+  list(): readonly EmbeddingModelEntry[]
+  getByRef(ref: ModelRef): EmbeddingModelEntry | null
+}
+
 /** The configured language models, with the project default. */
 export interface LanguageModelCatalog {
   readonly default: LanguageModelEntry
@@ -32,61 +47,74 @@ export interface LanguageModelEntry extends LanguageModelRef {
 
 /** Models a project allows Sixb to use, organized by technical model kind. */
 export interface ModelCatalog {
-  readonly language: LanguageModelCatalog
+  readonly language?: LanguageModelCatalog
+  readonly decision?: DecisionModelCatalog
+  readonly embedding: EmbeddingModelCatalog
 }
 
 export interface ModelCatalogInput {
   /** Ordered; the first entry is the project default. */
-  readonly language: readonly LanguageModel[]
+  readonly language?: readonly LanguageModel[]
+  /** Ordered; the first entry is the project default decision model. */
+  readonly decision?: readonly DecisionModel[]
+  readonly embedding?: readonly EmbeddingModel[]
 }
 
-/** Build the immutable project model catalog. Rejects invalid, duplicate, and empty catalogs. */
+// Only statically required inputs make their corresponding catalogs required.
+type ConfiguredModelKinds<TInput> = {
+  [Kind in keyof ModelCatalog]-?: [TInput] extends [Record<Kind, readonly unknown[]>] ? Kind : never
+}[keyof ModelCatalog]
+
+export type ModelCatalogFor<TInput extends ModelCatalogInput> = ModelCatalog &
+  Required<Pick<ModelCatalog, ConfiguredModelKinds<TInput>>>
+
+/** Build an immutable catalog while preserving each family's default and empty-list rules. */
+export function createModelCatalog<TInput extends ModelCatalogInput>(
+  input: TInput
+): ModelCatalogFor<TInput>
 export function createModelCatalog(input: ModelCatalogInput): ModelCatalog {
-  if (!Array.isArray(input?.language)) {
-    throw new RuntimeError("[Sixb] 'models.language' must be an array of Sixb language models.")
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new RuntimeError("[Sixb] 'models' must be a model catalog configuration.")
   }
 
-  const entries: LanguageModelEntry[] = []
-  const byProvider = new Map<string, Map<string, LanguageModelEntry>>()
+  const language = createLanguageCatalog(input.language)
+  const embedding = createEmbeddingCatalog(input.embedding)
+  const decision = createDecisionCatalog(input.decision)
 
-  for (const [index, model] of input.language.entries()) {
-    assertLanguageModel(model, index)
+  if (!language && !decision && embedding.list().length === 0) {
+    throw new RuntimeError("[Sixb] Configure at least one language, embedding or decision model.")
+  }
 
-    let byModelId = byProvider.get(model.providerId)
-    if (byModelId === undefined) {
-      byModelId = new Map()
-      byProvider.set(model.providerId, byModelId)
-    }
-    if (byModelId.has(model.modelId)) {
-      throw new RuntimeError(
-        `[Sixb] Duplicate language model '${model.providerId}/${model.modelId}' in 'models'. Each provider and model id pair may be configured once.`
-      )
-    }
+  return Object.freeze({ language, embedding, decision })
+}
 
-    const entry = Object.freeze({
-      provider: model.providerId,
-      modelId: model.modelId,
-      model,
-    })
-    byModelId.set(model.modelId, entry)
-    entries.push(entry)
+function createLanguageCatalog(
+  models: readonly LanguageModel[] | undefined
+): LanguageModelCatalog | undefined {
+  if (models === undefined) return undefined
+  if (!Array.isArray(models)) {
+    throw new RuntimeError("[Sixb] 'models.language' must be an array of Sixb language models.")
   }
 
-  const [defaultEntry] = entries
-  if (defaultEntry === undefined) {
+  const index = indexModelBindings(models, "language", assertLanguageModel)
+  const [defaultEntry] = index.list()
+  if (!defaultEntry) {
     throw new RuntimeError(
-      "[Sixb] 'models.language' needs at least one model. Configure one or omit 'models' from createSixb()."
+      "[Sixb] 'models.language' needs at least one model. Configure one or omit 'models.language'."
     )
   }
 
-  const listed = Object.freeze(entries.slice())
-  const language: LanguageModelCatalog = Object.freeze({
-    default: defaultEntry,
-    list: () => listed,
-    getByRef: (ref: LanguageModelRef) => byProvider.get(ref.provider)?.get(ref.modelId) ?? null,
-  })
+  return Object.freeze({ ...index, default: defaultEntry })
+}
+
+function createEmbeddingCatalog(
+  models: readonly EmbeddingModel[] | undefined
+): EmbeddingModelCatalog {
+  if (models !== undefined && !Array.isArray(models)) {
+    throw new RuntimeError("[Sixb] models.embedding must be an array of embedding models.")
+  }
 
-  return Object.freeze({ language })
+  return indexModelBindings(models ?? [], "embedding", assertEmbeddingModel)
 }
 
 function assertLanguageModel(model: unknown, index: number): asserts model is LanguageModel {

package/src/models/decision/catalog.ts

@@ -0,0 +1,32 @@
+import { RuntimeError } from "../../runtime/errors"
+import type { ModelRef } from "../catalog"
+import { indexModelBindings } from "../catalog-index"
+import type { DecisionModel } from "./types"
+import { assertDecisionModel } from "./validation"
+
+export interface DecisionModelEntry extends ModelRef {
+  readonly model: DecisionModel
+}
+
+export interface DecisionModelCatalog {
+  readonly default: DecisionModelEntry
+  list(): readonly DecisionModelEntry[]
+  getByRef(ref: ModelRef): DecisionModelEntry | null
+}
+
+export function createDecisionCatalog(
+  models: readonly DecisionModel[] | undefined
+): DecisionModelCatalog | undefined {
+  if (models === undefined) return undefined
+  if (!Array.isArray(models)) {
+    throw new RuntimeError("[Sixb] models.decision must be a nonempty array of decision models.")
+  }
+
+  const index = indexModelBindings(models, "decision", assertDecisionModel)
+  const [defaultEntry] = index.list()
+  if (!defaultEntry) {
+    throw new RuntimeError("[Sixb] models.decision must be a nonempty array of decision models.")
+  }
+
+  return Object.freeze({ ...index, default: defaultEntry })
+}

package/src/models/decision/errors.ts

@@ -0,0 +1,18 @@
+import { ModelProviderError } from "../errors"
+import type { DecisionModelResponseMetadata } from "./types"
+
+export class DecisionModelResponseError extends ModelProviderError {
+  constructor(
+    message: string,
+    providerId: string,
+    modelId: string,
+    readonly metadata: DecisionModelResponseMetadata,
+    options?: ErrorOptions
+  ) {
+    super(message, providerId, modelId, {
+      ...options,
+      code: "invalid_decision_response",
+      retryable: false,
+    })
+  }
+}

package/src/models/decision/output.ts

@@ -0,0 +1,101 @@
+import type { SchemaOrRef } from "../../ontology/refs"
+import type {
+  ChoiceQuestion,
+  DecisionContent,
+  DecisionQuestion,
+  DecisionQuestions,
+  ScoreQuestion,
+} from "./types"
+import { assertDecisionQuestions } from "./validation"
+
+type RequiredField<S extends SchemaOrRef> = { required: true; schema: S }
+type ChoiceAnswerSchema<C extends Readonly<Record<string, DecisionContent | null>>> = {
+  type: "object"
+  properties: {
+    choice: RequiredField<{
+      type: "enum"
+      valueType: "string"
+      values: `${Extract<keyof C, string | number>}`[]
+    }>
+    probabilities: RequiredField<{
+      type: "object"
+      properties: { [K in keyof C]: RequiredField<"double"> }
+    }>
+    confidence: { schema: "double" }
+  }
+}
+export type DecisionAnswerSchema<Q extends DecisionQuestion> =
+  Q extends ChoiceQuestion<infer C>
+    ? ChoiceAnswerSchema<C>
+    : Q extends ScoreQuestion
+      ? {
+          type: "object"
+          properties: {
+            score: RequiredField<"double">
+            probabilities: RequiredField<{ type: "array"; items: "double" }>
+            confidence: { schema: "double" }
+          }
+        }
+      : { type: "object"; properties: { probability: RequiredField<"double"> } }
+export type DecisionOutputShape<Q extends DecisionQuestions> = {
+  -readonly [K in keyof Q]: DecisionAnswerSchema<Q[K]>
+}
+
+/** Ordinary Sixb output schemas for actions/workflow steps; evaluate() validates distributions. */
+export function decisionOutput<const Q extends DecisionQuestions>(
+  questions: Q
+): DecisionOutputShape<Q> {
+  assertDecisionQuestions(questions)
+  const result: Record<string, SchemaOrRef> = Object.fromEntries(
+    Object.entries(questions).map(([key, q]) => {
+      if (q.type === "probability")
+        return [
+          key,
+          {
+            type: "object",
+            properties: { probability: { required: true, schema: "double" } },
+          },
+        ]
+      const confidence = { schema: "double" as const }
+      if (q.type === "score")
+        return [
+          key,
+          {
+            type: "object",
+            properties: {
+              score: { required: true, schema: "double" },
+              probabilities: { required: true, schema: { type: "array", items: "double" } },
+              confidence,
+            },
+          },
+        ]
+      return [
+        key,
+        {
+          type: "object",
+          properties: {
+            choice: {
+              required: true,
+              schema: { type: "enum", valueType: "string", values: Object.keys(q.options) },
+            },
+            probabilities: {
+              required: true,
+              schema: {
+                type: "object",
+                properties: Object.fromEntries(
+                  Object.keys(q.options).map((option) => [
+                    option,
+                    { required: true, schema: "double" },
+                  ])
+                ),
+              },
+            },
+            confidence,
+          },
+        },
+      ]
+    })
+  )
+  // Each branch builds the corresponding schema while retaining literal option keys in the type.
+  return result as DecisionOutputShape<Q>
+}

package/src/models/decision/questions.ts

@@ -0,0 +1,29 @@
+import type { ChoiceQuestion, DecisionContent, ProbabilityQuestion, ScoreQuestion } from "./types"
+import { assertDecisionQuestions } from "./validation"
+
+/** Plain serializable descriptors; no registration or inference takes place here. */
+export const question = {
+  choice<const TOptions extends Readonly<Record<string, DecisionContent | null>>>(input: {
+    readonly instructions: DecisionContent
+    readonly options: TOptions
+  }): ChoiceQuestion<TOptions> {
+    const result = { ...input, type: "choice" as const }
+    assertDecisionQuestions({ question: result })
+    return result
+  },
+  score<
+    const TLevels extends readonly [DecisionContent, DecisionContent, ...DecisionContent[]],
+  >(input: {
+    readonly instructions: DecisionContent
+    readonly levels: TLevels
+  }): ScoreQuestion<TLevels> {
+    const result = { ...input, type: "score" as const }
+    assertDecisionQuestions({ question: result })
+    return result
+  },
+  probability(instructions: DecisionContent): ProbabilityQuestion {
+    const result = { type: "probability" as const, instructions }
+    assertDecisionQuestions({ question: result })
+    return result
+  },
+}

package/src/models/decision/runtime.ts

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto"
+import { assertProviderAccess } from "../../authorization"
+import type { ExecutionContext } from "../../execution"
+import { cloneJsonValue } from "../../json"
+import type { SixbRuntimeContext } from "../../runtime/types"
+import type { ModelCatalog } from "../catalog"
+import { AI_MODEL_CALL_OUTPUT_TOKEN_ALLOWANCE } from "../execution/model-call-admission"
+import type { AiModelCallRecorder } from "../execution/model-call-recorder"
+import type { ModelExecutionSession } from "../execution/session"
+import { estimateModelCall } from "../pricing"
+import { DecisionModelResponseError } from "./errors"
+import type {
+  DecisionAnswers,
+  DecisionModel,
+  DecisionModelRequest,
+  DecisionModelResponseMetadata,
+  DecisionModelResult,
+  DecisionModelsRuntime,
+} from "./types"
+import {
+  assertDecisionContent,
+  assertDecisionModel,
+  assertDecisionQuestions,
+  assertDecisionSupport,
+  validateDecisionAnswers,
+} from "./validation"
+
+export function createDecisionRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  catalog: ModelCatalog | undefined,
+  session: ModelExecutionSession
+): DecisionModelsRuntime {
+  return {
+    async evaluate(input) {
+      assertProviderAccess(runtime, execution, "models.decision.evaluate")
+      assertDecisionContent(input.input, "input")
+      assertDecisionQuestions(input.questions)
+
+      // Snapshot before the first await; caller edits cannot change an admitted request.
+      const state = cloneJsonValue(input.input)
+      assertDecisionContent(state, "input")
+      const questions = structuredClone(input.questions)
+      const signal = session.signal(input.signal)
+      signal.throwIfAborted()
+
+      const binding = resolveDecisionModel(catalog, input.model)
+      assertDecisionModel(binding)
+      assertDecisionSupport(binding, questions)
+
+      const accounting = await session.accounting()
+      accounting.assertHealthy()
+      signal.throwIfAborted()
+      const model = binding.resolve ? await binding.resolve() : binding
+      assertDecisionModel(model)
+      if (model.providerId !== binding.providerId || model.modelId !== binding.modelId) {
+        throw new TypeError(
+          "[SixbModels] Resolved decision model identity does not match the selected model."
+        )
+      }
+      assertDecisionSupport(model, questions)
+      signal.throwIfAborted()
+      const request = { input: state, questions, signal }
+      const callId = await admitDecisionCall(accounting, model, request)
+
+      let result: DecisionModelResult
+      try {
+        signal.throwIfAborted()
+        result = await model.evaluate(request)
+      } catch (error) {
+        const metadata = error instanceof DecisionModelResponseError ? error.metadata : {}
+        await recordDecision(accounting, model, callId, metadata)
+        throw error
+      }
+
+      // Account before validation or cancellation can reject a billable response.
+      const event = await recordDecision(accounting, model, callId, result ?? {})
+      signal.throwIfAborted()
+
+      let output: DecisionAnswers<typeof input.questions>
+      try {
+        output = validateDecisionAnswers(
+          questions,
+          result?.output,
+          model.definition.capabilities.answerDecimalPlaces
+        )
+      } catch (cause) {
+        throw new DecisionModelResponseError(
+          "[SixbModels] Invalid decision response.",
+          model.providerId,
+          model.modelId,
+          result ?? {},
+          { cause }
+        )
+      }
+
+      return {
+        output,
+        callId,
+        ...(event.responseModelId === undefined ? {} : { responseModelId: event.responseModelId }),
+        usage: event.usage,
+        cost: event.cost,
+      }
+    },
+  }
+}
+
+function resolveDecisionModel(
+  catalog: ModelCatalog | undefined,
+  requested: DecisionModel | undefined
+): DecisionModel {
+  if (!requested) {
+    const model = catalog?.decision?.default.model
+    if (!model) {
+      throw new Error("[SixbModels] Configure models.decision or supply a model to evaluate().")
+    }
+    return model
+  }
+
+  if (!catalog) return requested
+
+  // The catalog owns the binding, even when a caller supplies another object with the same ID.
+  const entry = catalog.decision?.getByRef({
+    provider: requested.providerId,
+    modelId: requested.modelId,
+  })
+  if (!entry) {
+    throw new Error(
+      `[SixbModels] Model '${requested.providerId}/${requested.modelId}' is not configured in models.decision.`
+    )
+  }
+  return entry.model
+}
+
+async function admitDecisionCall(
+  accounting: AiModelCallRecorder,
+  model: DecisionModel,
+  request: DecisionModelRequest
+): Promise<string> {
+  const callId = `call_${randomUUID()}`
+  const serialized = JSON.stringify({ input: request.input, questions: request.questions })
+  const tokens = Math.ceil(new TextEncoder().encode(serialized).byteLength / 4)
+
+  // Reservation estimate only; neither an exact context check nor an enforced output cap.
+  const outputTokenAllowance = AI_MODEL_CALL_OUTPUT_TOKEN_ALLOWANCE
+  await accounting.admitCall({
+    callId,
+    providerId: model.providerId,
+    modelId: model.modelId,
+    costEstimator: model.costEstimator,
+    inputTokens: { status: "estimated", tokens, method: "utf8BytesDividedByFour" },
+    outputTokenAllowance,
+    estimatedTotalTokens: tokens + outputTokenAllowance,
+  })
+
+  return callId
+}
+
+async function recordDecision(
+  accounting: AiModelCallRecorder,
+  model: DecisionModel,
+  callId: string,
+  metadata: DecisionModelResponseMetadata
+) {
+  const usage = metadata.usage ?? {}
+  const estimate = estimateModelCall(model, {
+    usage,
+    route: metadata.route,
+    responseModelId: metadata.responseModelId,
+  })
+  const event = {
+    callId,
+    providerId: model.providerId,
+    modelId: model.modelId,
+    responseId: metadata.providerIds?.responseId ?? callId,
+    responseModelId: metadata.responseModelId,
+    providerIds: metadata.providerIds,
+    usage,
+    cost: metadata.reportedCost
+      ? { status: "reported" as const, ...metadata.reportedCost }
+      : estimate,
+    ...(metadata.reportedCost ? { estimate } : {}),
+    route: metadata.route,
+  }
+
+  await accounting.onModelCallEnd(event)
+  return event
+}

package/src/models/decision/types.ts

@@ -0,0 +1,109 @@
+import type { ReadonlyJsonArray, ReadonlyJsonObject } from "../../json"
+import type { ModelDefinition } from "../definitions"
+import type { ModelProviderIds, ModelRoute, ModelUsage } from "../events"
+import type { ModelCallCost, ModelCostEstimator, ModelReportedCost } from "../pricing"
+
+/** Text or structured text. Non-text media must be prepared explicitly by the application. */
+export type DecisionContent = string | ReadonlyJsonObject | ReadonlyJsonArray
+
+export interface ChoiceQuestion<
+  TOptions extends Readonly<Record<string, DecisionContent | null>> = Readonly<
+    Record<string, DecisionContent | null>
+  >,
+> {
+  readonly type: "choice"
+  readonly instructions: DecisionContent
+  readonly options: TOptions
+}
+
+export interface ScoreQuestion<
+  TLevels extends readonly DecisionContent[] = readonly DecisionContent[],
+> {
+  readonly type: "score"
+  readonly instructions: DecisionContent
+  readonly levels: TLevels
+}
+
+export interface ProbabilityQuestion {
+  readonly type: "probability"
+  readonly instructions: DecisionContent
+}
+
+export type DecisionQuestion = ChoiceQuestion | ScoreQuestion | ProbabilityQuestion
+export type DecisionQuestions = Readonly<Record<string, DecisionQuestion>>
+export type DecisionAnswer<TQuestion extends DecisionQuestion> =
+  TQuestion extends ChoiceQuestion<infer TOptions>
+    ? {
+        choice: `${Extract<keyof TOptions, string | number>}`
+        probabilities: { -readonly [K in keyof TOptions]: number }
+        confidence?: number
+      }
+    : TQuestion extends ScoreQuestion
+      ? { score: number; probabilities: number[]; confidence?: number }
+      : { probability: number }
+export type DecisionAnswers<TQuestions extends DecisionQuestions> = {
+  -readonly [K in keyof TQuestions]: DecisionAnswer<TQuestions[K]>
+}
+
+export interface DecisionModelDefinition extends ModelDefinition {
+  readonly kind: "decision"
+  readonly capabilities: {
+    readonly questions: readonly DecisionQuestion["type"][]
+    readonly maxChoices?: number
+    readonly maxScoreLevels?: number
+    /** Independent decimal rounding of returned scores/probabilities; omitted means strict validation. */
+    readonly answerDecimalPlaces?: number
+  }
+}
+
+export interface DecisionModelRequest {
+  readonly input: DecisionContent
+  readonly questions: DecisionQuestions
+  /** Providers must pass cancellation through to their transport. */
+  readonly signal?: AbortSignal
+}
+
+export interface DecisionModelResponseMetadata {
+  readonly usage?: ModelUsage
+  readonly providerIds?: ModelProviderIds
+  readonly responseModelId?: string
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: ModelRoute
+}
+
+export interface DecisionModelResult extends DecisionModelResponseMetadata {
+  /** Decoded answers; Sixb still validates them against the original questions at runtime. */
+  readonly output: DecisionAnswers<DecisionQuestions>
+}
+
+/** An explicit provider binding; declaring it never triggers inference. */
+export interface DecisionModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: DecisionModelDefinition
+  readonly costEstimator?: ModelCostEstimator
+  /** Resolve and pin optional metadata/pricing before admission, without inference. */
+  resolve?(): Promise<DecisionModel>
+  evaluate(request: DecisionModelRequest): Promise<DecisionModelResult>
+}
+
+export interface DecisionEvaluateInput<TQuestions extends DecisionQuestions> {
+  readonly input: DecisionContent
+  readonly questions: TQuestions
+  readonly model?: DecisionModel
+  readonly signal?: AbortSignal
+}
+
+export interface DecisionEvaluateResult<TQuestions extends DecisionQuestions> {
+  readonly output: DecisionAnswers<TQuestions>
+  readonly callId: string
+  readonly responseModelId?: string
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+}
+
+export interface DecisionModelsRuntime {
+  evaluate<const TQuestions extends DecisionQuestions>(
+    input: DecisionEvaluateInput<TQuestions>
+  ): Promise<DecisionEvaluateResult<TQuestions>>
+}