From bc1ef24308780146743b8cdfb1c6df4bf95c6626 Mon Sep 17 00:00:00 2001 From: BaniNaveen Date: Thu, 24 Sep 2026 15:47:16 +0530 Subject: [PATCH 1/3] feat(sdk): add typed client for Laya and Jev systemone --- .github/workflows/ci.yml | 34 +++ .gitignore | 3 + README.md | 24 ++ docs/typescript-sdk.md | 72 ++++++ sdk/typescript/LICENSE | 176 ++++++++++++++ sdk/typescript/README.md | 305 +++++++++++++++++++++++++ sdk/typescript/examples/benchmark.ts | 47 ++++ sdk/typescript/examples/triage.mjs | 19 ++ sdk/typescript/package-lock.json | 33 +++ sdk/typescript/package.json | 37 +++ sdk/typescript/scripts/build.mjs | 9 + sdk/typescript/scripts/sync_presets.py | 42 ++++ sdk/typescript/src/client.ts | 133 +++++++++++ sdk/typescript/src/errors.ts | 26 +++ sdk/typescript/src/index.ts | 5 + sdk/typescript/src/presets.ts | 203 ++++++++++++++++ sdk/typescript/src/response.ts | 60 +++++ sdk/typescript/src/types.ts | 101 ++++++++ sdk/typescript/src/validation.ts | 69 ++++++ sdk/typescript/test/client.test.mjs | 230 +++++++++++++++++++ sdk/typescript/test/commonjs.cts | 11 + sdk/typescript/test/integration.mjs | 70 ++++++ sdk/typescript/test/tsconfig.json | 5 + sdk/typescript/test/types.ts | 57 +++++ sdk/typescript/tsconfig.cjs.json | 9 + sdk/typescript/tsconfig.json | 16 ++ tests/sdk_server_fixture.py | 73 ++++++ 27 files changed, 1869 insertions(+) create mode 100644 docs/typescript-sdk.md create mode 100644 sdk/typescript/LICENSE create mode 100644 sdk/typescript/README.md create mode 100644 sdk/typescript/examples/benchmark.ts create mode 100644 sdk/typescript/examples/triage.mjs create mode 100644 sdk/typescript/package-lock.json create mode 100644 sdk/typescript/package.json create mode 100644 sdk/typescript/scripts/build.mjs create mode 100644 sdk/typescript/scripts/sync_presets.py create mode 100644 sdk/typescript/src/client.ts create mode 100644 sdk/typescript/src/errors.ts create mode 100644 sdk/typescript/src/index.ts create mode 100644 sdk/typescript/src/presets.ts create mode 100644 sdk/typescript/src/response.ts create mode 100644 sdk/typescript/src/types.ts create mode 100644 sdk/typescript/src/validation.ts create mode 100644 sdk/typescript/test/client.test.mjs create mode 100644 sdk/typescript/test/commonjs.cts create mode 100644 sdk/typescript/test/integration.mjs create mode 100644 sdk/typescript/test/tsconfig.json create mode 100644 sdk/typescript/test/types.ts create mode 100644 sdk/typescript/tsconfig.cjs.json create mode 100644 sdk/typescript/tsconfig.json create mode 100644 tests/sdk_server_fixture.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 11818be5d..e8ef1a3bc 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 3d264b236..f9cf84d09 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 0560d3e6d..31700bf85 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 000000000..5f1ebecce --- /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 000000000..d9a10c0d8 --- /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 000000000..69588710d --- /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 000000000..e0b1a7836 --- /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 000000000..17ea14d9b --- /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 000000000..61d00b16f --- /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 000000000..6fcc7de73 --- /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 000000000..288cf7ed4 --- /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 000000000..b9793fc0e --- /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>>(categories: C): + Omit & { category: Omit & { criteria: C } }; +export function emailQuestions(categories?: Readonly>) { + 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 000000000..93547b0b0 --- /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(state: State, questions: Q, options: PredictOptions = {}): Promise> { + validateQuestions(questions); + const result = await this.request>('/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 { + const result = await this.request('/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(path: string, body: string | undefined, options: RequestOptions): Promise { + 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 000000000..ce3df228b --- /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 000000000..6f8449f81 --- /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 000000000..1913aa2e9 --- /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>>(categories: C): + Omit & { category: Omit & { criteria: C } }; +export function emailQuestions(categories?: Readonly>) { + 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 000000000..4092b8589 --- /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 000000000..038919199 --- /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>; +} +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>; +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