@harperfast/harper 5.3.0-beta.3 → 5.3.0-beta.4

package/dist/resources/models/decideHook.d.ts

@@ -0,0 +1,33 @@
+import { type WriteHook, type WriteHookContext } from './embedHook.ts';
+import type { DecideInput, DecideOpts, Decision, DecisionLeaf } from './types.ts';
+export type DecideConfig = {
+    source: string;
+    model: string;
+    confidence?: string;
+    /** A nullable `String` attribute that receives the durable `Decision.id`; the decision is recorded only when this is named (#2852). */
+    decision?: string;
+    instructions?: string;
+    /** Resolved from the attribute type and the directive arguments, and validated, when the schema loads. */
+    schema: DecisionLeaf;
+};
+export type DecideAttribute = {
+    name: string;
+    decide: DecideConfig;
+};
+/**
+ * `null` clears the attribute, its confidence and its decision id; `probability` is required when the
+ * directive names a confidence attribute. `id` must come from a `models.decide` call; an override for a
+ * directive with a `decision` attribute gets it from a `models.decide` call made with `persist: true`.
+ */
+export type DeciderResult = {
+    value: unknown;
+    probability?: number;
+    id?: string;
+};
+export type Decider = (record: any, hook?: WriteHookContext) => Promise<DeciderResult | null | undefined>;
+type DecideFn = (state: DecideInput, schema: DecisionLeaf, opts: DecideOpts) => Promise<Decision>;
+/** Test seam: override the decide function. Pass `undefined` to reset to `Models.decide`. */
+export declare function __setDecideFnForTest(fn: DecideFn | undefined): void;
+export declare function createDefaultDecider(config: DecideConfig): Decider;
+export declare function buildDecideBefore(record: any, context: any, options: any, decideAttributes: DecideAttribute[] | undefined, deciders: Record<string, Decider>): WriteHook | undefined;
+export {};

package/dist/resources/models/decideHook.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__setDecideFnForTest = __setDecideFnForTest;
+exports.createDefaultDecider = createDefaultDecider;
+exports.buildDecideBefore = buildDecideBefore;
+const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
+const decision_ts_1 = require("./decision.js");
+const embedHook_ts_1 = require("./embedHook.js");
+// Lazy-imported so this module can be unit-tested without loading the transaction
+// stack `Models.ts` pulls in. Overridable via `__setDecideFnForTest`.
+let _decideFn;
+function resolveDecideFn() {
+    if (_decideFn)
+        return _decideFn;
+    const { Models } = require('#src/resources/models/Models'); // eslint-disable-line @typescript-eslint/no-var-requires
+    const models = new Models();
+    _decideFn = (state, schema, opts) => models.decide(state, schema, opts);
+    return _decideFn;
+}
+/** Test seam: override the decide function. Pass `undefined` to reset to `Models.decide`. */
+function __setDecideFnForTest(fn) {
+    _decideFn = fn;
+}
+function createDefaultDecider(config) {
+    const { source, model, instructions, schema } = config;
+    const persist = Boolean(config.decision);
+    return async (record, hook) => {
+        const sourceValue = record?.[source];
+        if (sourceValue == null)
+            return null;
+        // An object source is program state the primitive serializes itself; anything else is text.
+        const state = typeof sourceValue === 'object' ? sourceValue : String(sourceValue);
+        const decision = await resolveDecideFn()(state, schema, { model, instructions, signal: hook?.signal, persist });
+        return { value: decision.value, probability: decision.probability, id: decision.id };
+    };
+}
+function buildDecideBefore(record, context, options, decideAttributes, deciders) {
+    if (!decideAttributes || decideAttributes.length === 0)
+        return undefined;
+    const applies = (0, embedHook_ts_1.writeHookApplies)(record, context, options);
+    if (record && typeof record === 'object' && options?.isNotification !== true && context?.alreadyLogged !== true)
+        for (const attr of decideAttributes) {
+            const { decision, source } = attr.decide;
+            if (!decision || !(decision in record))
+                continue;
+            const state = applies ? (0, embedHook_ts_1.sourceState)(record, source) : 'absent';
+            // An outcome report trusts this id, so only a write that derives or clears it may carry it.
+            if (state !== 'value' && state !== 'null')
+                throw new hdbError_ts_1.ClientError(`"${decision}" is written by @decide on "${attr.name}"; a write may carry it only with a value for "${source}"`, 400);
+        }
+    if (!applies)
+        return undefined;
+    let present = false;
+    for (const attr of decideAttributes)
+        if ((0, embedHook_ts_1.sourceState)(record, attr.decide?.source) !== 'absent')
+            present = true;
+    if (!present)
+        return undefined;
+    return (signal) => (0, embedHook_ts_1.runWriteJobs)(decideAttributes.map((attr) => async (jobSignal) => {
+        const { source, confidence, decision, schema } = attr.decide;
+        const state = (0, embedHook_ts_1.sourceState)(record, source);
+        if (state === 'absent' || state === 'op')
+            return;
+        const clear = () => {
+            record[attr.name] = null;
+            if (confidence)
+                record[confidence] = null;
+            if (decision)
+                record[decision] = null;
+        };
+        if (state === 'null')
+            return clear();
+        const decider = deciders[attr.name];
+        // Committing the source without its pair would be indistinguishable from a decision later.
+        if (!decider)
+            throw new Error(`No decider is registered for the @decide attribute "${attr.name}"`);
+        let result;
+        try {
+            result = await decider(record, { signal: jobSignal });
+        }
+        catch (err) {
+            // An aborted job failed because a sibling did; only that failure is worth a log line.
+            throw (0, embedHook_ts_1.sanitizedHookError)('Decider', 'decision', attr.name, err, !jobSignal.aborted);
+        }
+        if (result == null)
+            return clear();
+        // The facade validates `models.decide` output; an author override is checked here so the
+        // stored pair keeps the closed-set guarantee a query relies on.
+        if (!(0, decision_ts_1.isAllowedValue)(schema, result.value))
+            throw new Error(`Decider for attribute "${attr.name}" returned a value outside its @decide set`);
+        if (confidence) {
+            const probability = result.probability;
+            if (!(typeof probability === 'number' && probability >= 0 && probability <= 1))
+                throw new Error(`Decider for attribute "${attr.name}" must return a probability in [0, 1] for its confidence attribute "${confidence}"`);
+            record[attr.name] = result.value;
+            record[confidence] = probability;
+        }
+        else {
+            record[attr.name] = result.value;
+        }
+        if (decision)
+            record[decision] = typeof result.id === 'string' && result.id !== '' ? result.id : null;
+    }), signal);
+}
+//# sourceMappingURL=decideHook.js.map

package/dist/resources/models/decideHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decideHook.js","sourceRoot":"","sources":["../../../resources/models/decideHook.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/decision.d.ts

@@ -0,0 +1,64 @@
+import { ClientError, ServerError } from '../../utility/errors/hdbError.ts';
+import type { DecideInput, Decision, DecisionLeaf, DecisionOutput, DecisionSchema } from './types.ts';
+export declare const MAX_LEAF_VALUES = 255;
+export declare const MAX_OBJECT_FIELDS = 32;
+/** Aggregate allowed values across an object schema; also the ceiling strict structured-output providers place on enum values per request. */
+export declare const MAX_SCHEMA_VALUES = 500;
+export type ObjectDecisionSchema = Extract<DecisionSchema, {
+    type: 'object';
+}>;
+export declare function isObjectSchema(schema: DecisionSchema): schema is ObjectDecisionSchema;
+export declare class DecisionSchemaError extends ClientError {
+    constructor(message: string);
+}
+export declare class DecisionInputError extends ClientError {
+    constructor(message: string);
+}
+/** A backend's output violated the decision contract. A backend error: the facade records it and tries the next candidate. */
+export declare class DecisionContractError extends ServerError {
+    constructor(backendName: string, message: string);
+}
+export declare function validateDecisionSchema(schema: unknown): asserts schema is DecisionSchema;
+/** In the order ties resolve; assumes a validated leaf. */
+export declare function allowedValues(leaf: DecisionLeaf): readonly unknown[];
+/** Assumes a validated leaf. */
+export declare function isAllowedValue(leaf: DecisionLeaf, raw: unknown): boolean;
+export declare function wantsNoMatch(schema: DecisionSchema): boolean;
+/** The text form of a `decide` state, or a `DecisionInputError` for a value no backend could serialize. */
+export declare function stateToText(state: DecideInput): string;
+/**
+ * Check a backend's output against the schema and shape it for the caller: complete distributions
+ * sorted descending (ties keep schema order), the argmax as `value`, per-field marginals for object
+ * schemas. `calibrated` falls back to the backend's capability when the output does not say.
+ * Messages never echo backend-supplied values, because they can reach an error response.
+ */
+export declare function normalizeDecision<T>(schema: DecisionSchema, output: DecisionOutput<unknown>, backendName: string, calibratedDefault: boolean, calibratedNoMatch?: boolean): Omit<Decision<T>, 'id' | 'usage'>;
+/**
+ * The JSON Schema a generative backend is asked to honor for one sample: an object at the root
+ * (leaf answers wrapped as `{ value }`), every property required, no additional properties, and
+ * bounded integers as an explicit enum — the shape strict structured-output modes accept.
+ */
+export declare function toResponseSchema(schema: DecisionSchema): object;
+/**
+ * Parse one generative sample against the schema: the leaf value, or a `{ [property]: value }`
+ * map for object schemas. Throws a plain `Error` naming what did not fit, never quoting the
+ * sample itself; the caller wraps it.
+ */
+export declare function parseDecisionSample(schema: DecisionSchema, content: unknown): unknown;
+export interface SamplePair {
+    value: unknown;
+    noMatch: boolean;
+}
+/** JSON with object keys sorted at every level; array order is kept because enum order is meaning. */
+export declare function canonicalJson(value: unknown): string;
+/** Identity of the schema as the model saw it: the allowed values and the descriptions, nothing else. */
+export declare function hashSchema(schema: DecisionSchema): string;
+/**
+ * The allowed values alone, for validating outcomes against. Descriptions are hashed, never stored,
+ * because they are free text that can carry request data; unknown keys are dropped from both.
+ */
+export declare function scoringSchema(schema: DecisionSchema): DecisionSchema;
+/** A copy of a validated schema with only its known keys, so a call and its record see one schema whatever the caller mutates afterwards. */
+export declare function snapshotSchema(schema: DecisionSchema): DecisionSchema;
+/** sha256 of a caller's per-call text, so decisions made under different instructions do not share an identity. */
+export declare function hashText(text: string): string;