@formio/uag-jev 0.0.0-stage → 2.0.0-rc.10

package/LICENSE.txt

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+Copyright (c) 2025 Form.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @formio/uag-jev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<sub>[Form.io UAG](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md) &rsaquo; [Engines](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md#engines-and-routing) &rsaquo; this page</sub>
+
+The TypeSafe **Jev** decision engine for the [UAG Agent API](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md#agent-api). It answers a task's closed-set fields (radio, select, checkbox, select boxes, survey and small resource selects) in one request, typically in 70–500 ms, with a confidence for each answer.
+
+It is included in the `formio/uag` Docker image. Enable it by naming it, and set its key:
+
+```
+UAG_ENGINES=jev
+TYPESAFE_API_KEY=...
+```
+
+Decisions are Agentic Formflow, so on a self-hosted project the UAG also needs a `LICENSE_KEY` that includes the UAG (see [License](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md#license)); a project on Form.io's hosted service needs none.
+
+## Settings
+
+| Setting | Variables | Default |
+|---|---|---|
+| `apiKey` | `UAG_ENGINE_<NAME>_API_KEY`, `TYPESAFE_API_KEY` | required (secret) |
+| `model` | `UAG_ENGINE_<NAME>_MODEL`, `TYPESAFE_MODEL` | `jev-1.13.0` |
+| `baseURL` | `UAG_ENGINE_<NAME>_BASE_URL`, `TYPESAFE_BASE_URL` | the SDK's default |
+
+`<NAME>` is the instance name, upper-cased with `-` as `_`. An instance's own variable wins over the shared one.
+
+The SDK's request timeout follows the instance's routing timeout (`routing.timeouts.<name>`, else `agentApi.timeout`, else 30 seconds; always 30 seconds on an engine server), so its retries of rate-limit and overload responses never outlast it. After the timeout, the UAG falls back to the next engine.
+
+## Instances
+
+Run a second Jev model next to the first, for example to compare a new version on live traffic before switching:
+
+```
+UAG_ENGINES=jev,next:jev
+TYPESAFE_API_KEY=...
+UAG_ENGINE_NEXT_MODEL=jev-1.14.0
+```
+
+Routing lists name the instances: `routing.decision: ["next", "jev"]`.
+
+## Pin the model
+
+Behavior differs between Jev versions. Keep `model` at a dated version, and run `uag-eval` on your own labeled examples before changing it or any threshold. `uag-eval --engine jev` works from a checkout of the UAG repository or inside the `formio/uag` image:
+
+```
+docker run --rm --entrypoint node -v "$PWD:/data" -e TYPESAFE_API_KEY -e LICENSE_KEY formio/uag:rc \
+  --no-node-snapshot bin/uag-eval.js --form /data/claim.json --examples /data/claim-examples.json \
+  --engine jev --project <your project URL>
+```
+
+The license must allow that project URL.
+
+## How it works
+
+The UAG builds the questions and interprets the answers; this package only maps them to and from `@typesafe-ai/sdk`. Answers outside the options asked are dropped, and scores are kept within their levels. Jev's [confidence](https://docs.typesafe.ai/confidence) is already normalized against an even split, which is what the UAG's confidence threshold expects, so it is passed on unchanged.
+
+**Errors:** a refused API key (401, 403), a rate limit (429) and a TypeSafe server failure (5xx) reach API callers as that, with no response body; any other failure is reported only as "the engine failed". Retries never wait longer than the request timeout for a `Retry-After`.
+
+**Data residency:** Jev is a hosted service. Each request sends TypeSafe:
+- the task's criteria and today's date;
+- the values at its `uagContext` paths;
+- its input fields, or, for a task with no input, the whole submission except the fields being decided.
+
+Deployments that cannot send data there should not enable this engine; decision fields then fall back to an agent engine.
+
+**Logging:** leave `TYPESAFE_LOG_LEVEL` unset (or `warn`) in production. At `debug`, the TypeSafe SDK writes each request and response body, which hold submission data, to the console.
+
+## Using it in your own server
+
+Name it in configuration instead of `UAG_ENGINES`, with options that take precedence over the environment:
+
+```js
+const server = new UAGServer({ engines: [{ name: 'jev', type: 'jev', options: { model: 'jev-1.13.0' } }] });
+```
+
+License: MIT.

package/index.js

@@ -0,0 +1,154 @@
+/**
+ * TypeSafe Jev decision engine for the UAG Agent API.
+ *
+ *   UAG_ENGINES=jev            TYPESAFE_API_KEY=...
+ *   UAG_ENGINES=jev,next:jev   UAG_ENGINE_NEXT_MODEL=jev-1.14.0
+ *
+ * The UAG compiles decision fields into Choice, Score and Noul questions and
+ * sends them all in one call; this engine only maps them to and from the SDK.
+ * The routing timeout aborts the request through its signal; without one (as
+ * in `uag-eval`), SDK retries wait at most the timeout for a `Retry-After`.
+ *
+ * Jev's `confidence` is already normalized as the contract asks: for a Choice,
+ * (p_max - 1/n) / (1 - 1/n); for a Score, how close the probability sits to the
+ * likeliest level, floored at 0 (https://docs.typesafe.ai/confidence).
+ */
+const { defineEngine, EngineError, ENGINE_API_VERSION } = require('@formio/uag-sdk');
+
+/** Pin a dated version, never an alias, and re-run `uag-eval` before changing it. */
+const DEFAULT_MODEL = 'jev-1.13.0';
+/** Jev accepts up to 255 options per Choice question. */
+const MAX_OPTIONS = 255;
+const DEFAULT_TIMEOUT = 30000;
+
+/** Map one UAG decision question to the SDK's question shape. */
+function toSdkQuestion(question) {
+    switch (question.type) {
+        case 'choice':
+            return { type: 'choice', instructions: question.instructions, criteria: question.options };
+        case 'score':
+            return { type: 'score', instructions: question.instructions, criteria: question.levels };
+        case 'noul':
+            return {
+                type: 'noul',
+                instructions: question.instructions,
+                ...(question.criteria && { criteria: question.criteria })
+            };
+        default:
+            throw new EngineError(`Unsupported question type "${question.type}".`);
+    }
+}
+
+/**
+ * Map one SDK answer to the UAG's answer shape, for the question asked: a
+ * choice that is not one of its options is dropped, and a score is kept within
+ * its levels.
+ */
+function fromSdkAnswer(answer, question) {
+    if (!answer || answer.type !== question.type) return undefined;
+    switch (answer.type) {
+        case 'choice':
+            if (typeof answer.choice !== 'string' || !Object.prototype.hasOwnProperty.call(question.options, answer.choice)) return undefined;
+            return { type: 'choice', choice: answer.choice, probabilities: { ...answer.probabilities }, confidence: answer.confidence };
+        case 'score':
+            if (!Number.isFinite(answer.score)) return undefined;
+            return {
+                type: 'score',
+                score: Math.min(Math.max(answer.score, 0), question.levels.length - 1),
+                probabilities: { ...answer.probabilities },
+                confidence: answer.confidence
+            };
+        case 'noul':
+            return { type: 'noul', probability: answer.noul };
+        default:
+            return undefined;
+    }
+}
+
+/**
+ * Provider failures an API caller can act on, as an `EngineError` with a fixed
+ * message: never the response body, which may echo the request.
+ */
+function providerError(err) {
+    const status = err && typeof err.status === 'number' ? err.status : undefined;
+    if (status === 401 || status === 403) return new EngineError(`TypeSafe refused the decision engine's API key (HTTP ${status}).`);
+    if (status === 429) return new EngineError('TypeSafe is rate-limiting the decision engine (HTTP 429). Try again later.');
+    if (status >= 500 && status <= 599) return new EngineError(`TypeSafe failed to answer (HTTP ${status}).`);
+    return err;
+}
+
+module.exports = defineEngine({
+    type: 'engine',
+    name: 'jev',
+    title: 'JEV',
+    kinds: ['decision'],
+    apiVersion: ENGINE_API_VERSION,
+    description: 'TypeSafe Jev: confidence-scored Choice, Score and yes/no decisions.',
+    settings: {
+        apiKey: { env: 'TYPESAFE_API_KEY', required: true, secret: true },
+        model: { env: 'TYPESAFE_MODEL', default: DEFAULT_MODEL, description: 'A dated model version.' },
+        baseURL: { env: 'TYPESAFE_BASE_URL', description: 'The API base URL, when not the SDK\'s default.' },
+    },
+    create({ name, settings, options, config }) {
+        const { model } = settings;
+        // Keep the SDK's own per-request timeout inside this instance's routing timeout.
+        const timeout = (config.routing && config.routing.timeouts && config.routing.timeouts[name])
+            || (config.agentApi && config.agentApi.timeout)
+            || DEFAULT_TIMEOUT;
+
+        let client = options.client;
+        if (!client) {
+            const { TypeSafeClient } = require('@typesafe-ai/sdk');
+            client = new TypeSafeClient({
+                apiKey: settings.apiKey,
+                // The SDK refuses to start when it sees `window.document` and
+                // `navigator`. Inside the UAG both exist: Node 21+ defines
+                // `navigator`, and Form.io's libraries install `window`/`document`
+                // shims. Allow it only when actually running on Node, so a real
+                // browser is still refused.
+                dangerouslyAllowBrowser: typeof process !== 'undefined' && !!(process.versions && process.versions.node),
+                defaultModel: model,
+                ...(settings.baseURL && { baseURL: settings.baseURL }),
+                timeout,
+                // Never wait longer than the timeout for a Retry-After.
+                retry: { maxRetries: 2, backoffMaxMs: Math.min(2000, Math.floor(timeout / 4)), maxRetryAfterMs: Math.min(timeout, 60000) }
+            });
+        }
+
+        return {
+            name,
+            kind: 'decision',
+            apiVersion: ENGINE_API_VERSION,
+            model,
+            maxOptions: MAX_OPTIONS,
+            async decide(request) {
+                if (request.signal) request.signal.throwIfAborted();
+                const questions = {};
+                for (const [id, question] of Object.entries(request.questions)) {
+                    questions[id] = toSdkQuestion(question);
+                }
+                let result;
+                try {
+                    result = await client.systemOne(
+                        { state: request.state, questions, model },
+                        { signal: request.signal, timeout }
+                    );
+                }
+                catch (err) {
+                    throw providerError(err);
+                }
+                const answers = {};
+                for (const [id, answer] of Object.entries(result.answers || {})) {
+                    // Only the questions asked: anything else is dropped here, not passed on.
+                    const mapped = Object.prototype.hasOwnProperty.call(request.questions, id) && fromSdkAnswer(answer, request.questions[id]);
+                    if (mapped) answers[id] = mapped;
+                }
+                return {
+                    model: result.model || model,
+                    answers,
+                    ...(result.usage && { usage: { inputTokens: result.usage.input_tokens ?? null, outputTokens: result.usage.output_tokens ?? null } })
+                };
+            }
+        };
+    },
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@formio/uag-jev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.10",
+  "description": "TypeSafe Jev decision engine for the Form.io Universal Agent Gateway (UAG): fast, confidence-scored Choice, Score and yes/no decisions for the Agent API.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "typesafe",
+    "jev",
+    "decisions"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/uag.git",
+    "directory": "engines/jev"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@formio/uag-sdk": "^2.0.0-rc.10",
+    "@typesafe-ai/sdk": "0.7.0"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}