@jevable/core 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @jevable/core
+
+The rule engine behind [`jev`](../cli/README.md): CEL expressions over a
+record (`line`, `json`) or a window (`window`) that can ask
+[Jev](https://docs.typesafe.ai) semantic questions through `judge.boolean`,
+`judge.choice` and `judge.score`. Plain conditions decide first; Jev is asked
+only when they cannot, and the same question on the same material once.
+
+```ts
+import { Client, Engine, parseRecord, toCel } from "@jevable/core";
+
+const engine = new Engine(new Client({ apiKey: process.env.TYPESAFE_API_KEY }));
+const rule = engine.compile(`json.user != "bot" && judge.boolean(json.body, "Does this comment ask for a code change?") >= 0.7`);
+
+const { line, json } = parseRecord(`{"user": "alice", "body": "can you rename this?"}`);
+const { pass, calls, error } = await rule.match({ line, json: toCel(json) });
+```
+
+`compile` throws a `RuleError` for a rule that cannot work (unknown variable,
+unknown function, a judge call not compared with a threshold).
+`@jevable/core/testing` serves a fake Jev for tests.

package/dist/cel/check.d.ts

@@ -0,0 +1,12 @@
+import { type Planned } from "./env.ts";
+/** A rule that cannot work as written. */
+export declare class RuleError extends Error {
+}
+export declare const HINT = "Variables: line, json (the parsed line) and, with --window, window. Run `jev guide` for functions and examples.";
+/** Throws a RuleError when the parsed expression cannot work as a rule (or key). */
+export declare function checkParsed(expr: unknown, kind: "rule" | "key"): void;
+/** Dry-runs a planned expression with neutral answers; throws a RuleError on what only evaluation shows. */
+export declare function checkPlanned(run: Planned, kind: "rule" | "key"): void;
+/** Is a runtime error a bug in the rule rather than in the record? */
+export declare function isRuleBug(err: Error): boolean;
+export declare function describe(v: unknown): string;

package/dist/cel/check.js

@@ -0,0 +1,101 @@
+// Compile-time checks: catch a rule that cannot work before any record is
+// read, since a rule that silently never passes looks exactly like quiet.
+import { isCelError } from "@bufbuild/cel";
+import { evaluateWith } from "./env.js";
+/** A rule that cannot work as written. */
+export class RuleError extends Error {
+}
+const VARIABLES = new Set(["line", "json", "window"]);
+// Identifiers CEL itself provides: type names usable in `type(x) == int`.
+const BUILTIN_IDENTS = new Set(["int", "uint", "double", "bool", "string", "bytes", "list", "map", "null_type", "type"]);
+export const HINT = "Variables: line, json (the parsed line) and, with --window, window. Run `jev guide` for functions and examples.";
+const COMPARE = `compare it, e.g. judge.boolean(line, "...") >= 0.7`;
+// Values for the dry run, shaped like real ones.
+const PROBE = {
+    line: "probe",
+    json: new Map(),
+    window: new Map([
+        ["total", 0n], ["prev_total", 0n], ["kinds", 0n], ["seconds", 0n],
+        ["start", ""], ["end", ""], ["groups", []], ["summary", "probe"],
+    ]),
+};
+/** Throws a RuleError when the parsed expression cannot work as a rule (or key). */
+export function checkParsed(expr, kind) {
+    const unknown = undeclared(expr);
+    if (unknown.length)
+        throw new RuleError(`unknown variable ${unknown.map((n) => `'${n}'`).join(", ")}\n\n${HINT}`);
+    if (kind === "rule" && isJudgeCall(expr))
+        throw new RuleError(`the rule must be true or false, but judge.* yields a number — ${COMPARE}`);
+}
+/** Dry-runs a planned expression with neutral answers; throws a RuleError on what only evaluation shows. */
+export function checkPlanned(run, kind) {
+    const out = evaluateWith({ answers: null, calls: [], keys: [] }, run, PROBE);
+    if (isCelError(out) && /unbound function|no matching overload for 'judge\./.test(out.message)) {
+        throw new RuleError(`${out.message}\n\n${HINT}`);
+    }
+    if (kind === "rule" && !isCelError(out) && typeof out !== "boolean") {
+        throw new RuleError(`the rule must be true or false, but it yields ${describe(out)} — ${COMPARE}`);
+    }
+}
+/** Is a runtime error a bug in the rule rather than in the record? */
+export function isRuleBug(err) {
+    return /unbound function|unresolved attribute/.test(err.message);
+}
+export function describe(v) {
+    if (typeof v === "number" || typeof v === "bigint")
+        return `a number (${v})`;
+    if (typeof v === "string")
+        return "a string";
+    return typeof v;
+}
+function isJudgeCall(e) {
+    const call = e?.exprKind?.case === "callExpr" ? e.exprKind.value : undefined;
+    const target = call?.target?.exprKind;
+    return target?.case === "identExpr" && target.value.name === "judge";
+}
+/** Names used as variables that are neither declared nor bound by a macro. */
+function undeclared(root) {
+    const found = new Set();
+    const walk = (e, scope) => {
+        if (!e?.exprKind)
+            return;
+        const { case: kind, value: v } = e.exprKind;
+        switch (kind) {
+            case "identExpr":
+                if (!scope.has(v.name) && !VARIABLES.has(v.name) && !BUILTIN_IDENTS.has(v.name))
+                    found.add(v.name);
+                return;
+            case "selectExpr":
+                return walk(v.operand, scope);
+            case "callExpr":
+                // judge.boolean(...) parses as a call on the identifier `judge`.
+                if (!(v.target?.exprKind?.case === "identExpr" && v.target.exprKind.value.name === "judge"))
+                    walk(v.target, scope);
+                for (const a of v.args)
+                    walk(a, scope);
+                return;
+            case "listExpr":
+                for (const el of v.elements)
+                    walk(el, scope);
+                return;
+            case "structExpr":
+                for (const en of v.entries) {
+                    if (en.keyKind?.case === "mapKey")
+                        walk(en.keyKind.value, scope);
+                    walk(en.value, scope);
+                }
+                return;
+            case "comprehensionExpr": {
+                walk(v.iterRange, scope);
+                walk(v.accuInit, scope);
+                const inner = new Set([...scope, v.iterVar, v.iterVar2, v.accuVar].filter(Boolean));
+                walk(v.loopCondition, inner);
+                walk(v.loopStep, inner);
+                walk(v.result, inner);
+                return;
+            }
+        }
+    };
+    walk(root, new Set());
+    return [...found];
+}

package/dist/cel/env.d.ts

@@ -0,0 +1,22 @@
+import { type CelEnv, type CelInput } from "@bufbuild/cel";
+import type { Answer, Question } from "../typesafe/client.ts";
+import type { Call } from "../types.ts";
+/** Where known answers come from; null in a pass means the compile-time dry run. */
+export interface Answers {
+    cached(key: string): Answer | undefined;
+}
+/** One evaluation pass: the answers it may use, the first question it lacked, the calls it made. */
+export interface Pass {
+    answers: Answers | null;
+    pending?: {
+        key: string;
+        state: unknown;
+        q: Question;
+    };
+    calls: Call[];
+    keys: string[];
+}
+export type Planned = (ctx: Record<string, CelInput>) => unknown;
+/** Runs a planned expression within a pass; a thrown error is returned like a CEL error. */
+export declare function evaluateWith(pass: Pass, run: Planned, ctx: Record<string, CelInput>): unknown;
+export declare const env: CelEnv;

package/dist/cel/env.js

@@ -0,0 +1,83 @@
+// The CEL environment: judge.boolean / judge.choice / judge.score and
+// fingerprint, and the evaluation pass they report into.
+//
+// CEL evaluation is synchronous and a Jev call is not, so a rule is
+// evaluated in passes (program.ts): a judge call whose answer is not known
+// yet records the question in the pass and fails it; the question is asked;
+// the rule is evaluated again.
+import { createHash } from "node:crypto";
+import { celEnv, celFunc, CelScalar, mapType } from "@bufbuild/cel";
+import { strings } from "@bufbuild/cel/ext";
+import { cutLongStrings, fingerprint } from "../text.js";
+import { fromCel } from "./values.js";
+// The pass in progress. Evaluation is synchronous, so one slot is enough.
+let current;
+/** Runs a planned expression within a pass; a thrown error is returned like a CEL error. */
+export function evaluateWith(pass, run, ctx) {
+    current = pass;
+    try {
+        return run(ctx);
+    }
+    catch (err) {
+        return err;
+    }
+    finally {
+        current = undefined;
+    }
+}
+const FN = { noul: "boolean", choice: "choice", score: "score" };
+function judge(type, material, question, criteria) {
+    const pass = current;
+    if (!pass)
+        throw new Error("judge.* evaluated outside a rule");
+    const q = { type, instructions: question };
+    if (criteria !== undefined)
+        q.criteria = fromCel(criteria);
+    if (!pass.answers)
+        return answerValue(type, probeAnswer(type, q));
+    const state = cutLongStrings(fromCel(material));
+    if (state === null || state === undefined || state === "")
+        throw new Error("judge material is empty");
+    const key = cacheKey(q, state);
+    const ans = pass.answers.cached(key);
+    if (!ans) {
+        pass.pending ??= { key, state, q };
+        throw new Error("waiting for Jev");
+    }
+    const call = { fn: FN[type], question };
+    if (type === "choice")
+        call.options = ans.probabilities ?? {};
+    else
+        call.value = (type === "score" ? ans.score : ans.noul) ?? 0;
+    pass.calls.push(call);
+    pass.keys.push(key);
+    return answerValue(type, ans);
+}
+function answerValue(type, ans) {
+    if (type === "choice")
+        return new Map(Object.entries(ans.probabilities ?? {}));
+    return (type === "score" ? ans.score : ans.noul) ?? 0;
+}
+/** A neutral answer for the compile-time dry run; nothing is sent. */
+function probeAnswer(type, q) {
+    if (type === "choice") {
+        const options = Object.keys(q.criteria ?? {});
+        return { type, probabilities: Object.fromEntries(options.map((o) => [o, 1 / Math.max(options.length, 1)])) };
+    }
+    return type === "score" ? { type, score: 0 } : { type, noul: 0.5 };
+}
+function cacheKey(q, state) {
+    return createHash("sha256").update(JSON.stringify([q.type, q.instructions, q.criteria ?? null, state])).digest("hex");
+}
+const D = CelScalar.DYN;
+const S = CelScalar.STRING;
+export const env = celEnv({
+    funcs: [
+        ...strings,
+        celFunc("judge.boolean", [D, S], CelScalar.DOUBLE, (m, q) => judge("noul", m, q)),
+        celFunc("judge.boolean", [D, S, D], CelScalar.DOUBLE, (m, q, c) => judge("noul", m, q, c)),
+        celFunc("judge.choice", [D, S, D], mapType(S, CelScalar.DOUBLE), (m, q, c) => judge("choice", m, q, c)),
+        celFunc("judge.score", [D, S, D], CelScalar.DOUBLE, (m, q, c) => judge("score", m, q, c)),
+        celFunc("fingerprint", [S], S, (s) => fingerprint(s)),
+    ],
+});

package/dist/cel/values.d.ts

@@ -0,0 +1,5 @@
+import { type CelInput, type CelValue } from "@bufbuild/cel";
+/** Turns a CEL value into plain JSON-able values. */
+export declare function fromCel(v: CelValue | unknown): unknown;
+/** Turns parsed JSON into CEL input: objects become maps. */
+export declare function toCel(v: unknown): CelInput;

package/dist/cel/values.js

@@ -0,0 +1,28 @@
+import { isCelList, isCelMap, isCelUint } from "@bufbuild/cel";
+/** Turns a CEL value into plain JSON-able values. */
+export function fromCel(v) {
+    if (typeof v === "bigint")
+        return Number(v);
+    if (isCelUint(v))
+        return Number(v.value);
+    if (isCelMap(v)) {
+        const out = {};
+        for (const [k, x] of v)
+            out[String(isCelUint(k) ? k.value : k)] = fromCel(x);
+        return out;
+    }
+    if (isCelList(v))
+        return Array.from(v, fromCel);
+    if (v === null || typeof v !== "object")
+        return v;
+    return String(v);
+}
+/** Turns parsed JSON into CEL input: objects become maps. */
+export function toCel(v) {
+    if (Array.isArray(v))
+        return v.map(toCel);
+    if (v !== null && typeof v === "object") {
+        return new Map(Object.entries(v).map(([k, x]) => [k, toCel(x)]));
+    }
+    return v;
+}

package/dist/engine.d.ts

@@ -0,0 +1,27 @@
+import { type Answers } from "./cel/env.ts";
+import { Program } from "./program.ts";
+import { type Answer, type Client, type Question } from "./typesafe/client.ts";
+export declare const NO_KEY = "no Jev API key: set TYPESAFE_API_KEY (or JEV_API_KEY)";
+/**
+ * What every program shares: the Jev client, an answer cache (the same
+ * question on the same material is asked once), and counters.
+ */
+export declare class Engine implements Answers {
+    readonly client: Client;
+    readonly stats: {
+        calls: number;
+        cacheHits: number;
+        tokens: number;
+    };
+    /** The first error retrying cannot fix (no key, a refused key). */
+    fatal: Error | undefined;
+    private readonly answers;
+    private readonly inflight;
+    constructor(client: Client);
+    get model(): string;
+    /** Compiles a rule (must yield true or false) or a key (anything); throws a RuleError when it cannot work. */
+    compile(source: string, kind?: "rule" | "key"): Program;
+    cached(key: string): Answer | undefined;
+    /** Asks one question unless its answer is known or on its way; reports whether this call asked. */
+    ask(key: string, state: unknown, q: Question, signal?: AbortSignal): Promise<boolean>;
+}

package/dist/engine.js

@@ -0,0 +1,79 @@
+import { parse, plan } from "@bufbuild/cel";
+import { checkParsed, checkPlanned, HINT, RuleError } from "./cel/check.js";
+import { env } from "./cel/env.js";
+import { Program } from "./program.js";
+import { HttpError } from "./typesafe/client.js";
+export const NO_KEY = "no Jev API key: set TYPESAFE_API_KEY (or JEV_API_KEY)";
+/**
+ * What every program shares: the Jev client, an answer cache (the same
+ * question on the same material is asked once), and counters.
+ */
+export class Engine {
+    client;
+    stats = { calls: 0, cacheHits: 0, tokens: 0 };
+    /** The first error retrying cannot fix (no key, a refused key). */
+    fatal;
+    answers = new Map();
+    inflight = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    get model() {
+        return this.client.model;
+    }
+    /** Compiles a rule (must yield true or false) or a key (anything); throws a RuleError when it cannot work. */
+    compile(source, kind = "rule") {
+        const text = source.trim();
+        if (!text)
+            throw new RuleError(`the ${kind} is empty`);
+        let parsed;
+        try {
+            parsed = parse(text);
+        }
+        catch (err) {
+            throw new RuleError(`${err.message}\n\n${HINT}`);
+        }
+        checkParsed(parsed.expr, kind);
+        const run = plan(env, parsed);
+        checkPlanned(run, kind);
+        return new Program(this, text, run);
+    }
+    cached(key) {
+        return this.answers.get(key);
+    }
+    /** Asks one question unless its answer is known or on its way; reports whether this call asked. */
+    async ask(key, state, q, signal) {
+        if (this.fatal)
+            throw this.fatal;
+        if (this.answers.has(key))
+            return false;
+        const running = this.inflight.get(key);
+        if (running) {
+            await running;
+            return false;
+        }
+        if (!this.client.apiKey)
+            throw (this.fatal = new Error(NO_KEY));
+        const request = (async () => {
+            this.stats.calls++;
+            const res = await this.client.ask(state, { q }, signal);
+            this.stats.tokens += res.usage?.input_tokens ?? 0;
+            return res.answers.q;
+        })();
+        this.inflight.set(key, request);
+        try {
+            this.answers.set(key, await request);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.fatal) {
+                this.fatal ??= new Error(`Jev refused the request (${err.message}) — check the API key and the judge arguments`);
+                throw this.fatal;
+            }
+            throw err;
+        }
+        finally {
+            this.inflight.delete(key);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Engine, NO_KEY } from "./engine.ts";
+export { Program } from "./program.ts";
+export { RuleError, isRuleBug } from "./cel/check.ts";
+export { toCel, fromCel } from "./cel/values.ts";
+export { clip, cutLongStrings, fingerprint, parseRecord } from "./text.ts";
+export { Client, HttpError, DEFAULT_BASE_URL, DEFAULT_MODEL, type Answer, type Question, type QuestionType, type Result } from "./typesafe/client.ts";
+export type { Bindings, Call, Outcome } from "./types.ts";
+export type { CelInput } from "@bufbuild/cel";

package/dist/index.js

@@ -0,0 +1,11 @@
+// @jevable/core: compile a rule once, match records against it.
+//
+//   const engine = new Engine(new Client({ apiKey: process.env.TYPESAFE_API_KEY }));
+//   const rule = engine.compile(`judge.boolean(line, "Is this an outage?") >= 0.7`);
+//   const { pass, calls } = await rule.match({ line: "checkout returns 500 for everyone" });
+export { Engine, NO_KEY } from "./engine.js";
+export { Program } from "./program.js";
+export { RuleError, isRuleBug } from "./cel/check.js";
+export { toCel, fromCel } from "./cel/values.js";
+export { clip, cutLongStrings, fingerprint, parseRecord } from "./text.js";
+export { Client, HttpError, DEFAULT_BASE_URL, DEFAULT_MODEL } from "./typesafe/client.js";

package/dist/program.d.ts

@@ -0,0 +1,21 @@
+import { type Planned } from "./cel/env.ts";
+import type { Engine } from "./engine.ts";
+import type { Bindings, Outcome } from "./types.ts";
+/** A compiled rule or key expression. Safe to share between concurrent evaluations. */
+export declare class Program {
+    readonly source: string;
+    private readonly engine;
+    private readonly run;
+    constructor(engine: Engine, source: string, run: Planned);
+    /** Evaluates a rule. An evaluation error (a missing field, a failed judge call) means no pass. */
+    match(vars: Bindings, signal?: AbortSignal): Promise<Outcome>;
+    /** Evaluates a key: strings as they are, anything else as JSON. */
+    key(vars: Bindings, signal?: AbortSignal): Promise<string>;
+    /**
+     * Evaluates in passes until no question is missing: each pass that lacks
+     * an answer asks for it, and the next pass starts over with it known. Plain
+     * conditions that decide the rule first mean a question is never reached,
+     * so never asked.
+     */
+    private evaluate;
+}

package/dist/program.js

@@ -0,0 +1,61 @@
+import { isCelError } from "@bufbuild/cel";
+import { evaluateWith } from "./cel/env.js";
+import { describe } from "./cel/check.js";
+import { fromCel } from "./cel/values.js";
+/** A compiled rule or key expression. Safe to share between concurrent evaluations. */
+export class Program {
+    source;
+    engine;
+    run;
+    constructor(engine, source, run) {
+        this.engine = engine;
+        this.source = source;
+        this.run = run;
+    }
+    /** Evaluates a rule. An evaluation error (a missing field, a failed judge call) means no pass. */
+    async match(vars, signal) {
+        const r = await this.evaluate(vars, signal);
+        if (r.error)
+            return { pass: false, calls: r.calls, error: r.error };
+        if (typeof r.out !== "boolean")
+            return { pass: false, calls: r.calls, error: new Error(`rule yielded ${describe(r.out)}, not true or false`) };
+        return { pass: r.out, calls: r.calls };
+    }
+    /** Evaluates a key: strings as they are, anything else as JSON. */
+    async key(vars, signal) {
+        const r = await this.evaluate(vars, signal);
+        if (r.error)
+            throw r.error;
+        return typeof r.out === "string" ? r.out : JSON.stringify(fromCel(r.out));
+    }
+    /**
+     * Evaluates in passes until no question is missing: each pass that lacks
+     * an answer asks for it, and the next pass starts over with it known. Plain
+     * conditions that decide the rule first mean a question is never reached,
+     * so never asked.
+     */
+    async evaluate(vars, signal) {
+        const ctx = { line: vars.line ?? "", json: vars.json ?? null, window: vars.window ?? null };
+        const fetched = new Set();
+        for (let round = 0; round < 64; round++) {
+            const pass = { answers: this.engine, calls: [], keys: [] };
+            const out = evaluateWith(pass, this.run, ctx);
+            if (!pass.pending) {
+                for (const k of pass.keys)
+                    if (!fetched.has(k))
+                        this.engine.stats.cacheHits++;
+                if (isCelError(out))
+                    return { calls: pass.calls, error: new Error(out.message) };
+                return { out, calls: pass.calls };
+            }
+            try {
+                if (await this.engine.ask(pass.pending.key, pass.pending.state, pass.pending.q, signal))
+                    fetched.add(pass.pending.key);
+            }
+            catch (err) {
+                return { calls: pass.calls, error: err };
+            }
+        }
+        return { calls: [], error: new Error("rule asked too many questions") };
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,18 @@
+import { Engine } from "./engine.ts";
+import { type Answer, type Question } from "./typesafe/client.ts";
+/** Decides one answer; state is the request's state as JSON (a string material arrives quoted). */
+export type Answerer = (state: string, q: Question) => Omit<Answer, "type">;
+export interface FakeJev {
+    url: string;
+    /** Requests received so far. */
+    calls(): number;
+    /** A fresh engine talking to this fake with the key it accepts. */
+    engine(): Engine;
+    close(): Promise<void>;
+}
+/** The API key the fake accepts; any other is refused with 401. */
+export declare const FAKE_KEY = "test-key";
+/** Starts a fake that bills 10 tokens per request. */
+export declare function fakeJev(answer: Answerer): Promise<FakeJev>;
+/** Answers yes (0.9) when the material mentions "outage", else 0.1; choice and score likewise. */
+export declare const outage: Answerer;

package/dist/testing.js

@@ -0,0 +1,46 @@
+// A fake System One endpoint for tests: @jevable/core/testing.
+import { createServer } from "node:http";
+import { Engine } from "./engine.js";
+import { Client } from "./typesafe/client.js";
+/** The API key the fake accepts; any other is refused with 401. */
+export const FAKE_KEY = "test-key";
+/** Starts a fake that bills 10 tokens per request. */
+export async function fakeJev(answer) {
+    let calls = 0;
+    const server = createServer((req, res) => {
+        calls++;
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+            if (req.headers.authorization !== `Bearer ${FAKE_KEY}`) {
+                res.writeHead(401).end('{"error":"invalid api key"}');
+                return;
+            }
+            const { state, model, questions } = JSON.parse(body);
+            const answers = {};
+            for (const [k, q] of Object.entries(questions))
+                answers[k] = { type: q.type, ...answer(JSON.stringify(state), q) };
+            res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ model, answers, usage: { input_tokens: 10, output_tokens: 0 } }));
+        });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const url = `http://127.0.0.1:${server.address().port}`;
+    return {
+        url,
+        calls: () => calls,
+        engine: () => new Engine(new Client({ apiKey: FAKE_KEY, baseUrl: url })),
+        close: () => new Promise((r) => {
+            server.closeAllConnections();
+            server.close(() => r());
+        }),
+    };
+}
+/** Answers yes (0.9) when the material mentions "outage", else 0.1; choice and score likewise. */
+export const outage = (state, q) => {
+    const hit = state.includes("outage");
+    if (q.type === "choice")
+        return { probabilities: hit ? { infra: 0.8, other: 0.2 } : { infra: 0.1, other: 0.9 } };
+    if (q.type === "score")
+        return { score: hit ? 1.8 : 0.2 };
+    return { noul: hit ? 0.9 : 0.1 };
+};

package/dist/text.d.ts

@@ -0,0 +1,14 @@
+/** One input line: the text, and the parsed value when the line is JSON. */
+export declare function parseRecord(line: string): {
+    line: string;
+    json: unknown;
+};
+export declare function cutLongStrings(v: unknown): unknown;
+/**
+ * Reduces a line to its kind: quoted strings, numbers and id-like tokens
+ * (anything containing a digit) become placeholders, so `timeout after
+ * 3012ms on req_8f2a` and `timeout after 95ms on req_77c1` share a
+ * fingerprint. Numbers are gone afterwards — compare them in plain CEL.
+ */
+export declare function fingerprint(s: string): string;
+export declare function clip(s: string, n: number): string;

package/dist/text.js

@@ -0,0 +1,55 @@
+// Plain-text helpers shared by the engine and its callers.
+/** One input line: the text, and the parsed value when the line is JSON. */
+export function parseRecord(line) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) {
+        try {
+            return { line, json: JSON.parse(t) };
+        }
+        catch {
+            // not JSON after all
+        }
+    }
+    return { line, json: null };
+}
+// Each string sent to Jev is bounded; longer ones keep their head and tail,
+// where the question and the verdict of a long text usually sit.
+const MAX_STRING_CHARS = 2000;
+export function cutLongStrings(v) {
+    if (typeof v === "string") {
+        const chars = Array.from(v);
+        if (chars.length <= MAX_STRING_CHARS)
+            return v;
+        return chars.slice(0, 1500).join("") + " […] " + chars.slice(-500).join("");
+    }
+    if (Array.isArray(v))
+        return v.map(cutLongStrings);
+    if (v !== null && typeof v === "object") {
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cutLongStrings(x)]));
+    }
+    return v;
+}
+const QUOTED = /"[^"]*"|'[^']*'/g;
+const TOKEN = /[A-Za-z0-9_.:\-]*[0-9][A-Za-z0-9_.:\-]*/g;
+const NUMBER = /^-?[0-9]+(\.[0-9]+)?([A-Za-z%]{0,3})$/;
+/**
+ * Reduces a line to its kind: quoted strings, numbers and id-like tokens
+ * (anything containing a digit) become placeholders, so `timeout after
+ * 3012ms on req_8f2a` and `timeout after 95ms on req_77c1` share a
+ * fingerprint. Numbers are gone afterwards — compare them in plain CEL.
+ */
+export function fingerprint(s) {
+    return s
+        .replace(QUOTED, '"<s>"')
+        .replace(TOKEN, (tok) => {
+        const m = NUMBER.exec(tok);
+        return m ? `<n>${m[2]}` : "<id>";
+    })
+        .split(/\s+/)
+        .filter(Boolean)
+        .join(" ");
+}
+export function clip(s, n) {
+    const chars = Array.from(s);
+    return chars.length <= n ? s : chars.slice(0, n).join("") + "…";
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type { CelInput } from "@bufbuild/cel";
+/** One judge question asked while evaluating a rule, and its answer. */
+export interface Call {
+    fn: "boolean" | "choice" | "score";
+    question: string;
+    /** boolean: probability of yes; score: weighted level. */
+    value?: number;
+    /** choice: probability of each option. */
+    options?: Record<string, number>;
+}
+/** The variables a rule sees; missing ones are empty. */
+export interface Bindings {
+    line?: string;
+    json?: CelInput;
+    window?: CelInput;
+}
+export interface Outcome {
+    pass: boolean;
+    calls: Call[];
+    error?: Error;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/typesafe/client.d.ts

@@ -0,0 +1,48 @@
+export declare const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+export declare const DEFAULT_MODEL = "jev-1.13.0";
+export type QuestionType = "noul" | "choice" | "score";
+/**
+ * One typed question. Criteria: noul — undefined or {true, false};
+ * choice — option → description (or null); score — ordered level list.
+ */
+export interface Question {
+    type: QuestionType;
+    instructions: string;
+    criteria?: unknown;
+}
+export interface Answer {
+    type: QuestionType;
+    noul?: number;
+    choice?: string;
+    score?: number;
+    probabilities?: Record<string, number>;
+    confidence?: number;
+}
+export interface Result {
+    model: string;
+    answers: Record<string, Answer>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+/** A non-2xx answer from the API. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+    /** Retrying cannot help: a bad key or a malformed request. */
+    get fatal(): boolean;
+}
+export declare class Client {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly model: string;
+    constructor(opts?: {
+        apiKey?: string;
+        baseUrl?: string;
+        model?: string;
+    });
+    /** Evaluates every question against state in one call, retrying once on anything but a fatal error. */
+    ask(state: unknown, questions: Record<string, Question>, signal?: AbortSignal): Promise<Result>;
+    private request;
+}

package/dist/typesafe/client.js

@@ -0,0 +1,59 @@
+// A minimal client for TypeSafe's System One endpoint
+// (https://docs.typesafe.ai/api): one state, a map of typed questions, one
+// typed answer per question.
+export const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+// Pinned rather than `jev-latest`: thresholds are tuned against one model,
+// and an alias moves without a change on our side.
+export const DEFAULT_MODEL = "jev-1.13.0";
+/** A non-2xx answer from the API. */
+export class HttpError extends Error {
+    status;
+    constructor(status, body) {
+        super(`typesafe API returned ${status}: ${body.slice(0, 512)}`);
+        this.status = status;
+    }
+    /** Retrying cannot help: a bad key or a malformed request. */
+    get fatal() {
+        return this.status === 401 || this.status === 403 || this.status === 422;
+    }
+}
+export class Client {
+    baseUrl;
+    apiKey;
+    model;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey ?? "";
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.model = opts.model || DEFAULT_MODEL;
+    }
+    /** Evaluates every question against state in one call, retrying once on anything but a fatal error. */
+    async ask(state, questions, signal) {
+        try {
+            return await this.request(state, questions, signal);
+        }
+        catch (err) {
+            if ((err instanceof HttpError && err.fatal) || signal?.aborted)
+                throw err;
+            await new Promise((r) => setTimeout(r, 1000));
+            return this.request(state, questions, signal);
+        }
+    }
+    async request(state, questions, signal) {
+        const timeout = AbortSignal.timeout(15_000);
+        const res = await fetch(`${this.baseUrl}/v1/systemone`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ state, model: this.model, questions }),
+            signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new HttpError(res.status, text);
+        const out = JSON.parse(text);
+        for (const key of Object.keys(questions)) {
+            if (!out.answers?.[key])
+                throw new Error(`typesafe: answer ${JSON.stringify(key)} missing`);
+        }
+        return out;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@jevable/core",
+  "version": "0.1.0",
+  "description": "The jev rule engine: CEL rules that ask Jev, TypeSafe's classification model, semantic questions",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "development": "./src/testing.ts",
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --conditions=development --test test/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@bufbuild/cel": "0.6.1"
+  },
+  "license": "MIT"
+}