Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat(sdk): add typed client for Laya and Jev systemone

BaniNaveenbc1ef2430878
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 11818be5..e8ef1a3b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -244,6 +244,40 @@ jobs:
- name: Byte-compile every module
run: python -m compileall -q laya/ tests/
+ typescript-sdk:
+ name: TypeScript SDK (node${{ matrix.node }})
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ node: [22, 24]
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node }}
+ cache: npm
+ cache-dependency-path: sdk/typescript/package-lock.json
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.11"
+ cache: pip
+ - name: Install server and SDK
+ run: |
+ pip install torch --index-url https://download.pytorch.org/whl/cpu
+ pip install -e '.[serve]' httpx pytest
+ npm ci --prefix sdk/typescript
+ - name: Server contract and generated presets
+ run: |
+ python -m pytest tests/test_serve.py
+ python sdk/typescript/scripts/sync_presets.py --check
+ - name: SDK types, transport, packaging and live inference
+ working-directory: sdk/typescript
+ run: |
+ npm test
+ npm run test:integration
+ npm pack --dry-run
+
build:
name: package
runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index 3d264b23..f9cf84d0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,9 @@ wheels/
*.egg-info/
.installed.cfg
*.egg
+node_modules/
+*.tgz
+.pytest_cache/
.DS_Store
.env
.pypirc
diff --git a/README.md b/README.md
index 0560d3e6..31700bf8 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,30 @@ curl -s localhost:8000/predict -H 'content-type: application/json' -d '{
`--no-preload` loads checkpoints lazily instead of all three up front; `--device cuda|cpu|mps`
pins the device. See `python examples/server.py --help` for the rest.
+### JavaScript / TypeScript
+
+The [TypeScript SDK](sdk/typescript/README.md) supports JavaScript and TypeScript
+apps through the existing Jev-compatible `/v1/systemone` HTTP server. It includes inferred
+answer types, all five question presets, ESM/CommonJS exports, and cancellation.
+
+```bash
+# From this checkout, install and start the Python inference service:
+pip install -e '.[serve]'
+LAYA_HOST=127.0.0.1 LAYA_MODELS=english laya-serve
+
+# In another terminal:
+cd sdk/typescript
+npm ci
+npm run build
+node examples/triage.mjs
+```
+
+The npm package is named `@laya/typescript-sdk`.
+The prediction API also accepts Jev's response format; see the SDK's
+[Jev compatibility guide](sdk/typescript/README.md#jev-compatibility-and-model-selection).
+See [installation, examples, and publishing](sdk/typescript/README.md) and the
+[repository analysis](docs/typescript-sdk.md) for architecture and scope.
+
---
## Quickstart: Route Mode (Recommended)
diff --git a/docs/typescript-sdk.md b/docs/typescript-sdk.md
new file mode 100644
index 00000000..5f1ebecc
--- /dev/null
+++ b/docs/typescript-sdk.md
@@ -0,0 +1,72 @@
+# TypeScript HTTP SDK design
+
+`@laya/typescript-sdk` is a dependency-free HTTP client for the existing
+`laya.serve` server. It uses the Jev-compatible `POST /v1/systemone` endpoint
+introduced in #31; it adds no Python production code or server dependencies.
+The npm package starts at version `0.1.0`, independently of Python releases.
+
+## Boundaries
+
+| Component | Responsibility |
+| --- | --- |
+| `sdk/typescript` | Question/answer types, presets, validation, native fetch, errors and cancellation |
+| `laya/serve.py` | Existing HTTP endpoint, Bearer authentication, health and request limits |
+| `laya/router.py` | Checkpoint selection, loading and inference routing |
+| `laya/agent.py` | Tokenization, PyTorch inference and calibrated answer formatting |
+| `laya/presets.py` | Source for the five generated TypeScript question presets |
+
+```mermaid
+flowchart LR
+ A[JavaScript or TypeScript application] --> B[Laya HTTP SDK]
+ B -->|POST /v1/systemone| C[Existing Laya server]
+ B -->|POST /v1/systemone| D[Jev API]
+ C --> E[Router and local checkpoint]
+```
+
+The SDK exports `predict` and a Laya-only `health` probe. It ships ESM,
+CommonJS and declarations, retaining inferred question IDs and choice labels.
+The separate `laya-ts` package runs local ONNX inference; this HTTP client has
+no JavaScript model runtime dependency.
+
+## Shared contract
+
+Requests contain `state`, `questions`, and `model`. The default `jev-latest`
+selects Jev's default model when calling TypeSafe and automatic routing when
+calling Laya, whose server ignores unrecognized model IDs. A client-wide or
+per-call `model` can select a Laya checkpoint or a different Jev model. Choice
+label arrays are normalized to maps with null descriptions before transport.
+
+Responses preserve `model`, `answers`, and token `usage`. Laya's `routing` and
+answer `action` fields are optional extensions; Noul confidence is optional too.
+Choice and Score confidence, distributions, and Score legends remain required.
+Optional extensions are validated when present. See the
+[official Jev API contract](https://docs.typesafe.ai/api).
+
+`/v1/systemone` does not expose Python's standalone routing method or `task` and
+`lang` overrides. The SDK rejects those legacy options instead of silently
+ignoring them. Laya's public `/health` returns `status`, `loaded`, and `device`;
+it is not part of the shared Jev protocol. Prediction never probes health first.
+
+FastAPI detail strings and validation arrays are preserved as `LayaAPIError`
+messages/details. Structured error envelopes from compatible backends are also
+accepted. Requests have configurable deadlines and caller cancellation, and
+are never retried automatically.
+
+## Verification and release
+
+Unit tests cover the shared request contract, all three Jev answer shapes,
+Laya extensions, FastAPI errors, JSON validation, deadlines and cancellation.
+Type checks cover optional metadata, rejected legacy methods/options, inferred
+answer types, and ESM/CommonJS consumers. The live integration test starts the
+unchanged `laya.serve` application with a tiny offline checkpoint, compares SDK
+predictions against direct Python inference, and exercises routing, presets,
+authentication and request limits. CI runs the SDK checks on Node.js 22 and 24.
+
+Jev compatibility is checked against documented contract fixtures; no hosted
+Jev request is made by the test suite. Tiny random weights verify transport and
+numerical parity, not pretrained quality or performance.
+
+See the [SDK guide](../sdk/typescript/README.md) for setup, examples, and npm
+publishing. The package is configured for public `@laya/typescript-sdk` releases
+but publishing requires access to that npm scope. Python release workflows are
+unchanged.
diff --git a/sdk/typescript/LICENSE b/sdk/typescript/LICENSE
new file mode 100644
index 00000000..d9a10c0d
--- /dev/null
+++ b/sdk/typescript/LICENSE
@@ -0,0 +1,176 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
new file mode 100644
index 00000000..69588710
--- /dev/null
+++ b/sdk/typescript/README.md
@@ -0,0 +1,305 @@
+# @laya/typescript-sdk
+
+A dependency-free HTTP client for Laya's Jev-compatible `/v1/systemone` endpoint. Supports ESM and
+CommonJS on Node.js 22+, and browsers with `fetch`, `AbortController`, and
+`structuredClone`. TypeScript consumers need TypeScript 5 or newer.
+
+Inference runs in Laya's existing `laya.serve` server or the Jev API. JavaScript clients do not need
+Python, PyTorch, or model weights installed; the server does. This package does
+not run models directly in a browser or Node.js.
+
+## Run from this repository
+
+In a terminal at the repository root, start the server:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[serve]'
+LAYA_HOST=127.0.0.1 LAYA_MODELS=english laya-serve
+```
+
+In a second terminal, build the SDK and run the plain JavaScript example:
+
+```sh
+cd sdk/typescript
+npm ci
+npm run build
+node examples/triage.mjs
+```
+
+The server preloads checkpoints at startup by default. The command above loads
+the English checkpoint; the router can load others when needed. To preload both
+English and multilingual on CPU:
+
+```sh
+LAYA_HOST=127.0.0.1 LAYA_MODELS=english,multilingual LAYA_DEVICE=cpu laya-serve
+# Set LAYA_DEVICE=cuda or mps for a suitable GPU installation.
+```
+
+Set `LAYA_PRELOAD=0` to defer loading until the first prediction. Initial loads
+download weights and need sufficient memory and disk space. The client timeout
+defaults to 120 seconds; the example allows 10 minutes for a cold load. Server
+configuration uses environment variables, not command-line flags. See the
+[server guide](../../README.md#self-hosting-http-server-jev-compatible).
+
+## Install in another JavaScript project
+
+The npm package name is `@laya/typescript-sdk`. After the first release is
+published, install it with:
+
+```sh
+npm install @laya/typescript-sdk
+```
+
+You can also install the locally built tarball before publication:
+
+```sh
+# From sdk/typescript:
+npm pack
+
+# From your app, substitute the actual checkout path:
+npm install /path/to/laya/sdk/typescript/laya-typescript-sdk-0.1.0.tgz
+```
+
+```js
+import { Laya, triageQuestions } from '@laya/typescript-sdk';
+
+const laya = new Laya({ baseURL: 'http://127.0.0.1:8000' });
+const result = await laya.predict(
+ { message: 'I was charged twice. Please refund the duplicate.' },
+ triageQuestions(),
+);
+
+console.log(result.answers.intent.choice);
+console.log(result.answers.refund_requested.noul); // P(true)
+console.log(result.routing?.model); // Laya-only metadata
+```
+
+CommonJS works too:
+
+```js
+const { Laya, triageQuestions } = require('@laya/typescript-sdk');
+const laya = new Laya();
+laya.predict({ message: 'Please refund my order' }, triageQuestions())
+ .then(result => console.log(result.answers));
+```
+
+## Typed custom questions
+
+Question IDs, primitive types, and choice labels are inferred. Use
+`defineQuestions` to preserve literal types when storing a schema in a variable.
+Inline schemas also infer automatically.
+
+```ts
+import { Laya, defineQuestions } from '@laya/typescript-sdk';
+
+const laya = new Laya();
+const questions = defineQuestions({
+ department: {
+ type: 'choice',
+ instructions: 'Which department should handle this request?',
+ criteria: {
+ billing: 'invoices, payments, refunds',
+ technical: 'bugs, outages, integrations',
+ },
+ },
+ urgency: {
+ type: 'score',
+ instructions: 'How urgent is this request?',
+ criteria: ['no time pressure', 'soon', 'blocking issue or deadline'],
+ },
+ refund: { type: 'noul', instructions: 'Does the user ask for a refund?' },
+});
+
+const result = await laya.predict({ body: 'Refund the duplicate charge today' }, questions);
+result.answers.department.choice; // 'billing' | 'technical'
+result.answers.urgency.score; // number: expected rubric index, from 0 to 2
+result.answers.refund.noul; // number: P(true), from 0 to 1
+result.answers.department.probabilities.billing;
+result.answers.department.confidence;
+result.answers.department.action?.act_probability; // Laya-only metadata
+result.usage.input_tokens;
+```
+
+Choice criteria also accept an array of unique labels, serialized as an option-to-null
+map for the shared protocol. Structured JSON values are
+supported in instructions and descriptions, as in Python. State may be text, a
+JSON object, an array (including chat turns), or null. Undefined values, dates,
+non-finite numbers, BigInts and cycles are rejected locally instead of silently
+changing during serialization. Empty questions or criteria are rejected.
+
+Response fields retain Python's spelling (`input_tokens`, `act_probability`,
+etc.). Scores use zero-based rubric levels. Confidence and accuracy have the
+same calibration limits as the Python model; see the root README.
+
+## Jev compatibility and model selection
+
+The same `predict` method calls [TypeSafe's System One API](https://docs.typesafe.ai/api):
+
+```js
+const jev = new Laya({
+ baseURL: 'https://api.typesafe.ai', // server root; do not append /v1
+ apiKey: process.env.TYPESAFE_API_KEY,
+});
+const result = await jev.predict('Please refund the duplicate charge.', triageQuestions());
+console.log(result.answers.refund_requested.noul);
+```
+
+The default request model is `jev-latest`. Jev uses that model alias; Laya ignores
+unrecognized model IDs and chooses a local checkpoint automatically. This lets
+the same prediction code switch servers through `baseURL` and credentials.
+Set a client-wide `model` or override it per prediction to select a checkpoint:
+
+```js
+const laya = new Laya({ model: 'english' });
+await laya.predict(state, questions, { model: 'typed-decisions' });
+await laya.predict(state, questions, { model: 'multilingual' });
+await jev.predict(state, questions, { model: 'jev-preview' });
+```
+
+Laya accepts its checkpoint aliases and published multilingual/typed-decisions
+model IDs. Use a Jev model ID when calling Jev. The HTTP endpoint supports
+`model`; it does not expose standalone `route()`, `task`, or `lang` overrides.
+Laya still detects language automatically; set `LAYA_AUTO_TASK=1` on the server
+to enable automatic workflow routing.
+
+Both servers return `model`, `answers`, and `usage`. Laya additionally returns
+`routing`, answer `action`, and Noul `confidence`. Those extensions are optional
+in the SDK types and validated when present. Choice and Score confidence remains
+required. `health()` is a Laya-only probe and is never called by `predict()`.
+
+Jev compatibility is covered by fixtures based on its official API contract;
+the automated suite does not call the hosted service. Jev also enforces its own
+input limits (up to 255 Choice options and 2–10 Score levels). Use text/object/array
+state for portability; null state and broader JSON scalar descriptions are Laya
+extensions accepted by this SDK.
+
+## Presets
+
+Available preset functions: `triageQuestions()`, `emailQuestions(categories?)`,
+`guardQuestions()`, `moderationQuestions()`, and `routerQuestions()`. Each returns
+a fresh schema. Email categories can be customized:
+
+```js
+import { emailQuestions } from '@laya/typescript-sdk';
+const questions = emailQuestions({ finance: 'payments', engineering: 'bugs' });
+```
+
+## Errors, cancellation, authentication
+
+```js
+import { Laya, LayaAPIError, LayaTimeoutError } from '@laya/typescript-sdk';
+
+const client = new Laya({
+ baseURL: 'http://127.0.0.1:8000',
+ apiKey: process.env.LAYA_API_KEY,
+ timeoutMs: 120_000,
+});
+const controller = new AbortController();
+try {
+ await client.predict(state, questions, { signal: controller.signal, timeoutMs: 300_000 });
+} catch (error) {
+ if (error instanceof LayaAPIError) console.error(error.status, error.code, error.details);
+ else if (error instanceof LayaTimeoutError) console.error('Request timed out');
+ else throw error;
+}
+```
+
+`timeoutMs: 0` disables the deadline. Calling `controller.abort()` stops waiting;
+inference already running on the server may still finish. Requests are never
+automatically retried. Other errors extend `LayaError`:
+`LayaValidationError`, `LayaConnectionError`, `LayaAbortError`, and
+`LayaResponseError` (invalid JSON or incompatible response structure).
+
+The client accepts custom `headers` and a Fetch-compatible `fetch` implementation.
+Keep API keys on your application's backend. For browser use, put a same-origin
+application proxy in front of a protected server, or configure an appropriate
+authenticated gateway. A shared server key embedded in browser code is public.
+
+Laya's server binds to `0.0.0.0` by default; the quickstart sets `LAYA_HOST=127.0.0.1`
+for local use. Set `LAYA_API_KEY` in its environment to require Bearer
+authentication for predictions. `/health` remains public. `HF_TOKEN`, if needed
+for checkpoint downloads, is a separate server-only credential. Configure CORS
+and TLS at your application proxy or gateway.
+
+## Python service contract
+
+| Endpoint | Request | Response |
+| --- | --- | --- |
+| `GET /health` (Laya only) | None | `{status, loaded, device}` |
+| `POST /v1/systemone` | `{state, questions, model}` | `{model, answers, usage}` plus optional Laya `routing` |
+
+Laya errors use FastAPI's `{detail: ...}` body: 400 for malformed requests, 401
+for authentication, 413 for request limits, 422 for invalid questions, and 500
+for inference failures. The SDK preserves the status and details in
+`LayaAPIError`; string details become the error message. It also accepts
+`{error: {code, message, details?}}` from compatible services. OpenAPI is
+available at `/openapi.json` and interactive request documentation at `/docs`.
+
+For custom checkpoint paths or an existing agent, configure Python's router:
+
+```python
+import uvicorn
+from laya import Router
+from laya.serve import create_app
+
+router = Router(models={"english": "/path/to/checkpoint"}, device="cpu")
+router.preload(["english"])
+app = create_app(router) # Reads LAYA_API_KEY from the environment.
+uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+This SDK uses the repository's existing server without changing its Python
+implementation. The integration fixture injects a router into that same server.
+
+## Development
+
+```sh
+# In sdk/typescript:
+npm ci
+npm test
+PYTHON=../../.venv/bin/python npm run test:integration
+python3 scripts/sync_presets.py --check
+```
+
+Integration testing uses real local PyTorch inference with a tiny random test
+checkpoint, compares answers against direct Python calls, and downloads no model
+weights. It verifies transport and runtime compatibility, not pretrained model
+accuracy. Run the repository's pretrained model tests separately when those
+weights are available. Presets are generated from `laya/presets.py`; regenerate
+with `python3 scripts/sync_presets.py` after editing that source.
+
+## Publishing
+
+Publish from `sdk/typescript` using an npm account with publishing rights in the
+`@laya` scope. npm uses `@scope/package` names; `laya/typescript-sdk` without `@`
+is not this registry package. See [npm's scoped package guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
+
+```sh
+npm login --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+npm ci
+npm test
+PYTHON=../../.venv/bin/python npm run test:integration
+python3 scripts/sync_presets.py --check
+npm publish --dry-run
+npm publish
+```
+
+`publishConfig` sets public access and the official npm registry. Publishing runs
+the build, type checks, and SDK tests through `prepublishOnly`; `prepack` rebuilds
+the distributable. Only `dist/`, this README, the license, and package metadata
+are included. Complete any authentication challenge npm presents locally.
+
+The first version is `0.1.0`. For later releases, run
+`npm version patch --no-git-tag-version` (or `minor` / `major`) here, then repeat
+the checks and publishing commands. Keep SDK versions independent of the Python
+package. npm does not allow republishing an already-used name/version pair.
+
+After publication, verify the release and install it into a clean project:
+
+```sh
+npm view @laya/typescript-sdk version --registry=https://registry.npmjs.org
+npm install @laya/typescript-sdk
+```
diff --git a/sdk/typescript/examples/benchmark.ts b/sdk/typescript/examples/benchmark.ts
new file mode 100644
index 00000000..e0b1a783
--- /dev/null
+++ b/sdk/typescript/examples/benchmark.ts
@@ -0,0 +1,47 @@
+import {
+ Laya,
+ defineQuestions,
+} from "@laya/typescript-sdk";
+const laya = new Laya({
+ baseURL: "http://127.0.0.1:8000",
+ // Allow time for the first model download.
+ timeoutMs: 600_000,
+});
+
+const questions = defineQuestions({
+ refund: {
+ type: "noul",
+ instructions: "Does the customer request a refund?",
+ },
+});
+
+const state = {
+ message: "I was charged twice. Please refund it.",
+};
+
+
+
+async function main() {
+ const health = await laya.health();
+ console.log("Server:", health);
+
+ for (let i = 1; i <= 10; i++) {
+ const start = performance.now();
+
+ const result = await laya.predict(state, questions, {
+ model: "english", // prefer the "english" model for this test
+ });
+
+ const elapsedMs = performance.now() - start;
+
+ console.log(
+ `Request ${i}: ${elapsedMs.toFixed(2)} ms, ` +
+ `tokens=${result.usage.input_tokens}, ` +
+ `model=${result.routing?.model ?? result.model}`,
+ );
+}
+}
+
+main().catch((error: unknown) => {
+ console.error(error);
+});
diff --git a/sdk/typescript/examples/triage.mjs b/sdk/typescript/examples/triage.mjs
new file mode 100644
index 00000000..17ea14d9
--- /dev/null
+++ b/sdk/typescript/examples/triage.mjs
@@ -0,0 +1,19 @@
+import { Laya, triageQuestions } from '@laya/typescript-sdk';
+
+const laya = new Laya({
+ baseURL: process.env.LAYA_BASE_URL ?? 'http://127.0.0.1:8000',
+ apiKey: process.env.LAYA_API_KEY,
+ timeoutMs: 600_000,
+});
+
+try {
+ const result = await laya.predict(
+ { message: 'I was billed twice for March. Please refund the duplicate today.' },
+ triageQuestions(),
+ { model: 'english'}
+ );
+ console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+ console.error(error);
+ process.exitCode = 1;
+}
diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json
new file mode 100644
index 00000000..61d00b16
--- /dev/null
+++ b/sdk/typescript/package-lock.json
@@ -0,0 +1,33 @@
+{
+ "name": "@laya/typescript-sdk",
+ "version": "0.1.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@laya/typescript-sdk",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "devDependencies": {
+ "typescript": "5.9.3"
+ },
+ "engines": {
+ "node": ">=22"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ }
+ }
+}
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
new file mode 100644
index 00000000..6fcc7de7
--- /dev/null
+++ b/sdk/typescript/package.json
@@ -0,0 +1,37 @@
+{
+ "name": "@laya/typescript-sdk",
+ "version": "0.1.0",
+ "description": "Typed JavaScript client for the self-hosted Laya decision engine",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./dist/cjs/index.js",
+ "module": "./dist/esm/index.js",
+ "types": "./dist/esm/index.d.ts",
+ "exports": {
+ ".": {
+ "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+ "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+ }
+ },
+ "files": ["dist", "README.md", "LICENSE"],
+ "sideEffects": false,
+ "publishConfig": {
+ "access": "public",
+ "registry": "https://registry.npmjs.org/"
+ },
+ "engines": { "node": ">=22" },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/NandhaKishorM/laya.git",
+ "directory": "sdk/typescript"
+ },
+ "scripts": {
+ "build": "node scripts/build.mjs",
+ "typecheck": "tsc --noEmit -p test/tsconfig.json",
+ "test": "npm run build && npm run typecheck && node --test test/*.test.mjs",
+ "test:integration": "node --test test/integration.mjs",
+ "prepack": "npm run build",
+ "prepublishOnly": "npm test"
+ },
+ "devDependencies": { "typescript": "5.9.3" }
+}
diff --git a/sdk/typescript/scripts/build.mjs b/sdk/typescript/scripts/build.mjs
new file mode 100644
index 00000000..288cf7ed
--- /dev/null
+++ b/sdk/typescript/scripts/build.mjs
@@ -0,0 +1,9 @@
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, rmSync, writeFileSync } from 'node:fs';
+
+rmSync('dist', { recursive: true, force: true });
+for (const config of ['tsconfig.json', 'tsconfig.cjs.json']) {
+ execFileSync(process.execPath, ['node_modules/typescript/bin/tsc', '-p', config], { stdio: 'inherit' });
+}
+writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }) + '\n');
+copyFileSync('../../LICENSE', 'LICENSE');
diff --git a/sdk/typescript/scripts/sync_presets.py b/sdk/typescript/scripts/sync_presets.py
new file mode 100644
index 00000000..b9793fc0
--- /dev/null
+++ b/sdk/typescript/scripts/sync_presets.py
@@ -0,0 +1,42 @@
+"""Generate TypeScript presets from Python without importing the ML runtime."""
+import argparse
+import importlib.util
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[3]
+spec = importlib.util.spec_from_file_location("laya_presets", ROOT / "laya/presets.py")
+presets = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(presets)
+
+output = [
+ "// Generated by scripts/sync_presets.py. Edit laya/presets.py, then regenerate.\n",
+ "import type { JsonValue, Questions } from './types.js';\n\n",
+]
+for name in ["triage", "email", "guard", "moderation", "router"]:
+ value = getattr(presets, name + "_questions")()
+ output.append(f"const {name}Preset = {json.dumps(value, ensure_ascii=False, indent=2)} as const satisfies Questions;\n\n")
+ if name != "email":
+ output.append(f"export function {name}Questions(): typeof {name}Preset {{\n"
+ f" return structuredClone({name}Preset);\n}}\n\n")
+
+output.append('''export function emailQuestions(): typeof emailPreset;
+export function emailQuestions<const C extends Readonly<Record<string, JsonValue>>>(categories: C):
+ Omit<typeof emailPreset, 'category'> & { category: Omit<typeof emailPreset.category, 'criteria'> & { criteria: C } };
+export function emailQuestions(categories?: Readonly<Record<string, JsonValue>>) {
+ const preset = structuredClone(emailPreset);
+ return { ...preset, category: { ...preset.category, criteria: categories === undefined
+ ? preset.category.criteria : structuredClone(categories) } };
+}
+''')
+
+target = ROOT / "sdk/typescript/src/presets.ts"
+content = "".join(output)
+parser = argparse.ArgumentParser()
+parser.add_argument("--check", action="store_true")
+args = parser.parse_args()
+if args.check:
+ if not target.exists() or target.read_text(encoding="utf-8") != content:
+ raise SystemExit("Presets are stale. Run python sdk/typescript/scripts/sync_presets.py")
+else:
+ target.write_text(content, encoding="utf-8")
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
new file mode 100644
index 00000000..93547b0b
--- /dev/null
+++ b/sdk/typescript/src/client.ts
@@ -0,0 +1,133 @@
+import {
+ LayaAbortError, LayaAPIError, LayaConnectionError, LayaError, LayaResponseError,
+ LayaTimeoutError, LayaValidationError,
+} from './errors.js';
+import type { Health, Prediction, PredictOptions, Questions, RequestOptions, State } from './types.js';
+import { isRecord, validateJson, validateQuestions, validateTimeout } from './validation.js';
+import { validateHealth, validatePrediction } from './response.js';
+
+export interface LayaOptions {
+ /** Server root URL, optionally including a reverse-proxy path prefix. */
+ baseURL?: string;
+ apiKey?: string;
+ /** Default jev-latest: used by Jev and treated as automatic routing by Laya. */
+ model?: string;
+ /** Default 120000 ms; cold checkpoint downloads may require more. Zero disables. */
+ timeoutMs?: number;
+ headers?: HeadersInit;
+ /** Supply a Fetch-compatible implementation for tests or a custom transport. */
+ fetch?: typeof globalThis.fetch;
+}
+
+export class Laya {
+ private readonly baseURL: string;
+ private readonly timeoutMs: number;
+ private readonly headers: Headers;
+ private readonly fetcher: typeof globalThis.fetch;
+ private readonly model: string;
+
+ constructor(options: LayaOptions = {}) {
+ let url: URL;
+ try { url = new URL(options.baseURL ?? 'http://127.0.0.1:8000'); }
+ catch { throw new LayaValidationError('baseURL must be an absolute HTTP(S) URL'); }
+ if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) {
+ throw new LayaValidationError('baseURL must be HTTP(S), without credentials, query, or fragment');
+ }
+ this.baseURL = url.href.replace(/\/+$/, '');
+ this.model = options.model ?? 'jev-latest';
+ if (typeof this.model !== 'string' || !this.model.trim()) {
+ throw new LayaValidationError('model must be a nonempty string');
+ }
+ this.timeoutMs = options.timeoutMs ?? 120_000;
+ validateTimeout(this.timeoutMs);
+ this.headers = new Headers(options.headers);
+ this.headers.set('Accept', 'application/json');
+ if (options.apiKey !== undefined) this.headers.set('Authorization', `Bearer ${options.apiKey}`);
+ const fetcher = options.fetch ?? globalThis.fetch;
+ if (typeof fetcher !== 'function') throw new LayaValidationError('A Fetch implementation is required');
+ this.fetcher = fetcher;
+ }
+
+ async predict<const Q extends Questions>(state: State, questions: Q, options: PredictOptions = {}): Promise<Prediction<Q>> {
+ validateQuestions(questions);
+ const result = await this.request<Prediction<Q>>('/v1/systemone', this.body(state, questions, options), options);
+ validatePrediction(result, questions);
+ return result;
+ }
+
+ /** Query the self-hosted Laya server's health probe. Not supported by Jev. */
+ async health(options: RequestOptions = {}): Promise<Health> {
+ const result = await this.request<Health>('/health', undefined, options);
+ validateHealth(result);
+ return result;
+ }
+
+ private body(state: State, questions: Questions, options: PredictOptions): string {
+ if (state !== null && typeof state !== 'string' && !Array.isArray(state) && !isRecord(state)) {
+ throw new LayaValidationError('state must be text, a JSON object, an array, or null');
+ }
+ for (const key of ['task', 'lang']) {
+ if (key in options) throw new LayaValidationError(`${key} is not supported by /v1/systemone; use model instead`);
+ }
+ const model = options.model ?? this.model;
+ if (typeof model !== 'string' || !model.trim()) throw new LayaValidationError('model must be a nonempty string');
+ // Validate before normalizing so JSON-incompatible values cannot be hidden.
+ validateJson({ state, questions, model });
+ const wireQuestions = Object.fromEntries(Object.entries(questions).map(([id, question]) => [id,
+ question.type === 'choice' && Array.isArray(question.criteria)
+ ? { ...question, criteria: Object.fromEntries(question.criteria.map(label => [label, null])) }
+ : question,
+ ]));
+ const body = { state, questions: wireQuestions, model };
+ validateJson(body);
+ return JSON.stringify(body);
+ }
+
+ private async request<T>(path: string, body: string | undefined, options: RequestOptions): Promise<T> {
+ const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+ validateTimeout(timeoutMs);
+ const controller = new AbortController();
+ const abort = () => controller.abort(new LayaAbortError('Request aborted', { cause: options.signal?.reason }));
+ options.signal?.addEventListener('abort', abort, { once: true });
+ if (options.signal?.aborted) abort();
+ const timer = timeoutMs > 0 ? setTimeout(() => {
+ controller.abort(new LayaTimeoutError(`Request timed out after ${timeoutMs} ms`));
+ }, timeoutMs) : undefined;
+
+ try {
+ controller.signal.throwIfAborted();
+ const headers = new Headers(this.headers);
+ if (body !== undefined) headers.set('Content-Type', 'application/json');
+ const init: RequestInit = { method: body === undefined ? 'GET' : 'POST', headers, signal: controller.signal };
+ if (body !== undefined) init.body = body;
+ // Never retry automatically: repeating an expensive inference request is surprising.
+ const response = await this.fetcher.call(globalThis, this.baseURL + path, init);
+ const raw = await response.text();
+ let payload: unknown;
+ try { payload = JSON.parse(raw); }
+ catch {
+ if (response.ok) throw new LayaResponseError('Server returned invalid JSON');
+ }
+ if (!response.ok) {
+ const error = isRecord(payload) && isRecord(payload.error) ? payload.error : undefined;
+ const detail = isRecord(payload) ? payload.detail : undefined;
+ throw new LayaAPIError(
+ typeof error?.message === 'string' ? error.message
+ : typeof detail === 'string' ? detail : `Laya returned HTTP ${response.status}`,
+ response.status,
+ typeof error?.code === 'string' ? error.code : 'http_error',
+ error?.details ?? detail ?? payload ?? raw,
+ );
+ }
+ if (!isRecord(payload)) throw new LayaResponseError('Server returned a non-object JSON response');
+ return payload as T;
+ } catch (error) {
+ if (controller.signal.aborted) throw controller.signal.reason;
+ if (error instanceof LayaError) throw error;
+ throw new LayaConnectionError('Could not reach the Laya server', { cause: error });
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ options.signal?.removeEventListener('abort', abort);
+ }
+ }
+}
diff --git a/sdk/typescript/src/errors.ts b/sdk/typescript/src/errors.ts
new file mode 100644
index 00000000..ce3df228
--- /dev/null
+++ b/sdk/typescript/src/errors.ts
@@ -0,0 +1,26 @@
+export class LayaError extends Error {
+ constructor(message: string, options?: ErrorOptions) {
+ super(message, options);
+ this.name = new.target.name;
+ }
+}
+
+/** Request rejected locally, before any network traffic. */
+export class LayaValidationError extends LayaError {}
+
+/** A non-2xx response. Includes JSON error details when available. */
+export class LayaAPIError extends LayaError {
+ constructor(
+ message: string,
+ public readonly status: number,
+ public readonly code: string,
+ public readonly details: unknown,
+ ) {
+ super(message);
+ }
+}
+
+export class LayaConnectionError extends LayaError {}
+export class LayaTimeoutError extends LayaError {}
+export class LayaAbortError extends LayaError {}
+export class LayaResponseError extends LayaError {}
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
new file mode 100644
index 00000000..6f8449f8
--- /dev/null
+++ b/sdk/typescript/src/index.ts
@@ -0,0 +1,5 @@
+export { Laya } from './client.js';
+export type { LayaOptions } from './client.js';
+export * from './types.js';
+export * from './errors.js';
+export * from './presets.js';
diff --git a/sdk/typescript/src/presets.ts b/sdk/typescript/src/presets.ts
new file mode 100644
index 00000000..1913aa2e
--- /dev/null
+++ b/sdk/typescript/src/presets.ts
@@ -0,0 +1,203 @@
+// Generated by scripts/sync_presets.py. Edit laya/presets.py, then regenerate.
+import type { JsonValue, Questions } from './types.js';
+
+const triagePreset = {
+ "intent": {
+ "type": "choice",
+ "instructions": "What does the customer want in `message`?",
+ "criteria": {
+ "refund": "money returned or a duplicate charge reversed",
+ "technical_help": "a bug, outage or integration problem",
+ "billing_question": "a question about an invoice, plan or payment method",
+ "information": "general information, pricing or how-to",
+ "cancellation": "wants to cancel or downgrade",
+ "other": "none of the other options fits"
+ }
+ },
+ "is_urgent": {
+ "type": "noul",
+ "instructions": "Does `message` communicate time pressure or a deadline?"
+ },
+ "frustration": {
+ "type": "score",
+ "instructions": "How frustrated does the customer sound in `message`?",
+ "criteria": [
+ "calm and neutral",
+ "concerned but civil",
+ "clearly annoyed",
+ "very angry or using strong language"
+ ]
+ },
+ "refund_requested": {
+ "type": "noul",
+ "instructions": "Does the customer ask for money back?"
+ },
+ "churn_risk": {
+ "type": "noul",
+ "instructions": "Does `message` suggest the customer may leave for a competitor or cancel?"
+ }
+} as const satisfies Questions;
+
+export function triageQuestions(): typeof triagePreset {
+ return structuredClone(triagePreset);
+}
+
+const emailPreset = {
+ "category": {
+ "type": "choice",
+ "instructions": "Which team should handle the email in `body`?",
+ "criteria": {
+ "billing": "invoices, payments, refunds",
+ "technical": "bugs, outages, integrations",
+ "sales": "pricing, demos, new purchases",
+ "security": "phishing, scams, account compromise",
+ "hr": "hiring, leave, payroll",
+ "other": "none of the above"
+ }
+ },
+ "is_spam": {
+ "type": "noul",
+ "instructions": "Is this email unsolicited spam or bulk marketing?"
+ },
+ "is_phishing": {
+ "type": "noul",
+ "instructions": "Is this email a phishing or scam attempt to steal money, credentials, or personal data?",
+ "criteria": {
+ "true": "phishing, scam, or fraud",
+ "false": "a legitimate email"
+ }
+ },
+ "urgency": {
+ "type": "score",
+ "instructions": "How urgent is the request in `body`?",
+ "criteria": [
+ "no time pressure",
+ "needs attention soon",
+ "blocking issue or hard deadline"
+ ]
+ },
+ "needs_reply": {
+ "type": "noul",
+ "instructions": "Does the sender expect a reply?"
+ }
+} as const satisfies Questions;
+
+const guardPreset = {
+ "jailbreak": {
+ "type": "noul",
+ "instructions": "Does `prompt` try to make an AI assistant ignore its rules, policies or system instructions?"
+ },
+ "prompt_injection": {
+ "type": "noul",
+ "instructions": "Does `prompt` contain instructions aimed at the AI system rather than a genuine user request?"
+ },
+ "sensitive_data": {
+ "type": "noul",
+ "instructions": "Does `prompt` contain credentials, personal data or other sensitive information?"
+ },
+ "harm_severity": {
+ "type": "score",
+ "instructions": "How much harm would complying with `prompt` cause?",
+ "criteria": [
+ "none: ordinary request",
+ "minor: mildly inappropriate",
+ "serious: unsafe advice or abuse",
+ "severe: dangerous or illegal"
+ ]
+ },
+ "topic": {
+ "type": "choice",
+ "instructions": "What is `prompt` about?",
+ "criteria": {
+ "product_support": null,
+ "coding": null,
+ "general_knowledge": null,
+ "personal_advice": null,
+ "security_testing": null,
+ "other": null
+ }
+ }
+} as const satisfies Questions;
+
+export function guardQuestions(): typeof guardPreset {
+ return structuredClone(guardPreset);
+}
+
+const moderationPreset = {
+ "toxic": {
+ "type": "noul",
+ "instructions": "Is `post` toxic: rude, disrespectful or likely to make someone leave the discussion?"
+ },
+ "harassment": {
+ "type": "noul",
+ "instructions": "Does `post` target or harass a specific person?"
+ },
+ "threat": {
+ "type": "noul",
+ "instructions": "Does `post` threaten violence, harm or intimidation?"
+ },
+ "spam": {
+ "type": "noul",
+ "instructions": "Is `post` spam or advertising?"
+ },
+ "severity": {
+ "type": "score",
+ "instructions": "How severe is any rule-breaking in `post`?",
+ "criteria": [
+ "no rule-breaking: ordinary on-topic post",
+ "mild: rude tone or off-topic, no target",
+ "clear violation: insults, harassment or spam aimed at someone",
+ "severe: threats, hate speech or calls for violence"
+ ]
+ }
+} as const satisfies Questions;
+
+export function moderationQuestions(): typeof moderationPreset {
+ return structuredClone(moderationPreset);
+}
+
+const routerPreset = {
+ "difficulty": {
+ "type": "score",
+ "instructions": "How hard is `request` for a language model?",
+ "criteria": [
+ "trivial: a lookup or one-liner",
+ "easy: short answer, no reasoning",
+ "moderate: several steps",
+ "hard: long multi-step reasoning or specialist knowledge"
+ ]
+ },
+ "domain": {
+ "type": "choice",
+ "instructions": "What domain does `request` belong to?",
+ "criteria": {
+ "code": "software engineering, programming, refactoring, architecture, debugging",
+ "math_or_logic": "mathematics, logic puzzles, proofs, complex calculation",
+ "writing": "creative writing, essays, emails, blog posts, copywriting",
+ "factual_lookup": "facts, definitions, trivia, history",
+ "data_analysis": "statistics, SQL, data manipulation, metrics",
+ "chitchat": "casual conversation, greetings, small talk"
+ }
+ },
+ "needs_tools": {
+ "type": "noul",
+ "instructions": "Does answering `request` require external tools, search or private data?"
+ },
+ "is_sensitive": {
+ "type": "noul",
+ "instructions": "Does `request` involve money, legal, medical or safety consequences?"
+ }
+} as const satisfies Questions;
+
+export function routerQuestions(): typeof routerPreset {
+ return structuredClone(routerPreset);
+}
+
+export function emailQuestions(): typeof emailPreset;
+export function emailQuestions<const C extends Readonly<Record<string, JsonValue>>>(categories: C):
+ Omit<typeof emailPreset, 'category'> & { category: Omit<typeof emailPreset.category, 'criteria'> & { criteria: C } };
+export function emailQuestions(categories?: Readonly<Record<string, JsonValue>>) {
+ const preset = structuredClone(emailPreset);
+ return { ...preset, category: { ...preset.category, criteria: categories === undefined
+ ? preset.category.criteria : structuredClone(categories) } };
+}
diff --git a/sdk/typescript/src/response.ts b/sdk/typescript/src/response.ts
new file mode 100644
index 00000000..4092b858
--- /dev/null
+++ b/sdk/typescript/src/response.ts
@@ -0,0 +1,60 @@
+import { LayaResponseError } from './errors.js';
+import type { Questions } from './types.js';
+import { isRecord } from './validation.js';
+
+function expect(condition: unknown, field: string): asserts condition {
+ if (!condition) throw new LayaResponseError(`Invalid Laya response: ${field}`);
+}
+const number = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const probability = (value: unknown) => number(value) && value >= 0 && value <= 1;
+const model = (value: unknown) => typeof value === 'string' && ['english', 'multilingual', 'typed-decisions'].includes(value);
+
+export function validateRoute(value: unknown): void {
+ expect(isRecord(value), 'routing');
+ expect(model(value.model) && typeof value.repo === 'string' && typeof value.reason === 'string', 'routing model/repo/reason');
+ expect(value.workflow === null || typeof value.workflow === 'string', 'routing workflow');
+ const detection = value.detection;
+ if (detection === null) return;
+ expect(isRecord(detection), 'routing detection');
+ expect(typeof detection.script === 'string' && isRecord(detection.script_profile), 'script detection');
+ expect(Object.values(detection.script_profile).every(number), 'script profile');
+ expect(detection.language === null || typeof detection.language === 'string', 'detected language');
+ expect(typeof detection.is_english === 'boolean' && typeof detection.language_undecided === 'boolean', 'language flags');
+ expect(probability(detection.diacritic_rate) && probability(detection.non_latin_fraction), 'language fractions');
+}
+
+export function validateHealth(value: unknown): void {
+ expect(isRecord(value) && value.status === 'ok' && typeof value.device === 'string', 'health');
+ expect(Array.isArray(value.loaded) && value.loaded.every(model), 'loaded');
+}
+
+export function validatePrediction(value: unknown, questions: Questions): void {
+ expect(isRecord(value) && typeof value.model === 'string' && isRecord(value.answers), 'prediction');
+ expect(isRecord(value.usage) && Number.isInteger(value.usage.input_tokens) && Number.isInteger(value.usage.output_tokens), 'usage');
+ if (value.routing !== undefined) validateRoute(value.routing);
+ for (const [id, question] of Object.entries(questions)) {
+ const answer = value.answers[id];
+ expect(isRecord(answer) && answer.type === question.type, `answers.${id}.type`);
+ if (question.type !== 'noul' || answer.confidence !== undefined) {
+ expect(probability(answer.confidence), `answers.${id}.confidence`);
+ }
+ if (answer.action !== undefined) {
+ expect(isRecord(answer.action) && probability(answer.action.act_probability), `answers.${id}.action`);
+ }
+ if (question.type === 'noul') {
+ expect(probability(answer.noul), `answers.${id}.noul`);
+ } else {
+ expect(isRecord(answer.probabilities) && Object.values(answer.probabilities).every(probability), `answers.${id}.probabilities`);
+ if (question.type === 'choice') {
+ const labels = Array.isArray(question.criteria) ? question.criteria : Object.keys(question.criteria);
+ expect(typeof answer.choice === 'string' && labels.includes(answer.choice), `answers.${id}.choice`);
+ expect(labels.every(label => Object.hasOwn(answer.probabilities as object, label)), `answers.${id}.probabilities labels`);
+ } else {
+ expect(number(answer.score) && answer.score >= 0 && answer.score <= question.criteria.length - 1, `answers.${id}.score`);
+ expect(isRecord(answer.legend), `answers.${id}.legend`);
+ expect(question.criteria.every((_, i) => Object.hasOwn(answer.legend as object, String(i)) &&
+ Object.hasOwn(answer.probabilities as object, String(i))), `answers.${id}.rubric levels`);
+ }
+ }
+ }
+}
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
new file mode 100644
index 00000000..03891919
--- /dev/null
+++ b/sdk/typescript/src/types.ts
@@ -0,0 +1,101 @@
+/** Values that survive the JSON transport without being changed or discarded. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+export type State = string | readonly JsonValue[] | { readonly [key: string]: JsonValue } | null;
+
+export interface ChoiceQuestion {
+ readonly type: 'choice';
+ readonly instructions: JsonValue;
+ readonly criteria: readonly string[] | Readonly<Record<string, JsonValue>>;
+}
+export interface ScoreQuestion {
+ readonly type: 'score';
+ readonly instructions: JsonValue;
+ readonly criteria: readonly JsonValue[];
+}
+export interface NoulQuestion {
+ readonly type: 'noul';
+ readonly instructions: JsonValue;
+ readonly criteria?: Readonly<{ true?: JsonValue; false?: JsonValue }> | null;
+}
+export type Question = ChoiceQuestion | ScoreQuestion | NoulQuestion;
+export type Questions = Readonly<Record<string, Question>>;
+export type ModelName = 'english' | 'multilingual' | 'typed-decisions';
+export type ModelAlias = ModelName | 'en' | 'laya' | 'default' | 'multi' | 'ml' | 'laya-multilingual'
+ | 'typed' | 'typed_decisions' | 'laya-typed-decisions' | 'decisions';
+
+export interface RequestOptions {
+ /** Abort waiting for the response. Running inference may still finish on the server. */
+ signal?: AbortSignal;
+ /** Override the client timeout. Zero disables the timeout. */
+ timeoutMs?: number;
+}
+export interface PredictOptions extends RequestOptions {
+ /** Laya checkpoint/alias or Jev model ID. Overrides the client's default model. */
+ model?: string;
+}
+
+interface AnswerBase {
+ /** Laya extension; absent from Jev responses. */
+ action?: { act_probability: number };
+}
+export interface ChoiceAnswer<Label extends string = string> extends AnswerBase {
+ type: 'choice';
+ confidence: number;
+ choice: Label;
+ probabilities: Record<Label, number>;
+}
+export interface ScoreAnswer extends AnswerBase {
+ type: 'score';
+ confidence: number;
+ /** Expected zero-based rubric index, not a normalized probability. */
+ score: number;
+ legend: Record<string, JsonValue>;
+ probabilities: Record<string, number>;
+}
+export interface NoulAnswer extends AnswerBase {
+ type: 'noul';
+ /** Laya extension; Jev returns only type and noul. */
+ confidence?: number;
+ /** P(true), between 0 and 1. */
+ noul: number;
+}
+type Labels<C> = C extends readonly string[] ? C[number] : Extract<keyof C, string>;
+export type ChoiceLabels<Q extends ChoiceQuestion> = Labels<Q['criteria']>;
+export type Answer<Q extends Question = Question> = Q extends ChoiceQuestion
+ ? ChoiceAnswer<ChoiceLabels<Q>> : Q extends ScoreQuestion ? ScoreAnswer : NoulAnswer;
+export type Answers<Q extends Questions> = { -readonly [K in keyof Q]: Answer<Q[K]> };
+
+export interface LanguageDetection {
+ script: string;
+ script_profile: Record<string, number>;
+ language: string | null;
+ is_english: boolean;
+ language_undecided: boolean;
+ diacritic_rate: number;
+ non_latin_fraction: number;
+}
+export interface RouteDecision {
+ model: ModelName;
+ repo: string;
+ reason: string;
+ detection: LanguageDetection | null;
+ workflow: string | null;
+}
+export interface Prediction<Q extends Questions = Questions> {
+ model: string;
+ answers: Answers<Q>;
+ usage: { input_tokens: number; output_tokens: number };
+ /** Laya extension; absent from Jev responses. */
+ routing?: RouteDecision;
+}
+/** Laya's health probe; not part of the shared Jev protocol. */
+export interface Health {
+ status: 'ok';
+ loaded: ModelName[];
+ device: string;
+}
+
+/** Preserve question IDs, primitive types, and literal choice labels when declaring a schema. */
+export function defineQuestions<const Q extends Questions>(questions: Q): Q {
+ return questions;
+}
diff --git a/sdk/typescript/src/validation.ts b/sdk/typescript/src/validation.ts
new file mode 100644
index 00000000..5aefc312
--- /dev/null
+++ b/sdk/typescript/src/validation.ts
@@ -0,0 +1,69 @@
+import { LayaValidationError } from './errors.js';
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Reject JS values JSON.stringify would silently drop or rewrite. */
+export function validateJson(value: unknown, path = 'request', ancestors = new Set<object>()): void {
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+ if (typeof value === 'number' && Number.isFinite(value)) return;
+ if (typeof value !== 'object' || value === null) {
+ throw new LayaValidationError(`${path} must contain only JSON values`);
+ }
+ if (ancestors.has(value)) throw new LayaValidationError(`${path} contains a circular reference`);
+ if (ancestors.size > 100) throw new LayaValidationError(`${path} exceeds the JSON nesting limit (100)`);
+ if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+ throw new LayaValidationError(`${path} must be a plain JSON object`);
+ }
+ ancestors.add(value);
+ if (Array.isArray(value)) {
+ for (const item of value) validateJson(item, `${path}[]`, ancestors);
+ } else {
+ for (const [key, item] of Object.entries(value)) validateJson(item, `${path}.${key}`, ancestors);
+ }
+ ancestors.delete(value);
+}
+
+export function validateQuestions(questions: unknown): void {
+ if (!isRecord(questions) || Object.keys(questions).length === 0) {
+ throw new LayaValidationError('questions must be an object containing at least one question');
+ }
+ for (const [id, q] of Object.entries(questions)) {
+ const invalid = (message: string): never => { throw new LayaValidationError(`questions.${id}: ${message}`); };
+ if (!isRecord(q)) invalid('expected a question object');
+ const question = q as Record<string, unknown>;
+ if (!Object.hasOwn(question, 'instructions')) invalid('instructions is required');
+ if (Object.keys(question).some(key => !['type', 'instructions', 'criteria'].includes(key))) {
+ invalid('unknown question field');
+ }
+ const criteria = question.criteria;
+ switch (question.type) {
+ case 'choice':
+ if (Array.isArray(criteria)) {
+ if (!criteria.length || criteria.some(c => typeof c !== 'string') || new Set(criteria).size !== criteria.length) {
+ invalid('choice criteria must contain unique string labels');
+ }
+ } else if (!isRecord(criteria) || !Object.keys(criteria).length) {
+ invalid('choice requires a nonempty criteria object or array');
+ }
+ break;
+ case 'score':
+ if (!Array.isArray(criteria) || !criteria.length) invalid('score requires a nonempty criteria array');
+ break;
+ case 'noul':
+ if (criteria !== undefined && criteria !== null &&
+ (!isRecord(criteria) || Object.keys(criteria).some(k => k !== 'true' && k !== 'false'))) {
+ invalid('noul criteria may only describe true and false');
+ }
+ break;
+ default: invalid('type must be choice, score, or noul');
+ }
+ }
+}
+
+export function validateTimeout(value: number): void {
+ if (!Number.isFinite(value) || value < 0 || value > 2_147_483_647) {
+ throw new LayaValidationError('timeoutMs must be between 0 and 2147483647');
+ }
+}
diff --git a/sdk/typescript/test/client.test.mjs b/sdk/typescript/test/client.test.mjs
new file mode 100644
index 00000000..748a9072
--- /dev/null
+++ b/sdk/typescript/test/client.test.mjs
@@ -0,0 +1,230 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { test } from 'node:test';
+import {
+ Laya, LayaAPIError, LayaAbortError, LayaConnectionError, LayaTimeoutError,
+ LayaValidationError, LayaResponseError, emailQuestions, triageQuestions,
+} from '@laya/typescript-sdk';
+
+const questions = { refund: { type: 'noul', instructions: 'Refund?' } };
+const json = (value, status = 200) => new Response(JSON.stringify(value), { status });
+const health = { status: 'ok', loaded: [], device: 'auto' };
+const route = { model: 'english', repo: 'convaiinnovations/laya', reason: 'test', detection: null, workflow: null };
+const prediction = { model: 'laya-rl-agent', routing: route, usage: { input_tokens: 10, output_tokens: 0 },
+ answers: { refund: { type: 'noul', noul: 0.9, confidence: 0.9, action: { act_probability: 0.8 } } } };
+
+test('ESM and CommonJS exports can be consumed by ordinary JavaScript', () => {
+ const cjs = createRequire(import.meta.url)('@laya/typescript-sdk');
+ assert.equal(typeof cjs.Laya, 'function');
+ assert.deepEqual(cjs.triageQuestions(), triageQuestions());
+});
+
+test('systemone request preserves Unicode/JSON, auth, model override and proxy prefix', async () => {
+ let calls = 0;
+ const client = new Laya({ baseURL: 'https://example.com/laya///', apiKey: 'key', headers: { 'X-App': 'test' },
+ fetch: async (url, init) => {
+ calls++;
+ assert.equal(url, 'https://example.com/laya/v1/systemone');
+ assert.equal(init.method, 'POST');
+ assert.equal(init.headers.get('Authorization'), 'Bearer key');
+ assert.equal(init.headers.get('Content-Type'), 'application/json');
+ assert.equal(init.headers.get('X-App'), 'test');
+ assert.deepEqual(JSON.parse(init.body), { state: { text: 'नमस्ते', count: 0 }, questions, model: 'en' });
+ return json(prediction);
+ } });
+ await client.predict({ text: 'नमस्ते', count: 0 }, questions, { model: 'en' });
+ assert.equal(calls, 1);
+});
+
+test('Laya health uses GET and accepts the existing server response', async () => {
+ const calls = [];
+ const client = new Laya({ fetch: async (url, init) => {
+ calls.push([new URL(url).pathname, init.method, init.body]);
+ return json(health);
+ } });
+ assert.deepEqual(await client.health(), health);
+ assert.deepEqual(calls, [['/health', 'GET', undefined]]);
+ assert.equal(client.route, undefined);
+});
+
+// Contract fixtures based on https://docs.typesafe.ai/api (no live Jev credentials required).
+const jevQuestions = {
+ team: { type: 'choice', instructions: 'Team?', criteria: ['billing', 'support'] },
+ urgency: { type: 'score', instructions: 'Urgency?', criteria: ['low', 'high'] },
+ refund: questions.refund,
+};
+const jevPrediction = {
+ model: 'jev-1.13.0', usage: { input_tokens: 20, output_tokens: 10 },
+ answers: {
+ team: { type: 'choice', choice: 'billing', probabilities: { billing: 0.8, support: 0.2 }, confidence: 0.6 },
+ urgency: { type: 'score', score: 0.7, probabilities: { '0': 0.3, '1': 0.7 }, legend: { '0': 'low', '1': 'high' }, confidence: 0.4 },
+ refund: { type: 'noul', noul: 0.9 },
+ },
+};
+
+test('shared protocol accepts all Jev answer types without Laya extensions', async () => {
+ for (const baseURL of ['http://127.0.0.1:8000', 'https://api.typesafe.ai']) {
+ const client = new Laya({ baseURL, apiKey: 'test-key', fetch: async (url, init) => {
+ assert.equal(url, `${baseURL}/v1/systemone`);
+ assert.equal(init.headers.get('Authorization'), 'Bearer test-key');
+ assert.deepEqual(JSON.parse(init.body), {
+ state: 'Refund please', model: 'jev-latest',
+ questions: { ...jevQuestions, team: { ...jevQuestions.team, criteria: { billing: null, support: null } } },
+ });
+ return json(jevPrediction);
+ } });
+ assert.deepEqual(await client.predict('Refund please', jevQuestions), jevPrediction);
+ }
+ assert.deepEqual(jevQuestions.team.criteria, ['billing', 'support'], 'normalization must not mutate the schema');
+});
+
+test('client model default supports arbitrary Jev IDs and request overrides', async () => {
+ const models = [];
+ const client = new Laya({ model: 'jev-preview', fetch: async (_url, init) => {
+ models.push(JSON.parse(init.body).model);
+ return json(prediction);
+ } });
+ await client.predict('hello', questions);
+ await client.predict('hello', questions, { model: 'convaiinnovations/laya-multilingual' });
+ assert.deepEqual(models, ['jev-preview', 'convaiinnovations/laya-multilingual']);
+});
+
+test('unsupported routing options and invalid models fail before sending a request', async () => {
+ const client = new Laya({ fetch: async () => { assert.fail('must not send'); } });
+ for (const options of [{ task: 'typed' }, { lang: 'hi' }, { model: '' }, { model: 1 }]) {
+ await assert.rejects(client.predict('hello', questions, options), LayaValidationError);
+ }
+ for (const model of ['', ' ', 1]) assert.throws(() => new Laya({ model }), LayaValidationError);
+});
+
+test('bad JavaScript inputs fail before fetch without lossy serialization', async () => {
+ let calls = 0;
+ const client = new Laya({ fetch: async () => { calls++; return json({}); } });
+ const cyclic = {}; cyclic.self = cyclic;
+ for (const state of [undefined, 1, true, { n: NaN }, { n: Infinity }, { n: 1n }, { n: undefined }, new Date(), cyclic]) {
+ await assert.rejects(client.predict(state, questions), LayaValidationError);
+ }
+ for (const q of [{}, { q: { type: 'wat', instructions: 'test' } },
+ { q: { type: 'choice', instructions: 'Pick', criteria: [] } },
+ { q: { type: 'choice', instructions: 'Pick', criteria: ['a', 'a'] } },
+ { q: { type: 'score', instructions: 'Score', criteria: [] } },
+ { q: { type: 'noul', instructions: 'True?', criteria: { yes: 'yes' } } },
+ { q: { type: 'noul', instructions: 'True?', typo: 1 } }]) {
+ await assert.rejects(client.predict('hello', q), LayaValidationError);
+ }
+ assert.equal(calls, 0);
+});
+
+test('invalid configuration is rejected', () => {
+ for (const baseURL of ['oops', 'ftp://example.com', 'https://x/?key=secret', 'https://user:password@x/', 'https://x/#fragment']) {
+ assert.throws(() => new Laya({ baseURL }), LayaValidationError);
+ }
+ for (const timeoutMs of [-1, Infinity, NaN, 2 ** 31]) {
+ assert.throws(() => new Laya({ timeoutMs }), LayaValidationError);
+ }
+});
+
+test('structured API errors keep status, code and validation details; no retries', async () => {
+ let calls = 0;
+ const details = [{ location: ['questions'], message: 'invalid' }];
+ const client = new Laya({ fetch: async () => { calls++; return json({ error: { message: 'Invalid request', code: 'validation_error', details } }, 422); } });
+ await assert.rejects(client.predict('Hello', questions), error => {
+ assert.ok(error instanceof LayaAPIError);
+ assert.equal(error.status, 422);
+ assert.equal(error.code, 'validation_error');
+ assert.deepEqual(error.details, details);
+ return true;
+ });
+ assert.equal(calls, 1);
+});
+
+test('FastAPI errors preserve detail strings and validation arrays', async () => {
+ for (const [status, detail] of [[401, 'invalid or missing bearer token'],
+ [422, [{ loc: ['body', 'model'], msg: 'Field required', type: 'missing' }]],
+ [413, 'request body too large'], [500, 'inference failed']]) {
+ await assert.rejects(new Laya({ fetch: async () => json({ detail }, status) }).predict('hello', questions), error => {
+ assert.ok(error instanceof LayaAPIError);
+ assert.equal(error.status, status);
+ assert.equal(error.code, 'http_error');
+ assert.equal(error.message, typeof detail === 'string' ? detail : `Laya returned HTTP ${status}`);
+ assert.deepEqual(error.details, detail);
+ return true;
+ });
+ }
+});
+
+test('non-JSON proxy errors remain API errors, malformed successes are response errors', async () => {
+ const client = new Laya({ fetch: async () => new Response('<html>bad gateway</html>', { status: 502 }) });
+ await assert.rejects(client.health(), error => error instanceof LayaAPIError && error.status === 502);
+ for (const raw of ['<html>success?</html>', 'null', '[]', '{}']) {
+ await assert.rejects(new Laya({ fetch: async () => new Response(raw) }).health(), LayaResponseError);
+ }
+});
+
+test('malformed answers cannot masquerade as typed predictions', async () => {
+ for (const mutate of [p => { p.answers = {}; }, p => { p.answers.refund.noul = 2; },
+ p => { p.answers.refund.type = 'choice'; }, p => { p.routing.repo = ['repo', 'sub']; },
+ p => { p.routing.model = ['english']; },
+ p => { p.usage.input_tokens = '10'; }]) {
+ const payload = structuredClone(prediction);
+ mutate(payload);
+ await assert.rejects(new Laya({ fetch: async () => json(payload) }).predict('Hello', questions), LayaResponseError);
+ }
+});
+
+test('Jev compatibility still rejects malformed required fields and optional extensions', async () => {
+ for (const mutate of [p => { delete p.answers.team.confidence; }, p => { delete p.answers.urgency.legend; },
+ p => { p.answers.team.choice = 'unknown'; }, p => { delete p.answers.team.probabilities.billing; },
+ p => { p.answers.urgency.score = 2; }, p => { p.answers.refund.confidence = 'high'; },
+ p => { p.answers.refund.action = { act_probability: 2 }; }, p => { p.routing = null; }]) {
+ const payload = structuredClone(jevPrediction);
+ mutate(payload);
+ await assert.rejects(new Laya({ fetch: async () => json(payload) }).predict('hello', jevQuestions), LayaResponseError);
+ }
+});
+
+test('network errors preserve the cause', async () => {
+ const cause = new TypeError('fetch failed');
+ await assert.rejects(new Laya({ fetch: async () => { throw cause; } }).health(), error =>
+ error instanceof LayaConnectionError && error.cause === cause);
+});
+
+const hangingFetch = async (_url, init) => new Promise((_resolve, reject) => {
+ init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true });
+});
+
+test('timeout aborts fetch and per-request override wins', async () => {
+ const client = new Laya({ timeoutMs: 1000, fetch: hangingFetch });
+ await assert.rejects(client.health({ timeoutMs: 10 }), LayaTimeoutError);
+});
+
+test('timeout includes response body consumption', async () => {
+ const client = new Laya({ timeoutMs: 10, fetch: async (_url, init) => ({
+ ok: true, text: () => new Promise((_resolve, reject) => {
+ init.signal.addEventListener('abort', () => reject(init.signal.reason), { once: true });
+ }),
+ }) });
+ await assert.rejects(client.health(), LayaTimeoutError);
+});
+
+test('caller cancellation works during a request and before fetch', async () => {
+ const controller = new AbortController();
+ const client = new Laya({ timeoutMs: 0, fetch: hangingFetch });
+ const promise = client.health({ signal: controller.signal });
+ controller.abort('user cancelled');
+ await assert.rejects(promise, LayaAbortError);
+ let called = false;
+ await assert.rejects(new Laya({ fetch: async () => { called = true; return json(health); } })
+ .health({ signal: controller.signal }), LayaAbortError);
+ assert.equal(called, false);
+});
+
+test('presets are fresh and custom email categories are copied', () => {
+ const first = triageQuestions(); first.frustration.criteria[0] = 'changed';
+ assert.equal(triageQuestions().frustration.criteria[0], 'calm and neutral');
+ const categories = { finance: { description: 'money' } };
+ const email = emailQuestions(categories);
+ email.category.criteria.finance.description = 'changed';
+ assert.equal(categories.finance.description, 'money');
+ assert.ok(emailQuestions().category.criteria.billing);
+});
diff --git a/sdk/typescript/test/commonjs.cts b/sdk/typescript/test/commonjs.cts
new file mode 100644
index 00000000..804876c8
--- /dev/null
+++ b/sdk/typescript/test/commonjs.cts
@@ -0,0 +1,11 @@
+import sdk = require('@laya/typescript-sdk');
+const client = new sdk.Laya();
+const questions = sdk.defineQuestions({ q: { type: 'noul', instructions: 'Does it work?' } });
+async function run() {
+ const result = await client.predict('Yes', questions);
+ const probability: number = result.answers.q.noul;
+ // @ts-expect-error Noul answers have no score.
+ result.answers.q.score;
+ return probability;
+}
+void run;
diff --git a/sdk/typescript/test/integration.mjs b/sdk/typescript/test/integration.mjs
new file mode 100644
index 00000000..f6067bc7
--- /dev/null
+++ b/sdk/typescript/test/integration.mjs
@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { test } from 'node:test';
+import { Laya, LayaAPIError, triageQuestions, emailQuestions, guardQuestions, moderationQuestions, routerQuestions } from '@laya/typescript-sdk';
+
+test('JavaScript → HTTP → Python Router → real offline Agent inference', { timeout: 90_000 }, async t => {
+ const script = fileURLToPath(new URL('../../../tests/sdk_server_fixture.py', import.meta.url));
+ const server = spawn(process.env.PYTHON ?? 'python3', [script], { stdio: ['ignore', 'pipe', 'pipe'] });
+ let stderr = '';
+ server.stderr.on('data', chunk => { stderr += chunk; });
+ t.after(async () => {
+ if (server.exitCode === null && server.signalCode === null) {
+ const exited = once(server, 'exit');
+ server.kill('SIGTERM');
+ const timer = setTimeout(() => server.kill('SIGKILL'), 5000);
+ try { await exited; } finally { clearTimeout(timer); }
+ }
+ });
+ const fixture = await new Promise((resolve, reject) => {
+ const lines = createInterface({ input: server.stdout });
+ const timer = setTimeout(() => reject(new Error(`Server startup timed out: ${stderr}`)), 60_000);
+ const failed = code => { clearTimeout(timer); reject(new Error(`Server exited (${code}): ${stderr}`)); };
+ server.once('exit', failed);
+ server.once('error', error => { clearTimeout(timer); reject(error); });
+ lines.on('line', line => {
+ if (line.startsWith('LAYA_TEST_SERVER=')) {
+ clearTimeout(timer);
+ server.off('exit', failed);
+ resolve(JSON.parse(line.slice('LAYA_TEST_SERVER='.length)));
+ }
+ });
+ });
+ const client = new Laya({ baseURL: fixture.baseURL, apiKey: 'integration-test', timeoutMs: 10_000 });
+ let ready = false;
+ for (let i = 0; i < 100; i++) {
+ try { await client.health(); ready = true; break; } catch { await delay(50); }
+ }
+ assert.ok(ready, `Server never became ready: ${stderr}`);
+
+ const result = await client.predict(fixture.state, fixture.questions, { model: 'english' });
+ const { routing, ...prediction } = result;
+ assert.deepEqual(prediction, fixture.expected, 'SDK answers must exactly match direct Python inference');
+ assert.equal(routing.model, 'english');
+ assert.equal(result.answers.single.choice, 'only');
+ assert.equal(result.answers.single.probabilities.only, 1);
+ assert.ok(result.usage.input_tokens > 0);
+ assert.equal(result.usage.output_tokens, 0);
+ assert.equal((await client.predict({ text: 'मुझे पैसे वापस चाहिए' }, fixture.questions)).routing.model, 'multilingual');
+ assert.equal((await client.predict('hello', fixture.questions, { model: 'typed_decisions' })).routing.model, 'typed-decisions');
+ assert.equal((await client.predict('hello', fixture.questions, { model: 'convaiinnovations/laya-multilingual' })).routing.model, 'multilingual');
+ assert.equal((await client.predict('hello', fixture.questions, { model: 'jev-preview' })).routing.model, 'english');
+
+ for (const preset of [triageQuestions, emailQuestions, guardQuestions, moderationQuestions, routerQuestions]) {
+ const questions = preset();
+ const response = await client.predict({ message: 'hello', body: 'hello', prompt: 'hello', post: 'hello', request: 'hello' }, questions);
+ assert.deepEqual(Object.keys(response.answers), Object.keys(questions));
+ }
+ const unauthenticated = new Laya({ baseURL: fixture.baseURL });
+ assert.equal((await unauthenticated.health()).status, 'ok');
+ await assert.rejects(unauthenticated.predict('hello', fixture.questions), error =>
+ error instanceof LayaAPIError && error.status === 401 && error.message === 'invalid or missing bearer token');
+ await assert.rejects(client.predict('x'.repeat(50_001), fixture.questions), error =>
+ error instanceof LayaAPIError && error.status === 413 && error.message.includes('state too large'));
+ assert.equal((await fetch(`${fixture.baseURL}/v1/predict`, { method: 'POST' })).status, 404);
+ assert.equal((await fetch(`${fixture.baseURL}/v1/route`, { method: 'POST' })).status, 404);
+});
diff --git a/sdk/typescript/test/tsconfig.json b/sdk/typescript/test/tsconfig.json
new file mode 100644
index 00000000..d46d3350
--- /dev/null
+++ b/sdk/typescript/test/tsconfig.json
@@ -0,0 +1,5 @@
+{
+ "extends": "../tsconfig.json",
+ "compilerOptions": { "rootDir": "..", "noEmit": true },
+ "include": ["*.ts", "*.cts"]
+}
diff --git a/sdk/typescript/test/types.ts b/sdk/typescript/test/types.ts
new file mode 100644
index 00000000..01105e30
--- /dev/null
+++ b/sdk/typescript/test/types.ts
@@ -0,0 +1,57 @@
+import { Laya, defineQuestions, emailQuestions, triageQuestions, type Questions, type Answer } from '@laya/typescript-sdk';
+
+const client = new Laya();
+const questions = defineQuestions({
+ team: { type: 'choice', instructions: 'Team?', criteria: { billing: null, support: { description: 'help' } } },
+ priority: { type: 'score', instructions: 'Urgency?', criteria: ['low', 'high'] },
+ refund: { type: 'noul', instructions: 'Refund?' },
+ arrayChoice: { type: 'choice', instructions: 'Pick', criteria: ['a', 'b'] },
+});
+const result = await client.predict('Hello', questions);
+const label: 'billing' | 'support' = result.answers.team.choice;
+const arrayLabel: 'a' | 'b' = result.answers.arrayChoice.choice;
+const probability: number = result.answers.team.probabilities.billing;
+const score: number = result.answers.priority.score;
+const noul: number = result.answers.refund.noul;
+const routingModel: string | undefined = result.routing?.model;
+const actionProbability: number | undefined = result.answers.team.action?.act_probability;
+const noulConfidence: number | undefined = result.answers.refund.confidence;
+// @ts-expect-error Jev does not return Laya routing metadata.
+result.routing.model;
+// @ts-expect-error Jev does not return action probabilities.
+result.answers.team.action.act_probability;
+// @ts-expect-error /v1/systemone does not expose standalone routing.
+client.route('hello');
+// @ts-expect-error /v1/systemone supports model, not task.
+client.predict('hello', questions, { task: 'typed' });
+// @ts-expect-error /v1/systemone supports model, not lang.
+client.predict('hello', questions, { lang: 'hi' });
+client.predict('hello', questions, { model: 'jev-preview' });
+new Laya({ model: 'jev-latest' });
+// @ts-expect-error A score answer has no choice field.
+result.answers.priority.choice;
+// @ts-expect-error Unknown question IDs are not valid.
+result.answers.unknown;
+// @ts-expect-error Unknown choice labels are not valid.
+result.answers.team.probabilities.sales;
+// @ts-expect-error Noul criteria must describe true or false.
+defineQuestions({ q: { type: 'noul', instructions: 'test', criteria: { yes: 'yes' } } });
+// @ts-expect-error A choice must have criteria.
+defineQuestions({ q: { type: 'choice', instructions: 'test' } });
+// @ts-expect-error Dates are not JSON state.
+client.predict(new Date(), questions);
+
+const inline = await client.predict('Hi', { q: { type: 'choice', instructions: 'Pick', criteria: ['x', 'y'] } });
+const inlineLabel: 'x' | 'y' = inline.answers.q.choice;
+const preset = await client.predict('Hi', triageQuestions());
+const intent: 'refund' | 'technical_help' | 'billing_question' | 'information' | 'cancellation' | 'other' = preset.answers.intent.choice;
+const custom = await client.predict('Hi', emailQuestions({ finance: 'money', engineering: 'bugs' }));
+const category: 'finance' | 'engineering' = custom.answers.category.choice;
+const dynamic: Questions = questions;
+const answer: Answer | undefined = (await client.predict('Hi', dynamic)).answers.anything;
+if (answer?.type === 'choice') {
+ const dynamicLabel: string = answer.choice;
+ const dynamicProbability: number | undefined = answer.probabilities.anyLabel;
+ void [dynamicLabel, dynamicProbability];
+}
+void [label, arrayLabel, probability, score, noul, inlineLabel, intent, category, routingModel, actionProbability, noulConfidence];
diff --git a/sdk/typescript/tsconfig.cjs.json b/sdk/typescript/tsconfig.cjs.json
new file mode 100644
index 00000000..c9404078
--- /dev/null
+++ b/sdk/typescript/tsconfig.cjs.json
@@ -0,0 +1,9 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "module": "CommonJS",
+ "moduleResolution": "Node",
+ "verbatimModuleSyntax": false,
+ "outDir": "dist/cjs"
+ }
+}
diff --git a/sdk/typescript/tsconfig.json b/sdk/typescript/tsconfig.json
new file mode 100644
index 00000000..3541dee9
--- /dev/null
+++ b/sdk/typescript/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "exactOptionalPropertyTypes": true,
+ "declaration": true,
+ "rootDir": "src",
+ "outDir": "dist/esm",
+ "verbatimModuleSyntax": true
+ },
+ "include": ["src/**/*.ts"]
+}
diff --git a/tests/sdk_server_fixture.py b/tests/sdk_server_fixture.py
new file mode 100644
index 00000000..15a02467
--- /dev/null
+++ b/tests/sdk_server_fixture.py
@@ -0,0 +1,73 @@
+"""Serve a tiny offline checkpoint for the JavaScript integration test, never for production."""
+import json
+import os
+from pathlib import Path
+import socket
+import sys
+import tempfile
+
+os.environ.setdefault("USE_TF", "0")
+os.environ.setdefault("USE_TORCH", "1")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import torch # noqa: E402
+import uvicorn # noqa: E402
+from safetensors.torch import save_file # noqa: E402
+from tokenizers import Tokenizer # noqa: E402
+from tokenizers.models import WordLevel # noqa: E402
+from transformers import BertConfig, BertModel, PreTrainedTokenizerFast # noqa: E402
+from laya import Router, load # noqa: E402
+from laya.common import DecisionModel # noqa: E402
+from laya.serve import create_app # noqa: E402
+
+
+def main():
+ torch.manual_seed(7)
+ torch.set_num_threads(1)
+ with tempfile.TemporaryDirectory(prefix="laya-sdk-test-") as directory:
+ root = Path(directory)
+ cfg = BertConfig(vocab_size=6, hidden_size=64, num_hidden_layers=1,
+ num_attention_heads=2, intermediate_size=128)
+ cfg.save_pretrained(root / "encoder")
+ tokenizer = PreTrainedTokenizerFast(
+ tokenizer_object=Tokenizer(WordLevel(
+ {"[PAD]": 0, "[UNK]": 1, "[CLS]": 2, "[SEP]": 3, "[MASK]": 4, "hello": 5},
+ unk_token="[UNK]")),
+ pad_token="[PAD]", unk_token="[UNK]", cls_token="[CLS]",
+ sep_token="[SEP]", mask_token="[MASK]",
+ )
+ tokenizer.save_pretrained(root / "tokenizer")
+ save_file(DecisionModel(BertModel(cfg), head_layers=1).state_dict(), root / "model.safetensors")
+ (root / "rl_agent_config.json").write_text(json.dumps({
+ "encoder": "unused/offline", "head_layers": 1, "act_costs": {"act": 0},
+ "max_len": 128, "head_max_len": 64,
+ }))
+ agent = load(str(root), device="cpu")
+ questions = {
+ "team": {"type": "choice", "instructions": "Which team?",
+ "criteria": {"billing": {"meaning": "money"}, "technical": None}},
+ "urgency": {"type": "score", "instructions": "Urgency?", "criteria": ["low", "medium", "high"]},
+ "refund": {"type": "noul", "instructions": "Refund?", "criteria": {"true": "yes", "false": "no"}},
+ "single": {"type": "choice", "instructions": "Pick", "criteria": ["only"]},
+ }
+ state = {"text": "hello", "unicode": "नमस्ते", "metadata": {"count": 0, "flag": False}}
+ expected = agent.predict(state, questions)
+ router = Router()
+ # Both routing branches reach the same tiny fixture; this tests transport,
+ # model invocation and numeric parity, not pretrained model quality.
+ for name in ["english", "multilingual", "typed-decisions"]:
+ router.attach(name, agent)
+ os.environ["LAYA_API_KEY"] = "integration-test"
+ app = create_app(router)
+ with socket.socket() as listener:
+ listener.bind(("127.0.0.1", 0))
+ print("LAYA_TEST_SERVER=" + json.dumps({
+ "baseURL": "http://127.0.0.1:%d" % listener.getsockname()[1],
+ "questions": questions, "state": state, "expected": expected,
+ }), flush=True)
+ uvicorn.Server(uvicorn.Config(app, log_level="warning")).run(sockets=[listener])
+
+
+if __name__ == "__main__":
+ main()