Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

test(sdk): hold the design page's control table to the request body it describes

Aashish5c7f5aa306f8
diff --git a/sdk/typescript/test/docs.test.mjs b/sdk/typescript/test/docs.test.mjs
new file mode 100644
index 00000000..616b7873
--- /dev/null
+++ b/sdk/typescript/test/docs.test.mjs
@@ -0,0 +1,130 @@
+/**
+ * The design page's request contract must be the contract the client implements.
+ *
+ * `docs/typescript-sdk.md` is the wire reference for callers who read the design doc instead of the
+ * guide, and its control paragraph had drifted into a positive lie: it said `/v1/systemone` does not
+ * expose `task` and `lang` and that the SDK rejects those options, while `body()` had long been
+ * forwarding them (and `lang_guess`, `max_len`, `head_max_len`, `min_confidence` besides). A caller who
+ * believed the page would keep paying server-side defaults it could have overridden.
+ *
+ * So the page is read through the same seam a server sees: the options are set, the request body the
+ * client hands to `fetch` is captured, and the table is compared against the keys that were really put
+ * on the wire. Nothing here transcribes the client's option list -- if `body()` gains or drops a control
+ * the table has to move with it, in both directions.
+ */
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { test } from 'node:test';
+import { Laya } from 'laya-client';
+
+const PAGE = fileURLToPath(new URL('../../../docs/typescript-sdk.md', import.meta.url));
+const DECLARATION = new URL('../dist/esm/client.d.ts', import.meta.url);
+const QUESTIONS = { single: { type: 'choice', instructions: 'Pick one', criteria: ['a', 'b'] } };
+
+/** One valid prediction, so `predict()` gets far enough to build its request. */
+const RESULT = {
+ model: 'english',
+ answers: { single: { type: 'choice', confidence: 1, answer_confidence: 1, choice: 'a',
+ probabilities: { a: 1, b: 0 } } },
+ usage: { input_tokens: 4, output_tokens: 0 },
+};
+
+/** The request body the client would send for `options`, minus `state` and `questions`. */
+async function controls(options) {
+ let body;
+ const laya = new Laya({ fetch: async (url, init) => {
+ body = JSON.parse(init.body);
+ return new Response(JSON.stringify(RESULT), { headers: { 'content-type': 'application/json' } });
+ } });
+ await laya.predict('the state', QUESTIONS, options);
+ const { state, questions, ...rest } = body;
+ assert.deepEqual([state, Object.keys(questions)], ['the state', ['single']],
+ 'a request must always carry the state and the questions it was given');
+ return Object.keys(rest).sort();
+}
+
+/** A value for every option the table names, chosen to survive the client's own validation. */
+const OPTION_VALUES = { model: 'english', task: 'typed', lang: 'de', langGuess: 'en',
+ maxLen: 512, headMaxLen: 24, minConfidence: 0.8 };
+
+function controlTable(page) {
+ const lines = page.split('\n');
+ const start = lines.indexOf('| option | request field |');
+ assert.notEqual(start, -1, 'the design page has no "| option | request field |" table; retarget this');
+ const rows = new Map();
+ for (const line of lines.slice(start + 2)
+ .filter(line => line.startsWith('| `'))) {
+ const cells = line.split('|').slice(1, -1).map(cell => cell.trim().replace(/^`|`$/g, ''));
+ assert.equal(cells.length, 2, `table row ${line} does not name exactly one option and one field`);
+ rows.set(cells[0], cells[1]);
+ }
+ assert.ok(rows.size, 'the control table has no rows');
+ return rows;
+}
+
+test('the design page names every control the client puts on the wire, and only those', async () => {
+ const page = readFileSync(PAGE, 'utf8');
+ const table = controlTable(page);
+
+ const sent = await controls(OPTION_VALUES);
+ // The fixture is what exercises each row, so it must stay the same size as the table: a row nobody
+ // sets would be an untested mapping, and an option the table omits would be an undocumented one.
+ assert.deepEqual([...table.keys()].sort(), Object.keys(OPTION_VALUES).sort(),
+ 'the table names options %s, this fixture exercises %s',
+ [...table.keys()].sort(), Object.keys(OPTION_VALUES).sort());
+ assert.deepEqual(sent, [...table.values()].sort(),
+ 'the page lists %s as the request fields, the client sends %s for the same options',
+ [...table.values()].sort(), sent);
+
+ // An option that is dropped on the floor would still be listed and still be accepted, so the mapping
+ // is checked one option at a time: setting only `langGuess` must arrive as `lang_guess` and nothing else.
+ for (const [option, field] of table) {
+ assert.deepEqual(await controls({ [option]: OPTION_VALUES[option] }), [field],
+ `predict({ ${option} }) must reach the server as exactly \`${field}\``);
+ }
+
+ // The other half of the contract the page states: an option the caller left out stays off the wire, so
+ // the deployment's own Router settings answer rather than a client-side default.
+ assert.deepEqual(await controls({}), [],
+ 'a bare predict() sends state and questions only');
+});
+
+test('no sentence on the page claims a control it documents is unsupported', async () => {
+ const page = readFileSync(PAGE, 'utf8');
+ const fields = [...controlTable(page).values()];
+ // Splitting on sentence boundaries rather than the whole page: "a blank `task` is refused locally" is
+ // true and must keep passing, while "does not expose `task`" is the lie this guards against.
+ for (const sentence of page.split(/(?<=[.!?])\s+/)) {
+ if (!/\bdoes not (?:expose|support|accept)\b|\bnot exposed\b|\bnot supported\b|\blegacy\b/i
+ .test(sentence)) continue;
+ const named = fields.filter(field => sentence.includes('`' + field + '`'));
+ assert.deepEqual(named, [],
+ `the page denies ${named.join(', ')} while its own table documents it as a request field: `
+ + `"${sentence.replace(/\s+/g, ' ').trim()}"`);
+ }
+});
+
+// The declaration is built, not committed -- `npm test` runs the build before the tests, so a bare
+// `node --test test/docs.test.mjs` on a fresh checkout has nothing to read yet.
+test('the endpoint surface the page describes is the one the client declares',
+ { skip: !existsSync(DECLARATION) && 'run `npm run build` first: dist/esm/client.d.ts is the surface' },
+ () => {
+ const page = readFileSync(PAGE, 'utf8');
+ // The published declaration is what a caller can actually reach, and it is the one place that keeps
+ // TypeScript's `private` (a prototype probe would report `body` and `request` as public too).
+ const declaration = readFileSync(DECLARATION, 'utf8');
+ // A member is public if it is spelled out as a signature; `private body;` collapses to the keyword.
+ const declared = [...declaration.matchAll(/^ {4}(?!constructor)(\w+)[<(]/gm)]
+ .map(([, name]) => name).sort();
+ assert.deepEqual(declared, ['health', 'predict'],
+ 'the client gained or lost a public method; the page describes exactly these two');
+ for (const name of declared) {
+ assert.ok(page.includes('`' + name + '`'),
+ `the page never names the ${name}() method the client declares`);
+ }
+ // The page's negative claim, on the code side: there is no standalone routing call to make.
+ for (const absent of ['route', 'decide', 'classify']) {
+ assert.equal(Laya.prototype[absent], undefined, `Laya unexpectedly exposes ${absent}()`);
+ }
+ });