cerno-sdk 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# cerno-sdk
+
+Three kinds of question about a piece of text, answered by a locally hosted model:
+
+- **noul** — how likely is the answer yes
+- **choice** — which one of up to 20 options
+- **score** — where on a rubric of 2–10 levels
+
+Each question is one forward pass, so answers come back in tens of milliseconds.
+
+```bash
+npm install cerno-sdk
+```
+
+```ts
+import { Client } from "cerno-sdk";
+
+const client = new Client("http://localhost:3000");
+
+const answers = await client
+  .systemone("Ticket: server room at 31C, rising, servers throttling.")
+  .noul("urgent", "Is this urgent?")
+  .choice("team", "Which team?", ["IT", "Facility", "HR"])
+  .score("sev", "How severe?", ["harmless", "minor", "moderate", "high", "critical"])
+  .send();
+
+answers.noul("urgent");     // 0.991
+answers.choice("team");     // "Facility"
+answers.score("sev");       // 5
+answers.legend("sev");      // "critical"
+answers.confidence("team"); // 0.939
+```
+
+Questions in one call share their state, so the text is sent and prefilled once.
+
+A choice whose options speak for themselves takes two arguments:
+
+```ts
+.choice("mood", ["positive", "neutral", "negative"])
+```
+
+## Reading the answer honestly
+
+Every answer carries the evidence it came from:
+
+```ts
+answers.truncated("team");            // a label fell outside the host's reporting window
+answers.truncatedLabels("team");      // ["C"] — which ones; their raw_logprobs entry is a bound
+answers.get("team").raw_logprobs;     // { A: -4.54, B: -0.02, ... }
+answers.get("team").probabilities;    // per option, in request order
+```
+
+`truncated` is worth checking when you act on a probability rather than on the winner: it means
+at least one option ranked below everything the host reported, so its probability is an upper
+bound, not an observation.
+
+To flatten an overconfident model, scale the logits before they are normalised:
+
+```ts
+await client.systemone(text).calibration(2.5).noul("urgent", "Is this urgent?").send();
+```
+
+Above 1 flattens, below 1 sharpens, and `raw_logprobs` is unaffected either way.
+
+`answers.get(id)` is a discriminated union, so narrowing on `type` gives you the full shape:
+
+```ts
+const answer = answers.get("team");
+if (answer.type === "choice") {
+  answer.probabilities[0].option; // typed
+}
+```
+
+## Errors
+
+```ts
+import { ApiError } from "cerno-sdk";
+
+try {
+  await client.systemone(text).choice("team", "Which?", options).send();
+} catch (err) {
+  if (err instanceof ApiError) {
+    err.code;       // "too_many_options" — branch on this, never on the message
+    err.questionId; // "team"
+  }
+}
+```
+
+`UnexpectedResponse` is thrown instead when a non-2xx body is not a cerno error at all, which
+usually means a proxy between you and the service. `TransportError` means the service could not
+be reached or did not answer within `timeoutMs`; the original error is its `cause`. All three
+extend `CernoError`.
+
+## Options
+
+```ts
+new Client({
+  baseUrl: "http://localhost:3000",
+  timeoutMs: 60_000,
+  headers: { "x-request-id": id },
+  fetch: customFetch, // injected for testing or custom transports
+});
+```

package/dist/cjs/answers.d.ts

@@ -0,0 +1,43 @@
+import type { Answer, SystemOneResponse, Usage } from "./types.ts";
+/**
+ * The answers to one request, with accessors that fail loudly on the wrong id or type.
+ *
+ * Reaching for `noul("team")` when `team` was a choice is a programming mistake, not a runtime
+ * condition, so it throws rather than handing back a default.
+ */
+export declare class Answers {
+    readonly model: string;
+    readonly usage: Usage;
+    readonly timingMs: number;
+    private readonly response;
+    constructor(response: SystemOneResponse);
+    /** The raw answer for `id`. */
+    get(id: string): Answer;
+    ids(): string[];
+    /** Probability that the answer to `id` is yes. */
+    noul(id: string): number;
+    /** The winning option for `id`. */
+    choice(id: string): string;
+    /** The winning option's position in the request. */
+    index(id: string): number;
+    /** The winning level for `id`, 1-based. */
+    score(id: string): number;
+    /** The probability-weighted mean level for `id`. */
+    expectedScore(id: string): number;
+    legend(id: string): string;
+    /**
+     * How peaked the distribution behind `id` was, in 0..=1. A noul has none, as in JEV: its
+     * probability is already the whole answer.
+     */
+    confidence(id: string): number;
+    /**
+     * Whether some label for `id` fell outside the host's reporting window. When true, that
+     * label's probability is an upper bound rather than an observation.
+     */
+    truncated(id: string): boolean;
+    /** The labels for `id` whose logprob is an upper bound rather than an observation. */
+    truncatedLabels(id: string): string[];
+    /** The response exactly as the service sent it. */
+    raw(): SystemOneResponse;
+    private typed;
+}

package/dist/cjs/answers.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Answers = void 0;
+const errors_ts_1 = require("./errors.js");
+/**
+ * The answers to one request, with accessors that fail loudly on the wrong id or type.
+ *
+ * Reaching for `noul("team")` when `team` was a choice is a programming mistake, not a runtime
+ * condition, so it throws rather than handing back a default.
+ */
+class Answers {
+    model;
+    usage;
+    timingMs;
+    // Declared explicitly rather than as a constructor parameter property: Node's native
+    // type-stripping does not support those, and the test suite runs the sources directly.
+    response;
+    constructor(response) {
+        this.response = response;
+        this.model = response.model;
+        this.usage = response.usage;
+        this.timingMs = response.timing_ms.total;
+    }
+    /** The raw answer for `id`. */
+    get(id) {
+        const answer = this.response.answers[id];
+        if (answer === undefined)
+            throw new errors_ts_1.MissingAnswer(id);
+        return answer;
+    }
+    ids() {
+        return Object.keys(this.response.answers);
+    }
+    /** Probability that the answer to `id` is yes. */
+    noul(id) {
+        return this.typed(id, "noul").noul;
+    }
+    /** The winning option for `id`. */
+    choice(id) {
+        return this.typed(id, "choice").choice;
+    }
+    /** The winning option's position in the request. */
+    index(id) {
+        return this.typed(id, "choice").index;
+    }
+    /** The winning level for `id`, 1-based. */
+    score(id) {
+        return this.typed(id, "score").score;
+    }
+    /** The probability-weighted mean level for `id`. */
+    expectedScore(id) {
+        return this.typed(id, "score").expected_score;
+    }
+    legend(id) {
+        return this.typed(id, "score").legend;
+    }
+    /**
+     * How peaked the distribution behind `id` was, in 0..=1. A noul has none, as in JEV: its
+     * probability is already the whole answer.
+     */
+    confidence(id) {
+        const answer = this.get(id);
+        if (answer.type === "noul") {
+            throw new errors_ts_1.WrongAnswerType(id, "choice or score", answer.type);
+        }
+        return answer.confidence;
+    }
+    /**
+     * Whether some label for `id` fell outside the host's reporting window. When true, that
+     * label's probability is an upper bound rather than an observation.
+     */
+    truncated(id) {
+        return this.get(id).truncated;
+    }
+    /** The labels for `id` whose logprob is an upper bound rather than an observation. */
+    truncatedLabels(id) {
+        return this.get(id).truncated_labels ?? [];
+    }
+    /** The response exactly as the service sent it. */
+    raw() {
+        return this.response;
+    }
+    typed(id, expected) {
+        const answer = this.get(id);
+        if (answer.type !== expected) {
+            throw new errors_ts_1.WrongAnswerType(id, expected, answer.type);
+        }
+        return answer;
+    }
+}
+exports.Answers = Answers;

package/dist/cjs/builder.d.ts

@@ -0,0 +1,31 @@
+import type { Answers } from "./answers.ts";
+import type { LevelSpec, SystemOneRequest } from "./types.ts";
+/** A request under construction. Chain questions onto it, then `send()`. */
+export declare class SystemOneBuilder {
+    private readonly request;
+    private readonly dispatch;
+    constructor(state: string, dispatch: (body: SystemOneRequest) => Promise<Answers>);
+    /** Name a model or a configured alias. The service's default applies otherwise. */
+    model(model: string): this;
+    /** Scale the label logits before normalising. Above 1 flattens, below 1 sharpens. */
+    calibration(temperature: number): this;
+    /** How likely the answer to `question` is yes. */
+    noul(id: string, question: string): this;
+    /**
+     * One of `options`.
+     *
+     * Called with two arguments the options come second and no question is sent, which is the
+     * right shape when the options speak for themselves.
+     */
+    choice(id: string, question: string, options: string[]): this;
+    choice(id: string, options: string[]): this;
+    /** A position on a rubric: a number for generated levels, or the level texts. */
+    score(id: string, question: string, levels: LevelSpec): this;
+    /**
+     * The request as it will be sent. Useful for logging, and for testing a chain without a
+     * server.
+     */
+    body(): SystemOneRequest;
+    send(): Promise<Answers>;
+    private push;
+}

package/dist/cjs/builder.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemOneBuilder = void 0;
+/** A request under construction. Chain questions onto it, then `send()`. */
+class SystemOneBuilder {
+    request;
+    dispatch;
+    constructor(state, dispatch) {
+        this.request = { state, questions: [] };
+        this.dispatch = dispatch;
+    }
+    /** Name a model or a configured alias. The service's default applies otherwise. */
+    model(model) {
+        this.request.model = model;
+        return this;
+    }
+    /** Scale the label logits before normalising. Above 1 flattens, below 1 sharpens. */
+    calibration(temperature) {
+        this.request.calibration = { temperature };
+        return this;
+    }
+    /** How likely the answer to `question` is yes. */
+    noul(id, question) {
+        return this.push({ id, noul: question });
+    }
+    choice(id, second, third) {
+        const options = third ?? second;
+        const question = third === undefined ? undefined : second;
+        return this.push({
+            id,
+            choice: question === undefined ? { options } : { question, options },
+        });
+    }
+    /** A position on a rubric: a number for generated levels, or the level texts. */
+    score(id, question, levels) {
+        return this.push({ id, score: { question, levels } });
+    }
+    /**
+     * The request as it will be sent. Useful for logging, and for testing a chain without a
+     * server.
+     */
+    body() {
+        return this.request;
+    }
+    send() {
+        return this.dispatch(this.request);
+    }
+    push(question) {
+        this.request.questions.push(question);
+        return this;
+    }
+}
+exports.SystemOneBuilder = SystemOneBuilder;

package/dist/cjs/client.d.ts

@@ -0,0 +1,39 @@
+import { SystemOneBuilder } from "./builder.ts";
+import type { ModelsResponse, SystemOneRequest } from "./types.ts";
+export interface ClientOptions {
+    /** Defaults to `http://localhost:3000`. */
+    baseUrl?: string;
+    /** Milliseconds before a request is aborted. Defaults to 60000. */
+    timeoutMs?: number;
+    /** Sent with every request. */
+    headers?: Record<string, string>;
+    /** Injected for testing, or to route through a custom transport. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Client for the cerno service.
+ *
+ * ```ts
+ * const client = new Client({ baseUrl: "http://localhost:3000" });
+ * const answers = await client
+ *   .systemone("Ticket: server room at 31C, rising.")
+ *   .noul("urgent", "Is this urgent?")
+ *   .choice("team", "Which team?", ["IT", "Facility", "HR"])
+ *   .send();
+ * ```
+ */
+export declare class Client {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly doFetch;
+    constructor(options?: ClientOptions | string);
+    /** Start a request about `state`. */
+    systemone(state: string): SystemOneBuilder;
+    /** The models this service will answer for. */
+    models(): Promise<ModelsResponse>;
+    /** Whether the service is up. False, not an error, when it cannot be reached in time. */
+    health(): Promise<boolean>;
+    private request;
+}
+export type { SystemOneRequest };

package/dist/cjs/client.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+const answers_ts_1 = require("./answers.js");
+const builder_ts_1 = require("./builder.js");
+const errors_ts_1 = require("./errors.js");
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Client for the cerno service.
+ *
+ * ```ts
+ * const client = new Client({ baseUrl: "http://localhost:3000" });
+ * const answers = await client
+ *   .systemone("Ticket: server room at 31C, rising.")
+ *   .noul("urgent", "Is this urgent?")
+ *   .choice("team", "Which team?", ["IT", "Facility", "HR"])
+ *   .send();
+ * ```
+ */
+class Client {
+    baseUrl;
+    timeoutMs;
+    headers;
+    doFetch;
+    constructor(options = {}) {
+        const opts = typeof options === "string" ? { baseUrl: options } : options;
+        this.baseUrl = (opts.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.headers = opts.headers ?? {};
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+    }
+    /** Start a request about `state`. */
+    systemone(state) {
+        return new builder_ts_1.SystemOneBuilder(state, async (body) => {
+            const response = await this.request("POST", "/v1/systemone", body);
+            return new answers_ts_1.Answers(response);
+        });
+    }
+    /** The models this service will answer for. */
+    models() {
+        return this.request("GET", "/v1/models");
+    }
+    /** Whether the service is up. False, not an error, when it cannot be reached in time. */
+    async health() {
+        try {
+            const response = await this.doFetch(`${this.baseUrl}/health`, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async request(method, path, body) {
+        // An explicit abort, so a wedged host surfaces as a timeout rather than hanging forever.
+        const abort = AbortSignal.timeout(this.timeoutMs);
+        let response;
+        let text;
+        try {
+            response = await this.doFetch(`${this.baseUrl}${path}`, {
+                method,
+                signal: abort,
+                headers: {
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    ...this.headers,
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            text = await response.text();
+        }
+        catch (err) {
+            throw new errors_ts_1.TransportError(`could not reach cerno: ${String(err)}`, err);
+        }
+        if (response.ok) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new errors_ts_1.UnexpectedResponse(response.status, text);
+            }
+        }
+        let parsed;
+        try {
+            const candidate = JSON.parse(text);
+            if (candidate && typeof candidate.code === "string")
+                parsed = candidate;
+        }
+        catch {
+            // Falls through to UnexpectedResponse below.
+        }
+        // Not our error shape, so do not pretend to know what went wrong.
+        if (!parsed)
+            throw new errors_ts_1.UnexpectedResponse(response.status, text);
+        throw new errors_ts_1.ApiError(response.status, parsed);
+    }
+}
+exports.Client = Client;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,37 @@
+import type { ErrorCode, ErrorResponse } from "./types.ts";
+export declare class CernoError extends Error {
+}
+/**
+ * The service answered with a structured failure.
+ *
+ * Branch on `code`, never on `message` — the codes are the contract, the prose is not.
+ */
+export declare class ApiError extends CernoError {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly questionId?: string;
+    constructor(status: number, body: ErrorResponse);
+}
+/**
+ * The service could not be reached, or did not answer within the timeout. The error `fetch`
+ * threw is kept as `cause`.
+ */
+export declare class TransportError extends CernoError {
+    constructor(message: string, cause: unknown);
+}
+/** A non-2xx response that was not shaped like a cerno error — a proxy, most likely. */
+export declare class UnexpectedResponse extends CernoError {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export declare class MissingAnswer extends CernoError {
+    readonly questionId: string;
+    constructor(questionId: string);
+}
+export declare class WrongAnswerType extends CernoError {
+    readonly questionId: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(questionId: string, expected: string, actual: string);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrongAnswerType = exports.MissingAnswer = exports.UnexpectedResponse = exports.TransportError = exports.ApiError = exports.CernoError = void 0;
+class CernoError extends Error {
+}
+exports.CernoError = CernoError;
+/**
+ * The service answered with a structured failure.
+ *
+ * Branch on `code`, never on `message` — the codes are the contract, the prose is not.
+ */
+class ApiError extends CernoError {
+    status;
+    code;
+    questionId;
+    constructor(status, body) {
+        super(`cerno returned ${status} (${body.code}): ${body.message}`);
+        this.name = "ApiError";
+        this.status = status;
+        this.code = body.code;
+        this.questionId = body.question_id;
+    }
+}
+exports.ApiError = ApiError;
+/**
+ * The service could not be reached, or did not answer within the timeout. The error `fetch`
+ * threw is kept as `cause`.
+ */
+class TransportError extends CernoError {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = "TransportError";
+    }
+}
+exports.TransportError = TransportError;
+/** A non-2xx response that was not shaped like a cerno error — a proxy, most likely. */
+class UnexpectedResponse extends CernoError {
+    status;
+    body;
+    constructor(status, body) {
+        super(`cerno returned ${status}: ${body.slice(0, 200)}`);
+        this.name = "UnexpectedResponse";
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.UnexpectedResponse = UnexpectedResponse;
+class MissingAnswer extends CernoError {
+    questionId;
+    constructor(questionId) {
+        super(`no answer for question ${JSON.stringify(questionId)}`);
+        this.name = "MissingAnswer";
+        this.questionId = questionId;
+    }
+}
+exports.MissingAnswer = MissingAnswer;
+class WrongAnswerType extends CernoError {
+    questionId;
+    expected;
+    actual;
+    constructor(questionId, expected, actual) {
+        super(`question ${JSON.stringify(questionId)} answered with a ${actual}, not a ${expected}`);
+        this.name = "WrongAnswerType";
+        this.questionId = questionId;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+exports.WrongAnswerType = WrongAnswerType;

package/dist/cjs/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TypeScript client for cerno.
+ *
+ * cerno answers three kinds of question about a piece of text — is it true (`noul`), which one
+ * is it (`choice`), where on a scale does it sit (`score`) — using a locally hosted model. Each
+ * question is one forward pass, so answers come back in tens of milliseconds.
+ */
+export { Answers } from "./answers.ts";
+export { SystemOneBuilder } from "./builder.ts";
+export { Client, type ClientOptions } from "./client.ts";
+export { ApiError, CernoError, MissingAnswer, TransportError, UnexpectedResponse, WrongAnswerType, } from "./errors.ts";
+export type * from "./types.ts";

package/dist/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * TypeScript client for cerno.
+ *
+ * cerno answers three kinds of question about a piece of text — is it true (`noul`), which one
+ * is it (`choice`), where on a scale does it sit (`score`) — using a locally hosted model. Each
+ * question is one forward pass, so answers come back in tens of milliseconds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrongAnswerType = exports.UnexpectedResponse = exports.TransportError = exports.MissingAnswer = exports.CernoError = exports.ApiError = exports.Client = exports.SystemOneBuilder = exports.Answers = void 0;
+var answers_ts_1 = require("./answers.js");
+Object.defineProperty(exports, "Answers", { enumerable: true, get: function () { return answers_ts_1.Answers; } });
+var builder_ts_1 = require("./builder.js");
+Object.defineProperty(exports, "SystemOneBuilder", { enumerable: true, get: function () { return builder_ts_1.SystemOneBuilder; } });
+var client_ts_1 = require("./client.js");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_ts_1.Client; } });
+var errors_ts_1 = require("./errors.js");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_ts_1.ApiError; } });
+Object.defineProperty(exports, "CernoError", { enumerable: true, get: function () { return errors_ts_1.CernoError; } });
+Object.defineProperty(exports, "MissingAnswer", { enumerable: true, get: function () { return errors_ts_1.MissingAnswer; } });
+Object.defineProperty(exports, "TransportError", { enumerable: true, get: function () { return errors_ts_1.TransportError; } });
+Object.defineProperty(exports, "UnexpectedResponse", { enumerable: true, get: function () { return errors_ts_1.UnexpectedResponse; } });
+Object.defineProperty(exports, "WrongAnswerType", { enumerable: true, get: function () { return errors_ts_1.WrongAnswerType; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}