Skip to content

feat(sdk): add TypeScript SDK - #198

Merged
NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
baninaveen:typescript-sdk
Sep 29, 2026
Merged

NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
baninaveen:typescript-sdk

Conversation

@baninaveen

@baninaveen baninaveen commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Adds @laya/typescript-sdk, a typed JavaScript/TypeScript HTTP client for the existing Jev-compatible POST /v1/systemone server from #31. Applications can use the same prediction API against self-hosted Laya or Jev by changing baseURL and credentials. This PR adds no Python production code or changes to the server dependencies.

The SDK ships ESM, CommonJS, and declarations with zero runtime dependencies. It infers answer types and choice labels, includes all five generated presets, and provides input/response validation, typed errors, timeouts, and cancellation.

Protocol and scope

  • predict() sends {state, questions, model} to /v1/systemone. The default jev-latest works as a Jev model alias and lets Laya auto-route; client-wide and per-request model overrides are supported.
  • Choice-label arrays are serialized as maps. Laya-only routing/action metadata and Noul confidence are optional, so documented Jev responses are accepted.
  • health() uses Laya's existing {status, loaded, device} probe. Standalone route(), task, and lang options are excluded because the shared HTTP endpoint does not expose them.
  • FastAPI {detail: ...} errors preserve their HTTP status, message, and validation details.
  • Documentation, examples, and Node.js 22/24 CI use the existing serve extra and environment-variable server configuration. The only Python additions are development/test helpers for generated presets and offline integration.

Try locally

At the repository root:

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

See the SDK guide for typed questions, Jev configuration, and publishing.

Validation

  • npm test: 18 client tests plus TypeScript and ESM/CommonJS checks passed.
  • Live SDK-to-laya.serve integration passed using a tiny offline PyTorch checkpoint; answers match direct Python inference, and tests cover presets, routing, authentication, and request limits.
  • pytest tests/test_serve.py: 22 tests passed.
  • Generated preset consistency, Ruff, Python byte compilation, TypeScript benchmark compilation, npm pack dry-run, and whitespace checks passed.

Jev compatibility is tested with fixtures based on its official API contract; no live Jev request was made. The npm package is configured as @laya/typescript-sdk@0.1.0 and has not been published. These checks verify transport and compatibility, not pretrained model quality or performance.

@NandhaKishorM

Copy link
Copy Markdown
Owner

Thank you for the substantial work, a typed SDK with no runtime dependencies is really nice. One direction question before review. #31 landed today as the repo's server, speaking the Jev-compatible /v1/systemone, so existing TypeSafe clients work by changing baseUrl. Could the SDK target that endpoint instead of a separate /v1/predict server? Then the Python side of this PR would mostly disappear, and the SDK becomes a Laya client that also works against Jev.

@baninaveen

Copy link
Copy Markdown
Contributor Author

@NandhaKishorM
Thanks, that makes sense. I’ll rebase onto the server from #31, target /v1/systemone, and remove the separate Python server from this PR.

I’ll keep the typed API and zero runtime dependencies, align request/response handling with the shared protocol, and update the tests and examples. I’ll also check compatibility with Jev before documenting support through a baseURL change.

@baninaveen baninaveen changed the title feat: add TypeScript SDK and optional HTTP inference server feat(sdk): add typed client for Laya and Jev System One API Sep 24, 2026
@baninaveen baninaveen changed the title feat(sdk): add typed client for Laya and Jev System One API feat(sdk): add TypeScript SDK Sep 24, 2026
@NandhaKishorM

Copy link
Copy Markdown
Owner

Thank you for reworking this so quickly. Targeting /v1/systemone and dropping the separate server is exactly what we hoped for, and the zero-dependency typed client with a live test against laya-serve is lovely. The open-source repo stays focused on local, self-hosted inference, so please remove the hosted-service parts: the TypeSafe base URL, API key and model examples, the docs.typesafe.ai links, the Jev API box in the diagram, and the jev-latest default (leave model unset so laya-serve auto-routes). Please also add a sentence on when to use this client versus laya-ts, drop examples/benchmark.ts, and use a package name we control, for example laya-client, rather than the @laya scope. With those changes it is ready for a final review.

@NandhaKishorM

Copy link
Copy Markdown
Owner

Thank you for such a thorough rework, every hosted piece is gone, model is unset by default, and the live test against laya-serve plus the zero-dependency build make this a really solid client. Two small things: please revert the edits to the existing 'Self-Hosting: HTTP Server' section of the main README and keep only your new JavaScript / TypeScript subsection. That keeps the PR focused, and the heading rename currently breaks the link from sdk/typescript/README.md to #self-hosting-http-server-jev-compatible. Please also change 'is published as laya-client' in docs/typescript-sdk.md to say it will be published under that name, since it is not on npm yet. With those two fixes it is ready.

@baninaveen

Copy link
Copy Markdown
Contributor Author

@NandhaKishorM I’ve made the changes. Could you please take a look and let me know if anything else needs to be updated?

@baninaveen

Copy link
Copy Markdown
Contributor Author

Hi @NandhaKishorM Is there anything else I need to check on this PR

@NandhaKishorM
NandhaKishorM merged commit ab0e4e4 into NandhaKishorM:main Sep 29, 2026
@NandhaKishorM

Copy link
Copy Markdown
Owner

Passed checks and merged. Thank you @baninaveen! It ships in 0.3.22.

@baninaveen

Copy link
Copy Markdown
Contributor Author

Thank you so much @NandhaKishorM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants