@sixb/core 0.1.11 → 0.1.13

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>>
+}