@fevex/core 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/tools/index.mjs

@@ -1,4 +1,224 @@
-//#region src/tools/index.ts
+//#region src/tools/connection.ts
+/** Safe, provider-neutral error surfaced by connection adapters. */
+var IntegrationError = class extends Error {
+	code;
+	category;
+	retryable;
+	safeMessage;
+	name = "IntegrationError";
+	constructor(code, category, retryable, safeMessage, options) {
+		super(safeMessage, options);
+		this.code = code;
+		this.category = category;
+		this.retryable = retryable;
+		this.safeMessage = safeMessage;
+		this.source = options?.source;
+	}
+	source;
+};
+function defineConnection(connection) {
+	return connection;
+}
+//#endregion
+//#region src/tools/json-schema-profile.ts
+const FEVEX_JSON_SCHEMA_PROFILE_VERSION = "1";
+const DEFAULT_LIMITS = {
+	maxBytes: 64e3,
+	maxDepth: 32,
+	maxNodes: 1e3,
+	maxProperties: 200
+};
+const KEYWORDS = /* @__PURE__ */ new Set([
+	"$defs",
+	"$ref",
+	"additionalProperties",
+	"allOf",
+	"anyOf",
+	"const",
+	"default",
+	"description",
+	"enum",
+	"items",
+	"maxItems",
+	"maxLength",
+	"maximum",
+	"minItems",
+	"minLength",
+	"minimum",
+	"oneOf",
+	"properties",
+	"required",
+	"title",
+	"type"
+]);
+const DEFERRED = /* @__PURE__ */ new Set([
+	"dependentSchemas",
+	"format",
+	"if",
+	"not",
+	"pattern",
+	"then",
+	"else",
+	"unevaluatedProperties"
+]);
+function validateFevexJsonSchemaProfile(schema, options = {}) {
+	const limits = {
+		...DEFAULT_LIMITS,
+		...options.limits
+	};
+	if (JSON.stringify(schema).length > limits.maxBytes) throw new TypeError(`JSON Schema exceeds maxBytes limit of ${limits.maxBytes}`);
+	visitSchema(schema, options.rootDocument ?? schema, options.requireRootObject ?? false, limits, { nodes: 0 }, [], 0);
+	return schema;
+}
+function compileFevexJsonSchema(schema, options = {}) {
+	validateFevexJsonSchemaProfile(schema, options);
+	const rootDocument = options.rootDocument ?? schema;
+	return {
+		schema,
+		validate(value, path = "$") {
+			validateValue(schema, rootDocument, value, path, []);
+			return toJsonValue(value, `${path} must be JSON-serializable`);
+		}
+	};
+}
+function visitSchema(schema, rootDocument, requireRootObject, limits, stats, refs, depth) {
+	stats.nodes += 1;
+	if (stats.nodes > limits.maxNodes) throw new TypeError(`JSON Schema exceeds maxNodes limit of ${limits.maxNodes}`);
+	if (depth > limits.maxDepth) throw new TypeError(`JSON Schema exceeds maxDepth limit of ${limits.maxDepth}`);
+	for (const key of Object.keys(schema)) if (DEFERRED.has(key) || !KEYWORDS.has(key)) throw new TypeError(`JSON Schema keyword "${key}" is not supported`);
+	if (requireRootObject && schema.type !== "object" && !schema.$ref && !schema.allOf) throw new TypeError("Tool input JSON Schema root must be object");
+	if (typeof schema.$ref === "string") {
+		const ref = schema.$ref;
+		if (!ref.startsWith("#/")) throw new TypeError(`Remote JSON Schema ref "${ref}" is not supported`);
+		if (refs.includes(ref)) throw new TypeError(`JSON Schema ref cycle detected at "${ref}"`);
+		visitSchema(resolveRef(rootDocument, ref), rootDocument, false, limits, stats, [...refs, ref], depth + 1);
+	}
+	if (schema.properties !== void 0) {
+		if (!isRecord(schema.properties)) throw new TypeError("JSON Schema properties must be an object");
+		const entries = Object.entries(schema.properties);
+		if (entries.length > limits.maxProperties) throw new TypeError(`JSON Schema exceeds maxProperties limit of ${limits.maxProperties}`);
+		for (const [, child] of entries) {
+			if (!isRecord(child)) throw new TypeError("JSON Schema property schemas must be objects");
+			visitSchema(child, rootDocument, false, limits, stats, refs, depth + 1);
+		}
+	}
+	for (const key of ["$defs"]) {
+		if (schema[key] === void 0) continue;
+		if (!isRecord(schema[key])) throw new TypeError(`JSON Schema ${key} must be an object`);
+		for (const child of Object.values(schema[key])) {
+			if (!isRecord(child)) throw new TypeError(`JSON Schema ${key} entries must be objects`);
+			visitSchema(child, rootDocument, false, limits, stats, refs, depth + 1);
+		}
+	}
+	if (schema.items !== void 0) {
+		if (!isRecord(schema.items)) throw new TypeError("JSON Schema items must be an object");
+		visitSchema(schema.items, rootDocument, false, limits, stats, refs, depth + 1);
+	}
+	for (const key of [
+		"allOf",
+		"anyOf",
+		"oneOf"
+	]) {
+		if (schema[key] === void 0) continue;
+		if (!Array.isArray(schema[key])) throw new TypeError(`JSON Schema ${key} must be an array`);
+		for (const child of schema[key]) {
+			if (!isRecord(child)) throw new TypeError(`JSON Schema ${key} entries must be objects`);
+			visitSchema(child, rootDocument, false, limits, stats, refs, depth + 1);
+		}
+	}
+	if (schema.additionalProperties !== void 0 && schema.additionalProperties !== false) {
+		if (schema.additionalProperties !== true && !isRecord(schema.additionalProperties)) throw new TypeError("JSON Schema additionalProperties must be boolean or object");
+		if (isRecord(schema.additionalProperties)) visitSchema(schema.additionalProperties, rootDocument, false, limits, stats, refs, depth + 1);
+	}
+}
+function validateValue(schema, rootDocument, value, path, refs) {
+	if (typeof schema.$ref === "string") {
+		if (refs.includes(schema.$ref)) throw new TypeError(`JSON Schema ref cycle detected at "${schema.$ref}"`);
+		return validateValue(resolveRef(rootDocument, schema.$ref), rootDocument, value, path, [...refs, schema.$ref]);
+	}
+	if (Array.isArray(schema.allOf)) for (const child of schema.allOf) validateValue(child, rootDocument, value, path, refs);
+	if (Array.isArray(schema.anyOf)) {
+		if (!schema.anyOf.some((child) => passes(child, rootDocument, value, path, refs))) throw new TypeError(`${path} must match anyOf`);
+	}
+	if (Array.isArray(schema.oneOf)) {
+		if (schema.oneOf.filter((child) => passes(child, rootDocument, value, path, refs)).length !== 1) throw new TypeError(`${path} must match exactly one oneOf schema`);
+	}
+	if ("const" in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) throw new TypeError(`${path} must equal const`);
+	if (Array.isArray(schema.enum) && !schema.enum.some((item) => JSON.stringify(item) === JSON.stringify(value))) throw new TypeError(`${path} must be one of enum`);
+	validateType(schema.type, value, path);
+	if (schema.type === "object" || isRecord(value)) validateObject(schema, rootDocument, value, path, refs);
+	if (schema.type === "array" || Array.isArray(value)) validateArray(schema, rootDocument, value, path, refs);
+	if (typeof value === "string") {
+		if (typeof schema.minLength === "number" && value.length < schema.minLength) throw new TypeError(`${path} is shorter than minLength`);
+		if (typeof schema.maxLength === "number" && value.length > schema.maxLength) throw new TypeError(`${path} is longer than maxLength`);
+	}
+	if (typeof value === "number") {
+		if (typeof schema.minimum === "number" && value < schema.minimum) throw new TypeError(`${path} is below minimum`);
+		if (typeof schema.maximum === "number" && value > schema.maximum) throw new TypeError(`${path} is above maximum`);
+	}
+}
+function validateObject(schema, rootDocument, value, path, refs) {
+	if (!isRecord(value)) return;
+	const required = Array.isArray(schema.required) ? schema.required : [];
+	for (const key of required) if (typeof key === "string" && !(key in value)) throw new TypeError(`${path}.${key} is required`);
+	const properties = isRecord(schema.properties) ? schema.properties : {};
+	for (const [key, child] of Object.entries(properties)) if (key in value && isRecord(child)) validateValue(child, rootDocument, value[key], `${path}.${key}`, refs);
+	if (schema.additionalProperties === false) {
+		for (const key of Object.keys(value)) if (!(key in properties)) throw new TypeError(`${path}.${key} is not allowed`);
+	} else if (isRecord(schema.additionalProperties)) {
+		for (const [key, item] of Object.entries(value)) if (!(key in properties)) validateValue(schema.additionalProperties, rootDocument, item, `${path}.${key}`, refs);
+	}
+}
+function validateArray(schema, rootDocument, value, path, refs) {
+	if (!Array.isArray(value)) return;
+	if (typeof schema.minItems === "number" && value.length < schema.minItems) throw new TypeError(`${path} has fewer than minItems`);
+	if (typeof schema.maxItems === "number" && value.length > schema.maxItems) throw new TypeError(`${path} has more than maxItems`);
+	if (isRecord(schema.items)) value.forEach((item, index) => validateValue(schema.items, rootDocument, item, `${path}[${index}]`, refs));
+}
+function validateType(type, value, path) {
+	if (type === void 0) return;
+	const types = Array.isArray(type) ? type : [type];
+	if (!types.some((item) => {
+		if (item === "array") return Array.isArray(value);
+		if (item === "integer") return Number.isInteger(value);
+		if (item === "number") return typeof value === "number" && Number.isFinite(value);
+		if (item === "object") return isRecord(value);
+		if (item === "null") return value === null;
+		return typeof value === item;
+	})) throw new TypeError(`${path} must be ${types.join(" or ")}`);
+}
+function passes(schema, rootDocument, value, path, refs) {
+	try {
+		validateValue(schema, rootDocument, value, path, refs);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function resolveRef(rootDocument, ref) {
+	const segments = ref.slice(2).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+	let current = rootDocument;
+	for (const segment of segments) {
+		if (!isRecord(current) || !(segment in current)) throw new TypeError(`JSON Schema ref "${ref}" cannot be resolved`);
+		current = current[segment];
+	}
+	if (!isRecord(current)) throw new TypeError(`JSON Schema ref "${ref}" must resolve to an object`);
+	return current;
+}
+function toJsonValue(value, message) {
+	try {
+		const cloned = JSON.parse(JSON.stringify(value));
+		if (cloned === void 0) throw new TypeError(message);
+		return cloned;
+	} catch {
+		throw new TypeError(message);
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/tools/tool.ts
 function defineTool(tool) {
 	return tool;
 }
@@ -10,4 +230,224 @@ function toToolSpec(tool, inputSchema) {
 	};
 }
 //#endregion
-export { defineTool, toToolSpec };
+//#region src/tools/tool-index.ts
+/** Bounded LRU cache for tool embeddings. */
+var InMemoryToolEmbeddingCache = class {
+	#entries = /* @__PURE__ */ new Map();
+	#maxEntries;
+	constructor(options = {}) {
+		const maxEntries = options.maxEntries ?? 1e3;
+		if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) throw new TypeError("Tool embedding cache maxEntries must be a positive safe integer");
+		this.#maxEntries = maxEntries;
+	}
+	get size() {
+		return this.#entries.size;
+	}
+	get(key) {
+		assertKey(key);
+		const value = this.#entries.get(key);
+		if (value === void 0) return void 0;
+		this.#entries.delete(key);
+		this.#entries.set(key, value);
+		return [...value];
+	}
+	set(key, vector) {
+		assertKey(key);
+		assertVector(vector, "Tool embedding cache vector");
+		this.#entries.delete(key);
+		this.#entries.set(key, [...vector]);
+		while (this.#entries.size > this.#maxEntries) {
+			const oldest = this.#entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.#entries.delete(oldest);
+		}
+	}
+	getMany(keys) {
+		return keys.map((key) => this.get(key));
+	}
+	setMany(entries) {
+		for (const entry of entries) this.set(entry.key, entry.vector);
+	}
+};
+/**
+* Builds or refreshes a semantic index for a tool catalog. The content key is
+* `sha256(embeddingModel.id + text)`, so changing the model or the tool text
+* invalidates the cached vector.
+*/
+async function buildToolEmbeddingIndex(options) {
+	assertEmbeddingModel(options.embeddings);
+	const batchSize = options.batchSize ?? 64;
+	if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new TypeError("Tool embedding batchSize must be a positive safe integer");
+	const tools = options.tools;
+	const texts = tools.map(toolEmbeddingText);
+	const keys = await Promise.all(texts.map((text) => toolEmbeddingKey(options.embeddings.id, text)));
+	const vectors = /* @__PURE__ */ new Map();
+	const missing = /* @__PURE__ */ new Map();
+	const batchCached = await readCacheMany(options.cache, keys, options.embeddings.dimensions);
+	for (let index = 0; index < tools.length; index += 1) {
+		const key = keys[index];
+		const cached = batchCached === void 0 ? await readCache(options.cache, key, options.embeddings.dimensions) : batchCached[index];
+		if (cached !== void 0) {
+			vectors.set(key, cached);
+			continue;
+		}
+		if (!missing.has(key)) missing.set(key, texts[index]);
+	}
+	const pending = [...missing.entries()];
+	for (let offset = 0; offset < pending.length; offset += batchSize) {
+		options.signal?.throwIfAborted();
+		const batch = pending.slice(offset, offset + batchSize);
+		const embedded = await options.embeddings.embed({
+			texts: batch.map(([, text]) => text),
+			...options.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!Array.isArray(embedded) || embedded.length !== batch.length) throw new Error(`Embedding model "${options.embeddings.id}" returned ${embedded.length} vectors for ${batch.length} texts`);
+		const writes = [];
+		for (let index = 0; index < batch.length; index += 1) {
+			const vector = embedded[index];
+			assertVector(vector, `Embedding for "${batch[index][1]}"`);
+			vectors.set(batch[index][0], vector);
+			writes.push({
+				key: batch[index][0],
+				vector
+			});
+		}
+		if (options.cache?.setMany !== void 0) try {
+			await options.cache.setMany(writes);
+		} catch {}
+		else for (const write of writes) await writeCache(options.cache, write.key, write.vector);
+	}
+	const dimensions = options.embeddings.dimensions ?? vectors.values().next().value?.length ?? 0;
+	for (const vector of vectors.values()) if (vector.length !== dimensions) throw new Error(`Embedding model "${options.embeddings.id}" returned mixed dimensions: ${dimensions} and ${vector.length}`);
+	return {
+		modelId: options.embeddings.id,
+		dimensions,
+		entries: tools.map((tool, index) => ({
+			tool,
+			vector: [...vectors.get(keys[index])]
+		}))
+	};
+}
+/** Returns cosine matches above `minScore`, ordered by score. */
+function searchToolEmbeddingIndex(index, query, limit, minScore = 0) {
+	if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError("Tool embedding search limit must be a positive safe integer");
+	if (query.length !== index.dimensions) throw new TypeError(`Query embedding has ${query.length} dimensions; index expects ${index.dimensions}`);
+	assertVector([...query], "Query embedding");
+	if (typeof minScore !== "number" || !Number.isFinite(minScore)) throw new TypeError("Tool embedding minScore must be a finite number");
+	return index.entries.map((entry) => ({
+		tool: entry.tool,
+		score: cosineSimilarity(query, entry.vector)
+	})).filter(({ score }) => score >= minScore).sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name)).slice(0, limit);
+}
+/** Canonical text indexed for one tool: name, description and schema keywords. */
+function toolEmbeddingText(tool) {
+	return [
+		tool.name,
+		tool.description ?? "",
+		schemaKeywords(tool.inputSchema)
+	].filter(Boolean).join("\n");
+}
+/** Extracts property names, descriptions, titles, required fields and enum values. */
+function schemaKeywords(schema) {
+	if (schema === void 0) return "";
+	const terms = /* @__PURE__ */ new Set();
+	const visit = (value, key) => {
+		if (typeof value === "string") {
+			if (key === "description" || key === "title" || key === "const") terms.add(value);
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, key);
+			return;
+		}
+		if (value === null || typeof value !== "object") return;
+		for (const [childKey, child] of Object.entries(value)) {
+			if (childKey === "properties" && child !== null && typeof child === "object" && !Array.isArray(child)) {
+				for (const property of Object.keys(child)) terms.add(property);
+				visit(child, childKey);
+				continue;
+			}
+			if (childKey === "required" && Array.isArray(child)) {
+				for (const item of child) if (typeof item === "string") terms.add(item);
+				continue;
+			}
+			if (childKey === "enum" && Array.isArray(child)) {
+				for (const item of child) terms.add(String(item));
+				continue;
+			}
+			visit(child, childKey);
+		}
+	};
+	visit(schema);
+	return [...terms].join(" ");
+}
+/** Stable content key for one embedding model and tool text. */
+async function toolEmbeddingKey(modelId, text) {
+	if (!modelId.trim()) throw new TypeError("Embedding model id cannot be empty");
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${modelId}\n${text}`));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function cosineSimilarity(left, right) {
+	assertVector(left, "Left cosine vector");
+	assertVector(right, "Right cosine vector");
+	if (left.length !== right.length) throw new TypeError(`Cosine vectors must have the same dimensions: ${left.length} and ${right.length}`);
+	let dot = 0;
+	let leftNorm = 0;
+	let rightNorm = 0;
+	for (let index = 0; index < left.length; index += 1) {
+		const a = left[index];
+		const b = right[index];
+		dot += a * b;
+		leftNorm += a * a;
+		rightNorm += b * b;
+	}
+	if (leftNorm === 0 || rightNorm === 0) return 0;
+	return dot / Math.sqrt(leftNorm * rightNorm);
+}
+function assertEmbeddingModel(model) {
+	if (typeof model.id !== "string" || !model.id.trim()) throw new TypeError("Embedding model id must be a non-empty string");
+	if (typeof model.embed !== "function") throw new TypeError("Embedding model must implement embed");
+	if (model.dimensions !== void 0 && (!Number.isSafeInteger(model.dimensions) || model.dimensions < 1)) throw new TypeError("Embedding model dimensions must be a positive safe integer");
+}
+function assertKey(key) {
+	if (typeof key !== "string" || !key.trim()) throw new TypeError("Tool embedding cache key must be a non-empty string");
+}
+function assertVector(vector, label) {
+	if (!Array.isArray(vector) || vector.length === 0 || vector.some((value) => typeof value !== "number" || !Number.isFinite(value))) throw new TypeError(`${label} must be a non-empty array of finite numbers`);
+}
+async function readCache(cache, key, dimensions) {
+	if (cache === void 0) return void 0;
+	try {
+		return normalizeCached(await cache.get(key), dimensions);
+	} catch {
+		return;
+	}
+}
+async function readCacheMany(cache, keys, dimensions) {
+	if (cache?.getMany === void 0) return void 0;
+	try {
+		const values = await cache.getMany(keys);
+		if (!Array.isArray(values) || values.length !== keys.length) return void 0;
+		return values.map((value) => normalizeCached(value, dimensions));
+	} catch {
+		return;
+	}
+}
+function normalizeCached(value, dimensions) {
+	if (value === void 0) return void 0;
+	try {
+		assertVector(value, "Cached tool embedding");
+		if (dimensions !== void 0 && value.length !== dimensions) return void 0;
+		return [...value];
+	} catch {
+		return;
+	}
+}
+async function writeCache(cache, key, vector) {
+	if (cache === void 0) return;
+	try {
+		await cache.set(key, [...vector]);
+	} catch {}
+}
+//#endregion
+export { FEVEX_JSON_SCHEMA_PROFILE_VERSION, InMemoryToolEmbeddingCache, IntegrationError, buildToolEmbeddingIndex, compileFevexJsonSchema, cosineSimilarity, defineConnection, defineTool, schemaKeywords, searchToolEmbeddingIndex, toToolSpec, toolEmbeddingKey, toolEmbeddingText, validateFevexJsonSchemaProfile };