@ai-ecoverse/kev.js 0.1.0

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 2026 Jared Palmer
+
+   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/README.md

@@ -0,0 +1,171 @@
+# @ai-ecoverse/kev.js
+
+[Kev](https://github.com/jaredpalmer/kev) decision models running in the browser on WebGPU (or WASM), with the same
+TypeSafe System One request and response shapes as `kev.serve`. No server: the model, tokenizer and pointer head
+run in a Web Worker.
+
+**[Homepage and live demo](https://ai-ecoverse.github.io/kev.js/)** · **[Weights](https://huggingface.co/ai-ecoverse/kev.js)** · `npm install @ai-ecoverse/kev.js onnxruntime-web`
+
+![kev.js demo](docs/demo.png)
+
+```ts
+import * as ort from "onnxruntime-web/webgpu";
+import { loadKev } from "@ai-ecoverse/kev.js";
+
+const kev = await loadKev("https://huggingface.co/ai-ecoverse/kev.js/resolve/main/kev-0.8b", { ort, variant: "q8f32" });
+const res = await kev.systemOne({
+  state: "I was charged twice. Please fix this ASAP.",
+  questions: {
+    billing: { type: "noul", instructions: "Is this ticket about billing?" },
+    urgency: { type: "score", instructions: "How urgent is this ticket?", criteria: ["can wait", "this week", "today"] },
+  },
+});
+// Kev-0.8B (kev-0.8b@2256796):
+res.answers.billing.noul;    // 1.0    probability of yes, rounded to 2 places like kev.serve
+res.answers.urgency.score;   // 1.77   expected level: mostly "today"
+```
+
+## Results
+
+Measured in Chrome on an Apple M4 Max (WebGPU on Metal), against the fp32 PyTorch model (`kev.evaluate.load`) at the
+same commit. Each fp32 ONNX export matches PyTorch to 1e-4 or better, so the 300-record comparisons use it as the
+reference. The 300 records are held-out transfer-v4 development data (sources Kev was not trained on).
+
+| Model (pinned checkpoint) | Download | Accuracy, browser / reference | Brier, browser / reference | Mean / max \|Δp\| (300 records) | Answers changed | 3-question request |
+|---|---|---|---|---|---|---|
+| Kev-0.8B `q8f32` (`kev-0.8b@2256796`) | 822 MB | 0.660 / 0.657 | 0.475 / 0.472 | 0.0063 / 0.085 | 3 / 300 | 108 ms |
+| Kev-0.8B `q8` (int8, fp16 activations) | 788 MB | 0.663 / 0.657 | 0.476 / 0.472 | 0.0073 / 0.087 | 4 / 300 | 115 ms |
+| Kev-4B `q8f32` (`kev-4b@4bc64c6`) | 4.7 GB | 0.773 / 0.773 | 0.324 / 0.324 | 0.0028 / 0.075 | 0 / 300 | 360 ms |
+| Kev-9B `q8f32` (`kev-9b@442e597`) | 8.8 GB | 0.800 / 0.800 | 0.318 / 0.318 | 0.0033 / 0.160 | 0 / 300 | 570 ms |
+
+Kev's own PyTorch server takes 329 ms (Kev-0.8B), 779 ms (Kev-4B) and about 2 s (Kev-9B) for a comparable request
+on an M5 with MPS, which has no fast DeltaNet kernels. Kev-9B needs a GPU with roughly 9 GB free for its weights,
+and some browsers cap one origin's Cache Storage below that; the loader then runs uncached and downloads again next
+time. The WASM (CPU) fallback is roughly 5× slower than WebGPU. The largest
+deviations come from near-ties, where the reference itself is split close to 50/50.
+
+`q8f32` (int8 weights, fp32 activations) is the default everywhere. int4 is not usable: at 0.8B, round-to-nearest,
+k-quant, block size 16, and int8 for the linear-attention layers all moved probabilities by 0.24–0.78 and flipped
+1–8 of 49 answers, and at 4B int4 moved them by 0.31–0.37 with 3 of 29 flipped. For a model whose output is a
+calibrated probability that is disqualifying. `export/build.sh` lists the variants that were tried.
+
+### Checkpoint revisions
+
+Kev's checkpoints are republished under the same Hub ids (all three were updated on 2026-09-21), so everything
+here is pinned to a commit. `kev_web_export.pin` resolves `jaredpalmer/kev-4b` to `jaredpalmer/kev-4b@<sha>`. The
+merge, the fixtures and the reference sets record it, and `package.py` refuses to combine fixtures and weights
+from different commits. Each bundle's `manifest.json` names its revision (`run`), and its files live under
+`r-<sha>/`. Publishing a new checkpoint therefore never overwrites a file an older manifest points at: the switch is
+the single commit that replaces `manifest.json`, and browsers key their cache by that revision.
+
+## How It Works
+
+Kev is a Qwen3.5 base, a rank-16 LoRA and a small pointer head. The head scores each option's `</opt>` hidden state
+against the question's `<decide>` hidden state. Nothing is generated, so one forward pass is the whole job.
+
+Qwen3.5 mixes Gated DeltaNet (recurrent) layers with full attention, so Kev serves hybrid models in rows. The state
+runs once, and each question runs as a continuation of the state's cache
+(`kev.model._branch_rows_from_prefix`). That maps directly onto an ordinary exported decoder with a KV cache,
+with no custom attention mask:
+
+1. **Merge** (`kev_web_export.merge`): fold the LoRA into the base in fp32 (exact), write a
+   `Qwen3_5ForConditionalGeneration` checkpoint, the head (`head.safetensors`) and `kev.json`.
+2. **Build** (`export/build.sh`): the onnxruntime-genai model builder with `exclude_lm_head=true` outputs
+   `hidden_states` after the final norm. It emits `LinearAttention`, `CausalConvWithState`,
+   `LinearAttentionGate`, `GatedRMSNorm`, `MRotaryEmbedding` and `GroupQueryAttention`, all of which have WebGPU
+   kernels in onnxruntime-web 1.30 (`onnxruntime-web/webgpu`, the native WebGPU EP). 667 of 675 nodes run on
+   WebGPU; the other 8 are shape ops.
+3. **Post-process** (`kev_web_export.postprocess`): the builder can only quantize embeddings to int4. The
+   embedding table (0.5 GB fp16 for 0.8B, 2.5 GB fp32 for 4B) becomes int8 with one scale per row, using plain
+   `Gather`/`Cast`/`Mul`. The rotary caches are trimmed from 262k positions to 8,192, which is `kev.serve`'s limit.
+   External weights are split into files of at most 32 MB (`--shard-mb`): proxies and CDNs cap response bodies (bb
+   connect cuts one at 34.5 MiB), a failed file is cheap to retry, and browsers cap a single buffer near 2 GB. A
+   single tensor larger than that keeps its own file — Kev-9B's MLP matrices are 50 MB each — which Hugging Face
+   serves fine but a capped proxy would not. An
+   embedding table is one tensor of hundreds of MB and an ONNX initializer cannot span files, so it is stored as
+   column slices that are gathered separately and concatenated — bit-identical, and every file stays small.
+4. **Package** (`kev_web_export.package`): `manifest.json` (I/O names, empty-cache shapes, parity), tokenizer,
+   head and one directory per variant.
+
+The runtime (`src/`) is a port of `kev/api.py` and `kev/model.py`. `render`, `to_record`, `to_answers`,
+`encode` and the delimiter escaping are reproduced exactly, including Python's `str()` formatting (`True`,
+`1e-07`). On WebGPU the state's recurrent, conv and KV caches stay on the GPU (`gpu-buffer`) and are reused by
+every question, and by later requests with the same state (LRU of 4, as in `kev.serve`).
+
+## Quick Start
+
+Using the library needs nothing but `npm install @ai-ecoverse/kev.js onnxruntime-web` and the published weights.
+Building the weights yourself needs Python 3.12 with [uv](https://docs.astral.sh/uv/) and a lot of disk (Kev-0.8B
+about 20 GB, Kev-4B about 45 GB, Kev-9B about 85 GB at peak):
+
+```bash
+git clone --recursive https://github.com/ai-ecoverse/kev.js && cd kev.js
+cd export && uv sync
+./build_model.sh kev-0.8b                  # or kev-4b, kev-9b; optionally a pinned run: jaredpalmer/kev-4b@<sha>
+cd .. && npm install && npm run dev        # http://127.0.0.1:5173, serving public/models
+```
+
+`build_model.sh` pins the checkpoint, merges the LoRA in fp32, builds the int8 WebGPU graph, shards it, builds the
+fp32 reference, writes the PyTorch fixtures and the 300-record reference set, measures parity and packages the bundle
+into `public/models/<name>`. On macOS the onnxruntime-genai builder can abort with `recursive_mutex lock failed`
+after it has written everything, so `build.sh` checks for `genai_config.json` instead of the exit code.
+
+### Publishing
+
+```bash
+HF_TOKEN=... uv run python -m kev_web_export.upload_hf --repo ai-ecoverse/kev.js   # weights + model card
+npm run build:lib                                                                 # dist/ for npm (tsc)
+npm run build:demo                                                                # homepage (PAGES_BASE=/kev.js/ in CI)
+```
+
+`.github/workflows` builds the homepage to GitHub Pages on every push to `main`, runs the tests that need no
+weights, and publishes the npm package from a `v*` tag with trusted publishing (OIDC, no token). The demo loads
+weights from Hugging Face unless `VITE_MODEL_BASE` or `?models=<url>` says otherwise; `npm run dev` serves
+`public/models` instead. GitHub Pages cannot set COOP/COEP headers, so `crossOriginIsolated` is false there and the
+WASM fallback runs single-threaded; WebGPU is unaffected.
+
+`kev.systemOne(req, { onAnswer })` reports each question as it finishes, so a UI can fill answers in as they land.
+`kev.systemOneSeparate()` answers each question in its own pass. `kev.probs(record)` returns raw probabilities.
+Weight files are cached in Cache Storage (`kev-web-v1`). In the demo page, `window.kev.systemOne(...)` works from
+the console, and `?verbose` logs where onnxruntime placed each node.
+
+## Testing
+
+```bash
+npm test                                   # rendering, tokenization and encoding parity; full runtime on onnxruntime-node
+KEV_VARIANTS=fp32 npm test                 # just the exact variant
+KEV_MODEL=kev-4b npm test                  # fixtures/kev-4b.json against public/models/kev-4b
+cd export && uv run python -m kev_web_export.parity --model build/kev-0.8b/web-q8f32/model.onnx \
+    --head build/kev-0.8b/head.safetensors --fixtures ../fixtures/kev-0.8b.json
+```
+
+`scripts/cdp.mjs` drives a page in a Chrome started with `--remote-debugging-port=9222`, for checking the demo in a
+real browser: `node scripts/cdp.mjs '<expression>'` evaluates in the tab (`MATCH=` picks it by URL), and
+`node scripts/cdp.mjs --shot out.png` screenshots it.
+
+- `fixtures/kev-0.8b.json`: 43 records (3 hand-written, including structured state and delimiter injection, plus
+  40 from transfer-v4 dev) with the rendered record, Kev's token encoding and the PyTorch probabilities.
+  Regenerate with `kev_web_export.fixtures`.
+- `fixtures/kev-4b.json`: the same 3 hand-written records plus 20 dev records, for Kev-4B.
+- `fixtures/kev-*-transfer-v4-dev300.json`: 300 labelled records with fp32 reference probabilities
+  (`kev_web_export.evalset`), used for the browser accuracy and Brier comparisons above.
+
+## Limitations
+
+- JSON parsing loses two things Kev's Python server keeps. `1.0` arrives as `1` and is rendered `1`, where Python
+  renders `1.0`. Object keys that look like integers (`"10"`, `"2"`) are iterated in numeric order, which can
+  reorder Choice options with numeric names.
+- The first load downloads 822 MB for Kev-0.8B, or 4.7 GB for Kev-4B, and the files stay in Cache Storage. Serve
+  them from a fast origin: over a tunnel at ~1.2 MB/s, Kev-0.8B takes 11 minutes. More parallel requests do not
+  help on a bandwidth-limited link (measured: 1.2 MB/s with one stream, 0.75 MB/s across six), so the loader
+  fetches 2 files at a time.
+  Kev-4B needs a GPU with enough memory for about 4.5 GB of weights. Only Chrome was tested; Safari and Firefox
+  WebGPU are untested.
+- Kev-9B is not packaged. At int8 it would be about 10 GB.
+- onnxruntime-node 1.30 on Node 24+ reads 0 bytes from `Float16Array` float16 tensors, so the tests hide
+  `Float16Array` (`test/no-float16.ts`). Browsers are not affected.
+- Requests run one at a time per model instance.
+
+## License
+
+Apache-2.0, like Kev and the Qwen3.5 weights. Kev itself is vendored as a pinned submodule (`vendor/kev`).

package/dist/api.d.ts

@@ -0,0 +1,97 @@
+export type JSONContent = string | number | boolean | null | JSONContent[] | {
+    [key: string]: JSONContent;
+};
+export interface NoulQuestion {
+    type: "noul";
+    instructions: JSONContent;
+    criteria?: {
+        true?: JSONContent;
+        false?: JSONContent;
+    } | null;
+}
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: JSONContent;
+    criteria: Record<string, JSONContent>;
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions: JSONContent;
+    criteria: JSONContent[];
+}
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+export interface SystemOneRequest {
+    state: JSONContent;
+    model?: string;
+    questions: Record<string, Question>;
+}
+export interface NoulAnswer {
+    type: "noul";
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+}
+export interface ScoreAnswer {
+    type: "score";
+    score: number;
+    legend: Record<string, string>;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface SystemOneResponse {
+    model: string;
+    answers: Record<string, Answer>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    latency_ms: number;
+}
+/** Internal record consumed by encode(): rendered state and, per question, instruction + option texts. */
+export interface DecisionRecord {
+    state: string;
+    questions: {
+        instr: string;
+        options: string[];
+    }[];
+}
+export type QuestionMeta = {
+    id: string;
+    type: "noul";
+} | {
+    id: string;
+    type: "choice";
+    keys: string[];
+} | {
+    id: string;
+    type: "score";
+    legend: Record<string, string>;
+};
+export declare const MAX_OPTIONS = 255;
+export declare class ValidationError extends Error {
+    status: number;
+}
+export declare function validate(req: unknown): SystemOneRequest;
+/** Python's repr(float): shortest round-trip digits, exponent form below 1e-4 and from 1e16. */
+export declare function pyFloat(x: number): string;
+/** Flatten str | object | array into the text the model sees. Field names are kept as labels. */
+export declare function render(v: JSONContent | undefined, indent?: number): string;
+export declare function optionText(name: string, desc: JSONContent | undefined): string;
+export declare function toRecord(req: SystemOneRequest): {
+    record: DecisionRecord;
+    meta: QuestionMeta[];
+};
+export declare function choiceConfidence(p: number[]): number;
+/** Approximation of TypeSafe's 'distance from the modal level' statistic: 1 - E|level - mode| / (L - 1). */
+export declare function scoreConfidence(p: number[]): number;
+/** Python round(x, 2): nearest, exact ties to even. */
+export declare function r2(x: number): number;
+export declare function toAnswers(probs: number[][], meta: QuestionMeta[]): Record<string, Answer>;
+/** Python json.dumps (default separators, ensure_ascii). Every number in an answer is a Python float. */
+export declare function pyJsonDumps(v: unknown): string;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -0,0 +1,166 @@
+// TypeSafe System One request/response shapes mapped onto Kev's pointer primitive (port of kev/api.py).
+//
+// Noul   -> 2 options [no, yes];                answer = p(yes)
+// Choice -> options 'name' or 'name: desc';     answer = argmax, probabilities by name, confidence
+// Score  -> options = ordered level descriptions; answer = expected level, legend, probabilities by index
+//
+// Kev renders JSON content with Python's str(), so the text the model sees depends on Python formatting rules
+// (True/False, float repr). Those are reproduced here so browser and server feed the model identical text.
+export const MAX_OPTIONS = 255;
+export class ValidationError extends Error {
+    status = 422;
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function validate(req) {
+    if (!isObject(req))
+        throw new ValidationError("request must be an object");
+    if (!("state" in req))
+        throw new ValidationError("state is required");
+    if (!isObject(req.questions) || Object.keys(req.questions).length < 1)
+        throw new ValidationError("questions must have at least 1 entry");
+    for (const [id, q] of Object.entries(req.questions)) {
+        if (!isObject(q))
+            throw new ValidationError(`questions.${id} must be an object`);
+        if (!("instructions" in q))
+            throw new ValidationError(`questions.${id}.instructions is required`);
+        if (q.type === "noul") {
+            if (q.criteria != null && !isObject(q.criteria))
+                throw new ValidationError(`questions.${id}.criteria must be an object`);
+        }
+        else if (q.type === "choice") {
+            if (!isObject(q.criteria))
+                throw new ValidationError(`questions.${id}.criteria must be an object`);
+            const n = Object.keys(q.criteria).length;
+            if (n < 1 || n > MAX_OPTIONS)
+                throw new ValidationError(`criteria must have 1..${MAX_OPTIONS} options`);
+        }
+        else if (q.type === "score") {
+            if (!Array.isArray(q.criteria) || q.criteria.length < 2 || q.criteria.length > MAX_OPTIONS)
+                throw new ValidationError(`questions.${id}.criteria must be a list of 2..${MAX_OPTIONS} levels`);
+        }
+        else {
+            throw new ValidationError(`questions.${id}.type must be noul, choice or score`);
+        }
+    }
+    return req;
+}
+/** Python's repr(float): shortest round-trip digits, exponent form below 1e-4 and from 1e16. */
+export function pyFloat(x) {
+    if (Number.isNaN(x))
+        return "nan";
+    if (!Number.isFinite(x))
+        return x > 0 ? "inf" : "-inf";
+    if (x === 0)
+        return Object.is(x, -0) ? "-0.0" : "0.0";
+    const sign = x < 0 ? "-" : "";
+    const [mant, expS] = Math.abs(x).toExponential().split("e");
+    const exp = parseInt(expS, 10);
+    const digits = mant.replace(".", "");
+    if (exp < -4 || exp >= 16) {
+        const m = digits.length > 1 ? `${digits[0]}.${digits.slice(1)}` : digits;
+        return `${sign}${m}e${exp < 0 ? "-" : "+"}${String(Math.abs(exp)).padStart(2, "0")}`;
+    }
+    if (exp >= 0)
+        return `${sign}${digits.slice(0, exp + 1).padEnd(exp + 1, "0")}.${digits.slice(exp + 1) || "0"}`;
+    return `${sign}0.${"0".repeat(-exp - 1)}${digits}`;
+}
+/** Python's str() for JSON scalars. JSON cannot tell 1 from 1.0 once parsed, so integral numbers print as ints. */
+function pyStr(v) {
+    if (typeof v === "boolean")
+        return v ? "True" : "False";
+    if (typeof v === "number")
+        return Number.isInteger(v) && Math.abs(v) < 1e21 ? String(v) : pyFloat(v);
+    return v;
+}
+/** Flatten str | object | array into the text the model sees. Field names are kept as labels. */
+export function render(v, indent = 0) {
+    const pad = "  ".repeat(indent);
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v !== "object")
+        return pyStr(v);
+    if (Array.isArray(v))
+        return v.map((x) => `${pad}- ${render(x, indent + 1).trimStart()}`).join("\n");
+    return Object.entries(v)
+        .map(([k, x]) => (typeof x === "object" && x !== null ? `${pad}${k}:\n${render(x, indent + 1)}` : `${pad}${k}: ${render(x)}`))
+        .join("\n");
+}
+export function optionText(name, desc) {
+    return desc === null || desc === undefined || desc === "" ? name : `${name}: ${render(desc)}`;
+}
+export function toRecord(req) {
+    const questions = [];
+    const meta = [];
+    for (const [id, q] of Object.entries(req.questions)) {
+        const instr = render(q.instructions);
+        let options;
+        if (q.type === "noul") {
+            const c = q.criteria ?? {};
+            options = [optionText("no", c.false), optionText("yes", c.true)];
+            meta.push({ id, type: "noul" });
+        }
+        else if (q.type === "choice") {
+            options = Object.entries(q.criteria).map(([k, v]) => optionText(k, v));
+            meta.push({ id, type: "choice", keys: Object.keys(q.criteria) });
+        }
+        else {
+            options = q.criteria.map((x) => render(x));
+            meta.push({ id, type: "score", legend: Object.fromEntries(q.criteria.map((x, i) => [String(i), render(x)])) });
+        }
+        questions.push({ instr, options });
+    }
+    return { record: { state: render(req.state), questions }, meta };
+}
+const argmax = (p) => p.reduce((best, v, i) => (v > p[best] ? i : best), 0);
+export function choiceConfidence(p) {
+    const K = p.length;
+    return K === 1 ? 1 : (Math.max(...p) - 1 / K) / (1 - 1 / K);
+}
+/** Approximation of TypeSafe's 'distance from the modal level' statistic: 1 - E|level - mode| / (L - 1). */
+export function scoreConfidence(p) {
+    const mode = argmax(p);
+    return 1 - p.reduce((s, pi, i) => s + pi * Math.abs(i - mode), 0) / (p.length - 1);
+}
+/** Python round(x, 2): nearest, exact ties to even. */
+export function r2(x) {
+    const t = x * 100;
+    if (Number.isInteger(t * 2) && !Number.isInteger(t)) {
+        const f = Math.floor(t);
+        return (f % 2 === 0 ? f : f + 1) / 100;
+    }
+    return Number(x.toFixed(2));
+}
+export function toAnswers(probs, meta) {
+    const out = {};
+    probs.forEach((p, i) => {
+        const m = meta[i];
+        if (m.type === "noul")
+            out[m.id] = { type: "noul", noul: r2(p[1]) };
+        else if (m.type === "choice")
+            out[m.id] = {
+                type: "choice", choice: m.keys[argmax(p)], confidence: r2(choiceConfidence(p)),
+                probabilities: Object.fromEntries(m.keys.map((k, j) => [k, r2(p[j])])),
+            };
+        else
+            out[m.id] = {
+                type: "score", score: r2(p.reduce((s, pi, j) => s + j * pi, 0)), legend: m.legend,
+                probabilities: Object.fromEntries(p.map((v, j) => [String(j), r2(v)])), confidence: r2(scoreConfidence(p)),
+            };
+    });
+    return out;
+}
+/** Python json.dumps (default separators, ensure_ascii). Every number in an answer is a Python float. */
+export function pyJsonDumps(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (typeof v === "number")
+        return pyFloat(v);
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "string")
+        return JSON.stringify(v).replace(/[\u0080-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+    if (Array.isArray(v))
+        return `[${v.map(pyJsonDumps).join(", ")}]`;
+    return `{${Object.entries(v).map(([k, x]) => `${pyJsonDumps(k)}: ${pyJsonDumps(x)}`).join(", ")}}`;
+}
+//# sourceMappingURL=api.js.map