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

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,61 @@
-# Temporary Holding Version
+# @formio/uag-grok
 
-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 **Grok** agent engine for the [UAG Agent API](https://github.com/formio/uag/blob/main/README.md#agent-api): xAI's models, through xAI's OpenAI-compatible API. It extracts and generates open values (dates, amounts, names, free text) with structured outputs. When a task lists read-only tools in `uagTools`, it researches with them first.
+
+It is included in the `formio/uag` Docker image. Enable it by naming it, and set its key and model:
+
+```
+UAG_ENGINES=grok
+XAI_API_KEY=...
+XAI_MODEL=<a Grok 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 |
+|---|---|---|
+| `apiKey` | `UAG_ENGINE_<NAME>_API_KEY`, `XAI_API_KEY` | required (secret) |
+| `model` | `UAG_ENGINE_<NAME>_MODEL`, `XAI_MODEL` | required; there is no default |
+| `baseURL` | `UAG_ENGINE_<NAME>_BASE_URL` | `https://api.x.ai/v1` |
+| `structuredOutput` | `UAG_ENGINE_<NAME>_STRUCTURED_OUTPUT` | `json_schema`; `json_object` or `prompt` if a model refuses strict schemas |
+
+`<NAME>` is the instance name, upper-cased with `-` as `_`. An instance's own variable wins over the shared one.
+
+## Instances
+
+A fast Grok model for routine values next to Claude for the rest:
+
+```
+UAG_ENGINES=jev,fast:grok,claude
+XAI_API_KEY=...
+UAG_ENGINE_FAST_MODEL=<a fast Grok model ID>
+CLAUDE_API_KEY=...
+```
+
+Routing lists, and a field's `uagEngine` property, name the instances, for example `routing.value: ["fast", "claude"]`.
+
+## Choosing a model
+
+There is no default model: set `model` to a specific model ID from xAI's documentation, 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
+
+It is the [OpenAI engine](https://github.com/formio/uag/tree/main/engines/openai)'s agent kind with xAI's endpoint and key built in: one chat completion with a strict JSON schema per extraction, and a function-calling loop over the task's read-only tools for research, ending in the same structured answer. A refusal, a truncated answer or an answer that is not JSON is an engine failure, and the UAG falls back to the next engine.
+
+Each field's format (such as `date`) and pattern are written into its description, not sent as schema constraints. Grok enforces constraints strictly, and every field is required in a strict schema, so it would otherwise invent a value that fits the pattern for a field the input does not state. The UAG validates every value either way.
+
+Grok has no decision API, and current Grok models return no token probabilities, so this is an agent engine only. Decision fields routed to it are answered as extraction and reported `calibrated: false`.
+
+**Data residency:** each request sends xAI the task's criteria, its input (or, without an input, the whole submission except the fields being answered), its `uagContext` values and today's date, and, for a task that researches, what its tools return.
+
+## Using it in your own server
+
+```js
+const server = new UAGServer({ engines: [{ name: 'grok', type: 'grok', options: { model: '<a Grok model ID>' } }] });
+```
+
+License: MIT.

package/index.js

@@ -0,0 +1,19 @@
+/**
+ * Grok engine for the UAG Agent API: xAI's models, through xAI's
+ * OpenAI-compatible API, for structured extraction with research over
+ * read-only tools.
+ *
+ *   UAG_ENGINES=grok   XAI_API_KEY=...   XAI_MODEL=<a Grok model ID>
+ *
+ * Grok has no decision API, so this is an agent engine only.
+ */
+const { openAICompatible } = require('@formio/uag-openai/compatible');
+
+module.exports = openAICompatible({
+    type: 'grok',
+    description: 'xAI\'s Grok models: structured extraction, with research over read-only tools.',
+    baseURL: 'https://api.x.ai/v1',
+    apiKey: { env: 'XAI_API_KEY' },
+    model: { env: 'XAI_MODEL' },
+    structuredOutput: 'json_schema',
+});

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@formio/uag-grok",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.2",
+  "description": "Grok engine for the Form.io Universal Agent Gateway (UAG): xAI's models, for structured extraction with research over read-only tools.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "grok",
+    "xai"
+  ],
+  "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/grok"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@formio/uag-openai": "^2.0.0-rc.2",
+    "@formio/uag-sdk": "^2.0.0-rc.2"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}