jevais 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ivo-toby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# jevais
+
+Small semantic functions on top of the [TypeSafe Jev](https://docs.typesafe.ai) API.
+Zero runtime dependencies, native `fetch`, strict TypeScript, ESM only (Node >= 20).
+
+Every function makes probability judgments and keeps them honest: a network, API,
+timeout, or malformed-response failure throws a `JevError` — it is never converted
+into `false` or an empty result — and an uncertain judgment is never silently
+treated as `no`.
+
+## Install
+
+```bash
+npm install jevais
+```
+
+## Auth
+
+The `TYPESAFE_API_KEY` environment variable is the default key source, or set it
+once with `configure()`:
+
+```ts
+import { configure } from 'jevais';
+
+configure({ apiKey: process.env.TYPESAFE_API_KEY });
+```
+
+Every function also accepts these options per call (per-call > `configure()` >
+defaults):
+
+| option      | default            | meaning                                                            |
+| ----------- | ------------------ | ------------------------------------------------------------------ |
+| `apiKey`    | `TYPESAFE_API_KEY` | TypeSafe API key                                                   |
+| `model`     | `"jev-latest"`     | model id sent with every request                                   |
+| `timeoutMs` | `30000`            | per-attempt request timeout                                        |
+| `retries`   | `3`                | retries on HTTP 429/529, exponential backoff, honors `Retry-After` |
+
+## ifjev
+
+One yes/no question over one state. Resolves `true` when P(yes) >= threshold
+(default 0.85).
+
+```ts
+import { ifjev } from 'jevais';
+
+if (await ifjev('user reacts angry', userResponse, 0.85)) {
+  // do thing
+}
+```
+
+## findMeaning
+
+The first item (original order) whose P(yes) >= threshold, or `undefined`.
+One request per item with bounded concurrency (default 4), so completion order
+never changes the result.
+
+```ts
+import { findMeaning } from 'jevais';
+
+const match = await findMeaning(messages, 'the customer wants to cancel');
+if (match) {
+  // offer the cancellation flow
+}
+```
+
+## partitionMeaning
+
+Splits items by P(yes): `p >= threshold` -> `yes`, `p <= 1 - threshold` -> `no`,
+the rest -> `uncertain`. Uncertain stays explicit — never silently `no`.
+
+```ts
+import { partitionMeaning } from 'jevais';
+
+const { yes, no, uncertain } = await partitionMeaning(
+  tickets,
+  'the customer explicitly requests a refund',
+  { threshold: 0.85 },
+);
+```
+
+## rankMeaning
+
+Orders items by a Score judgment using the identical 2-to-10-level rubric for
+every item; sorted by score descending, stable for ties. Returns the items only.
+
+```ts
+import { rankMeaning } from 'jevais';
+
+const ranked = await rankMeaning(feedback, [
+  'irrelevant noise',
+  'minor, optional improvement',
+  'clear, actionable improvement',
+  'critical, must fix now',
+]);
+```
+
+## changedMeaning
+
+Detects a substantive change between two states while ignoring rewording.
+One Noul question over the structured state `{ before, after }`.
+
+```ts
+import { changedMeaning } from 'jevais';
+
+if (await changedMeaning(oldConfig, newConfig, 'deployment requirements changed')) {
+  // redeploy
+}
+```
+
+Like `partitionMeaning`, it accepts `threshold` through the options object
+(default `0.85`).
+
+## Errors
+
+All failures throw `JevError`, which carries the HTTP `status` (when the failure
+came from a response) and a raw `body` snippet:
+
+```ts
+import { JevError, ifjev } from 'jevais';
+
+try {
+  await ifjev('user reacts angry', userResponse);
+} catch (error) {
+  if (error instanceof JevError) {
+    console.error(`jev failed: ${error.status ?? 'network'} - ${error.message}`);
+  }
+}
+```
+
+HTTP 429/529 are retried up to `retries` times with exponential backoff (honoring
+`Retry-After` when present); 401, 422, and everything else throw immediately.
+Empty item arrays resolve with an empty result without calling the API.
+
+## Notes
+
+- One request per item: every item is judged with its own minimal state, which
+  keeps large, irrelevant state from distracting the judge.
+- Keep questions literal, in English, and free of math/counting/date logic.
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,38 @@
+import { type JevaisOptions, type ScoreAnswer } from './types.js';
+interface JevErrorOptions {
+    status?: number;
+    body?: string;
+    cause?: unknown;
+}
+/**
+ * Error for every jevais failure: missing API key, HTTP error (401, 422, ...),
+ * network error, timeout, or malformed response. Public functions never
+ * convert a JevError into a false/empty result.
+ */
+export declare class JevError extends Error {
+    /** HTTP status, when the failure came from a response. */
+    readonly status?: number;
+    /** Raw response body snippet, when available. */
+    readonly body?: string;
+    constructor(message: string, options?: JevErrorOptions);
+}
+/**
+ * Set module-level defaults; later calls merge over earlier ones and
+ * per-call options still take precedence. When no apiKey is set anywhere,
+ * the TYPESAFE_API_KEY environment variable is used.
+ */
+export declare function configure(options?: JevaisOptions): void;
+/**
+ * Ask one Noul question over `state` in a single request; resolves P(yes) in
+ * [0, 1]. The question id never reaches the model; only `instructions` does.
+ * Throws JevError on any failure (never resolves a failure as a probability).
+ */
+export declare function askNoul(instructions: string, state: unknown, options?: JevaisOptions): Promise<number>;
+/**
+ * Ask one Score question over `state` in a single request using the given
+ * ordered level descriptions (2 to 10 levels). Throws JevError on any
+ * failure.
+ */
+export declare function askScore(instructions: string, criteria: readonly string[], state: unknown, options?: JevaisOptions): Promise<ScoreAnswer>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EAElB,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AAUpB,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAM3D;AAKD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,aAAkB,GAAG,IAAI,CAK3D;AA8ID;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,WAAW,CAAC,CAkBtB"}

package/dist/client.js

@@ -0,0 +1,196 @@
+import { DEFAULT_MODEL, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS, JEV_ENDPOINT, } from './types.js';
+/** HTTP statuses that are retried with backoff (rate limit / overloaded). */
+const RETRYABLE_STATUSES = [429, 529];
+/** First backoff delay; doubles per retry, capped at MAX_RETRY_DELAY_MS. */
+const BASE_RETRY_DELAY_MS = 500;
+const MAX_RETRY_DELAY_MS = 8000;
+const BODY_SNIPPET_LIMIT = 500;
+/**
+ * Error for every jevais failure: missing API key, HTTP error (401, 422, ...),
+ * network error, timeout, or malformed response. Public functions never
+ * convert a JevError into a false/empty result.
+ */
+export class JevError extends Error {
+    /** HTTP status, when the failure came from a response. */
+    status;
+    /** Raw response body snippet, when available. */
+    body;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'JevError';
+        this.status = options.status;
+        this.body = options.body;
+    }
+}
+/** Module-level defaults set through configure(). */
+const moduleConfig = {};
+/**
+ * Set module-level defaults; later calls merge over earlier ones and
+ * per-call options still take precedence. When no apiKey is set anywhere,
+ * the TYPESAFE_API_KEY environment variable is used.
+ */
+export function configure(options = {}) {
+    if (options.apiKey !== undefined)
+        moduleConfig.apiKey = options.apiKey;
+    if (options.model !== undefined)
+        moduleConfig.model = options.model;
+    if (options.timeoutMs !== undefined)
+        moduleConfig.timeoutMs = options.timeoutMs;
+    if (options.retries !== undefined)
+        moduleConfig.retries = options.retries;
+}
+/** Throws (before any fetch) when no API key is available. */
+function resolveConfig(overrides) {
+    const apiKey = overrides?.apiKey ?? moduleConfig.apiKey ?? process.env.TYPESAFE_API_KEY;
+    if (apiKey === undefined || apiKey === '') {
+        throw new JevError('Missing TypeSafe API key: pass { apiKey }, configure({ apiKey }), or set TYPESAFE_API_KEY.');
+    }
+    return {
+        apiKey,
+        model: overrides?.model ?? moduleConfig.model ?? DEFAULT_MODEL,
+        timeoutMs: overrides?.timeoutMs ?? moduleConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        retries: overrides?.retries ?? moduleConfig.retries ?? DEFAULT_RETRIES,
+    };
+}
+/**
+ * POST one question set over the shared `state` and return the validated
+ * response. Retries 429/529 (up to `retries` times, exponential backoff,
+ * honoring numeric Retry-After in seconds); every other failure throws a
+ * JevError carrying status and/or a raw body snippet.
+ */
+async function postJev(questions, state, config) {
+    const payload = JSON.stringify({ state, model: config.model, questions });
+    let retry = 0;
+    for (;;) {
+        let response;
+        try {
+            response = await fetch(JEV_ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: payload,
+                signal: AbortSignal.timeout(config.timeoutMs),
+            });
+        }
+        catch (cause) {
+            throw new JevError(`Jev request failed: ${describe(cause)}`, { cause });
+        }
+        if (RETRYABLE_STATUSES.includes(response.status)) {
+            if (retry >= config.retries) {
+                const body = await bodySnippet(response);
+                throw new JevError(`Jev API returned HTTP ${response.status} after ${retry + 1} attempt${retry === 0 ? '' : 's'}`, {
+                    status: response.status,
+                    body,
+                });
+            }
+            retry += 1;
+            await sleep(retryDelayMs(response, retry));
+            continue;
+        }
+        if (!response.ok) {
+            const body = await bodySnippet(response);
+            throw new JevError(`Jev API request failed with HTTP ${response.status}`, {
+                status: response.status,
+                body,
+            });
+        }
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch (cause) {
+            throw new JevError('Jev API returned a malformed (non-JSON) response body', { cause });
+        }
+        return validateResponse(data);
+    }
+}
+function retryDelayMs(response, retry) {
+    const raw = response.headers.get('retry-after');
+    if (raw !== null) {
+        const seconds = Number(raw);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return seconds * 1000;
+    }
+    return Math.min(BASE_RETRY_DELAY_MS * 2 ** (retry - 1), MAX_RETRY_DELAY_MS);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+async function bodySnippet(response) {
+    try {
+        const text = await response.text();
+        if (text === '')
+            return undefined;
+        return text.length > BODY_SNIPPET_LIMIT ? `${text.slice(0, BODY_SNIPPET_LIMIT)}...` : text;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateResponse(data) {
+    if (!isPlainObject(data)) {
+        throw new JevError('Jev API returned a malformed response body');
+    }
+    if (!isPlainObject(data.answers)) {
+        throw new JevError('Jev API returned a malformed response body: missing "answers"');
+    }
+    if (typeof data.model !== 'string') {
+        throw new JevError('Jev API returned a malformed response body: "model" is not a string');
+    }
+    if (!isPlainObject(data.usage)) {
+        throw new JevError('Jev API returned a malformed response body: missing "usage"');
+    }
+    // Runtime validation above; the Record narrowing cannot express JevResponse.
+    return data;
+}
+function isUnitProbability(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+/**
+ * Ask one Noul question over `state` in a single request; resolves P(yes) in
+ * [0, 1]. The question id never reaches the model; only `instructions` does.
+ * Throws JevError on any failure (never resolves a failure as a probability).
+ */
+export async function askNoul(instructions, state, options) {
+    const config = resolveConfig(options);
+    const questions = { noul: { type: 'noul', instructions } };
+    const response = await postJev(questions, state, config);
+    const answer = response.answers.noul;
+    if (answer === undefined || answer.type !== 'noul' || !isUnitProbability(answer.noul)) {
+        throw new JevError('Jev API returned a malformed Noul answer');
+    }
+    return answer.noul;
+}
+/**
+ * Ask one Score question over `state` in a single request using the given
+ * ordered level descriptions (2 to 10 levels). Throws JevError on any
+ * failure.
+ */
+export async function askScore(instructions, criteria, state, options) {
+    const config = resolveConfig(options);
+    const questions = {
+        score: { type: 'score', instructions, criteria: [...criteria] },
+    };
+    const response = await postJev(questions, state, config);
+    const answer = response.answers.score;
+    if (answer === undefined ||
+        answer.type !== 'score' ||
+        !Number.isFinite(answer.score) ||
+        typeof answer.confidence !== 'number' ||
+        !isPlainObject(answer.legend) ||
+        !isPlainObject(answer.probabilities)) {
+        throw new JevError('Jev API returned a malformed Score answer');
+    }
+    return answer;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { JevError, configure } from './client.js';
+export { changedMeaning, findMeaning, ifjev, partitionMeaning, rankMeaning } from './meaning.js';
+export type { PartitionResult } from './meaning.js';
+export type { JevAnswer, JevQuestion, JevResponse, JevUsage, JevaisOptions, MeaningOptions, NoulAnswer, NoulQuestion, RankOptions, ScoreAnswer, ScoreQuestion, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjG,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,QAAQ,EACR,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { JevError, configure } from './client.js';
+export { changedMeaning, findMeaning, ifjev, partitionMeaning, rankMeaning } from './meaning.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/meaning.d.ts

@@ -0,0 +1,40 @@
+import { type JevaisOptions, type MeaningOptions, type RankOptions } from './types.js';
+/** Partition result of partitionMeaning. */
+export interface PartitionResult<T> {
+    yes: T[];
+    no: T[];
+    uncertain: T[];
+}
+/**
+ * Ask whether `question` holds of `state`; resolves true when P(yes) >=
+ * threshold. One Noul question in one request.
+ */
+export declare function ifjev(question: string, state: unknown, threshold?: number, options?: JevaisOptions): Promise<boolean>;
+/**
+ * Return the first item (original order) whose P(yes) >= threshold, or
+ * undefined when none match. One Noul request per item with bounded
+ * concurrency, so completion order never affects the result. Empty input
+ * resolves undefined without calling the API.
+ */
+export declare function findMeaning<T>(items: readonly T[], question: string, options?: MeaningOptions): Promise<T | undefined>;
+/**
+ * Split items by P(yes): p >= threshold -> yes, p <= 1 - threshold -> no,
+ * everything else -> uncertain. Uncertain is explicit and never silently
+ * treated as no. One Noul request per item with bounded concurrency. Empty
+ * input returns three empty arrays without calling the API.
+ */
+export declare function partitionMeaning<T>(items: readonly T[], question: string, options?: MeaningOptions): Promise<PartitionResult<T>>;
+/**
+ * Order items by a Score judgment using the identical 2-to-10-level rubric
+ * for every item; sorted by score descending, stable for ties. Returns the
+ * items only (no scores). One Score request per item with bounded
+ * concurrency. Invalid levels (empty, one, or > 10) throw before any fetch;
+ * empty input returns [] without calling the API.
+ */
+export declare function rankMeaning<T>(items: readonly T[], levels: readonly string[], options?: RankOptions): Promise<T[]>;
+/**
+ * Ask whether `after` changed in the sense of `question`, judged over the
+ * structured state { before, after }; resolves true when P(yes) >= threshold.
+ */
+export declare function changedMeaning(before: unknown, after: unknown, question: string, options?: MeaningOptions): Promise<boolean>;
+//# sourceMappingURL=meaning.d.ts.map

package/dist/meaning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meaning.d.ts","sourceRoot":"","sources":["../src/meaning.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAQpB,4CAA4C;AAC5C,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,GAAG,EAAE,CAAC,EAAE,CAAC;IACT,EAAE,EAAE,CAAC,EAAE,CAAC;IACR,SAAS,EAAE,CAAC,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,KAAK,CACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,MAA0B,EACrC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAMxB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAa7B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CAYd;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/meaning.js

@@ -0,0 +1,116 @@
+import { JevError, askNoul, askScore } from './client.js';
+import { DEFAULT_CONCURRENCY, DEFAULT_THRESHOLD, } from './types.js';
+/**
+ * Neutral instructions for ranking: the ordered `levels` carry the rubric, so
+ * the wording stays identical (and literal) for every item.
+ */
+const RANK_INSTRUCTIONS = 'Rate this item on the provided scale.';
+/**
+ * Ask whether `question` holds of `state`; resolves true when P(yes) >=
+ * threshold. One Noul question in one request.
+ */
+export async function ifjev(question, state, threshold = DEFAULT_THRESHOLD, options) {
+    const p = await askNoul(question, state, options);
+    return p >= threshold;
+}
+/**
+ * Return the first item (original order) whose P(yes) >= threshold, or
+ * undefined when none match. One Noul request per item with bounded
+ * concurrency, so completion order never affects the result. Empty input
+ * resolves undefined without calling the API.
+ */
+export async function findMeaning(items, question, options) {
+    if (items.length === 0)
+        return undefined;
+    const threshold = options?.threshold ?? DEFAULT_THRESHOLD;
+    const probabilities = await judgeAll(items, question, options);
+    const index = probabilities.findIndex((p) => p >= threshold);
+    return index === -1 ? undefined : items[index];
+}
+/**
+ * Split items by P(yes): p >= threshold -> yes, p <= 1 - threshold -> no,
+ * everything else -> uncertain. Uncertain is explicit and never silently
+ * treated as no. One Noul request per item with bounded concurrency. Empty
+ * input returns three empty arrays without calling the API.
+ */
+export async function partitionMeaning(items, question, options) {
+    const result = { yes: [], no: [], uncertain: [] };
+    if (items.length === 0)
+        return result;
+    const threshold = options?.threshold ?? DEFAULT_THRESHOLD;
+    const noCutoff = 1 - threshold;
+    const probabilities = await judgeAll(items, question, options);
+    for (let i = 0; i < items.length; i += 1) {
+        const p = probabilities[i];
+        if (p >= threshold)
+            result.yes.push(items[i]);
+        else if (p <= noCutoff)
+            result.no.push(items[i]);
+        else
+            result.uncertain.push(items[i]);
+    }
+    return result;
+}
+/**
+ * Order items by a Score judgment using the identical 2-to-10-level rubric
+ * for every item; sorted by score descending, stable for ties. Returns the
+ * items only (no scores). One Score request per item with bounded
+ * concurrency. Invalid levels (empty, one, or > 10) throw before any fetch;
+ * empty input returns [] without calling the API.
+ */
+export async function rankMeaning(items, levels, options) {
+    assertLevels(levels);
+    if (items.length === 0)
+        return [];
+    const scores = await mapWithConcurrency(items, concurrencyOf(options), async (item) => {
+        const answer = await askScore(RANK_INSTRUCTIONS, levels, item, options);
+        return answer.score;
+    });
+    const order = scores
+        .map((score, index) => ({ index, score }))
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .map((entry) => entry.index);
+    return order.map((index) => items[index]);
+}
+/**
+ * Ask whether `after` changed in the sense of `question`, judged over the
+ * structured state { before, after }; resolves true when P(yes) >= threshold.
+ */
+export async function changedMeaning(before, after, question, options) {
+    const p = await askNoul(question, { before, after }, options);
+    return p >= (options?.threshold ?? DEFAULT_THRESHOLD);
+}
+/** One Noul request per item, bounded concurrency, results in input order. */
+async function judgeAll(items, question, options) {
+    return mapWithConcurrency(items, concurrencyOf(options), (item) => askNoul(question, item, options));
+}
+function assertLevels(levels) {
+    if (!Array.isArray(levels) || levels.length < 2 || levels.length > 10) {
+        throw new JevError('levels must be an array of 2 to 10 ordered level descriptions');
+    }
+}
+function concurrencyOf(options) {
+    const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new JevError('concurrency must be a positive integer');
+    }
+    return concurrency;
+}
+/**
+ * Run `fn` over `items` with at most `limit` calls in flight; results keep
+ * input order. Any rejection rejects the whole operation (failures are never
+ * turned into missing/empty results).
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await fn(items[index], index);
+        }
+    }));
+    return results;
+}
+//# sourceMappingURL=meaning.js.map

package/dist/meaning.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/** TypeSafe Jev systemone endpoint. */
+export declare const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+/** Default model id. */
+export declare const DEFAULT_MODEL = "jev-latest";
+/** Default per-attempt request timeout in milliseconds. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Default number of 429/529 retries after the first attempt. */
+export declare const DEFAULT_RETRIES = 3;
+/** Default yes threshold: p >= threshold counts as yes. */
+export declare const DEFAULT_THRESHOLD = 0.85;
+/** Default cap on in-flight per-item requests. */
+export declare const DEFAULT_CONCURRENCY = 4;
+/** Noul (yes/no) question; `instructions` carries the question wording. */
+export interface NoulQuestion {
+    type: 'noul';
+    instructions: string | object | unknown[];
+    criteria?: {
+        true?: unknown;
+        false?: unknown;
+    };
+}
+/** Score question; `criteria` is 2 to 10 ordered level descriptions. */
+export interface ScoreQuestion {
+    type: 'score';
+    instructions: string | object | unknown[];
+    criteria: string[];
+}
+export type JevQuestion = NoulQuestion | ScoreQuestion;
+/** Noul answer: `noul` is P(yes) in [0, 1]. There is no confidence field. */
+export interface NoulAnswer {
+    type: 'noul';
+    noul: number;
+}
+/** Score answer. Level keys are stringified indices ("0", "1", ...). */
+export interface ScoreAnswer {
+    type: 'score';
+    /** Fractional score; may land between levels. */
+    score: number;
+    legend: Record<string, unknown>;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export type JevAnswer = NoulAnswer | ScoreAnswer;
+export interface JevUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+/** Response body of POST /v1/systemone. */
+export interface JevResponse {
+    model: string;
+    answers: Record<string, JevAnswer>;
+    usage: JevUsage;
+}
+/** Module-level and per-call options shared by every jevais function. */
+export interface JevaisOptions {
+    /** TypeSafe API key; falls back to configure(), then TYPESAFE_API_KEY. */
+    apiKey?: string;
+    /** Model id. Default: "jev-latest". */
+    model?: string;
+    /** Per-attempt request timeout in ms. Default: 30000. */
+    timeoutMs?: number;
+    /** 429/529 retries after the first attempt. Default: 3. */
+    retries?: number;
+}
+/** Options for threshold-based judgments. */
+export interface MeaningOptions extends JevaisOptions {
+    /** Yes threshold, expected in (0, 1). Default: 0.85. */
+    threshold?: number;
+    /** Max in-flight per-item requests. Default: 4. */
+    concurrency?: number;
+}
+/** Options for rankMeaning. */
+export interface RankOptions extends JevaisOptions {
+    /** Max in-flight per-item requests. Default: 4. */
+    concurrency?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,eAAO,MAAM,YAAY,yCAAyC,CAAC;AAEnE,wBAAwB;AACxB,eAAO,MAAM,aAAa,eAAe,CAAC;AAE1C,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,iEAAiE;AACjE,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;IAC1C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,aAAa,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAEjD,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+BAA+B;AAC/B,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/** TypeSafe Jev systemone endpoint. */
+export const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
+/** Default model id. */
+export const DEFAULT_MODEL = 'jev-latest';
+/** Default per-attempt request timeout in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** Default number of 429/529 retries after the first attempt. */
+export const DEFAULT_RETRIES = 3;
+/** Default yes threshold: p >= threshold counts as yes. */
+export const DEFAULT_THRESHOLD = 0.85;
+/** Default cap on in-flight per-item requests. */
+export const DEFAULT_CONCURRENCY = 4;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,sCAAsC,CAAC;AAEnE,wBAAwB;AACxB,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC;AAE1C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,kDAAkD;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "jevais",
+  "version": "0.1.0",
+  "description": "Small semantic functions on top of the TypeSafe Jev API: ifjev, findMeaning, partitionMeaning, rankMeaning, changedMeaning.",
+  "keywords": [
+    "jev",
+    "typesafe",
+    "noul",
+    "score",
+    "llm",
+    "semantic",
+    "classification",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "ivo-toby",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivo-toby/jevais.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^20.11.0",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.9"
+  }
+}