@caldrix-ai/caldrix 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Format after [Keep a Changelog](https://keepachangelog.com/); versions are independent semver, tagged
+`caldrix-js-v<version>`.
+
+## 0.1.0 — 2026-10-27
+
+### Added
+
+- The first release, published to npm as `@caldrix-ai/caldrix` (the product is caldrix.js).
+- `Caldrix.load(alias, options)`: loads a model by alias into a dedicated worker and returns an engine
+  with `chat`, `complete` (both async iterables of deltas), `doctor` and `dispose`; `probe()` reports
+  what the browser offers.
+- Two tiers behind one API: the wasm tier (plan dtypes f32 and bf16) and the WebGPU tier (f32 plan, f32
+  or f16 weight storage; f16 has not run in a browser), chosen by `backend: "auto"` from the probe, with the reason in `doctor().why`.
+- Model files from the Hugging Face Hub, digest-checked where the Hub exposes one, cached in the
+  browser; `hubBaseUrl` and `offline` options.
+- `assets` option for where the package's worker and `.wasm` come from, and a jsdelivr fallback for the
+  package's own files at the installed version (on by default; reported in `doctor().assets` and on
+  the console; `assets.fallback: false` turns it off).
+- A same-origin shim so the worker can be served from another origin.
+- Built and driven under Vite 8.3.5 and Next.js 16.4.3 (Turbopack and webpack, `output: "export"`) on the wasm tier, with no bundler configuration.
+- A default context clamp on WebGPU, reported by `doctor()`.
+- Apache-2.0 license for the package, including the compiled browser host it ships, and
+  `THIRD_PARTY_NOTICES.md` for the crates compiled into it.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+caldrix.js (the npm package @caldrix-ai/caldrix)
+Copyright 2026 Jyothsna Muttineni, for Caldrix GmbH (in formation)

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# caldrix.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a language model in the browser, in a worker, on WebGPU or WebAssembly. One package: the engine's
+compiled browser host (WebAssembly), the worker that drives it, and the typed API around them. On npm it
+is [`@caldrix-ai/caldrix`](https://www.npmjs.com/package/@caldrix-ai/caldrix).
+
+This page states only what `inferno/WEB-VERIFICATION.md` records (in
+the Caldrix repository, which is private, so you cannot open it), what the package's own tests run in
+CI, and what the source does.
+
+<!-- host-commit: 16f90f2ef2c3f43cdb9c2520f8d7b573aa13a4d8 -->
+
+The compiled host in `host/` is built from the `caldrix-web` crate at the commit in the marker above.
+The release workflow overwrites that marker with the commit it builds; the value in a source checkout
+is a placeholder.
+
+## Install and quick start
+
+```sh
+npm install @caldrix-ai/caldrix
+```
+
+```ts
+import { Caldrix } from "@caldrix-ai/caldrix";
+
+const engine = await Caldrix.load("smollm2-instruct", {
+  onProgress: ({ file, loaded, total }) => console.log(file, loaded, total),
+});
+
+for await (const delta of engine.chat([{ role: "user", content: "Say hello." }], { maxTokens: 32 })) {
+  if (!delta.done) document.body.append(delta.text);
+}
+
+console.log(engine.doctor());
+engine.dispose();
+```
+
+The API, as the package's declarations have it:
+
+```ts
+class Caldrix {
+  static load(alias: string, opts?: LoadOptions): Promise<Engine>;
+}
+class Engine {
+  chat(messages: ChatMessage[], opts?: GenerateOptions): AsyncIterable<Delta>;
+  complete(input: string | { ids: number[] }, opts?: GenerateOptions): AsyncIterable<Delta>;
+  doctor(): DoctorReport;
+  /** Release the worker and everything in it. Every later call throws `request`. */
+  dispose(): void;
+}
+declare function probe(): Promise<Capabilities>;
+```
+
+A `Delta` is `{ text, token?, done, finishReason?: "stop" | "length" | "abort", usage? }`. Generation
+options are `temperature`, `topK`, `topP`, `minP`, `repetitionPenalty`, `seed` and `maxTokens`, plus a
+`signal` (an `AbortSignal`). Errors are `CaldrixError` with a `kind` of `probe`, `fit`, `architecture`,
+`fetch`, `digest`, `validate`, `lowering`, `backend` or `request`.
+
+## Options
+
+```ts
+interface LoadOptions {
+  backend?: "auto" | "webgpu" | "wasm" | "webgl";
+  offline?: boolean;
+  onProgress?: (p: { file: string; loaded: number; total: number | null }) => void;
+  hubBaseUrl?: string;
+  dtype?: "f32" | "bf16";
+  maxContext?: number;
+  storage?: "auto" | "f32";
+  signal?: AbortSignal;
+  assets?: { worker?: string | URL; hostWasm?: string | URL; fallback?: boolean; cdn?: string | URL };
+}
+```
+
+- **`backend`**: `"auto"` (the default) probes the browser and picks WebGPU when an adapter is present
+  and `requestDevice` succeeds, wasm otherwise; a bf16 plan goes to wasm on the page, before the worker starts. `"webgpu"` and `"wasm"` force a tier. `"webgl"` is declared and refused: the backend is
+  not built. Under `"auto"`, a load WebGPU then refuses (a larger explicit context, a limit, a
+  device that fails to open) is served by the wasm tier, and `doctor().why` says so.
+- **`storage`**: the WebGPU tier's weight storage. `"auto"` stores the block GEMM weights as f16 when the
+  adapter has `shader-f16`; `"f32"` keeps them f32 on any adapter. `doctor().storage` reports it (`null`
+  on wasm). `storage: "f32"` with `backend: "wasm"` is refused.
+- **`hubBaseUrl`**: where model files are fetched from (default `https://huggingface.co`). `offline`
+  uses only the browser's cache and fails with `fetch` for a file it lacks.
+- **`assets`**: where the package's own files come from; see "Network" below.
+- **`doctor()`** reports the tier that runs, `device`, `dtype`, `storage`, `adapter`, on WebGPU only `maxContext` and `contextClamp`, where each model file came from and whether its digest was checked, `assets` (the
+  source and URL of the worker and the `.wasm`: `bundle`, `cdn` or `page`), and `why`.
+
+## What has run, and where
+
+Only these runs are recorded (`inferno/WEB-VERIFICATION.md`, entries 5, 8 and 9); nothing else is claimed.
+
+- **Model:** SmolLM2-135M-Instruct, one prompt, 8 greedy tokens. No other model or prompt.
+- **Browser:** Chromium driven by Playwright, headless only: the headless shell 153.0.8010.12 on Linux and on
+  the operator's Apple M1 Max, and on that Mac Playwright's full Chromium (new headless mode, userAgent
+  `HeadlessChrome/153.0.0.0`) for the WebGPU tier. No other browser.
+- **wasm tier:** both plan dtypes, f32 and bf16, on Linux and on the Mac with the same lines. The tokens
+  equal the references' tokens. The f32 logits stayed inside the 1e-2 bound on every row, worst 7.796401e-4.
+  The bf16 result rests on token equality alone; the logits were recorded, not gated.
+- **WebGPU tier on a real adapter:** the Mac's own, vendor `apple`, architecture `metal-3` (its own
+  strings; `device` and `description` empty), with `shader-f16`. The f32 plan at f32 weight storage,
+  token-exact, logits worst 6.6792103e-4 against the same 1e-2 bound; at f16 weight storage, a diagnostic
+  gated by no bound, every row finite, worst 5.0272985e-4, token-exact. The product path's tokens equal the
+  test worker's at both storage forms.
+- **WebGPU tier on SwiftShader:** Dawn on SwiftShader, Google's CPU Vulkan implementation, which is a CPU and
+  not a GPU. The f32 plan at f32 weight storage, token-exact, logits worst 5.874168e-4 against the same bound.
+- **Phase 2's exit is closed on the gates** (entry 9), with the run's two process deviations recorded there:
+  the browser stages ran outside the sandbox, and the build's first attempt failed at its install step.
+- **Not run:** any other adapter or GPU; a headed browser; the browser stages inside a sandbox; the scalar
+  (non-SIMD) wasm spelling in a browser; real-Hub digest behaviour (the runs used a loopback Hub stand-in);
+  any browser other than Playwright's headless Chromium; any other model. No performance figure is recorded
+  or claimed.
+
+## The WebGPU default context
+
+Without `maxContext`, the WebGPU tier clamps the context so the attention kernel's grid stays within
+`maxComputeWorkgroupsPerDimension`. At the standard 65535 workgroups per dimension, SmolLM2's 8192
+default context loads at 7282; `doctor()` reports the clamp in `contextClamp` and the value in
+`maxContext`. A larger `maxContext` that the adapter's limits cannot hold is refused by WebGPU, and
+`"auto"` then serves the load on wasm.
+
+## Network
+
+No telemetry. The network is the Hub, for the model files you asked for, and jsdelivr, for the
+package's own assets when the bundle's copy fails.
+
+- **When the fallback fires:** the worker falls back if it fails before it is ready (its script, a chunk
+  or the host glue did not load, or the page refused to construct it); the `.wasm` falls back, inside
+  the worker, if its fetch fails. Each asset is tried locally first and falls back independently.
+- **What it fetches:** `https://cdn.jsdelivr.net/npm/@caldrix-ai/caldrix@<installed version>/dist/worker.js` and
+  `.../host/caldrix_web_bg.wasm`, at the version you installed, so the `.wasm` matches the glue.
+- **It is never silent:** it is warned once per load on the console, and `doctor().assets` reports the
+  source and URL of each asset.
+- **Opt out:** `assets: { fallback: false }`. An explicit `assets.worker` or `assets.hostWasm` is used as
+  given, with no fallback for that asset. `assets.cdn` points the fallback at your own mirror.
+- **What it trusts:** the fallback runs jsdelivr's copy of that version with your page's origin (the
+  worker can fetch your origin with its credentials and read its IndexedDB and caches), and no integrity
+  check is possible for a worker's module import, so a page that cannot accept that sets
+  `assets.fallback: false`.
+- **Not yet exercised:** until the package is on npm, the real jsdelivr path has not run; the tests point
+  `assets.cdn` at a loopback origin.
+- **Content-Security-Policy:** a page that uses the fallback needs `worker-src blob:` (a cross-origin
+  worker starts through a same-origin module shim), `script-src` and `connect-src` for the CDN origin,
+  and `'wasm-unsafe-eval'` for any WebAssembly.
+
+## Bundlers
+
+What ran: Vite 8.3.5 and Next.js 16.4.3 (Turbopack and webpack) with `output: "export"`, a minimal app
+each, on the wasm tier with a tiny Llama fixture served from a loopback Hub, in headless Chromium. The
+package's own bundler test (`tests/bundlers/`) installs the packed tarball into those apps and runs in
+CI. Those apps needed no bundler configuration. Nothing else is claimed: other versions, other bundlers
+and the WebGPU tier under a bundler have not been run. Production builds only (`vite build`, `next build`);
+`vite dev` and `next dev` were not run. Notes:
+
+- Each app ships an unused copy of the worker, about 16 kB, and (Next only) an unused copy of the host
+  glue, about 13.5 kB. The worker copy comes from the package's `new URL("./worker.js", import.meta.url)`
+  literal, which it keeps so bundlers find the worker; the glue copy comes from wasm-bindgen's own
+  `.wasm` URL literal inside the glue, which the package does not control.
+- By the package's design, not run: with assets on another origin (Vite `base`, Next `assetPrefix`) the
+  bundle try is cross-origin, the shim imports the raw copy of the worker whose `../host/` is not beside
+  it, and every load falls back to jsdelivr. Set `assets.worker` and `assets.hostWasm` instead, serving
+  `dist/` and `host/` together on that origin.
+- Next pages that import the package are client components.
+
+## Releases and provenance
+
+Versions are independent semver; releases are tagged `caldrix-js-v0.x.y` and the tag must equal the
+version in `package.json`. There is no npm provenance: the source repository is private, and npm does not
+generate provenance for a private repository. Publishes are staged by a limited token and released by
+hand with 2FA: the release workflow's token can only stage a version (npm's "stage only" access), and
+a staged version goes live only when the owner approves it on npmjs.com with two-factor
+authentication. The tarball carries no sourcemaps.
+
+## License
+
+The npm package `@caldrix-ai/caldrix` (caldrix.js) is under Apache-2.0 (`LICENSE`, `NOTICE`). The compiler itself is not open source; this package ships its compiled
+browser host (`host/`) under this license. Third-party components compiled into the host remain under
+their own licenses; see `THIRD_PARTY_NOTICES.md`.