@posthog/ai 8.15.2 → 8.16.0

package/dist/evaluations/index.mjs

@@ -0,0 +1,1547 @@
+import { randomUUID } from "node:crypto";
+//#region src/evaluations/serialization.ts
+function object(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Expected an object.");
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) throw new TypeError("Expected a plain object.");
+	return value;
+}
+function text(value) {
+	if (typeof value !== "string") throw new TypeError("Expected a string.");
+	for (let i = 0; i < value.length; i++) {
+		const c = value.charCodeAt(i);
+		if (c === 0) throw new TypeError("Strings cannot contain null characters.");
+		if (c >= 55296 && c <= 56319) {
+			const next = value.charCodeAt(++i);
+			if (!(next >= 56320 && next <= 57343)) throw new TypeError("Strings must contain valid Unicode.");
+		} else if (c >= 56320 && c <= 57343) throw new TypeError("Strings must contain valid Unicode.");
+	}
+	return value;
+}
+function identifier(value, max = 255) {
+	const result = text(value);
+	if (!result || [...result].length > max) throw new TypeError(`Expected a nonempty identifier of at most ${max} characters.`);
+	return result;
+}
+function integer(value, minimum = 1, maximum = Number.MAX_SAFE_INTEGER) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new TypeError(`Expected a safe integer between ${minimum} and ${maximum}.`);
+	return value;
+}
+function count(value) {
+	if (typeof value === "bigint") {
+		if (value < 0n || value > 9223372036854775807n) throw new TypeError("Count must fit a nonnegative signed 64-bit integer.");
+		return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : value;
+	}
+	return integer(value, 0);
+}
+function boolean(value) {
+	if (typeof value !== "boolean") throw new TypeError("Expected a boolean.");
+	return value;
+}
+function uuid(value) {
+	const raw = text(value).replace(/^urn:uuid:/i, "").replace(/^\{(.*)\}$/, "$1").replace(/-/g, "");
+	if (!/^[0-9a-f]{32}$/i.test(raw)) throw new TypeError("Expected a UUID.");
+	return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`.toLowerCase();
+}
+function timestamp(value) {
+	if (value instanceof Date) {
+		if (!Number.isFinite(value.getTime())) throw new TypeError("Expected a valid timestamp.");
+		return value.toISOString();
+	}
+	const raw = text(value);
+	const match = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.exec(raw);
+	if (!match) throw new TypeError("Timestamps must include a timezone.");
+	const date = /* @__PURE__ */ new Date(`${match[1]}T${match[2]}${match[4]}`);
+	const day = /* @__PURE__ */ new Date(`${match[1]}T00:00:00Z`);
+	if (!Number.isFinite(date.getTime()) || !Number.isFinite(day.getTime()) || day.toISOString().slice(0, 10) !== match[1] || match[2].startsWith("24:")) throw new TypeError("Expected a valid timestamp.");
+	return date.toISOString().replace(".000Z", `${match[3] ?? ".000"}Z`);
+}
+function json(value, depth = 1, ancestors = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string") return text(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("JSON numbers must be finite.");
+		return value;
+	}
+	if (typeof value !== "object") throw new TypeError("Expected JSON values without automatic conversion.");
+	if (depth > 32 || ancestors.has(value)) throw new TypeError("JSON must be acyclic and at most 32 containers deep.");
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (Reflect.ownKeys(value).some((key) => key !== "length" && (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length))) throw new TypeError("Unexpected array property.");
+			const result = [];
+			for (let i = 0; i < value.length; i++) {
+				const d = Object.getOwnPropertyDescriptor(value, String(i));
+				if (!d || !("value" in d)) throw new TypeError("Sparse arrays and accessors are not JSON.");
+				result.push(json(d.value, depth + 1, ancestors));
+			}
+			return result;
+		}
+		const source = object(value);
+		return Object.fromEntries(Reflect.ownKeys(source).map((key) => {
+			if (typeof key !== "string") throw new TypeError("JSON keys must be strings.");
+			text(key);
+			const d = Object.getOwnPropertyDescriptor(source, key);
+			if (!("value" in d) || !d.enumerable) throw new TypeError("JSON objects must contain enumerable data properties.");
+			return [key, json(d.value, depth + 1, ancestors)];
+		}));
+	} finally {
+		ancestors.delete(value);
+	}
+}
+function metadata(value) {
+	return json(object(value));
+}
+/** Convert losslessly decoded response integers only when JavaScript can retain their value. */
+function responseJSON(value) {
+	function convert(current) {
+		if (typeof current === "bigint") {
+			const number = Number(current);
+			if (!Number.isFinite(number) || BigInt(number) !== current) throw new TypeError("Response JSON integer cannot be represented exactly.");
+			return number;
+		}
+		if (Array.isArray(current)) return current.map(convert);
+		if (current !== null && typeof current === "object") return Object.fromEntries(Object.entries(object(current)).map(([key, v]) => [key, convert(v)]));
+		return current;
+	}
+	return json(convert(value));
+}
+function responseMetadata(value) {
+	object(value);
+	return responseJSON(value);
+}
+/** Internal codec: bigint is allowed only after validation of designated count fields. */
+function encode(value) {
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "number" && Number.isInteger(value)) return BigInt(value).toString();
+	if (Array.isArray(value)) return `[${value.map(encode).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${encode(value[key])}`).join(",")}}`;
+	const encoded = JSON.stringify(value);
+	if (encoded === void 0) throw new TypeError("Cannot encode undefined.");
+	return encoded;
+}
+/** Preserve integer tokens before JSON.parse can round signed-64-bit counters. */
+function decode(source) {
+	JSON.parse(source);
+	const tokens = source.match(/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}[\]:,]/g);
+	let i = 0;
+	function read(depth) {
+		if (depth > 256) throw new TypeError("Response JSON nesting is too deep.");
+		const token = tokens[i++];
+		if (token === "{") {
+			const entries = [];
+			while (tokens[i] !== "}") {
+				const key = JSON.parse(tokens[i++]);
+				i++;
+				entries.push([key, read(depth + 1)]);
+				if (tokens[i] !== ",") break;
+				i++;
+			}
+			i++;
+			return Object.fromEntries(entries);
+		}
+		if (token === "[") {
+			const values = [];
+			while (tokens[i] !== "]") {
+				values.push(read(depth + 1));
+				if (tokens[i] !== ",") break;
+				i++;
+			}
+			i++;
+			return values;
+		}
+		if (/^-?\d+$/.test(token)) {
+			const exact = BigInt(token);
+			if (exact > BigInt(Number.MAX_SAFE_INTEGER) || exact < BigInt(Number.MIN_SAFE_INTEGER)) return exact;
+		}
+		return JSON.parse(token);
+	}
+	return read(0);
+}
+function copy(value) {
+	return structuredClone(value);
+}
+function bytes(value) {
+	return new TextEncoder().encode(value).length;
+}
+function keys(value, allowed) {
+	for (const key of Reflect.ownKeys(value)) {
+		if (typeof key !== "string" || !allowed.includes(key)) throw new TypeError("Unsupported option.");
+		if (!("value" in Object.getOwnPropertyDescriptor(value, key))) throw new TypeError("Options cannot contain accessors.");
+	}
+}
+function defined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+function nullable(value, parse) {
+	return value === null ? null : parse(value);
+}
+function tags(value, limit = 100) {
+	if (!Array.isArray(value) || value.length > limit) throw new TypeError(`Expected at most ${limit} tag names.`);
+	for (let i = 0; i < value.length; i++) if (!Object.hasOwn(value, i)) throw new TypeError("Tag lists cannot be sparse.");
+	return value.map((v) => {
+		const s = text(v);
+		identifier(s.trim());
+		return s;
+	});
+}
+function responseTags(value) {
+	if (!Array.isArray(value)) throw new TypeError("Expected tags.");
+	return value.map(text);
+}
+function tagParams(value, match = "any") {
+	if (match !== "any" && match !== "all") throw new TypeError("Unsupported tag matching mode.");
+	return defined({
+		tags: value === void 0 ? void 0 : encode(tags(value, 20)),
+		tag_match: value !== void 0 || match !== "any" ? match : void 0
+	});
+}
+function pageParams(limit, offset, maximum = 100) {
+	return {
+		limit: integer(limit, 1, maximum),
+		offset: integer(offset, 0)
+	};
+}
+function nextOffset(value, offset) {
+	if (value === null) return null;
+	const params = new URL(text(value), "https://pagination.invalid").searchParams.getAll("offset");
+	if (params.length !== 1 || !/^\d+$/.test(params[0])) throw new TypeError("Invalid page continuation.");
+	return integer(Number(params[0]), offset + 1);
+}
+function page(data, parse, offset) {
+	if (!Array.isArray(data.results)) throw new TypeError("Expected page results.");
+	const results = data.results.map((v) => parse(object(v)));
+	const next = nextOffset(data.next, offset);
+	if (next !== null && results.length === 0) throw new TypeError("Empty page has a continuation.");
+	return {
+		count: count(data.count),
+		results,
+		nextOffset: next
+	};
+}
+//#endregion
+//#region src/evaluations/errors.ts
+/** Native cancellation with the prepared creation fields needed for recovery. */
+var ExperimentCreationAbortedError = class extends DOMException {
+	#cause;
+	#submission;
+	constructor(cause, submission) {
+		super("Offline evaluation creation was cancelled.", cause instanceof DOMException ? cause.name : "AbortError");
+		this.#cause = cause;
+		this.#submission = copy(submission);
+		Object.defineProperty(this, "cause", {
+			get: () => this.#cause,
+			enumerable: false
+		});
+	}
+	get submission() {
+		return copy(this.#submission);
+	}
+};
+/** An operation did not receive a valid acknowledgment. Inspect persistence before recovery. */
+var EvaluationAPIError = class extends Error {
+	#errors;
+	#submission;
+	constructor(fields = {}) {
+		super(`Offline evaluation request failed (${fields.status === void 0 ? "no acknowledgment" : `HTTP ${fields.status}`}).`);
+		this.name = "EvaluationAPIError";
+		this.status = fields.status;
+		this.code = fields.code;
+		this.detail = fields.detail === void 0 ? void 0 : copy(fields.detail);
+		this.attr = fields.attr;
+		this.#errors = fields.errors === void 0 ? void 0 : copy(fields.errors);
+		this.response = fields.response === void 0 ? void 0 : copy(fields.response);
+		this.retryAfter = fields.retryAfter;
+		this.persistence = fields.persistence ?? "unknown";
+		this.#submission = fields.submission === void 0 ? void 0 : copy(fields.submission);
+		for (const key of ["detail", "response"]) Object.defineProperty(this, key, { enumerable: false });
+		Object.defineProperty(this, "errors", {
+			get: () => this.#errors === void 0 ? void 0 : copy(this.#errors),
+			enumerable: false
+		});
+	}
+	get submission() {
+		return this.#submission === void 0 ? void 0 : copy(this.#submission);
+	}
+};
+function parseResponse(data, parser) {
+	try {
+		return parser(data);
+	} catch {
+		throw new EvaluationAPIError({
+			code: "invalid_response",
+			response: data
+		});
+	}
+}
+//#endregion
+//#region src/evaluations/datasets.ts
+function audit(data, project) {
+	if (integer(data.team_id) !== project) throw new TypeError("Response belongs to another project.");
+	return {
+		createdAt: timestamp(data.created_at),
+		createdBy: nullable(data.created_by, responseMetadata),
+		teamId: project
+	};
+}
+function dataset(data, project, id) {
+	const identity = uuid(data.id);
+	if (id !== void 0 && identity !== id) throw new TypeError("Mismatched dataset.");
+	if (data.current_revision === null !== (data.current_revision_id === null)) throw new TypeError("Incomplete revision reference.");
+	return {
+		...audit(data, project),
+		id: identity,
+		name: text(data.name),
+		description: text(data.description),
+		metadata: responseMetadata(data.metadata),
+		tags: responseTags(data.tags === void 0 ? [] : data.tags),
+		archived: boolean(data.archived),
+		currentRevision: nullable(data.current_revision, integer),
+		currentRevisionId: nullable(data.current_revision_id, uuid),
+		updatedAt: nullable(data.updated_at, timestamp)
+	};
+}
+function revision(data, project, datasetId) {
+	if (uuid(data.dataset_id) !== datasetId) throw new TypeError("Mismatched revision dataset.");
+	return {
+		...audit(data, project),
+		id: uuid(data.id),
+		datasetId,
+		revision: integer(data.revision)
+	};
+}
+function item(data, project, scope = {}) {
+	const id = uuid(data.id), datasetId = uuid(data.dataset), introduced = integer(data.dataset_revision), archived = boolean(data.archived);
+	if (scope.id !== void 0 && scope.id !== id || scope.datasetId !== void 0 && scope.datasetId !== datasetId || scope.revision !== void 0 && introduced > scope.revision || scope.archived !== void 0 && archived !== scope.archived) throw new TypeError("Item is outside requested scope.");
+	if (data.input === null) throw new TypeError("Dataset input cannot be null.");
+	return {
+		...audit(data, project),
+		id,
+		datasetId,
+		datasetRevision: introduced,
+		archived,
+		clientItemId: nullable(data.client_item_id, identifier),
+		version: integer(data.version),
+		versionId: uuid(data.version_id),
+		datasetRevisionId: uuid(data.dataset_revision_id),
+		input: responseJSON(data.input),
+		expectedOutput: responseJSON(data.expected_output),
+		sourceOutput: responseJSON(data.source_output),
+		metadata: responseMetadata(data.metadata),
+		sourceTraceId: nullable(data.source_trace_id, identifier),
+		sourceEventId: nullable(data.source_event_id, identifier),
+		sourceTimestamp: nullable(data.source_timestamp, timestamp),
+		updatedAt: nullable(data.updated_at, timestamp),
+		versionCreatedAt: timestamp(data.version_created_at),
+		versionCreatedBy: nullable(data.version_created_by, responseMetadata)
+	};
+}
+function body(fields) {
+	const data = defined(fields);
+	for (const key of ["name", "description"]) if (Object.hasOwn(data, key)) {
+		const value = text(data[key]), maximum = key === "name" ? 400 : 1e4;
+		if ([...value].length > maximum || key === "name" && !value.trim()) throw new TypeError("Invalid dataset metadata.");
+	}
+	if (Object.hasOwn(data, "input") && data.input === null) throw new TypeError("Dataset input cannot be null.");
+	if (Object.hasOwn(data, "metadata")) metadata(data.metadata);
+	if (Object.hasOwn(data, "tags")) data.tags = tags(data.tags);
+	return encode(json(data));
+}
+const METADATA_KEYS = [
+	"name",
+	"description",
+	"metadata",
+	"tags"
+];
+const ITEM_KEYS = [
+	"input",
+	"expectedOutput",
+	"sourceOutput",
+	"metadata",
+	"clientItemId",
+	"sourceTraceId",
+	"sourceEventId",
+	"sourceTimestamp"
+];
+/** Dataset management. Writes require a personal key with dataset:write. */
+var Datasets = class {
+	#transport;
+	#base;
+	#items;
+	constructor(transport) {
+		this.#transport = transport;
+		this.#base = `/api/projects/${transport.projectId}/datasets/`;
+		this.#items = `/api/projects/${transport.projectId}/dataset_items/`;
+	}
+	async #request(method, path, parse, options) {
+		return parseResponse(await this.#transport.request(method, path, options), parse);
+	}
+	async create(options, request = {}) {
+		keys(options, METADATA_KEYS);
+		if (options.name === void 0) throw new TypeError("Dataset name is required.");
+		return this.#request("POST", this.#base, (data) => dataset(data, this.#transport.projectId), {
+			...request,
+			body: body({ ...options })
+		});
+	}
+	async get(datasetId, request = {}) {
+		const id = uuid(datasetId);
+		return this.#request("GET", `${this.#base}${id}/`, (data) => dataset(data, this.#transport.projectId, id), request);
+	}
+	async list(options = {}) {
+		const { limit = 50, offset = 0, archived = false, orderBy = "-created_at" } = options;
+		if (![
+			"created_at",
+			"-created_at",
+			"updated_at",
+			"-updated_at"
+		].includes(orderBy)) throw new TypeError("Invalid dataset order.");
+		const params = {
+			...pageParams(limit, offset),
+			...tagParams(options.tags, options.tagMatch),
+			archived: String(boolean(archived)),
+			order_by: orderBy
+		};
+		if (options.search !== void 0 && !text(options.search).trim()) throw new TypeError("Search cannot be blank.");
+		return this.#request("GET", this.#base, (data) => page(data, (row) => dataset(row, this.#transport.projectId), offset), {
+			signal: options.signal,
+			params: {
+				...params,
+				...defined({ search: options.search })
+			}
+		});
+	}
+	async update(datasetId, options, request = {}) {
+		const id = uuid(datasetId);
+		keys(options, METADATA_KEYS);
+		return this.#request("PATCH", `${this.#base}${id}/`, (data) => dataset(data, this.#transport.projectId, id), {
+			...request,
+			body: body({ ...options })
+		});
+	}
+	async archive(datasetId, request = {}) {
+		return this.#state(datasetId, "archive", request);
+	}
+	async restore(datasetId, request = {}) {
+		return this.#state(datasetId, "restore", request);
+	}
+	async #state(datasetId, action, request) {
+		const id = uuid(datasetId);
+		return this.#request("POST", `${this.#base}${id}/${action}/`, (data) => dataset(data, this.#transport.projectId, id), {
+			...request,
+			body: "{}"
+		});
+	}
+	async listRevisions(datasetId, options = {}) {
+		const id = uuid(datasetId), { limit = 50, offset = 0 } = options;
+		return this.#request("GET", `${this.#base}${id}/revisions/`, (data) => page(data, (row) => revision(row, this.#transport.projectId, id), offset), {
+			signal: options.signal,
+			params: pageParams(limit, offset)
+		});
+	}
+	async listItems(datasetId, options = {}) {
+		const id = uuid(datasetId), { limit = 25, offset = 0, archived = false, revision: selectedRevision } = options;
+		const params = {
+			...pageParams(limit, offset, 25),
+			dataset: id,
+			archived: String(boolean(archived)),
+			...defined({ revision: selectedRevision === void 0 ? void 0 : integer(selectedRevision) })
+		};
+		return this.#request("GET", this.#items, (data) => page(data, (row) => item(row, this.#transport.projectId, {
+			datasetId: id,
+			revision: selectedRevision,
+			archived
+		}), offset), {
+			signal: options.signal,
+			params
+		});
+	}
+	async getItem(itemId, options = {}) {
+		const id = uuid(itemId), selectedRevision = options.revision;
+		const params = defined({ revision: selectedRevision === void 0 ? void 0 : integer(selectedRevision) });
+		return this.#request("GET", `${this.#items}${id}/`, (data) => item(data, this.#transport.projectId, {
+			id,
+			revision: selectedRevision
+		}), {
+			signal: options.signal,
+			params
+		});
+	}
+	async createItem(datasetId, options, request = {}) {
+		const id = uuid(datasetId);
+		keys(options, ITEM_KEYS);
+		if (options.input === void 0) throw new TypeError("Dataset input is required.");
+		const clientId = options.clientItemId == null ? null : identifier(options.clientItemId);
+		const trace = options.sourceTraceId == null ? null : identifier(options.sourceTraceId);
+		const event = options.sourceEventId == null ? null : identifier(options.sourceEventId);
+		const time = options.sourceTimestamp == null ? null : timestamp(options.sourceTimestamp);
+		if (trace === null !== (time === null) || event !== null && trace === null) throw new TypeError("Source provenance requires a trace and timezone-qualified timestamp.");
+		const prepared = body({
+			dataset: id,
+			input: options.input,
+			expected_output: options.expectedOutput,
+			source_output: options.sourceOutput,
+			metadata: options.metadata,
+			client_item_id: clientId,
+			source_trace_id: trace,
+			source_event_id: event,
+			source_timestamp: time
+		});
+		return this.#request("POST", this.#items, (data) => item(data, this.#transport.projectId, {
+			datasetId: id,
+			archived: false
+		}), {
+			...request,
+			body: prepared,
+			retrySafe: clientId !== null
+		});
+	}
+	async updateItem(itemId, options, request = {}) {
+		const id = uuid(itemId);
+		keys(options, [
+			"baseVersion",
+			"input",
+			"expectedOutput",
+			"metadata"
+		]);
+		const prepared = body({
+			base_version: integer(options.baseVersion),
+			input: options.input,
+			expected_output: options.expectedOutput,
+			metadata: options.metadata
+		});
+		return this.#request("PATCH", `${this.#items}${id}/`, (data) => item(data, this.#transport.projectId, {
+			id,
+			archived: false
+		}), {
+			...request,
+			body: prepared
+		});
+	}
+	async archiveItem(itemId, options, request = {}) {
+		keys(options, ["baseVersion"]);
+		return this.#itemState(itemId, "archive", { base_version: integer(options.baseVersion) }, request);
+	}
+	async restoreItem(itemId, options, request = {}) {
+		keys(options, ["baseVersion", "sourceVersion"]);
+		return this.#itemState(itemId, "restore", {
+			base_version: integer(options.baseVersion),
+			source_version: options.sourceVersion === void 0 ? null : integer(options.sourceVersion)
+		}, request);
+	}
+	async #itemState(itemId, action, fields, request) {
+		const id = uuid(itemId);
+		return this.#request("POST", `${this.#items}${id}/${action}/`, (data) => item(data, this.#transport.projectId, {
+			id,
+			archived: action === "archive"
+		}), {
+			...request,
+			body: body(fields)
+		});
+	}
+	async listItemVersions(itemId, options = {}) {
+		const id = uuid(itemId), { limit = 25, offset = 0 } = options;
+		return this.#request("GET", `${this.#items}${id}/versions/`, (data) => page(data, (row) => item(row, this.#transport.projectId, { id }), offset), {
+			signal: options.signal,
+			params: pageParams(limit, offset)
+		});
+	}
+	async snapshot(datasetId, options = {}) {
+		const selectedRevision = options.revision;
+		if (selectedRevision !== void 0) integer(selectedRevision);
+		const data = await this.get(datasetId, options), selected = selectedRevision ?? data.currentRevision;
+		if (selected === null) throw new TypeError("Dataset has no revision. Add an item first.");
+		if (data.currentRevision === null || selected > data.currentRevision) throw new TypeError("Dataset revision does not exist.");
+		if (selected === data.currentRevision && data.currentRevisionId !== null) return new DatasetSnapshot(this, data, selected, data.currentRevisionId);
+		const found = (await this.listRevisions(data.id, {
+			limit: 1,
+			offset: data.currentRevision - selected,
+			signal: options.signal
+		})).results.find((r) => r.revision === selected);
+		if (found) return new DatasetSnapshot(this, data, selected, found.id);
+		let offset = 0;
+		for (;;) {
+			const revisions = await this.listRevisions(data.id, {
+				limit: 100,
+				offset,
+				signal: options.signal
+			});
+			const match = revisions.results.find((r) => r.revision === selected);
+			if (match) return new DatasetSnapshot(this, data, selected, match.id);
+			if (revisions.nextOffset === null || revisions.results.at(-1).revision < selected) throw new TypeError("Dataset revision does not exist.");
+			offset = revisions.nextOffset;
+		}
+	}
+};
+/** A repeatable, lazy read of active items at one immutable revision. Keep its client open. */
+var DatasetSnapshot = class {
+	#datasets;
+	#dataset;
+	constructor(datasets, dataset, revisionNumber, revisionId) {
+		this.#datasets = datasets;
+		this.#dataset = structuredClone(dataset);
+		this.revision = revisionNumber;
+		this.revisionId = revisionId;
+		Object.freeze(this);
+	}
+	get dataset() {
+		return structuredClone(this.#dataset);
+	}
+	async *iterItems(options = {}) {
+		const limit = integer(options.pageSize ?? 25, 1, 25);
+		let offset = 0;
+		for (;;) {
+			const result = await this.#datasets.listItems(this.#dataset.id, {
+				revision: this.revision,
+				archived: false,
+				limit,
+				offset,
+				signal: options.signal
+			});
+			for (const row of result.results) {
+				options.signal?.throwIfAborted();
+				yield row;
+			}
+			if (result.nextOffset === null) return;
+			offset = result.nextOffset;
+		}
+	}
+	[Symbol.asyncIterator]() {
+		return this.iterItems();
+	}
+};
+//#endregion
+//#region src/evaluations/declarations.ts
+const ITEM_FIELDS = {
+	input: "input",
+	output: "output",
+	expectedOutput: "expected_output",
+	metadata: "metadata"
+};
+const RESULT_FIELDS = {
+	reasoning: "reasoning",
+	errorMessage: "error_message",
+	metadata: "metadata"
+};
+const ITEM_IDS = {
+	caseKey: "case_key",
+	trial: "trial",
+	datasetItemIdentifier: "dataset_item_identifier",
+	datasetItemVersionIdentifier: "dataset_item_version_identifier",
+	applicationTraceId: "application_trace_id"
+};
+const items = /* @__PURE__ */ new WeakMap();
+const results = /* @__PURE__ */ new WeakMap();
+function payload(options, fields, limit) {
+	const supplied = Object.keys(fields).filter((key) => options[key] !== void 0);
+	if (options.payload !== void 0 && supplied.length) throw new TypeError("Supply payload or individual fields, not both.");
+	if (options.payload === void 0 && !supplied.length) return void 0;
+	const source = options.payload === void 0 ? Object.fromEntries(supplied.map((key) => [key, options[key]])) : object(options.payload);
+	keys(source, Object.keys(fields));
+	const snapshot = json(Object.fromEntries(Object.entries(source).map(([key, v]) => {
+		if (key === "metadata" && v !== null) metadata(v);
+		if ((key === "reasoning" || key === "errorMessage") && v !== null && typeof v !== "string") throw new TypeError("Expected a string or null.");
+		return [fields[key], v];
+	})));
+	if (bytes(encode(snapshot)) > limit) throw new TypeError("Evaluation payload exceeds its UTF-8 byte limit.");
+	return snapshot;
+}
+function restoredPayload(value, fields) {
+	const source = object(value);
+	keys(source, Object.values(fields));
+	return Object.fromEntries(Object.entries(fields).filter(([, wire]) => Object.hasOwn(source, wire)).map(([key, wire]) => [key, source[wire]]));
+}
+function score(value) {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "bigint") {
+		const result = Number(value);
+		if (!Number.isFinite(result) || BigInt(result) !== value) throw new TypeError("Integer scores must be exactly representable as binary64.");
+		return result;
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) throw new TypeError("Use bigint for exact integer scores outside the safe number range.");
+		return value;
+	}
+	if (!Array.isArray(value) || !value.length) throw new TypeError("Expected a boolean, finite number, or nonempty category list.");
+	for (let i = 0; i < value.length; i++) if (!Object.hasOwn(value, i)) throw new TypeError("Category lists cannot be sparse.");
+	const categories = value.map((v) => identifier(v, 128));
+	if (new Set(categories).size !== categories.length) throw new TypeError("Category keys must be distinct.");
+	return categories.sort((a, b) => {
+		const aa = Array.from(a, (c) => c.codePointAt(0)), bb = Array.from(b, (c) => c.codePointAt(0));
+		for (let i = 0; i < Math.min(aa.length, bb.length); i++) if (aa[i] !== bb[i]) return aa[i] - bb[i];
+		return aa.length - bb.length;
+	});
+}
+/** One immutable execution. Reuse across scorers; construct a new item for each trial. */
+var EvaluationItem = class EvaluationItem {
+	constructor(options = {}) {
+		object(options);
+		keys(options, [
+			"id",
+			"datasetItemVersionId",
+			"payload",
+			...Object.keys(ITEM_IDS),
+			...Object.keys(ITEM_FIELDS)
+		]);
+		this.id = uuid(options.id ?? randomUUID());
+		const body = { id: this.id };
+		for (const [key, wire] of Object.entries(ITEM_IDS)) {
+			const value = options[key];
+			if (value !== void 0 && value !== null) body[wire] = identifier(value);
+		}
+		if (options.datasetItemVersionId != null) body.dataset_item_version_id = uuid(options.datasetItemVersionId);
+		const data = payload(options, ITEM_FIELDS, 1048576);
+		if (data !== void 0) body.payload = data;
+		items.set(this, encode(body));
+		Object.freeze(this);
+	}
+	/** Detached wire-format object. Use toJSONString() for lossless cross-language persistence. */
+	toJSON() {
+		return JSON.parse(itemJSON(this));
+	}
+	/** Exact wire JSON, including large integers. Restore with fromJSON(JSON.parse(saved)). */
+	toJSONString() {
+		return itemJSON(this);
+	}
+	static fromJSON(value) {
+		const data = object(value);
+		keys(data, [
+			"id",
+			"dataset_item_version_id",
+			"payload",
+			...Object.values(ITEM_IDS)
+		]);
+		const options = { id: uuid(data.id) };
+		for (const [key, wire] of Object.entries(ITEM_IDS)) if (Object.hasOwn(data, wire)) options[key] = data[wire];
+		if (Object.hasOwn(data, "dataset_item_version_id")) options.datasetItemVersionId = data.dataset_item_version_id;
+		if (Object.hasOwn(data, "payload")) options.payload = restoredPayload(data.payload, ITEM_FIELDS);
+		return new EvaluationItem(options);
+	}
+	static fromDatasetItem(item, options = {}) {
+		if (item.archived !== false) throw new TypeError("Archived dataset items cannot be evaluated.");
+		keys(options, [
+			"output",
+			"id",
+			"caseKey",
+			"trial",
+			"applicationTraceId"
+		]);
+		return new EvaluationItem({
+			...options,
+			caseKey: options.caseKey ?? item.clientItemId ?? item.id,
+			input: item.input,
+			expectedOutput: item.expectedOutput,
+			metadata: item.metadata,
+			datasetItemIdentifier: uuid(item.id),
+			datasetItemVersionIdentifier: uuid(item.versionId),
+			datasetItemVersionId: item.versionId
+		});
+	}
+};
+/** An evaluator outcome pinned to an exact scorer version. `ok` does not imply passing. */
+var EvaluationResult = class EvaluationResult {
+	constructor(options) {
+		object(options);
+		keys(options, [
+			"item",
+			"scorerVersionId",
+			"status",
+			"value",
+			"errorCode",
+			"evaluatorTraceId",
+			"evaluatedAt",
+			"payload",
+			...Object.keys(RESULT_FIELDS)
+		]);
+		this.item = options.item instanceof EvaluationItem ? options.item : uuid(options.item);
+		this.itemId = typeof this.item === "string" ? this.item : this.item.id;
+		this.scorerVersionId = uuid(options.scorerVersionId);
+		const status = options.status ?? "ok";
+		if (![
+			"ok",
+			"error",
+			"skipped",
+			"not_applicable"
+		].includes(status)) throw new TypeError("Unsupported result status.");
+		if (status !== "ok" && options.value !== void 0 && options.value !== null) throw new TypeError("Only ok results can contain a score.");
+		if (status !== "error" && options.errorCode != null) throw new TypeError("Only error results can contain an error code.");
+		const body = {
+			item_id: this.itemId,
+			scorer_version_id: this.scorerVersionId,
+			status
+		};
+		if (status === "ok") body.value = score(options.value);
+		if (options.errorCode != null) body.error_code = identifier(options.errorCode, 128);
+		if (options.evaluatorTraceId != null) body.evaluator_trace_id = identifier(options.evaluatorTraceId);
+		if (options.evaluatedAt != null) body.evaluated_at = timestamp(options.evaluatedAt);
+		const data = payload(options, RESULT_FIELDS, 262144);
+		if (data !== void 0) {
+			if (status !== "error" && data.error_message != null) throw new TypeError("Only error results can contain an error message.");
+			body.payload = data;
+		}
+		results.set(this, encode(body));
+		Object.freeze(this);
+	}
+	/** Detached wire-format object. Use toJSONString() for lossless cross-language persistence. */
+	toJSON() {
+		return JSON.parse(resultJSON(this));
+	}
+	/** Exact wire JSON. Save the attached item separately and restore with fromJSON(JSON.parse(saved), { item }). */
+	toJSONString() {
+		return resultJSON(this);
+	}
+	static fromJSON(value, options = {}) {
+		const data = object(value);
+		keys(data, [
+			"item_id",
+			"scorer_version_id",
+			"status",
+			"value",
+			"error_code",
+			"evaluator_trace_id",
+			"evaluated_at",
+			"payload"
+		]);
+		const itemId = uuid(data.item_id);
+		if (options.item !== void 0 && options.item.id !== itemId) throw new TypeError("Restored item identity does not match.");
+		const valueInput = typeof data.value === "number" && Number.isInteger(data.value) && !Number.isSafeInteger(data.value) && Number.isFinite(data.value) ? BigInt(data.value) : data.value;
+		return new EvaluationResult(defined({
+			item: options.item ?? itemId,
+			scorerVersionId: data.scorer_version_id,
+			status: data.status,
+			value: valueInput,
+			errorCode: data.error_code,
+			evaluatorTraceId: data.evaluator_trace_id,
+			evaluatedAt: data.evaluated_at,
+			payload: Object.hasOwn(data, "payload") ? restoredPayload(data.payload, RESULT_FIELDS) : void 0
+		}));
+	}
+};
+function itemJSON(item) {
+	const value = items.get(item);
+	if (value === void 0) throw new TypeError("Expected an EvaluationItem.");
+	return value;
+}
+function resultJSON(result) {
+	const value = results.get(result);
+	if (value === void 0) throw new TypeError("Expected an EvaluationResult.");
+	return value;
+}
+//#endregion
+//#region src/evaluations/scorers.ts
+const CONFIG_KEYS = {
+	trueLabel: "true_label",
+	falseLabel: "false_label",
+	trueIsFailure: "true_is_failure",
+	passingRule: "passing_rule",
+	selectionMode: "selection_mode",
+	minSelections: "min_selections",
+	maxSelections: "max_selections"
+};
+function kind(value) {
+	if (value !== "boolean" && value !== "numeric" && value !== "categorical") throw new TypeError("Unsupported scorer kind.");
+	return value;
+}
+function config(value, toWire) {
+	const fields = toWire ? CONFIG_KEYS : Object.fromEntries(Object.entries(CONFIG_KEYS).map(([k, v]) => [v, k]));
+	return Object.fromEntries(Object.entries(toWire ? metadata(value) : responseMetadata(value)).map(([key, v]) => [Object.hasOwn(fields, key) ? fields[key] : key, v]));
+}
+function parsedConfig(value, raw) {
+	const selected = kind(value);
+	const snapshot = config(raw, false);
+	const finite = (v) => {
+		if (typeof v !== "number" || !Number.isFinite(v)) throw new TypeError("Expected a finite configuration number.");
+	};
+	if (selected === "boolean") {
+		for (const key of ["trueLabel", "falseLabel"]) if (snapshot[key] !== void 0) text(snapshot[key]);
+		if (snapshot.trueIsFailure != null) boolean(snapshot.trueIsFailure);
+		return {
+			kind: selected,
+			config: snapshot
+		};
+	}
+	if (selected === "numeric") {
+		for (const key of [
+			"min",
+			"max",
+			"step"
+		]) if (snapshot[key] != null) finite(snapshot[key]);
+		if (snapshot.passingRule != null) {
+			const rule = object(snapshot.passingRule);
+			if (rule.operator !== "gte" && rule.operator !== "lte") throw new TypeError("Invalid passing operator.");
+			finite(rule.threshold);
+		}
+		return {
+			kind: selected,
+			config: snapshot
+		};
+	}
+	if (!Array.isArray(snapshot.options)) throw new TypeError("Expected categorical options.");
+	for (const option of snapshot.options) {
+		const row = object(option);
+		text(row.key);
+		text(row.label);
+	}
+	if (snapshot.selectionMode !== void 0 && snapshot.selectionMode !== "single" && snapshot.selectionMode !== "multiple") throw new TypeError("Invalid selection mode.");
+	for (const key of ["minSelections", "maxSelections"]) if (snapshot[key] != null) integer(snapshot[key]);
+	if (snapshot.passingRule != null) {
+		const categories = object(snapshot.passingRule).categories;
+		if (!Array.isArray(categories)) throw new TypeError("Expected passing categories.");
+		categories.forEach(text);
+	}
+	return {
+		kind: selected,
+		config: snapshot
+	};
+}
+function scorer(data, project, id) {
+	const identity = uuid(data.id);
+	if (id !== void 0 && identity !== id || integer(data.team) !== project) throw new TypeError("Mismatched scorer scope.");
+	return {
+		id: identity,
+		name: text(data.name),
+		description: text(data.description),
+		archived: boolean(data.archived),
+		...parsedConfig(data.kind, data.config),
+		tags: responseTags(data.tags === void 0 ? [] : data.tags),
+		currentVersion: integer(data.current_version),
+		currentVersionId: uuid(data.current_version_id),
+		team: project,
+		createdAt: timestamp(data.created_at),
+		updatedAt: timestamp(data.updated_at),
+		createdBy: nullable(data.created_by, responseMetadata)
+	};
+}
+function version(data, scorerId, versionId) {
+	const id = uuid(data.id);
+	if (uuid(data.definition_id) !== scorerId || versionId !== void 0 && versionId !== id) throw new TypeError("Mismatched scorer version.");
+	return {
+		id,
+		definitionId: scorerId,
+		version: integer(data.version),
+		...parsedConfig(data.kind, data.config),
+		createdAt: timestamp(data.created_at),
+		createdBy: nullable(data.created_by, responseMetadata)
+	};
+}
+function fields(options) {
+	return defined({
+		name: options.name === void 0 ? void 0 : identifier(options.name, 400),
+		description: options.description === void 0 ? void 0 : nullable(options.description, text),
+		archived: options.archived === void 0 ? void 0 : boolean(options.archived),
+		tags: options.tags === void 0 ? void 0 : tags(options.tags)
+	});
+}
+/** Versioned scorer definitions. Evaluator execution remains caller-owned. */
+var Scorers = class {
+	#transport;
+	#base;
+	constructor(transport) {
+		this.#transport = transport;
+		this.#base = `/api/projects/${transport.projectId}/llm_analytics/score_definitions/`;
+	}
+	async #request(method, path, parse, options) {
+		return parseResponse(await this.#transport.request(method, path, options), parse);
+	}
+	async create(options, request = {}) {
+		keys(options, [
+			"name",
+			"kind",
+			"config",
+			"description",
+			"tags"
+		]);
+		const selectedKind = kind(options.kind);
+		const body = encode(json({
+			...fields(options),
+			name: identifier(options.name, 400),
+			kind: selectedKind,
+			config: config(options.config, true)
+		}));
+		return this.#request("POST", this.#base, (data) => {
+			const result = scorer(data, this.#transport.projectId);
+			if (result.kind !== selectedKind) throw new TypeError("Mismatched scorer kind.");
+			return result;
+		}, {
+			...request,
+			body
+		});
+	}
+	async get(scorerId, request = {}) {
+		const id = uuid(scorerId);
+		return this.#request("GET", `${this.#base}${id}/`, (data) => scorer(data, this.#transport.projectId, id), request);
+	}
+	async list(options = {}) {
+		const { limit = 100, offset = 0 } = options;
+		if (options.orderBy !== void 0 && ![
+			"name",
+			"-name",
+			"kind",
+			"-kind",
+			"created_at",
+			"-created_at",
+			"updated_at",
+			"-updated_at",
+			"current_version",
+			"-current_version"
+		].includes(options.orderBy)) throw new TypeError("Unsupported scorer order.");
+		const params = {
+			...pageParams(limit, offset, Number.MAX_SAFE_INTEGER),
+			...tagParams(options.tags, options.tagMatch),
+			...defined({
+				search: options.search === void 0 ? void 0 : text(options.search),
+				kind: options.kind === void 0 ? void 0 : kind(options.kind),
+				archived: options.archived === void 0 ? void 0 : String(boolean(options.archived)),
+				order_by: options.orderBy
+			})
+		};
+		return this.#request("GET", this.#base, (data) => ({
+			...page(data, (row) => scorer(row, this.#transport.projectId), offset),
+			next: nullable(data.next, text),
+			previous: nullable(data.previous, text)
+		}), {
+			signal: options.signal,
+			params
+		});
+	}
+	async update(scorerId, options, request = {}) {
+		keys(options, [
+			"name",
+			"description",
+			"archived",
+			"tags"
+		]);
+		const id = uuid(scorerId);
+		return this.#request("PATCH", `${this.#base}${id}/`, (data) => scorer(data, this.#transport.projectId, id), {
+			...request,
+			body: encode(json(fields(options)))
+		});
+	}
+	async createVersion(scorerId, options, request = {}) {
+		keys(options, [
+			"config",
+			"baseVersion",
+			"name",
+			"description"
+		]);
+		const id = uuid(scorerId);
+		const body = encode(json({
+			...fields(options),
+			config: config(options.config, true),
+			...defined({ base_version: options.baseVersion === void 0 ? void 0 : integer(options.baseVersion) })
+		}));
+		return this.#request("POST", `${this.#base}${id}/new_version/`, (data) => scorer(data, this.#transport.projectId, id), {
+			...request,
+			body
+		});
+	}
+	async getVersion(scorerId, versionId, request = {}) {
+		const id = uuid(scorerId), selected = uuid(versionId);
+		return this.#request("GET", `${this.#base}${id}/versions/${selected}/`, (data) => version(data, id, selected), request);
+	}
+	async listVersions(scorerId, options = {}) {
+		const id = uuid(scorerId), cursor = options.cursor;
+		const params = {
+			limit: integer(options.limit ?? 50, 1, 100),
+			...defined({ cursor: cursor === void 0 ? void 0 : text(cursor) })
+		};
+		return this.#request("GET", `${this.#base}${id}/versions/`, (data) => {
+			if (!Array.isArray(data.results)) throw new TypeError("Expected version results.");
+			const next = nullable(data.next_cursor, text);
+			if (next !== null && (!next || next === cursor || !data.results.length)) throw new TypeError("Invalid cursor continuation.");
+			return {
+				count: count(data.count),
+				results: data.results.map((row) => version(object(row), id)),
+				nextCursor: next
+			};
+		}, {
+			signal: options.signal,
+			params
+		});
+	}
+};
+//#endregion
+//#region src/evaluations/transport.ts
+const RETRY_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const HOSTS = {
+	"app.posthog.com": "us.posthog.com",
+	"us.i.posthog.com": "us.posthog.com",
+	"eu.i.posthog.com": "eu.posthog.com"
+};
+function normalizeHost(host) {
+	const url = new URL(text(host));
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || host.includes("?") || host.includes("#")) throw new TypeError("Host must be an absolute HTTP(S) URL without credentials, query, or fragment.");
+	if (url.protocol === "https:" && !url.port && Object.hasOwn(HOSTS, url.hostname)) url.hostname = HOSTS[url.hostname];
+	return url.href.replace(/\/+$/, "");
+}
+function retryAfter(value) {
+	if (!value?.trim()) return void 0;
+	const number = Number(value);
+	const seconds = Number.isFinite(number) ? number : (Date.parse(value) - Date.now()) / 1e3;
+	return Number.isFinite(seconds) ? Math.max(0, seconds) : void 0;
+}
+function delay(ms, signal) {
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason);
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+var Transport = class {
+	#host;
+	#secret;
+	#timeout;
+	#retries;
+	#closed = new AbortController();
+	constructor(options) {
+		this.projectId = integer(options.projectId);
+		this.#secret = text(options.secretKey);
+		if (!this.#secret || /\s/.test(this.#secret)) throw new TypeError("Secret key must be nonempty and contain no whitespace.");
+		this.#host = normalizeHost(options.host ?? "https://us.posthog.com");
+		this.#timeout = options.timeoutMs === void 0 ? 15e3 : options.timeoutMs;
+		if (typeof this.#timeout !== "number" || !Number.isFinite(this.#timeout) || this.#timeout <= 0 || this.#timeout > 2147483647) throw new TypeError("Invalid timeoutMs.");
+		this.#retries = integer(options.maxRetries === void 0 ? 3 : options.maxRetries, 0);
+	}
+	close() {
+		this.#closed.abort(new EvaluationAPIError({ code: "client_closed" }));
+	}
+	async request(method, path, request = {}) {
+		const options = {
+			...request,
+			params: request.params === void 0 ? void 0 : { ...request.params }
+		};
+		if (this.#closed.signal.aborted) throw new EvaluationAPIError({
+			code: "client_closed",
+			persistence: "not_sent"
+		});
+		options.signal?.throwIfAborted();
+		if (!path.startsWith("/") || path.startsWith("//") || /[?#]/.test(path)) throw new TypeError("Invalid API path.");
+		const url = new URL(this.#host + path);
+		for (const [key, value] of Object.entries(options.params ?? {})) url.searchParams.set(key, String(value));
+		const operation = new AbortController();
+		const forward = (signal) => operation.abort(signal.reason);
+		const externalAbort = () => forward(options.signal);
+		const closeAbort = () => forward(this.#closed.signal);
+		options.signal?.addEventListener("abort", externalAbort, { once: true });
+		this.#closed.signal.addEventListener("abort", closeAbort, { once: true });
+		let hadUnknown = false;
+		try {
+			for (let attempt = 0;; attempt++) {
+				operation.signal.throwIfAborted();
+				const controller = new AbortController();
+				const abort = () => controller.abort(operation.signal.reason);
+				operation.signal.addEventListener("abort", abort, { once: true });
+				const timer = setTimeout(() => controller.abort(), this.#timeout);
+				let error;
+				try {
+					const response = await fetch(url, {
+						method,
+						body: options.body,
+						redirect: "manual",
+						signal: controller.signal,
+						headers: {
+							Authorization: `Bearer ${this.#secret}`,
+							Accept: "application/json",
+							"Content-Type": "application/json"
+						}
+					});
+					const raw = await response.text();
+					operation.signal.throwIfAborted();
+					let payload;
+					try {
+						payload = decode(raw);
+					} catch {
+						payload = void 0;
+					}
+					if (response.ok) try {
+						return object(payload);
+					} catch {
+						throw new EvaluationAPIError({
+							status: response.status,
+							code: "invalid_response"
+						});
+					}
+					let fields = {};
+					try {
+						fields = object(payload);
+					} catch {}
+					throw new EvaluationAPIError({
+						status: response.status,
+						code: typeof fields.code === "string" ? fields.code : void 0,
+						detail: fields.detail ?? payload,
+						attr: typeof fields.attr === "string" ? fields.attr : void 0,
+						errors: fields.errors,
+						response: Object.keys(fields).length ? fields : void 0,
+						retryAfter: retryAfter(response.headers.get("Retry-After")),
+						persistence: response.status >= 400 && response.status < 500 && response.status !== 408 ? "rejected" : "unknown"
+					});
+				} catch (caught) {
+					operation.signal.throwIfAborted();
+					error = caught instanceof EvaluationAPIError ? caught : new EvaluationAPIError({ code: "transport_error" });
+				} finally {
+					clearTimeout(timer);
+					operation.signal.removeEventListener("abort", abort);
+				}
+				hadUnknown ||= error.persistence === "unknown";
+				if (hadUnknown) error.persistence = "unknown";
+				if (!(options.retrySafe ?? method === "GET") || attempt >= this.#retries || error.code === "invalid_response" || error.status !== void 0 && !RETRY_STATUSES.has(error.status) || (error.retryAfter ?? 0) > 30) throw error;
+				const backoff = Math.min(30, .5 * 2 ** Math.min(attempt, 6) * (.8 + Math.random() * .4));
+				await delay(Math.max(backoff, error.retryAfter ?? 0) * 1e3, operation.signal);
+			}
+		} finally {
+			options.signal?.removeEventListener("abort", externalAbort);
+			this.#closed.signal.removeEventListener("abort", closeAbort);
+		}
+	}
+};
+/** One handle's operations are atomic with respect to each other, including all bulk chunks. */
+var OperationQueue = class {
+	#tail = Promise.resolve();
+	async run(operation, signal) {
+		signal?.throwIfAborted();
+		const previous = this.#tail;
+		let release;
+		const done = new Promise((resolve) => {
+			release = resolve;
+		});
+		this.#tail = previous.then(() => done);
+		let abort;
+		try {
+			if (signal) {
+				await Promise.race([previous, new Promise((_, reject) => {
+					abort = () => reject(signal.reason);
+					signal.addEventListener("abort", abort, { once: true });
+				})]);
+				signal.throwIfAborted();
+			} else await previous;
+			return await operation();
+		} finally {
+			if (abort) signal.removeEventListener("abort", abort);
+			release();
+		}
+	}
+};
+//#endregion
+//#region src/evaluations/client.ts
+const EXPERIMENT_TEXT = {
+	suiteKey: "suite_key",
+	datasetSource: "dataset_source",
+	datasetIdentifier: "dataset_identifier",
+	datasetRevisionIdentifier: "dataset_revision_identifier",
+	applicationVersion: "application_version",
+	modelVersion: "model_version",
+	promptVersion: "prompt_version"
+};
+function experimentBody(options) {
+	keys(options, [
+		"name",
+		"id",
+		"startedAt",
+		"runSource",
+		"expectedItemCount",
+		"expectedResultCount",
+		"datasetRevisionId",
+		...Object.keys(EXPERIMENT_TEXT)
+	]);
+	const body = {
+		name: identifier(options.name, 400),
+		id: uuid(options.id === void 0 ? randomUUID() : options.id),
+		started_at: timestamp(options.startedAt === void 0 ? /* @__PURE__ */ new Date() : options.startedAt)
+	};
+	for (const [key, wire] of Object.entries(EXPERIMENT_TEXT)) {
+		const value = options[key];
+		if (value !== void 0) body[wire] = nullable(value, identifier);
+	}
+	if (options.runSource !== void 0) {
+		if (options.runSource !== null && ![
+			"ci",
+			"local",
+			"scheduled"
+		].includes(options.runSource)) throw new TypeError("Invalid run source.");
+		body.run_source = options.runSource;
+	}
+	if (options.expectedItemCount !== void 0) body.expected_item_count = nullable(options.expectedItemCount, count);
+	if (options.expectedResultCount !== void 0) body.expected_result_count = nullable(options.expectedResultCount, count);
+	if (options.datasetRevisionId !== void 0) body.dataset_revision_id = nullable(options.datasetRevisionId, uuid);
+	return encode(body);
+}
+function experimentReceipt(data, id) {
+	if (uuid(data.id) !== id || typeof data.status !== "string" || ![
+		"uploading",
+		"completed",
+		"failed"
+	].includes(data.status)) throw new TypeError("Mismatched experiment receipt.");
+	return {
+		id,
+		status: data.status,
+		created: boolean(data.created),
+		startedAt: timestamp(data.started_at),
+		createdAt: timestamp(data.created_at),
+		finishedAt: nullable(data.finished_at, timestamp),
+		expectedItemCount: nullable(data.expected_item_count, count),
+		expectedResultCount: nullable(data.expected_result_count, count),
+		acceptedItemCount: count(data.accepted_item_count),
+		acceptedResultCount: count(data.accepted_result_count)
+	};
+}
+function itemReceipt(value) {
+	const data = object(value);
+	return {
+		id: uuid(data.id),
+		created: boolean(data.created),
+		acceptedAt: timestamp(data.accepted_at)
+	};
+}
+function uploadReceipt(data, submitted) {
+	if (!Array.isArray(data.items) || !Array.isArray(data.results)) throw new TypeError("Expected acknowledgment lists.");
+	const items = data.items.map(itemReceipt);
+	const results = data.results.map((value) => {
+		const row = object(value);
+		return {
+			...itemReceipt(row),
+			itemId: uuid(row.item_id),
+			scorerVersionId: uuid(row.scorer_version_id)
+		};
+	});
+	const expectedItems = new Set(submitted.map((r) => r.itemId)), actualItems = new Set(items.map((i) => i.id));
+	if (actualItems.size !== items.length || actualItems.size !== expectedItems.size || [...expectedItems].some((id) => !actualItems.has(id))) throw new TypeError("Incomplete item acknowledgments.");
+	if (results.length !== submitted.length || results.some((r, i) => r.itemId !== submitted[i].itemId || r.scorerVersionId !== submitted[i].scorerVersionId) || new Set(results.map((r) => r.id)).size !== results.length) throw new TypeError("Incomplete result acknowledgments.");
+	return {
+		items,
+		results
+	};
+}
+function uploadBody(items, results) {
+	return `{"items":[${items.join(",")}],"results":[${results.join(",")}]}`;
+}
+function chunks(input) {
+	if (!Array.isArray(input)) throw new TypeError("uploadResults expects a finite array of EvaluationResult declarations.");
+	const original = Array.from(input), identities = /* @__PURE__ */ new Set(), declarations = /* @__PURE__ */ new Map();
+	for (const result of original) {
+		resultJSON(result);
+		const pair = `${result.itemId}/${result.scorerVersionId}`;
+		if (identities.has(pair)) throw new TypeError("Duplicate item/scorer-version pair.");
+		identities.add(pair);
+		if (result.item instanceof EvaluationItem) {
+			const previous = declarations.get(result.itemId);
+			if (previous && itemJSON(previous) !== itemJSON(result.item)) throw new TypeError("Conflicting item declarations.");
+			declarations.set(result.itemId, result.item);
+		}
+	}
+	const prepared = original.map((r) => typeof r.item === "string" && declarations.has(r.itemId) ? EvaluationResult.fromJSON(r.toJSON(), { item: declarations.get(r.itemId) }) : r);
+	const output = [];
+	let start = 0, size = bytes(uploadBody([], [])), encodedItems = [], encodedResults = [], itemIds = /* @__PURE__ */ new Set();
+	for (let index = 0; index < prepared.length; index++) {
+		const result = prepared[index], resultBody = resultJSON(result), declaration = declarations.get(result.itemId);
+		let itemBody = declaration && !itemIds.has(result.itemId) ? itemJSON(declaration) : void 0;
+		let extra = bytes(resultBody) + (encodedResults.length ? 1 : 0) + (itemBody === void 0 ? 0 : bytes(itemBody) + (encodedItems.length ? 1 : 0));
+		if (encodedResults.length && (encodedResults.length >= 1e3 || encodedItems.length + (itemBody === void 0 ? 0 : 1) > 1e3 || size + extra > 5242880)) {
+			output.push({
+				start,
+				results: prepared.slice(start, index),
+				body: uploadBody(encodedItems, encodedResults)
+			});
+			start = index;
+			size = bytes(uploadBody([], []));
+			encodedItems = [];
+			encodedResults = [];
+			itemIds = /* @__PURE__ */ new Set();
+			itemBody = declaration ? itemJSON(declaration) : void 0;
+			extra = bytes(resultBody) + (itemBody === void 0 ? 0 : bytes(itemBody));
+		}
+		if (size + extra > 5242880) throw new TypeError("One item/result pair exceeds the request byte limit.");
+		if (itemBody !== void 0) {
+			itemIds.add(result.itemId);
+			encodedItems.push(itemBody);
+		}
+		encodedResults.push(resultBody);
+		size += extra;
+	}
+	if (encodedResults.length) output.push({
+		start,
+		results: prepared.slice(start),
+		body: uploadBody(encodedItems, encodedResults)
+	});
+	return {
+		chunks: output,
+		prepared
+	};
+}
+/** Earlier chunks are acknowledged; pendingResults includes the uncertain failed chunk. */
+var BulkUploadError = class extends EvaluationAPIError {
+	#completed;
+	#pending;
+	#failed;
+	constructor(cause, completed, failed, pending) {
+		super(cause);
+		this.name = "BulkUploadError";
+		this.failedIndex = failed.start;
+		this.#completed = copy(completed);
+		this.#pending = pending.slice();
+		this.#failed = failed.body;
+	}
+	get completed() {
+		return copy(this.#completed);
+	}
+	get pendingResults() {
+		return this.#pending.slice();
+	}
+	get failedChunk() {
+		return JSON.parse(this.#failed);
+	}
+};
+var Experiment = class {
+	#transport;
+	#base;
+	#queue = new OperationQueue();
+	#submission;
+	#receipt;
+	constructor(transport, id, receipt, submission) {
+		this.id = uuid(id);
+		this.#transport = transport;
+		this.#receipt = receipt;
+		this.#submission = submission;
+		this.#base = `/api/projects/${transport.projectId}/ai_observability/offline_experiments/${this.id}/`;
+		Object.freeze(this);
+	}
+	get receipt() {
+		return this.#receipt === void 0 ? void 0 : copy(this.#receipt);
+	}
+	/** Original creation options, suitable for createExperiment(submission). Large counts may be bigint. */
+	get submission() {
+		return this.#submission === void 0 ? void 0 : submissionOptions(object(decode(this.#submission)));
+	}
+	async uploadResult(options, request = {}) {
+		const chunk = chunks([new EvaluationResult(options)]).chunks[0];
+		return this.#queue.run(() => this.#upload(chunk, request), request.signal);
+	}
+	async #upload(chunk, request) {
+		return parseResponse(await this.#transport.request("POST", `${this.#base}upload/`, {
+			...request,
+			body: chunk.body,
+			retrySafe: true
+		}), (data) => uploadReceipt(data, chunk.results));
+	}
+	async uploadResults(results, request = {}) {
+		const prepared = chunks(results);
+		return this.#queue.run(async () => {
+			const receipts = [];
+			for (const chunk of prepared.chunks) try {
+				receipts.push(await this.#upload(chunk, request));
+			} catch (error) {
+				if (!(error instanceof EvaluationAPIError)) throw error;
+				throw new BulkUploadError(error, { chunks: receipts }, chunk, prepared.prepared.slice(chunk.start));
+			}
+			return { chunks: receipts };
+		}, request.signal);
+	}
+	async complete(request = {}) {
+		return this.#finish("complete", request);
+	}
+	async fail(request = {}) {
+		return this.#finish("fail", request);
+	}
+	async #finish(action, request) {
+		return this.#queue.run(async () => {
+			const receipt = parseResponse(await this.#transport.request("POST", `${this.#base}${action}/`, {
+				...request,
+				body: "{}",
+				retrySafe: true
+			}), (data) => {
+				const result = experimentReceipt(data, this.id);
+				if (result.status !== (action === "complete" ? "completed" : "failed")) throw new TypeError("Unexpected experiment status.");
+				return result;
+			});
+			this.#receipt = copy(receipt);
+			return receipt;
+		}, request.signal);
+	}
+	async getTags(request = {}) {
+		return this.#tags("GET", void 0, request);
+	}
+	async setTags(names, request = {}) {
+		return this.#tags("PATCH", encode({ tags: tags(names) }), request);
+	}
+	async #tags(method, body, request) {
+		return this.#queue.run(async () => parseResponse(await this.#transport.request(method, this.#base, {
+			...request,
+			body
+		}), (data) => {
+			if (uuid(data.id) !== this.id) throw new TypeError("Mismatched experiment.");
+			return responseTags(data.tags);
+		}), request.signal);
+	}
+};
+function submissionOptions(data) {
+	const result = {
+		name: data.name,
+		id: data.id,
+		startedAt: data.started_at
+	};
+	for (const [key, wire] of Object.entries({
+		...EXPERIMENT_TEXT,
+		runSource: "run_source",
+		expectedItemCount: "expected_item_count",
+		expectedResultCount: "expected_result_count",
+		datasetRevisionId: "dataset_revision_id"
+	})) if (Object.hasOwn(data, wire)) result[key] = data[wire];
+	return result;
+}
+/** Acknowledged management APIs, independent of analytics capture and flush. */
+var OfflineEvaluations = class {
+	#transport;
+	constructor(options) {
+		this.#transport = new Transport(options);
+		this.datasets = new Datasets(this.#transport);
+		this.scorers = new Scorers(this.#transport);
+		Object.freeze(this);
+	}
+	async createExperiment(options, request = {}) {
+		const signal = request.signal, body = experimentBody(options), submission = object(decode(body)), id = uuid(submission.id);
+		try {
+			const data = await this.#transport.request("POST", `/api/projects/${this.#transport.projectId}/ai_observability/offline_experiments/`, {
+				...request,
+				body,
+				retrySafe: true
+			});
+			return new Experiment(this.#transport, id, parseResponse(data, (value) => experimentReceipt(value, id)), body);
+		} catch (error) {
+			if (signal?.aborted && Object.is(error, signal.reason)) throw new ExperimentCreationAbortedError(error, submissionOptions(submission));
+			if (!(error instanceof EvaluationAPIError)) throw error;
+			throw new EvaluationAPIError({
+				...error,
+				detail: error.detail,
+				errors: error.errors,
+				response: error.response,
+				submission: submissionOptions(submission)
+			});
+		}
+	}
+	/** Local only; existence and permissions are checked on the next network operation. */
+	resumeExperiment(id) {
+		return new Experiment(this.#transport, id);
+	}
+	/** Stop owned requests and timers. This never completes or fails experiments. */
+	close() {
+		this.#transport.close();
+	}
+};
+//#endregion
+export { BulkUploadError, DatasetSnapshot, Datasets, EvaluationAPIError, EvaluationItem, EvaluationResult, Experiment, ExperimentCreationAbortedError, OfflineEvaluations, Scorers };
+
+//# sourceMappingURL=index.mjs.map