@formio/uag-sdk 0.0.0-stage → 2.0.0-rc.2

package/define.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/** The engine contract version this SDK describes. */
+const ENGINE_API_VERSION = 1;
+
+/** Engine type and instance names: what `UAG_ENGINES` and routing lists use. */
+const ENGINE_NAME = /^[a-z][a-z0-9-]{0,62}$/;
+
+const KINDS = ['decision', 'agent'];
+const SETTING_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const VARIABLE_NAME = /^[A-Z][A-Z0-9_]*$/;
+const SETTING_TYPES = ['string', 'number', 'boolean'];
+const SETTING_KEYS = ['env', 'required', 'secret', 'default', 'type', 'description'];
+
+/** The reasons a value is not a valid engine type definition; empty when it is. */
+function definitionProblems(definition) {
+    if (!definition || typeof definition !== 'object') {
+        return ['it is not an object'];
+    }
+    const problems = [];
+    if (typeof definition.type !== 'string' || !ENGINE_NAME.test(definition.type)) {
+        problems.push('"type" must be a name of lowercase letters, digits and "-", starting with a letter');
+    }
+    if (!Array.isArray(definition.kinds) || !definition.kinds.length || !definition.kinds.every((kind) => KINDS.includes(kind))) {
+        problems.push('"kinds" must list "decision", "agent" or both');
+    }
+    if (!Number.isInteger(definition.apiVersion) || definition.apiVersion < 1) {
+        problems.push('"apiVersion" must be the engine contract version it was built for');
+    }
+    if (typeof definition.create !== 'function') {
+        problems.push('"create" must be a function');
+    }
+    const settings = definition.settings === undefined ? {} : definition.settings;
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+        problems.push('"settings" must be an object');
+    }
+    else {
+        for (const [key, spec] of Object.entries(settings)) {
+            problems.push(...settingProblems(key, spec));
+        }
+    }
+    return problems;
+}
+
+function settingProblems(key, spec) {
+    const label = `setting "${key}"`;
+    if (!SETTING_NAME.test(key)) {
+        return [`${label} must be a camelCase name`];
+    }
+    if (!spec || typeof spec !== 'object') {
+        return [`${label} must be an object`];
+    }
+    const problems = [];
+    const unknown = Object.keys(spec).filter((name) => !SETTING_KEYS.includes(name));
+    if (unknown.length) {
+        problems.push(`${label} has unknown keys: ${unknown.join(', ')}`);
+    }
+    const env = spec.env === undefined ? [] : [].concat(spec.env);
+    if (!env.every((name) => typeof name === 'string' && VARIABLE_NAME.test(name))) {
+        problems.push(`${label}: "env" must name upper-case environment variables`);
+    }
+    if (spec.type !== undefined && !SETTING_TYPES.includes(spec.type)) {
+        problems.push(`${label}: "type" must be one of ${SETTING_TYPES.join(', ')}`);
+    }
+    for (const flag of ['required', 'secret']) {
+        if (spec[flag] !== undefined && typeof spec[flag] !== 'boolean') {
+            problems.push(`${label}: "${flag}" must be true or false`);
+        }
+    }
+    if (spec.default !== undefined && typeof spec.default !== (spec.type || 'string')) {
+        problems.push(`${label}: "default" must be a ${spec.type || 'string'}`);
+    }
+    return problems;
+}
+
+/** Whether a value is a valid engine type definition, from this SDK or any other copy of it. */
+function isEngineType(value) {
+    return definitionProblems(value).length === 0;
+}
+
+/**
+ * Define an engine type. Validates the definition and returns it frozen, so a
+ * mistake in it fails when the package loads rather than when the UAG starts:
+ *
+ *   module.exports = defineEngine({
+ *       type: 'acme',
+ *       kinds: ['agent'],
+ *       apiVersion: ENGINE_API_VERSION,
+ *       settings: { apiKey: { env: 'ACME_API_KEY', required: true, secret: true } },
+ *       create({ name, settings }) { return { name, kind: 'agent', model: '...', extract }; },
+ *   });
+ */
+function defineEngine(definition) {
+    const problems = definitionProblems(definition);
+    if (problems.length) {
+        const type = definition && typeof definition.type === 'string' ? ` "${definition.type}"` : '';
+        throw new TypeError(`The engine type${type} is not valid: ${problems.join('; ')}.`);
+    }
+    const settings = {};
+    for (const [key, spec] of Object.entries(definition.settings || {})) {
+        settings[key] = Object.freeze({ ...spec, ...(spec.env !== undefined && { env: Object.freeze([].concat(spec.env)) }) });
+    }
+    return Object.freeze({ ...definition, kinds: Object.freeze([...definition.kinds]), settings: Object.freeze(settings) });
+}
+
+module.exports = { ENGINE_API_VERSION, ENGINE_NAME, KINDS, defineEngine, definitionProblems, isEngineType };

package/errors.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * An engine failure whose message is safe to show to API callers, such as
+ * "Quota exceeded for this API key". The UAG reports any other engine error only
+ * as "the engine failed (see the logs for request X)", because a provider SDK's
+ * error can carry URLs or account details.
+ */
+class EngineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineError';
+        Object.defineProperty(this, 'expose', { value: true, enumerable: true });
+    }
+}
+
+/**
+ * Thrown when an engine instance cannot be enabled. The message names the
+ * instance, and is what the operator reads when the UAG refuses to start.
+ */
+class EngineConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineConfigError';
+    }
+}
+
+/** Shorter values are too likely to occur by chance to be worth redacting. */
+const MIN_SECRET_LENGTH = 4;
+
+/** `text` with every occurrence of each secret value replaced. */
+function redact(text, secrets) {
+    let result = String(text);
+    for (const secret of secrets || []) {
+        const value = secret === undefined || secret === null ? '' : String(secret);
+        if (value.length >= MIN_SECRET_LENGTH) {
+            result = result.split(value).join('[redacted]');
+        }
+    }
+    return result;
+}
+
+module.exports = { EngineError, EngineConfigError, redact };

package/helpers.js

@@ -0,0 +1,145 @@
+'use strict';
+const { EngineError } = require('./errors');
+
+/**
+ * Helpers shared by agent engines built on model APIs with structured outputs.
+ */
+
+/**
+ * The extraction schema with every field required, for strict structured
+ * outputs: providers limit how many optional properties and union types a
+ * strict schema may have, and OpenAI's strict mode needs every property in
+ * `required`. An empty value stands for "not stated": "" for text and options,
+ * [] for lists. Numbers and booleans travel as strings, keeping the field's
+ * title and description. `decode` maps an answer
+ * back to the UAG's schema, leaving the "not stated" fields out.
+ *
+ *   const { schema, decode } = requiredSchema(request.schema);
+ *   // ... ask the model for `schema` ...
+ *   return { model, values: decode(answer) };
+ */
+function requiredSchema(schema) {
+    const { schema: sent, decoders } = encodeObject(schema, false);
+    return { schema: sent, decode: (values) => decodeValues(values, decoders) };
+}
+
+function encodeObject(schema, nested) {
+    const properties = {};
+    const decoders = {};
+    for (const [path, property] of Object.entries((schema && schema.properties) || {})) {
+        const { sent, decode } = encodeProperty(property, nested);
+        properties[path] = sent;
+        if (decode) decoders[path] = decode;
+    }
+    return { schema: { ...schema, properties, required: Object.keys(properties) }, decoders };
+}
+
+function encodeProperty(property, nested) {
+    // Before the number and boolean cases, so a typed enum keeps its values.
+    if (Array.isArray(property.enum)) {
+        if (property.enum.every((value) => typeof value === 'string')) {
+            return { sent: { ...property, enum: [...new Set([...property.enum, ''])] } };
+        }
+        // Other values travel as their JSON text. A provider that does not
+        // enforce the schema may answer anything: only an allowed value is kept.
+        const { type, ...rest } = property;
+        const allowed = new Map(property.enum.map((value) => [JSON.stringify(value), value]));
+        return {
+            sent: { ...rest, type: 'string', enum: [...allowed.keys(), ''] },
+            decode: (value) => (allowed.has(value) ? allowed.get(value) : undefined),
+        };
+    }
+    if (property.type === 'number' || property.type === 'integer') {
+        return {
+            sent: { type: 'string', ...described(property, NUMBER_HINT) },
+            decode: parseNumber,
+        };
+    }
+    // Inside an object (select boxes) false already means "not selected".
+    if (property.type === 'boolean' && !nested) {
+        return {
+            sent: { enum: ['true', 'false', ''], ...described(property) },
+            decode: (value) => (value === 'true' || value === true ? true : value === 'false' || value === false ? false : undefined),
+        };
+    }
+    if (property.type === 'object' && property.properties) {
+        const inner = encodeObject(property, true);
+        return {
+            sent: inner.schema,
+            decode: (value) => {
+                const decoded = decodeValues(value, inner.decoders);
+                return Object.keys(decoded).length ? decoded : undefined;
+            },
+        };
+    }
+    return { sent: property };
+}
+
+const NUMBER_HINT = 'Answer in digits only, such as 4250 or -3.5, with no currency or units.';
+
+/** The field's title and description, which a string encoding would otherwise drop, with a hint. */
+function described(property, hint) {
+    const description = [property.description, hint].filter(Boolean).join(' ');
+    return { ...(property.title && { title: property.title }), ...(description && { description }) };
+}
+
+/**
+ * A number from a model's answer. Models write amounts as they read them
+ * ("$4,250"), so a currency sign and thousands separators are accepted;
+ * anything else that is not a plain number is "not stated".
+ */
+function parseNumber(value) {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string') return undefined;
+    const match = /^\s*([+-])?\s*[$€£¥]?\s*(\d[\d,]*(?:\.\d+)?|\.\d+)\s*[$€£¥]?\s*$/.exec(value);
+    if (!match) return undefined;
+    const digits = match[2];
+    if (digits.includes(',') && !/^\d{1,3}(,\d{3})+(\.\d+)?$/.test(digits)) return undefined;
+    const number = Number(`${match[1] || ''}${digits.replace(/,/g, '')}`);
+    return Number.isFinite(number) ? number : undefined;
+}
+
+/** The answer without the empty "not stated" values, in the UAG's types. */
+function decodeValues(values, decoders) {
+    const decoded = {};
+    if (!values || typeof values !== 'object' || Array.isArray(values)) return decoded;
+    for (const [path, value] of Object.entries(values)) {
+        if (value === '' || value === null || (Array.isArray(value) && !value.length)) continue;
+        const result = decoders[path] ? decoders[path](value) : value;
+        if (result !== undefined) decoded[path] = result;
+    }
+    return decoded;
+}
+
+/**
+ * The first JSON object in a model's text answer, tolerating code fences and
+ * prose around it. Throws an `EngineError` when there is none.
+ */
+function parseJsonObject(text) {
+    const unfenced = String(text || '').replace(/```(?:json)?/gi, '');
+    const start = unfenced.indexOf('{');
+    const end = unfenced.lastIndexOf('}');
+    let parsed;
+    if (start !== -1 && end > start) {
+        try {
+            parsed = JSON.parse(unfenced.slice(start, end + 1));
+        }
+        catch {
+            parsed = undefined;
+        }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new EngineError('The engine did not return a JSON object.');
+    }
+    return parsed;
+}
+
+/** A tool call's result as text for the model: its text blocks, other blocks as JSON. */
+function toolResultText(result) {
+    const text = ((result && result.content) || [])
+        .map((block) => (block && typeof block.text === 'string' ? block.text : JSON.stringify(block)))
+        .join('\n');
+    return text || '(no output)';
+}
+
+module.exports = { requiredSchema, decodeValues, parseJsonObject, toolResultText };

package/index.d.ts

@@ -0,0 +1,102 @@
+import type { Engine } from './contract';
+
+export * from './contract';
+
+/** Engine type and instance names: lowercase letters, digits and "-", starting with a letter. */
+export declare const ENGINE_NAME: RegExp;
+
+/** One setting an engine type reads. */
+export type SettingSpec = {
+    /** The type's own environment variables for the setting, read after `UAG_ENGINE_<NAME>_<SETTING>`. */
+    env?: string | readonly string[];
+    /** Startup fails, naming the instance and the variables, when no value is set. */
+    required?: boolean;
+    /** Kept out of startup errors and capability discovery. */
+    secret?: boolean;
+    default?: string | number | boolean;
+    /** Values from the environment are converted to this type. Default: "string". */
+    type?: 'string' | 'number' | 'boolean';
+    description?: string;
+};
+
+/** What an engine type's `create` receives for one instance. */
+export type EngineCreateContext<Settings = Record<string, any>> = {
+    /** The instance name. The engine must use it as its `name`. */
+    name: string;
+    /** The instance's value for each declared setting that has one. */
+    settings: Settings;
+    /** The instance's options as given in configuration, including ones that are not settings (such as a test client). */
+    options: Record<string, any>;
+    /** The host's configuration, read-only (for example routing timeouts). */
+    config: Record<string, any>;
+    /** A setting's value, or the standard "needs its setting" error, for settings required only in some cases. */
+    requireSetting(key: string): any;
+};
+
+/** What an engine package exports. */
+export interface EngineTypeDefinition<Settings = Record<string, any>> {
+    /** The type name, as in `UAG_ENGINES=<type>` and `<name>:<type>`. */
+    type: string;
+    kinds: readonly ('decision' | 'agent')[];
+    /** The engine contract version the type was built for: `ENGINE_API_VERSION`. */
+    apiVersion: number;
+    description?: string;
+    settings?: Record<string, SettingSpec>;
+    create(context: EngineCreateContext<Settings>): Engine | Promise<Engine>;
+}
+
+/** Validate an engine type definition and return it frozen. Throws a TypeError naming every problem. */
+export declare function defineEngine<T extends EngineTypeDefinition<any>>(definition: T): Readonly<T>;
+
+/** Whether a value is a valid engine type definition, from this SDK, another copy of it, or none. */
+export declare function isEngineType(value: unknown): value is EngineTypeDefinition;
+
+/**
+ * An engine failure whose message is safe to show to API callers. Other engine
+ * errors are reported only as "the engine failed (see the logs for request X)".
+ */
+export declare class EngineError extends Error {
+    readonly expose: true;
+    constructor(message: string);
+}
+
+/** An engine instance that cannot be enabled. The message names the instance. */
+export declare class EngineConfigError extends Error {
+    constructor(message: string);
+}
+
+/** `text` with each secret value replaced by "[redacted]". */
+export declare function redact(text: unknown, secrets: unknown[]): string;
+
+/** An engine instance to enable. `name` is undefined until loading when only a package or definition was given. */
+export type EngineInstanceSpec = {
+    name?: string;
+    type: string | EngineTypeDefinition;
+    options?: Record<string, any>;
+};
+
+/** Parse a `UAG_ENGINES` string (`jev,fast:claude`) or a configuration list. Nothing named means none. */
+export declare function parseInstances(source: string | (string | EngineInstanceSpec)[] | undefined | null): EngineInstanceSpec[];
+
+/** The instances from configuration (`engines`) when it lists them, otherwise from `UAG_ENGINES`. */
+export declare function engineInstances(config?: Record<string, any>, env?: Record<string, string | undefined>): EngineInstanceSpec[];
+
+/** An instance's own variable for a setting: `UAG_ENGINE_<NAME>_<SETTING>`. */
+export declare function settingVariable(instance: string, setting: string): string;
+
+/** An instance's settings: options, then `UAG_ENGINE_<NAME>_<SETTING>`, then the type's variables, then the default. */
+export declare function resolveSettings(definition: EngineTypeDefinition, name: string, options?: Record<string, any>, env?: Record<string, string | undefined>): Record<string, any>;
+
+/**
+ * The extraction schema with every field required, for strict structured
+ * outputs, and `decode`, which maps an answer back to the UAG's schema.
+ */
+export declare function requiredSchema(schema: Record<string, any>): { schema: Record<string, any>; decode(values: unknown): Record<string, any> };
+
+export declare function decodeValues(values: unknown, decoders: Record<string, (value: any) => any>): Record<string, any>;
+
+/** The first JSON object in a model's text answer. Throws an `EngineError` when there is none. */
+export declare function parseJsonObject(text: string): Record<string, any>;
+
+/** A tool call's result as text for a model. */
+export declare function toolResultText(result: { content?: { type: string; text?: string; [key: string]: any }[] }): string;

package/index.js

@@ -0,0 +1,30 @@
+'use strict';
+/**
+ * @formio/uag-sdk: what engine packages for the Form.io UAG are built
+ * with. The engine contract's types are in contract.d.ts; the loader is
+ * `@formio/uag-sdk/loader` and the conformance check
+ * `@formio/uag-sdk/conformance`.
+ */
+const { ENGINE_API_VERSION, ENGINE_NAME, defineEngine, isEngineType } = require('./define');
+const { EngineError, EngineConfigError, redact } = require('./errors');
+const { parseInstances, engineInstances } = require('./instances');
+const { settingVariable, resolveSettings } = require('./settings');
+const { requiredSchema, decodeValues, parseJsonObject, toolResultText } = require('./helpers');
+
+module.exports = {
+    ENGINE_API_VERSION,
+    ENGINE_NAME,
+    defineEngine,
+    isEngineType,
+    EngineError,
+    EngineConfigError,
+    redact,
+    parseInstances,
+    engineInstances,
+    settingVariable,
+    resolveSettings,
+    requiredSchema,
+    decodeValues,
+    parseJsonObject,
+    toolResultText,
+};

package/instances.js

@@ -0,0 +1,117 @@
+'use strict';
+const { ENGINE_NAME } = require('./define');
+const { EngineConfigError } = require('./errors');
+
+/**
+ * npm package names, scoped or not. Every segment starts with a letter or digit,
+ * so "." and ".." (and so any relative path) can never match.
+ */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const MAX_PACKAGE_NAME = 214;
+
+/**
+ * Whether a type is given as a package name rather than a type name: scoped
+ * (`@acme/uag-engine-x`), or unscoped with the conventional prefix (`uag-engine-x`).
+ */
+function isPackageName(type) {
+    return type.startsWith('@') || type.includes('/') || type.startsWith('uag-engine-');
+}
+
+/** Refuse a type that is neither a type name nor a package name, before any lookup. */
+function checkType(type) {
+    const valid = isPackageName(type)
+        ? PACKAGE_NAME.test(type) && type.length <= MAX_PACKAGE_NAME
+        : ENGINE_NAME.test(type);
+    if (!valid) {
+        throw new EngineConfigError(
+            `The engine type name ${JSON.stringify(type)} is not valid. Use a type name such as "claude", ` +
+            'or a package name such as "@acme/uag-engine-x" or "uag-engine-x".'
+        );
+    }
+}
+
+function checkName(name) {
+    if (!ENGINE_NAME.test(name)) {
+        throw new EngineConfigError(
+            `The engine name ${JSON.stringify(name)} is not valid: use lowercase letters, digits and "-", ` +
+            'starting with a letter, up to 63 characters.'
+        );
+    }
+}
+
+/** Refuse two instances with the same name. Instances without a name yet are skipped. */
+function checkUnique(instances) {
+    const seen = new Set();
+    for (const { name } of instances) {
+        if (!name) continue;
+        if (seen.has(name)) {
+            throw new EngineConfigError(`Two engines are named "${name}". Engine instance names must be unique.`);
+        }
+        seen.add(name);
+    }
+}
+
+/** One `UAG_ENGINES` entry: `<type>` or `<name>:<type>`. */
+function parseEntry(entry) {
+    const colon = entry.indexOf(':');
+    const name = colon === -1 ? undefined : entry.slice(0, colon).trim();
+    const type = colon === -1 ? entry : entry.slice(colon + 1).trim();
+    if (name !== undefined) checkName(name);
+    checkType(type);
+    // A bare package name takes its type's name, which is known once it loads.
+    return { name: name ?? (isPackageName(type) ? undefined : type), type, options: {} };
+}
+
+/** One configuration entry: a `UAG_ENGINES` string, or `{ name, type, options }`. */
+function parseConfigured(entry) {
+    if (typeof entry === 'string') {
+        return parseEntry(entry.trim());
+    }
+    if (!entry || typeof entry !== 'object') {
+        throw new EngineConfigError(`An engine entry must be a string or { name, type, options }, not ${JSON.stringify(entry)}.`);
+    }
+    const { name, type, options = {} } = entry;
+    if (name !== undefined) checkName(name);
+    if (typeof type === 'string') {
+        checkType(type);
+    }
+    else if (!type || typeof type !== 'object') {
+        throw new EngineConfigError(`The engine${name ? ` "${name}"` : ''} needs a type: a type name, a package name, or an engine type definition.`);
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new EngineConfigError(`The options of the engine${name ? ` "${name}"` : ''} must be an object.`);
+    }
+    const named = name ?? (typeof type === 'string' ? (isPackageName(type) ? undefined : type) : undefined);
+    return { name: named, type, options };
+}
+
+/**
+ * The engine instances in a `UAG_ENGINES` string or a configuration list. Each
+ * is `{ name, type, options }`; `name` is undefined until the type is known when
+ * the entry names only a package or a definition. Nothing named means none.
+ */
+function parseInstances(source) {
+    if (source === undefined || source === null) return [];
+    let entries;
+    if (typeof source === 'string') {
+        entries = source.split(',').map((entry) => entry.trim()).filter(Boolean).map(parseEntry);
+    }
+    else if (Array.isArray(source)) {
+        entries = source.filter((entry) => entry !== '').map(parseConfigured);
+    }
+    else {
+        throw new EngineConfigError('The engine list must be a comma-separated string or an array.');
+    }
+    checkUnique(entries);
+    return entries;
+}
+
+/**
+ * The instances to enable: from configuration (`engines`) when it lists them,
+ * otherwise from `UAG_ENGINES`. Configuration takes precedence.
+ */
+function engineInstances(config = {}, env = process.env) {
+    return parseInstances(Array.isArray(config && config.engines) ? config.engines : env.UAG_ENGINES);
+}
+
+module.exports = { PACKAGE_NAME, isPackageName, checkName, checkType, checkUnique, parseInstances, engineInstances };

package/loader.d.ts

@@ -0,0 +1,48 @@
+import type { Engine } from './contract';
+import type { EngineInstanceSpec, EngineTypeDefinition } from './index';
+
+export type LoadOptions = {
+    /** Types resolved before any package: the built-in ones, and ones the embedding application passes. */
+    types?: Record<string, EngineTypeDefinition>;
+    /** The directories whose `node_modules` packages are looked up in, from `enginePaths`; nowhere else. */
+    paths?: string[];
+    env?: Record<string, string | undefined>;
+    config?: Record<string, any>;
+    /** The engine contract version the host supports. Default: this SDK's. */
+    apiVersion?: number;
+};
+
+/** An enabled engine and where it came from, ready for `Formflow.engineRegistry`. */
+export type LoadedEngine = {
+    engine: Engine;
+    type: string;
+    package?: string;
+    version?: string;
+};
+
+/**
+ * The directories whose `node_modules` packages are looked up in: the host's own
+ * installation and each directory above it, then each absolute directory in
+ * `UAG_ENGINE_PATH` (without the directories above it).
+ */
+export declare function enginePaths(root: string | undefined, env?: Record<string, string | undefined>): string[];
+
+/** The packages a type name may come from, in order. */
+export declare function packageCandidates(type: string): string[];
+
+export declare function resolveType(type: string | EngineTypeDefinition, options?: LoadOptions): {
+    definition: EngineTypeDefinition;
+    package?: string;
+    version?: string;
+};
+
+/** Create one engine for an instance, resolving its settings. */
+export declare function createEngine(definition: EngineTypeDefinition, options: {
+    name: string;
+    options?: Record<string, any>;
+    env?: Record<string, string | undefined>;
+    config?: Record<string, any>;
+}): Promise<Engine>;
+
+/** Resolve, configure and create each instance. Any problem stops loading, with the instance named. */
+export declare function loadEngines(instances: EngineInstanceSpec[], options?: LoadOptions): Promise<LoadedEngine[]>;