@voltro/ai 0.85.0 → 0.86.0

package/dist/inferenceDispatch.js

@@ -0,0 +1,493 @@
+import { gatewayCostUsd as e, recordAiUsageBestEffort as t } from "./cost.js";
+import { generateObjectJson as n, generateText as r } from "./api.js";
+import { mediaCall as i } from "./mediaCall.js";
+import { generateImage as a, generateSpeech as o, generateVideo as s } from "./media.js";
+import { transcribe as c } from "./transcribe.js";
+import { mediaTaskProvider as l } from "./mediaTaskProvider.js";
+import { AI_INFERENCES_TABLE as u, decideInferenceFailure as d, toQueuedInference as f } from "./inferenceQueue.js";
+import { and as p, eq as m, gt as h, gte as g, lt as _, lte as v, or as y, registerRetention as b, retentionTtlMsFromEnv as x } from "@voltro/database";
+//#region src/inferenceDispatch.ts
+var S = 4, C = 250, w = 5e3, T = 36e5, E = {
+	examined: !1,
+	claimed: 0,
+	succeeded: 0,
+	failed: 0,
+	retried: 0,
+	reclaimed: 0,
+	polled: 0,
+	failures: []
+}, D = (e) => {
+	let t = e instanceof Error ? e.message : String(e);
+	return t.length > 1e3 ? `${t.slice(0, 1e3)}…` : t;
+}, O = (e) => {
+	let t = e;
+	if (typeof t?.retryAfterMillis == "number") return t.retryAfterMillis;
+	if (typeof t?.retryAfter == "number") return t.retryAfter * 1e3;
+}, k = (e) => {
+	if (typeof e != "object" || !e) return;
+	let t = e;
+	return t.__voltro_inference_delivery === 1 && (t.status === "succeeded" || t.status === "failed") && typeof t.attempts == "number" && "payload" in t && (t.errorMessage === null || typeof t.errorMessage == "string") ? e : void 0;
+}, A = (e) => y(p(m("status", "pending"), v("enqueuedAt", new Date(e))), p(m("status", "running"), _("leaseUntil", new Date(e)))), j = 720, M = () => {
+	b({
+		source: "framework",
+		table: u,
+		timeColumn: "completedAt",
+		ttlMs: x(process.env.VOLTRO_AI_INFERENCES_TTL_HOURS, 720),
+		envVar: "VOLTRO_AI_INFERENCES_TTL_HOURS",
+		label: "offloaded inference queue"
+	});
+}, N = async (e, t = {}) => {
+	M();
+	let n = e.now?.() ?? Date.now(), r = t.batch ?? 4, i = t.leaseMs ?? 3e5, a = t.maxAttempts ?? 4, o = e.replicaId ?? `pid-${process.pid}`, s;
+	try {
+		s = await e.store.query({
+			table: u,
+			predicate: A(n),
+			order: [{
+				column: "enqueuedAt",
+				direction: "asc"
+			}],
+			take: r,
+			skip: void 0,
+			projection: void 0
+		});
+	} catch (e) {
+		return {
+			...E,
+			examined: !0,
+			failures: [{
+				id: u,
+				detail: D(e)
+			}]
+		};
+	}
+	if (s.length === 0) return {
+		...E,
+		examined: !0,
+		...await P(e.store, n)
+	};
+	let c = [], h = 0, g = 0, y = 0, b = 0, x = 0, S = 0, C = s.map((r) => async () => {
+		let s = f(r), C = String(r.status) === "running", w = s.fence + 1, T = 0;
+		try {
+			T = await e.store.updateMany(u, {
+				status: "running",
+				leaseUntil: new Date(n + i),
+				claimedBy: o,
+				startedAt: new Date(n),
+				fence: w
+			}, { where: p(m("id", s.id), C ? p(m("status", "running"), _("leaseUntil", new Date(n))) : p(m("status", "pending"), v("enqueuedAt", new Date(n)))) });
+		} catch (e) {
+			c.push({
+				id: s.id,
+				detail: D(e)
+			});
+			return;
+		}
+		if (T !== 1) return;
+		h += 1, C && (x += 1);
+		let E = async (t) => {
+			let n = await e.store.updateMany(u, t, { where: p(m("id", s.id), m("fence", w), m("status", "running")) });
+			return n !== 1 && c.push({
+				id: s.id,
+				detail: `a stale worker (fence ${w}) tried to write; the row has moved on`
+			}), n === 1;
+		}, A = Date.now(), j = async (r) => {
+			c.push({
+				id: s.id,
+				detail: D(r)
+			}), e.log?.warn("ai.infer: recovery deferred without a new submission", {
+				id: s.id,
+				model: s.model,
+				attempts: s.attempts,
+				detail: D(r)
+			}), await E({ leaseUntil: new Date(n + (t.baseDelayMs ?? 1e3)) }).catch(() => !1) && b++;
+		}, M = async (t, n = !1) => {
+			try {
+				if (!n && !await E({
+					result: t,
+					errorMessage: t.errorMessage
+				}) || (await e.resume({
+					executionId: s.executionId,
+					workflowName: s.workflowName,
+					signalName: s.signalName,
+					payload: t.payload
+				}), !await E({
+					status: t.status,
+					result: t.payload,
+					attempts: t.attempts,
+					errorMessage: t.errorMessage,
+					completedAt: /* @__PURE__ */ new Date(),
+					durationMs: Date.now() - A,
+					leaseUntil: null
+				}))) return;
+				t.status === "failed" ? (y++, e.log?.warn("ai.infer: offloaded call gave up", {
+					id: s.id,
+					model: s.model,
+					attempts: t.attempts,
+					detail: t.errorMessage,
+					outcome: t.payload.outcome
+				})) : (g++, e.log?.info("ai.infer: offloaded call completed", {
+					id: s.id,
+					model: s.model,
+					durationMs: Date.now() - A,
+					recoveredDelivery: n
+				}));
+			} catch (e) {
+				await j(e);
+			}
+		}, N = async (e, t, n) => {
+			c.push({
+				id: s.id,
+				detail: e
+			}), await M({
+				__voltro_inference_delivery: 1,
+				status: "failed",
+				attempts: t,
+				errorMessage: e,
+				payload: {
+					__voltro_ai_error: !0,
+					message: e,
+					attempts: t,
+					outcome: n
+				}
+			});
+		}, P = async (e) => {
+			await M({
+				__voltro_inference_delivery: 1,
+				status: "succeeded",
+				payload: e,
+				attempts: s.attempts,
+				errorMessage: null
+			});
+		}, I = s.kind === "media" ? l(s.provider) : void 0, L = !1;
+		try {
+			let n = k(r.result);
+			if (n !== void 0) {
+				await M(n, !0);
+				return;
+			}
+			if (s.kind === "media" && e.persistMedia === void 0) {
+				await N(`inference ${s.id}: no media persistence is wired on this host`, s.attempts, "failed");
+				return;
+			}
+			if (C && s.kind === "media" && s.taskHandle === null && I?.idempotentSubmit !== !0) {
+				await N(`media job ${s.id} was claimed by a worker that was lost before it reported; ` + (I === void 0 ? "the provider has no job lookup, so its outcome is unknown and the job is not submitted again" : "no task handle had reached the row, so its outcome is unknown and the job is not submitted again"), s.attempts, "unknown");
+				return;
+			}
+			if (I !== void 0) {
+				let n = await z(e, {
+					...s,
+					fence: w
+				}, I, E, {
+					pollMs: t.taskPollMs ?? 5e3,
+					timeoutMs: t.taskTimeoutMs ?? 36e5
+				});
+				if (n.kind === "stale") return;
+				if (n.kind === "pending") {
+					await E({
+						status: "pending",
+						leaseUntil: null,
+						enqueuedAt: new Date(Date.now() + n.delayMs)
+					}).catch(() => !1) && (S += 1);
+					return;
+				}
+				if (n.kind === "failed") {
+					if (!n.retryable) {
+						await N(n.detail, s.attempts + 1, n.outcome ?? "failed");
+						return;
+					}
+					throw L = !0, Error(n.detail);
+				}
+				await P(n.payload);
+				return;
+			}
+			await P((await F(e, {
+				...s,
+				fence: w
+			})).payload);
+		} catch (e) {
+			if (s.kind === "media" && !L) {
+				await j(e);
+				return;
+			}
+			let n = d({
+				attempts: s.attempts,
+				maxAttempts: a,
+				baseDelayMs: t.baseDelayMs ?? 1e3,
+				maxDelayMs: t.maxDelayMs ?? 3e4,
+				retryAfterMs: O(e)
+			}), r = D(e);
+			if (c.push({
+				id: s.id,
+				detail: r
+			}), n.kind === "retry") {
+				await E({
+					status: "pending",
+					attempts: n.attempts,
+					errorMessage: r,
+					leaseUntil: null,
+					enqueuedAt: new Date(Date.now() + n.delayMs),
+					taskHandle: null,
+					taskSubmittedAt: null
+				}).catch(() => !1) && (b += 1);
+				return;
+			}
+			c.pop(), await N(r, n.attempts, "failed");
+		}
+	});
+	await Promise.all(C.map((e) => e()));
+	let w = h === 0 ? await P(e.store, n) : {};
+	return {
+		examined: !0,
+		claimed: h,
+		succeeded: g,
+		failed: y,
+		retried: b,
+		reclaimed: x,
+		polled: S,
+		failures: c,
+		...w
+	};
+}, P = async (e, t) => {
+	let n = async (t, n) => {
+		let [r] = await e.query({
+			table: u,
+			predicate: t,
+			order: [{
+				column: n,
+				direction: "asc"
+			}],
+			take: 1,
+			skip: void 0,
+			projection: void 0
+		}), i = r?.[n], a = i instanceof Date ? i.getTime() : typeof i == "string" || typeof i == "number" ? new Date(i).getTime() : NaN;
+		return Number.isFinite(a) ? a : void 0;
+	};
+	try {
+		let [e, r] = await Promise.all([n(p(m("status", "pending"), h("enqueuedAt", new Date(t))), "enqueuedAt"), n(p(m("status", "running"), g("leaseUntil", new Date(t))), "leaseUntil")]), i = [e, r === void 0 ? void 0 : r + 1].filter((e) => e !== void 0);
+		return { nextDueAt: i.length === 0 ? null : Math.min(...i) };
+	} catch {
+		return {};
+	}
+}, F = async (e, t) => {
+	let i = {
+		name: t.provider,
+		model: t.model
+	}, a = {
+		prompt: t.prompt,
+		provider: i,
+		...t.system === null ? {} : { system: t.system },
+		...t.maxTokens === null ? {} : { maxTokens: t.maxTokens },
+		...t.providerOptions !== null && t.providerOptions !== void 0 ? { providerOptions: t.providerOptions } : {}
+	};
+	if (t.kind === "transcription") {
+		let n = t.transcription;
+		if (n === null) throw Error(`inference ${t.id} is kind 'transcription' but carries no source`);
+		let r = await e.run(c({
+			...n,
+			provider: i,
+			...e.resolveTranscriptionRef === void 0 ? {} : { resolveRef: e.resolveTranscriptionRef }
+		}));
+		return await B(e, t, "transcribe", { usage: {} }), { payload: r };
+	}
+	if (t.kind === "media") return { payload: await I(e, t, i) };
+	if (t.kind === "object") {
+		if (t.jsonSchema === null) throw Error(`inference ${t.id} is kind 'object' but carries no jsonSchema`);
+		let r = await e.run(n({
+			...a,
+			jsonSchema: t.jsonSchema
+		}));
+		return await B(e, t, "generateObject", r), { payload: r.object };
+	}
+	let o = await e.run(r(a));
+	return await B(e, t, "generateText", o), { payload: {
+		text: o.text,
+		inputTokens: o.usage.inputTokens ?? null,
+		outputTokens: o.usage.outputTokens ?? null,
+		totalTokens: o.usage.totalTokens ?? null
+	} };
+}, I = async (e, t, n) => {
+	let r = t.media;
+	if (r === null) throw Error(`inference ${t.id} is kind 'media' but carries no job`);
+	let i = L(e, t), c = r.params;
+	if (r.modality === "image") {
+		let o = await e.run(a({
+			prompt: t.prompt,
+			provider: n,
+			...c,
+			...Object.keys(r.inputs).length > 0 ? { inputs: r.inputs } : {}
+		}));
+		await B(e, t, "generateImage", {
+			usage: o.usage ?? {},
+			providerMetadata: o.providerMetadata
+		});
+		let s = [];
+		for (let [e, t] of o.images.entries()) s.push(await i(e, t));
+		return {
+			artifacts: s,
+			usage: o.usage ?? null,
+			providerMetadata: o.providerMetadata ?? null
+		};
+	}
+	if (r.modality === "video") {
+		let a = await e.run(s({
+			prompt: t.prompt,
+			provider: n,
+			params: c,
+			...Object.keys(r.inputs).length > 0 ? { inputs: r.inputs } : {}
+		}));
+		return await B(e, t, "generateVideo", {
+			usage: a.usage ?? {},
+			providerMetadata: a.providerMetadata
+		}), {
+			artifacts: [await i(0, a.video)],
+			usage: a.usage ?? null,
+			providerMetadata: a.providerMetadata ?? null
+		};
+	}
+	let l = await e.run(o({
+		text: t.prompt,
+		provider: n,
+		...c
+	}));
+	return await B(e, t, "generateSpeech", {
+		usage: l.usage ?? {},
+		providerMetadata: l.providerMetadata
+	}), {
+		artifacts: [await i(0, l.audio)],
+		usage: l.usage ?? null,
+		providerMetadata: l.providerMetadata ?? null
+	};
+}, L = (e, t) => {
+	let n = t.media?.persist ?? {}, r = e.persistMedia;
+	if (r === void 0) throw Error(`inference ${t.id} is a media job, but no media persistence is wired: install the storage plugin (it provides the mediaPersist capability) or pass persistMedia to the dispatcher`);
+	let i = (e) => `${t.id}#${t.attempts}#${e}`;
+	return async (e, a) => {
+		if (a.url !== void 0) {
+			if (r.ingestUrl === void 0) return {
+				url: a.url,
+				refId: null,
+				mediaType: a.mediaType
+			};
+			let o = await r.ingestUrl({
+				...n,
+				url: a.url,
+				tenantId: t.tenantId,
+				operationId: i(e)
+			});
+			return {
+				url: o.url,
+				refId: o.refId,
+				mediaType: a.mediaType
+			};
+		}
+		if (a.data === void 0) throw Error(`inference ${t.id}: the provider returned an artifact with neither bytes nor a URL`);
+		let o = typeof a.data == "string" ? Uint8Array.from(Buffer.from(a.data, "base64")) : a.data, s = await r.put({
+			...n,
+			bytes: o,
+			mediaType: a.mediaType,
+			tenantId: t.tenantId,
+			operationId: i(e)
+		});
+		return {
+			url: s.url,
+			refId: s.refId,
+			mediaType: a.mediaType
+		};
+	};
+}, R = (e) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return !1;
+	try {
+		return typeof JSON.stringify(e) == "string";
+	} catch {
+		return !1;
+	}
+}, z = async (e, t, n, r, a) => {
+	let o = t.media;
+	if (o === null) throw Error(`inference ${t.id} is kind 'media' but carries no job`);
+	let s = L(e, t), c = {
+		modality: o.modality,
+		prompt: t.prompt,
+		...t.model === "unknown" ? {} : { model: t.model },
+		params: o.params,
+		inputs: o.inputs,
+		...t.providerOptions !== null && t.providerOptions !== void 0 ? { providerOptions: t.providerOptions } : {},
+		tenantId: t.tenantId,
+		idempotencyKey: `${t.id}#${t.attempts}`
+	}, l = t.taskHandle, u = t.taskSubmittedAt;
+	if (u !== null && Date.now() - u.getTime() > a.timeoutMs) return {
+		kind: "failed",
+		retryable: !1,
+		detail: `media task ${t.id} is still pending after ${Math.round(a.timeoutMs / 1e3)}s at provider '${t.provider}'; the run is not kept waiting past the task timeout`
+	};
+	if (l === null) {
+		if (u === null && (u = /* @__PURE__ */ new Date(), !await r({ taskSubmittedAt: u }))) return { kind: "stale" };
+		let a = await e.run(i((e) => n.submit({
+			...c,
+			abortSignal: e
+		})));
+		if (!R(a)) return {
+			kind: "failed",
+			retryable: !1,
+			outcome: "unknown",
+			detail: `media task provider '${t.provider}' returned a task handle that cannot be stored as JSON (a plain object is required); the job cannot be found again`
+		};
+		if (!await r({
+			taskHandle: a,
+			taskSubmittedAt: u
+		})) return { kind: "stale" };
+		l = a;
+	}
+	if (u !== null && Date.now() - u.getTime() > a.timeoutMs) return {
+		kind: "failed",
+		retryable: !1,
+		detail: `media task ${t.id} is still pending after ${Math.round(a.timeoutMs / 1e3)}s at provider '${t.provider}'; the run is not kept waiting past the task timeout`
+	};
+	let d = await e.run(i((e) => n.poll(l, {
+		...c,
+		abortSignal: e
+	})));
+	if (d.status === "pending") return {
+		kind: "pending",
+		delayMs: Math.max(a.pollMs, d.retryAfterMs ?? 0)
+	};
+	if (d.status === "failed") return {
+		kind: "failed",
+		retryable: d.retryable === !0,
+		detail: `media task provider '${t.provider}' failed the job: ${d.message}`
+	};
+	await B(e, t, `generate${o.modality[0].toUpperCase()}${o.modality.slice(1)}`, {
+		usage: d.usage ?? {},
+		providerMetadata: d.providerMetadata
+	});
+	let f = [];
+	for (let [e, t] of d.artifacts.entries()) f.push(await s(e, t));
+	return {
+		kind: "done",
+		payload: {
+			artifacts: f,
+			usage: d.usage ?? null,
+			providerMetadata: d.providerMetadata ?? null
+		}
+	};
+}, B = async (n, r, i, a) => {
+	let o = e(a.providerMetadata);
+	await n.run(t(n.store, {
+		provider: r.provider,
+		model: r.model,
+		operation: i,
+		agent: r.stepName,
+		requestId: r.id,
+		attempt: r.attempts,
+		usage: a.usage,
+		...r.tenantId === null ? {} : { tenantId: r.tenantId },
+		...o === void 0 ? {} : { actualCostUsd: o },
+		...r.promptId !== null && r.promptDigest !== null ? { prompt: {
+			promptId: r.promptId,
+			digest: r.promptDigest,
+			...r.promptRevision === null ? {} : { revision: r.promptRevision }
+		} } : {}
+	}));
+};
+//#endregion
+export { S as DEFAULT_INFERENCE_CONCURRENCY, C as DEFAULT_INFERENCE_POLL_MS, j as DEFAULT_INFERENCE_RETENTION_HOURS, w as DEFAULT_MEDIA_TASK_POLL_MS, T as DEFAULT_MEDIA_TASK_TIMEOUT_MS, N as dispatchInferences };

package/dist/inferenceQueue.js

@@ -0,0 +1,96 @@
+import { id as e, integer as t, json as n, table as r, text as i, timestamp as a } from "@voltro/database";
+import { createHash as o } from "node:crypto";
+//#region src/inferenceQueue.ts
+var s = "_voltro_ai_inferences", c = r(s, {
+	id: e({ prefix: "aiinf" }),
+	tenantId: i().nullable(),
+	executionId: i(),
+	workflowName: i(),
+	runId: i().nullable(),
+	signalName: i(),
+	stepName: i(),
+	status: i().oneOf([
+		"pending",
+		"running",
+		"succeeded",
+		"failed"
+	]).default("pending"),
+	kind: i().oneOf([
+		"text",
+		"object",
+		"transcription",
+		"media"
+	]).default("text"),
+	provider: i(),
+	model: i(),
+	prompt: i(),
+	system: i().nullable(),
+	promptId: i().nullable(),
+	promptDigest: i().nullable(),
+	promptRevision: t().nullable(),
+	maxTokens: t().nullable(),
+	providerOptions: n().nullable(),
+	jsonSchema: n().nullable(),
+	transcription: n().nullable(),
+	media: n().nullable(),
+	taskHandle: n().nullable(),
+	taskSubmittedAt: a().nullable(),
+	result: n().nullable(),
+	errorMessage: i().nullable(),
+	attempts: t().default(0),
+	fence: t().default(0),
+	leaseUntil: a().nullable(),
+	claimedBy: i().nullable(),
+	queuedAt: a().nullable(),
+	enqueuedAt: a().default("now"),
+	startedAt: a().nullable(),
+	completedAt: a().nullable(),
+	durationMs: t().nullable()
+}).index(["status", "enqueuedAt"]).index(["status", "leaseUntil"]).index(["executionId"]).index(["tenantId"]), l = 3e5, u = 4, d = (e, t) => {
+	let n = typeof e == "number" ? e : Number(e);
+	return Number.isFinite(n) ? Math.trunc(n) : t;
+}, f = (e) => e == null ? null : String(e), p = (e) => {
+	if (e instanceof Date) return e;
+	if (typeof e == "string" || typeof e == "number") {
+		let t = new Date(e);
+		return Number.isNaN(t.getTime()) ? null : t;
+	}
+	return null;
+}, m = (e) => ({
+	id: String(e.id),
+	tenantId: f(e.tenantId),
+	executionId: String(e.executionId),
+	workflowName: String(e.workflowName),
+	runId: f(e.runId),
+	signalName: String(e.signalName),
+	stepName: String(e.stepName),
+	kind: e.kind === "object" ? "object" : e.kind === "transcription" ? "transcription" : e.kind === "media" ? "media" : "text",
+	provider: String(e.provider),
+	model: String(e.model),
+	prompt: String(e.prompt ?? ""),
+	system: f(e.system),
+	promptId: f(e.promptId),
+	promptDigest: f(e.promptDigest),
+	promptRevision: e.promptRevision === null || e.promptRevision === void 0 ? null : d(e.promptRevision, 0),
+	maxTokens: e.maxTokens === null || e.maxTokens === void 0 ? null : d(e.maxTokens, 0),
+	providerOptions: e.providerOptions ?? null,
+	jsonSchema: e.jsonSchema ?? null,
+	transcription: e.transcription ?? null,
+	media: e.media ?? null,
+	taskHandle: typeof e.taskHandle == "object" ? e.taskHandle : null,
+	taskSubmittedAt: p(e.taskSubmittedAt),
+	attempts: d(e.attempts, 0),
+	fence: d(e.fence, 0)
+}), h = (e) => {
+	let t = e.attempts + 1;
+	return t >= e.maxAttempts ? {
+		kind: "give-up",
+		attempts: t
+	} : {
+		kind: "retry",
+		attempts: t,
+		delayMs: e.retryAfterMs !== void 0 && e.retryAfterMs > 0 ? e.retryAfterMs : Math.min(e.baseDelayMs * 2 ** (t - 1), e.maxDelayMs)
+	};
+}, g = (e) => `voltro.ai.infer:${e}`, _ = (e, t) => `aiinf_${o("sha256").update(`${e}\u0000${t}`).digest("hex").slice(0, 40)}`;
+//#endregion
+export { s as AI_INFERENCES_TABLE, u as DEFAULT_INFERENCE_ATTEMPTS, l as DEFAULT_INFERENCE_LEASE_MS, c as aiInferencesTable, h as decideInferenceFailure, g as inferenceSignalName, _ as offloadedInferenceId, m as toQueuedInference };

package/dist/jsonOutputValidation.js

@@ -0,0 +1,27 @@
+import { jsonSchema as e } from "ai";
+import { Ajv as t } from "ajv";
+import { Ajv2019 as n } from "ajv/dist/2019.js";
+import { Ajv2020 as r } from "ajv/dist/2020.js";
+import i from "ajv-formats";
+//#region src/jsonOutputValidation.ts
+var a = (a) => {
+	let o = structuredClone(a), s = {
+		strict: !0,
+		strictTypes: !1,
+		strictTuples: !1,
+		strictRequired: !1,
+		allowUnionTypes: !0
+	}, c = o.$schema, l = c === "https://json-schema.org/draft/2020-12/schema" ? new r(s) : c === "https://json-schema.org/draft/2019-09/schema" ? new n(s) : new t(s);
+	i(l);
+	let u = l.compile(o);
+	if ("$async" in u && u.$async === !0) throw Error("asynchronous output schemas are not supported");
+	return e(o, { validate: (e) => u(e) ? {
+		success: !0,
+		value: e
+	} : {
+		success: !1,
+		error: /* @__PURE__ */ Error("model output does not satisfy the declared JSON Schema")
+	} });
+};
+//#endregion
+export { a as validatedOutputSchema };