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.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat(sdk): add typed client for Laya and Jev systemone
BaniNaveenbc1ef2430878
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 11818be5..e8ef1a3b 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -244,6 +244,40 @@ jobs:- name: Byte-compile every modulerun: 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: packageruns-on: ubuntu-latestdiff --git a/.gitignore b/.gitignoreindex 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.pypircdiff --git a/README.md b/README.mdindex 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.mdnew file mode 100644index 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/LICENSEnew file mode 100644index 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 CONDITIONSdiff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdnew file mode 100644index 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.pynew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.ctsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.pynew file mode 100644index 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()