@formio/uag-openai 0.0.0-stage → 2.0.0-rc.1

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,108 @@
-# Temporary Holding Version
+# @formio/uag-openai
 
-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/main/README.md) &rsaquo; [Engines](https://github.com/formio/uag/blob/main/README.md#engines-and-routing) &rsaquo; this page</sub>
+
+The OpenAI engine for the [UAG Agent API](https://github.com/formio/uag/blob/main/README.md#agent-api). An instance is one of two kinds:
+
+- **agent** (the default): extracts and generates open values on OpenAI's Responses API, or, through Chat Completions, on any server that implements that API: local models (Ollama, vLLM, LM Studio) and routers (OpenRouter). When a task lists read-only tools in `uagTools`, it researches with them first. Grok and Gemini have their own packages built on it: [`grok`](https://github.com/formio/uag/tree/main/engines/grok) and [`gemini`](https://github.com/formio/uag/tree/main/engines/gemini).
+- **decision**: decides closed-set fields with a probability for each answer, on OpenAI's Decisions API, like the [`jev`](https://github.com/formio/uag/tree/main/engines/jev) engine. See [Decisions](#decisions).
+
+It is included in the `formio/uag` Docker image. Enable it by naming it, and set its model and key:
+
+```
+UAG_ENGINES=openai
+OPENAI_API_KEY=...
+OPENAI_MODEL=<a dated model ID>
+```
+
+Its tasks are Agentic Formflow, so the UAG also needs a `LICENSE_KEY` that includes the UAG (see [License](https://github.com/formio/uag/blob/main/README.md#license)).
+
+## Settings
+
+| Setting | Variables | Default |
+|---|---|---|
+| `kind` | `UAG_ENGINE_<NAME>_KIND`, `OPENAI_KIND` | `agent`; `decision` for the Decisions API |
+| `model` | `UAG_ENGINE_<NAME>_MODEL`, `OPENAI_MODEL` | required; there is no default |
+| `apiKey` | `UAG_ENGINE_<NAME>_API_KEY`; `OPENAI_API_KEY` for OpenAI itself only | required for OpenAI itself (secret) |
+| `baseURL` | `UAG_ENGINE_<NAME>_BASE_URL`, `OPENAI_BASE_URL` | `https://api.openai.com/v1` |
+| `structuredOutput` | `UAG_ENGINE_<NAME>_STRUCTURED_OUTPUT`, `OPENAI_STRUCTURED_OUTPUT` | `json_schema` |
+| `reasoningEffort` | `UAG_ENGINE_<NAME>_REASONING_EFFORT`, `OPENAI_REASONING_EFFORT` | not sent |
+| `api` | `UAG_ENGINE_<NAME>_API`, `OPENAI_API` | `responses` for OpenAI itself; `chat` for any other server |
+| `maxOptions` | `UAG_ENGINE_<NAME>_MAX_OPTIONS` | `255`, the Decisions API's limit and the most it takes; decision kind only |
+
+`<NAME>` is the instance name, upper-cased with `-` as `_`. An instance's own variable wins over the shared one.
+
+OpenAI's own variables, `OPENAI_API_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID` and `OPENAI_CUSTOM_HEADERS`, are sent only to OpenAI itself (`api.openai.com`). An instance whose `baseURL` is any other server, including a proxy in front of OpenAI, gets none of them: give it its own key with `UAG_ENGINE_<NAME>_API_KEY`, or none for a server that needs no key. Grok, Gemini and the other engines built on this one never get them either.
+
+`structuredOutput` says how the server is asked for the answer:
+
+| Mode | Use when |
+|---|---|
+| `json_schema` | The server supports strict JSON schema response formats: OpenAI, and recent vLLM, Ollama and OpenRouter models. |
+| `json_object` | The server supports JSON mode but not schemas. The schema goes in the prompt. |
+| `prompt` | The server supports neither. The schema goes in the prompt, and the answer is read from the text. |
+
+In every mode, an answer that is not a JSON object fails as an engine failure, and the UAG routes the fields to the next engine.
+
+## Instances
+
+A local model through Ollama, next to Claude, with no key:
+
+```
+UAG_ENGINES=jev,local:openai,claude
+UAG_ENGINE_LOCAL_BASE_URL=http://ollama:11434/v1
+UAG_ENGINE_LOCAL_MODEL=llama4:16x17b
+CLAUDE_API_KEY=...
+```
+
+For Grok and Gemini, use their own engines ([`grok`](https://github.com/formio/uag/tree/main/engines/grok), [`gemini`](https://github.com/formio/uag/tree/main/engines/gemini)), which have the right endpoints and keys built in. Any other OpenAI-compatible server works with `baseURL`; check its documentation for model IDs and for which `structuredOutput` mode it supports.
+
+## Decisions
+
+With `kind` set to `decision`, an instance is a decision engine on OpenAI's [Decisions API](https://developers.openai.com/api/docs/guides/decisions). It answers the same questions `jev` does, with all of a task's decision fields in one request:
+
+| UAG question | Decisions API question | Answer |
+|---|---|---|
+| yes/no (a field addressed, affirmed or denied) | `predicate` | the probability it holds |
+| choice (radio, select, checkbox) | `choice` | the option, a probability for each, and a confidence |
+| score (an ordered scale) | `score` | the position on the scale, a probability for each level, and a confidence |
+
+```
+UAG_ENGINES=decide:openai,writer:openai
+OPENAI_API_KEY=...
+UAG_ENGINE_DECIDE_KIND=decision
+UAG_ENGINE_DECIDE_MODEL=gpt-6-luna
+UAG_ENGINE_WRITER_MODEL=<a dated model ID>
+```
+
+Its answers are reported `calibrated: true`, like `jev`'s, and the same thresholds (`uagThreshold`, `uagUncertainBand`) apply. OpenAI makes no calibration guarantee for these probabilities, and neither does any provider: measure with `uag-eval --engine decide` on your own labeled examples before relying on the default thresholds, and again when you change the model.
+
+- A question the API declines is left undecided, so its field is reported `missing` or decided by the next engine in the routing list.
+- A request with more than 400 questions is split across calls.
+- `maxOptions` caps the options one choice question may have. Closed sets with more options go to an agent engine.
+- Both `jev` and an `openai` decision instance can be enabled; list both in `routing.decision` to fall back from one to the other.
+
+## Choosing a model
+
+There is no default model: set `model` to a specific, dated model ID, not an alias that moves. Answers differ between models, so compare them on your own labeled examples before switching (`uag-eval` measures decision engines only).
+
+## How it works
+
+- **Which API.** With OpenAI itself, the engine uses the Responses API, which lets current models reason while they use tools (Chat Completions refuses tools on a reasoning model). Nothing is stored at OpenAI (`store: false`): the model's reasoning carries across research turns as encrypted reasoning items, sent back with the history. With any other server (`baseURL`), it uses Chat Completions, which local servers and routers implement. Set `api` to `responses` or `chat` to choose yourself, for example for a gateway in front of OpenAI.
+- **Dates with OpenAI.** OpenAI's strict mode corrupts dates when the schema constrains them (the year comes back as 1000, 1010, 3362 …), so with OpenAI itself the engine writes each field's format (such as `date`) and pattern into its description instead. Measured October 2026; other servers keep the constraints, and the UAG validates every value either way.
+- **Extraction** makes one request, constrained as `structuredOutput` says. Values from this engine are always reported as `suggested`, and only the requested fields are returned.
+- **Research:** when a task lists read-only tools, the model may call them first through function calling, up to `agentApi.research.maxIterations` turns. Every call goes back through the UAG with the caller's identity, and tool errors are returned to the model. The model then answers with tools turned off. It never writes: the UAG validates the values and saves them itself. Tasks that research need a server that supports function calling; on one that does not, the request fails as an engine failure.
+- **Failures:** a refusal, a content filter, a truncated answer or an answer that is not JSON fails as an engine failure, and the UAG falls back to the next engine.
+- **Aborts:** the routing timeout (for research, `agentApi.research.timeout`) aborts the request, and research stops before its next call.
+
+## 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: 'local', type: 'openai', options: { baseURL: 'http://localhost:11434/v1', model: 'llama4:16x17b' } }],
+});
+```
+
+License: MIT.

package/compatible.js

@@ -0,0 +1,479 @@
+/**
+ * The OpenAI-compatible core of the UAG's agent engines: structured extraction
+ * and research over a chat completions API, shared by `@formio/uag-openai` and
+ * the provider packages built on it (Grok and Gemini; MAI, not yet released).
+ *
+ *   const { openAICompatible } = require('@formio/uag-openai/compatible');
+ *   module.exports = openAICompatible({
+ *       type: 'acme',
+ *       description: 'Acme models, through their OpenAI-compatible API.',
+ *       baseURL: 'https://api.acme.example/v1',
+ *       apiKey: { env: 'ACME_API_KEY' },
+ *       model: { env: 'ACME_MODEL' },
+ *   });
+ *
+ * How an answer is constrained depends on what the server supports
+ * (`structuredOutput`):
+ *
+ *   json_schema  a strict JSON schema response format
+ *   json_object  a JSON object response format, with the schema in the prompt
+ *   prompt       the schema in the prompt only
+ *
+ * When the UAG passes read-only tools (a task that enables research), the
+ * engine first runs a function-calling loop over them - calls go through the
+ * UAG's `callTool`, which enforces the task's tool list and the caller's
+ * permissions - and then asks for the same answer with tools turned off.
+ */
+const { defineEngine, EngineConfigError, EngineError, ENGINE_API_VERSION, parseJsonObject, requiredSchema, toolResultText } = require('@formio/uag-sdk');
+
+const MODES = ['json_schema', 'json_object', 'prompt'];
+
+function isEmpty(value) {
+    return value === '' || value === null || value === undefined || (Array.isArray(value) && !value.length);
+}
+
+/** Refuse an unknown structured-output mode at startup. */
+function checkMode(name, mode) {
+    if (!MODES.includes(mode)) {
+        throw new EngineConfigError(`The "${name}" engine's structuredOutput setting must be one of ${MODES.join(', ')}, not ${JSON.stringify(mode)}.`);
+    }
+    return mode;
+}
+
+/** OpenAI's own API, the only server that gets OpenAI's own settings from the environment. */
+function isOpenAI(baseURL) {
+    try {
+        return new URL(baseURL).hostname === 'api.openai.com';
+    }
+    catch {
+        return false;
+    }
+}
+
+/** The header names in OPENAI_CUSTOM_HEADERS (`Name: value` lines), as the SDK reads them. */
+function customHeaderNames(value) {
+    return String(value || '').split('\n').filter((line) => line.includes(':')).map((line) => line.slice(0, line.indexOf(':')).trim()).filter(Boolean);
+}
+
+/**
+ * An OpenAI SDK client. Retries stay small: the UAG's routing timeout aborts the
+ * request (through the signal) and falls back to the next engine before retries
+ * pile up.
+ *
+ * The SDK reads OpenAI's own settings from the environment (OPENAI_ORG_ID,
+ * OPENAI_PROJECT_ID, OPENAI_CUSTOM_HEADERS) and sends them with every request.
+ * They are OpenAI's, so any other server (Grok, Gemini, a local model) gets
+ * none of them. `apiKey: null` sends no Authorization header, for a server
+ * that needs no key or takes it in another header.
+ */
+function openAIClient({ apiKey, baseURL, defaultHeaders, fetch }) {
+    const { OpenAI } = require('openai');
+    const headers = { ...(defaultHeaders || {}) };
+    const openAI = isOpenAI(baseURL);
+    if (!openAI) {
+        const own = new Set(Object.keys(headers).map((header) => header.toLowerCase()));
+        for (const header of customHeaderNames(process.env.OPENAI_CUSTOM_HEADERS)) {
+            if (!own.has(header.toLowerCase())) headers[header] = null;
+        }
+    }
+    if (!apiKey) headers.Authorization = null;
+    return new OpenAI({
+        // The SDK will not start without a key, even when none is sent.
+        apiKey: apiKey || 'unused',
+        // Always explicit, so the SDK never falls back to OPENAI_BASE_URL for an
+        // instance that was configured without it.
+        baseURL,
+        ...(!openAI && { organization: null, project: null }),
+        // Never read from the environment: these engines only use `apiKey`.
+        adminAPIKey: null,
+        webhookSecret: null,
+        ...(Object.keys(headers).length && { defaultHeaders: headers }),
+        // Tests pass a fetch to see exactly what is sent, without the network.
+        ...(fetch && { fetch }),
+        maxRetries: 2,
+        // The SDK refuses to start in a "browser-like environment". Inside the
+        // UAG, Form.io's libraries install `window`/`document` shims, so allow it
+        // only when actually running on Node; a real browser is still refused.
+        dangerouslyAllowBrowser: typeof process !== 'undefined' && !!(process.versions && process.versions.node)
+    });
+}
+
+/** End the attempt as an engine failure when the answer is unusable, so routing can fall back. */
+function checkChoice(choice) {
+    if (!choice || !choice.message) {
+        throw new EngineError('The model returned no answer.');
+    }
+    if (choice.message.refusal) {
+        throw new EngineError('The model declined the request.');
+    }
+    if (choice.finish_reason === 'length') {
+        throw new EngineError('The model stopped at the token limit before finishing the answer.');
+    }
+    if (choice.finish_reason === 'content_filter') {
+        throw new EngineError('The model\'s content filter stopped the answer.');
+    }
+    return choice.message;
+}
+
+/** How a string format reads in a field's description, instead of as a schema constraint. */
+const FORMAT_WORDING = {
+    date: 'Write it as a date, YYYY-MM-DD.',
+    'date-time': 'Write it as an ISO 8601 date and time, such as 2026-10-22T14:30:00Z.',
+    time: 'Write it as a time, HH:MM:SS.',
+    email: 'Write it as an email address.',
+    uri: 'Write it as a URL.',
+};
+
+/**
+ * The schema with every string `format` and `pattern` moved into the property's
+ * description. OpenAI's strict mode enforces those constraints in a way that
+ * corrupts dates (the year comes out as 1000, 1010, 3362 ...). A server that
+ * enforces them also rules out the empty "not stated" answer every field is
+ * allowed, so the model must invent a value (Grok answers a policy number
+ * pattern with POL-000000). The same requirement in words is followed, and the
+ * UAG validates every value afterwards.
+ */
+function describeFormats(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema;
+    const out = { ...schema };
+    const notes = [];
+    if (typeof out.format === 'string') {
+        notes.push(FORMAT_WORDING[out.format] || `Write it in the "${out.format}" format.`);
+        delete out.format;
+    }
+    if (typeof out.pattern === 'string') {
+        notes.push(`It must match the regular expression ${out.pattern}.`);
+        delete out.pattern;
+    }
+    if (notes.length) {
+        out.description = [out.description, ...notes].filter(Boolean).join(' ');
+    }
+    if (out.properties) {
+        out.properties = Object.fromEntries(Object.entries(out.properties).map(([key, value]) => [key, describeFormats(value)]));
+    }
+    if (out.items) {
+        out.items = describeFormats(out.items);
+    }
+    return out;
+}
+
+/** The prompt describing the information and the fields, and how to answer in each mode. */
+function prompt(request, mode) {
+    const lines = [
+        'Information:',
+        JSON.stringify(request.state, null, 2),
+        '',
+        'Fields to fill in (path, label, rule, format and allowed options):',
+        JSON.stringify(request.fields, null, 2),
+        '',
+    ];
+    if (mode === 'json_schema') {
+        lines.push('Return one JSON object keyed by field path. For a field the information does not support, give an empty string, or an empty list for a list.');
+    }
+    else {
+        lines.push(
+            'Respond with only one JSON object keyed by field path, matching this JSON schema, and nothing else. Leave out any field the information does not support.',
+            JSON.stringify(request.schema)
+        );
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Run one tool call through the UAG's `callTool`. A call that throws, other
+ * than because the request was aborted, goes back to the model as a tool error
+ * instead of failing the extraction.
+ */
+async function runTool(request, name, args) {
+    try {
+        return await request.callTool(name, args);
+    }
+    catch (err) {
+        if (request.signal && request.signal.aborted) throw err;
+        return { content: [{ type: 'text', text: 'The tool call failed.' }], isError: true };
+    }
+}
+
+/**
+ * An agent engine over a chat completions client. It never sends `max_tokens`,
+ * which reasoning models and some providers refuse; the server's own limit
+ * applies.
+ */
+function agentEngine({ name, model, client, mode, reasoningEffort, formatsInWords = false }) {
+    /** One chat completion, counted into `usage`. */
+    async function complete(params, signal, usage) {
+        if (signal) signal.throwIfAborted();
+        const completion = await client.chat.completions.create({
+            model,
+            ...(reasoningEffort && { reasoning_effort: reasoningEffort }),
+            ...params
+        }, { signal });
+        if (completion && completion.usage) {
+            usage.counted = true;
+            usage.inputTokens += completion.usage.prompt_tokens || 0;
+            usage.outputTokens += completion.usage.completion_tokens || 0;
+        }
+        return completion;
+    }
+
+    /**
+     * Look up what the fields need with the read-only tools, appending every
+     * turn to `messages`. Stops when the model stops calling tools, or at the
+     * iteration limit.
+     */
+    async function research(request, tools, messages, usage) {
+        const toolCalls = [];
+        messages[1].content += '\n\nYou may first call the listed tools to look up information the fields need. The tools only read; nothing you do is saved.';
+        for (let iteration = 0; iteration < (request.maxIterations || 10); iteration++) {
+            const completion = await complete({ messages, tools }, request.signal, usage);
+            const message = checkChoice(completion.choices && completion.choices[0]);
+            const calls = (message.tool_calls || []).filter((call) => call.function);
+            messages.push({ role: 'assistant', content: message.content ?? null, ...(calls.length && { tool_calls: calls }) });
+            if (!calls.length) {
+                break;
+            }
+            // Run the calls of one turn concurrently, and return every result,
+            // recording the calls in the order the model made them.
+            const results = await Promise.all(calls.map(async (call) => {
+                let args;
+                try {
+                    args = JSON.parse(call.function.arguments || '{}');
+                }
+                catch {
+                    args = undefined;
+                }
+                if (!args || typeof args !== 'object' || Array.isArray(args)) {
+                    return { message: { role: 'tool', tool_call_id: call.id, content: 'Error: the arguments were not a JSON object. Call the tool again with a JSON object.' } };
+                }
+                const result = await runTool(request, call.function.name, args);
+                const text = toolResultText(result);
+                return {
+                    call: { name: call.function.name, isError: !!result.isError },
+                    message: { role: 'tool', tool_call_id: call.id, content: result.isError ? `Error: ${text}` : text }
+                };
+            }));
+            for (const { call, message: result } of results) {
+                if (call) toolCalls.push(call);
+                messages.push(result);
+            }
+        }
+        messages.push({ role: 'user', content: 'Now give the answer: one JSON object keyed by field path.' });
+        return toolCalls;
+    }
+
+    return {
+        name,
+        kind: 'agent',
+        apiVersion: ENGINE_API_VERSION,
+        model,
+        toolUse: true,
+
+        async extract(request) {
+            const strict = requiredSchema(request.schema);
+            const messages = [
+                { role: 'system', content: request.instructions },
+                { role: 'user', content: prompt(request, mode) },
+            ];
+            const usage = { inputTokens: 0, outputTokens: 0, counted: false };
+            const tools = (request.tools || []).map((tool) => ({
+                type: 'function',
+                function: { name: tool.name, description: tool.description, parameters: tool.inputSchema }
+            }));
+            const toolCalls = tools.length ? await research(request, tools, messages, usage) : undefined;
+            const completion = await complete({
+                messages,
+                // The tools stay declared because the history may hold tool calls.
+                ...(tools.length && { tools, tool_choice: 'none' }),
+                ...(mode === 'json_schema' && { response_format: { type: 'json_schema', json_schema: { name: 'fields', strict: true, schema: formatsInWords ? describeFormats(strict.schema) : strict.schema } } }),
+                ...(mode === 'json_object' && { response_format: { type: 'json_object' } })
+            }, request.signal, usage);
+            const message = checkChoice(completion.choices && completion.choices[0]);
+            const answer = parseJsonObject(message.content || '');
+            // A strict answer is in the encoded schema; a prompted one in the UAG's own types.
+            const decoded = mode === 'json_schema' ? strict.decode(answer) : answer;
+            // Only the fields asked, whatever the model answered.
+            const asked = new Set(Object.keys((request.schema && request.schema.properties) || {}));
+            const values = Object.fromEntries(Object.entries(decoded).filter(([path, value]) => asked.has(path) && !isEmpty(value)));
+            return {
+                model: completion.model || model,
+                values,
+                ...(usage.counted && { usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens } }),
+                ...(toolCalls && { toolCalls })
+            };
+        }
+    };
+}
+
+/** The text of a Responses API answer, or an engine failure when there is none. */
+function responseText(response) {
+    if (response.status === 'incomplete') {
+        const reason = response.incomplete_details && response.incomplete_details.reason;
+        throw new EngineError(reason === 'max_output_tokens'
+            ? 'The model stopped at the token limit before finishing the answer.'
+            : reason === 'content_filter'
+                ? 'The model\'s content filter stopped the answer.'
+                : 'The model did not finish the answer.');
+    }
+    const parts = (response.output || []).filter((item) => item.type === 'message').flatMap((item) => item.content || []);
+    if (parts.some((part) => part.type === 'refusal')) {
+        throw new EngineError('The model declined the request.');
+    }
+    return parts.filter((part) => part.type === 'output_text').map((part) => part.text).join('');
+}
+
+/**
+ * An agent engine on OpenAI's Responses API, which allows function tools while
+ * a model reasons (Chat Completions does not). Nothing is stored at OpenAI
+ * (`store: false`); the model's reasoning carries across research turns as
+ * encrypted reasoning items in the history.
+ */
+function responsesAgentEngine({ name, model, client, mode, reasoningEffort, formatsInWords = false }) {
+    /** One response, counted into `usage`. */
+    async function respond(params, signal, usage) {
+        if (signal) signal.throwIfAborted();
+        const response = await client.responses.create({
+            model,
+            store: false,
+            include: ['reasoning.encrypted_content'],
+            ...(reasoningEffort && { reasoning: { effort: reasoningEffort } }),
+            ...params
+        }, { signal });
+        if (response && response.usage) {
+            usage.counted = true;
+            usage.inputTokens += response.usage.input_tokens || 0;
+            usage.outputTokens += response.usage.output_tokens || 0;
+        }
+        return response;
+    }
+
+    return {
+        name,
+        kind: 'agent',
+        apiVersion: ENGINE_API_VERSION,
+        model,
+        toolUse: true,
+
+        async extract(request) {
+            const strict = requiredSchema(request.schema);
+            const tools = (request.tools || []).map((tool) => ({
+                type: 'function',
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema,
+                // The UAG's tool schemas are not written for strict mode.
+                strict: false,
+            }));
+            const input = [{ role: 'user', content: prompt(request, mode) }];
+            const usage = { inputTokens: 0, outputTokens: 0, counted: false };
+            const toolCalls = [];
+            if (tools.length) {
+                input[0].content += '\n\nYou may first call the listed tools to look up information the fields need. The tools only read; nothing you do is saved.';
+                for (let iteration = 0; iteration < (request.maxIterations || 10); iteration++) {
+                    const response = await respond({ instructions: request.instructions, input, tools }, request.signal, usage);
+                    responseText(response);
+                    // The whole output goes back: reasoning items, messages and calls.
+                    input.push(...(response.output || []));
+                    const calls = (response.output || []).filter((item) => item.type === 'function_call');
+                    if (!calls.length) {
+                        break;
+                    }
+                    // Run the calls of one turn concurrently, and return every result,
+                    // recording the calls in the order the model made them.
+                    const results = await Promise.all(calls.map(async (call) => {
+                        let args;
+                        try {
+                            args = JSON.parse(call.arguments || '{}');
+                        }
+                        catch {
+                            args = undefined;
+                        }
+                        if (!args || typeof args !== 'object' || Array.isArray(args)) {
+                            return { output: { type: 'function_call_output', call_id: call.call_id, output: 'Error: the arguments were not a JSON object. Call the tool again with a JSON object.' } };
+                        }
+                        const result = await runTool(request, call.name, args);
+                        const text = toolResultText(result);
+                        return {
+                            call: { name: call.name, isError: !!result.isError },
+                            output: { type: 'function_call_output', call_id: call.call_id, output: result.isError ? `Error: ${text}` : text }
+                        };
+                    }));
+                    for (const { call, output } of results) {
+                        if (call) toolCalls.push(call);
+                        input.push(output);
+                    }
+                }
+                input.push({ role: 'user', content: 'Now give the answer: one JSON object keyed by field path.' });
+            }
+            const response = await respond({
+                instructions: request.instructions,
+                input,
+                // The tools stay declared because the history may hold tool calls.
+                ...(tools.length && { tools, tool_choice: 'none' }),
+                ...(mode === 'json_schema' && { text: { format: { type: 'json_schema', name: 'fields', strict: true, schema: formatsInWords ? describeFormats(strict.schema) : strict.schema } } }),
+                ...(mode === 'json_object' && { text: { format: { type: 'json_object' } } })
+            }, request.signal, usage);
+            const answer = parseJsonObject(responseText(response));
+            // A strict answer is in the encoded schema; a prompted one in the UAG's own types.
+            const decoded = mode === 'json_schema' ? strict.decode(answer) : answer;
+            // Only the fields asked, whatever the model answered.
+            const asked = new Set(Object.keys((request.schema && request.schema.properties) || {}));
+            const values = Object.fromEntries(Object.entries(decoded).filter(([path, value]) => asked.has(path) && !isEmpty(value)));
+            return {
+                model: response.model || model,
+                values,
+                ...(usage.counted && { usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens } }),
+                ...(tools.length && { toolCalls })
+            };
+        }
+    };
+}
+
+/**
+ * An agent engine type for a provider with an OpenAI-compatible API.
+ *
+ * - `type`, `description`: the type's name and what it is.
+ * - `baseURL`: the provider's API, or a function `(settings, requireSetting)`
+ *   that returns it. Every instance can override it with its `baseURL` setting.
+ * - `apiKey`, `model`: the variables (`env`) for the key and the model, which
+ *   are both required and have no default.
+ * - `apiKeyHeader`: send the key in this header instead of as a bearer token.
+ * - `settings`: more settings the type needs, such as an endpoint.
+ * - `structuredOutput`: the default structured-output mode.
+ * - `reasoningEffort`: the variable for `reasoning_effort`, for providers that take it.
+ * - `formatsInWords`: false to send string formats and patterns as schema
+ *   constraints rather than in words (see `describeFormats`). Default true.
+ */
+function openAICompatible(provider) {
+    const settings = {
+        ...(provider.settings || {}),
+        apiKey: { env: provider.apiKey.env, required: true, secret: true },
+        model: { env: provider.model.env, required: true, description: provider.model.description || 'A dated model version. There is no default.' },
+        baseURL: { env: provider.baseURLEnv, description: 'Override the provider\'s API URL, for a proxy or a regional endpoint.' },
+        structuredOutput: { env: provider.structuredOutputEnv, default: provider.structuredOutput || 'json_schema', description: 'json_schema, json_object or prompt.' },
+        ...(provider.reasoningEffort && { reasoningEffort: { env: provider.reasoningEffort.env, description: 'Sent as reasoning_effort, for models that take it.' } }),
+    };
+    for (const spec of Object.values(settings)) {
+        if (spec.env === undefined) delete spec.env;
+    }
+    return defineEngine({
+        type: provider.type,
+        kinds: ['agent'],
+        apiVersion: ENGINE_API_VERSION,
+        description: provider.description,
+        settings,
+        create({ name, settings: resolved, options, requireSetting }) {
+            const mode = checkMode(name, resolved.structuredOutput);
+            const baseURL = resolved.baseURL || (typeof provider.baseURL === 'function' ? provider.baseURL(resolved, requireSetting) : provider.baseURL);
+            const client = options.client || openAIClient({
+                // With a custom header, no bearer token is sent.
+                apiKey: provider.apiKeyHeader ? null : resolved.apiKey,
+                baseURL,
+                ...(provider.apiKeyHeader && { defaultHeaders: { [provider.apiKeyHeader]: resolved.apiKey } }),
+                fetch: options.fetch,
+            });
+            return agentEngine({ name, model: resolved.model, client, mode, reasoningEffort: resolved.reasoningEffort, formatsInWords: provider.formatsInWords !== false });
+        },
+    });
+}
+
+module.exports = { MODES, checkMode, isOpenAI, openAIClient, agentEngine, responsesAgentEngine, describeFormats, openAICompatible };

package/decisions.js

@@ -0,0 +1,149 @@
+/**
+ * The decision kind of the `openai` engine type: the UAG's decision questions,
+ * answered by OpenAI's Decisions API (`POST /v1/decisions`).
+ *
+ *   UAG UAG question   Decisions API question     answer
+ *   noul (yes/no)      predicate                  probability
+ *   choice             choice                     choice, probabilities, confidence
+ *   score              score (levels, lowest first) score, probabilities, confidence
+ *
+ * Question ids are mapped to generated names and back, so the API's naming
+ * rules never matter. A question the API declines is left unanswered, which
+ * the UAG treats as an undecided field.
+ */
+const { EngineError, ENGINE_API_VERSION } = require('@formio/uag-sdk');
+
+/** The most questions the Decisions API accepts in one request. */
+const MAX_QUESTIONS = 400;
+
+/** A yes/no question as a predicate, with its true and false criteria in the instructions. */
+function predicate(question) {
+    const criteria = question.criteria || {};
+    const notes = [
+        criteria.true && `It holds when: ${criteria.true}`,
+        criteria.false && `It does not hold when: ${criteria.false}`,
+    ].filter(Boolean);
+    return { type: 'predicate', instructions: [question.instructions, ...notes].join('\n') };
+}
+
+function toApiQuestion(question, name) {
+    switch (question.type) {
+        case 'noul':
+            return { ...predicate(question), name };
+        case 'choice':
+            return {
+                type: 'choice',
+                name,
+                instructions: question.instructions,
+                choices: Object.entries(question.options).map(([label, description]) => ({ value: label, ...(description && { description }) })),
+            };
+        case 'score':
+            return { type: 'score', name, instructions: question.instructions, levels: question.levels.map((level) => ({ label: level })) };
+        default:
+            throw new EngineError(`Unsupported question type "${question.type}".`);
+    }
+}
+
+/** A probability or confidence: a number from 0 to 1. */
+function isUnit(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+/** One API answer in the UAG's shape, or undefined when it does not fit the question asked. */
+function fromApiAnswer(answer, question) {
+    if (!answer || answer.type === 'refusal') return undefined;
+    if (question.type === 'noul' && answer.type === 'predicate') {
+        return isUnit(answer.probability) ? { type: 'noul', probability: answer.probability } : undefined;
+    }
+    if (question.type === 'choice' && answer.type === 'choice') {
+        const labels = Object.keys(question.options);
+        const choice = String(answer.choice);
+        if (!labels.includes(choice) || !isUnit(answer.confidence)) return undefined;
+        const probabilities = {};
+        for (const entry of answer.probabilities || []) {
+            if (entry && labels.includes(String(entry.value)) && isUnit(entry.probability)) probabilities[String(entry.value)] = entry.probability;
+        }
+        return { type: 'choice', choice, probabilities, confidence: answer.confidence };
+    }
+    if (question.type === 'score' && answer.type === 'score') {
+        const top = question.levels.length - 1;
+        if (typeof answer.score !== 'number' || !Number.isFinite(answer.score) || answer.score < 0 || answer.score > top || !isUnit(answer.confidence)) {
+            return undefined;
+        }
+        const probabilities = {};
+        for (const entry of answer.probabilities || []) {
+            if (entry && Number.isInteger(entry.value) && entry.value >= 0 && entry.value <= top && isUnit(entry.probability)) {
+                probabilities[String(entry.value)] = entry.probability;
+            }
+        }
+        return { type: 'score', score: answer.score, probabilities, confidence: answer.confidence };
+    }
+    return undefined;
+}
+
+/**
+ * A decision engine over the Decisions API. `maxOptions` bounds the options
+ * the planner sends one choice question; larger closed sets go to an agent.
+ */
+function decisionEngine({ name, model, client, maxOptions }) {
+    async function decideBatch(input, batch, signal) {
+        signal?.throwIfAborted();
+        const response = await client.decisions.create({
+            model,
+            input,
+            questions: batch.map(({ question, name: apiName }) => toApiQuestion(question, apiName)),
+        }, { signal });
+        if (!response || !Array.isArray(response.answers)) {
+            throw new EngineError('The Decisions API returned no answers.');
+        }
+        return response;
+    }
+
+    return {
+        name,
+        kind: 'decision',
+        apiVersion: ENGINE_API_VERSION,
+        model,
+        maxOptions,
+
+        async decide({ state, questions, signal }) {
+            signal?.throwIfAborted();
+            // A choice the API cannot take (fewer than 2 options, or more than
+            // maxOptions) is not sent, and is left undecided, so it fails alone
+            // instead of failing the whole request.
+            const entries = Object.entries(questions)
+                .filter(([, question]) => question.type !== 'choice' || (Object.keys(question.options || {}).length >= 2 && Object.keys(question.options).length <= maxOptions))
+                .map(([id, question], index) => ({ id, question, name: `q${index}` }));
+            const byName = new Map(entries.map((entry) => [entry.name, entry]));
+            const input = JSON.stringify(state);
+            const batches = [];
+            for (let start = 0; start < entries.length; start += MAX_QUESTIONS) {
+                batches.push(entries.slice(start, start + MAX_QUESTIONS));
+            }
+            const responses = await Promise.all(batches.map((batch) => decideBatch(input, batch, signal)));
+            const answers = {};
+            const usage = { inputTokens: 0, outputTokens: 0 };
+            let reported = false;
+            for (const response of responses) {
+                for (const answer of response.answers) {
+                    const entry = byName.get(answer && answer.name);
+                    // Only the questions asked: anything else is dropped here.
+                    const mapped = entry && fromApiAnswer(answer, entry.question);
+                    if (mapped) answers[entry.id] = mapped;
+                }
+                if (response.usage) {
+                    reported = true;
+                    usage.inputTokens += response.usage.input_tokens || 0;
+                    usage.outputTokens += response.usage.output_tokens || 0;
+                }
+            }
+            return {
+                model: (responses[0] && responses[0].model) || model,
+                answers,
+                ...(reported && { usage }),
+            };
+        },
+    };
+}
+
+module.exports = { MAX_QUESTIONS, decisionEngine, toApiQuestion, fromApiAnswer };

package/index.js

@@ -0,0 +1,74 @@
+/**
+ * OpenAI engine for the UAG Agent API: OpenAI itself, or any server that
+ * implements its chat completions API (Ollama, vLLM, LM Studio, OpenRouter).
+ *
+ *   UAG_ENGINES=openai         OPENAI_API_KEY=...  OPENAI_MODEL=<a dated model version>
+ *   UAG_ENGINES=local:openai   UAG_ENGINE_LOCAL_BASE_URL=http://ollama:11434/v1
+ *                              UAG_ENGINE_LOCAL_MODEL=llama4:16x17b
+ *   UAG_ENGINES=decide:openai  UAG_ENGINE_DECIDE_KIND=decision  UAG_ENGINE_DECIDE_MODEL=gpt-6-luna
+ *
+ * An instance is an agent engine (the default: structured extraction, with
+ * research over read-only tools; see compatible.js), or, with `kind` set to
+ * `decision`, a decision engine on OpenAI's Decisions API (see decisions.js).
+ *
+ * An agent instance talks to OpenAI through the Responses API, which allows
+ * tools while a model reasons, and to any other server (`baseURL`) through
+ * Chat Completions. The `api` setting overrides the choice.
+ */
+const { defineEngine, EngineConfigError, ENGINE_API_VERSION, settingVariable } = require('@formio/uag-sdk');
+const { checkMode, isOpenAI, openAIClient, agentEngine, responsesAgentEngine } = require('./compatible');
+const { decisionEngine } = require('./decisions');
+
+const KINDS = ['agent', 'decision'];
+const APIS = ['responses', 'chat'];
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+/** The Decisions API accepts at most 255 choices per question (measured October 2026), as Jev does. */
+const MAX_OPTIONS = 255;
+
+module.exports = defineEngine({
+    type: 'openai',
+    kinds: ['agent', 'decision'],
+    apiVersion: ENGINE_API_VERSION,
+    description: 'OpenAI: structured extraction with research over read-only tools, on OpenAI or any server with its chat completions API; or decisions with probabilities, on OpenAI\'s Decisions API.',
+    settings: {
+        kind: { env: 'OPENAI_KIND', default: 'agent', description: 'agent, or decision for the Decisions API.' },
+        // The instance's own key, for any server. OpenAI's (OPENAI_API_KEY) is a
+        // setting of its own, so it is only ever sent to OpenAI itself.
+        apiKey: { secret: true, description: 'This instance\'s key, sent to its server. Required for OpenAI itself unless OPENAI_API_KEY is set.' },
+        openaiApiKey: { env: 'OPENAI_API_KEY', secret: true, description: 'OpenAI\'s key, sent only to OpenAI itself, never to a baseURL server.' },
+        baseURL: { env: 'OPENAI_BASE_URL', description: 'An OpenAI-compatible server, such as http://ollama:11434/v1.' },
+        model: { env: 'OPENAI_MODEL', required: true, description: 'A dated model version. There is no default.' },
+        structuredOutput: { env: 'OPENAI_STRUCTURED_OUTPUT', default: 'json_schema', description: 'json_schema, json_object or prompt.' },
+        api: { env: 'OPENAI_API', description: 'responses or chat. Default: responses for OpenAI itself, chat for any other server.' },
+        reasoningEffort: { env: 'OPENAI_REASONING_EFFORT', description: 'Sent as reasoning_effort, for models that take it.' },
+        maxOptions: { type: 'number', default: MAX_OPTIONS, description: 'Decision kind: the most options one choice question may carry, up to 255.' },
+    },
+    create({ name, settings, options }) {
+        const { kind, model } = settings;
+        if (!KINDS.includes(kind)) {
+            throw new EngineConfigError(`The "${name}" engine's kind setting must be one of ${KINDS.join(', ')}, not ${JSON.stringify(kind)}.`);
+        }
+        const baseURL = settings.baseURL || DEFAULT_BASE_URL;
+        // A server other than OpenAI gets only the instance's own key, or none.
+        const apiKey = isOpenAI(baseURL) ? settings.apiKey || settings.openaiApiKey : settings.apiKey;
+        if (!apiKey && isOpenAI(baseURL)) {
+            throw new EngineConfigError(`The "${name}" engine (type "openai") needs its apiKey setting: set ${settingVariable(name, 'apiKey')} or OPENAI_API_KEY.`);
+        }
+        const client = options.client || openAIClient({ apiKey, baseURL, fetch: options.fetch });
+        if (kind === 'decision') {
+            if (!Number.isInteger(settings.maxOptions) || settings.maxOptions < 2 || settings.maxOptions > MAX_OPTIONS) {
+                throw new EngineConfigError(`The "${name}" engine's maxOptions setting must be a whole number from 2 to ${MAX_OPTIONS}.`);
+            }
+            return decisionEngine({ name, model, client, maxOptions: settings.maxOptions });
+        }
+        const mode = checkMode(name, settings.structuredOutput);
+        const own = isOpenAI(baseURL);
+        const api = settings.api || (own ? 'responses' : 'chat');
+        if (!APIS.includes(api)) {
+            throw new EngineConfigError(`The "${name}" engine's api setting must be one of ${APIS.join(', ')}, not ${JSON.stringify(api)}.`);
+        }
+        const engine = api === 'responses' ? responsesAgentEngine : agentEngine;
+        // OpenAI's strict mode corrupts constrained dates, so it gets them in words.
+        return engine({ name, model, client, mode, reasoningEffort: settings.reasoningEffort, formatsInWords: own });
+    },
+});

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@formio/uag-openai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.1",
+  "description": "OpenAI engine for the Form.io Universal Agent Gateway (UAG): structured extraction, with research over read-only tools, on OpenAI or any server with its chat completions API (Ollama, vLLM, LM Studio, OpenRouter); and decisions with probabilities on OpenAI's Decisions API.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "openai",
+    "ollama",
+    "vllm",
+    "openrouter"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./compatible": "./compatible.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "compatible.js",
+    "decisions.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/uag.git",
+    "directory": "engines/openai"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@formio/uag-sdk": "^2.0.0-rc.1",
+    "openai": "7.43.0"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}