cerno-sdk 0.1.0

package/dist/cjs/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Wire types for the cerno API.
+ *
+ * These mirror `spec/openapi.json` exactly. A change here without a change there is a bug.
+ */
+/** Temperature scaling applied to label logits before the softmax. */
+export interface Calibration {
+    /** 1 leaves the model's own distribution alone; above 1 flattens, below 1 sharpens. */
+    temperature: number;
+}
+export interface ChoiceSpec {
+    question?: string;
+    options: string[];
+}
+/** A rubric given either as a plain count or as the text of each level, lowest first. */
+export type LevelSpec = number | string[];
+export interface ScoreSpec {
+    question?: string;
+    levels: LevelSpec;
+}
+export type Question = {
+    id: string;
+    noul: string;
+} | {
+    id: string;
+    choice: ChoiceSpec;
+} | {
+    id: string;
+    score: ScoreSpec;
+};
+export interface SystemOneRequest {
+    state: string;
+    model?: string;
+    calibration?: Calibration;
+    questions: Question[];
+}
+export interface OptionProbability {
+    option: string;
+    probability: number;
+}
+export interface LevelProbability {
+    level: number;
+    legend: string;
+    probability: number;
+}
+interface AnswerBase {
+    /**
+     * The logprob fed into the softmax, per label. A floor substitution appears here like any
+     * other value; `truncated` is what says one happened.
+     */
+    raw_logprobs: Record<string, number>;
+    /**
+     * Whether some label fell outside the host's reporting window, which makes its probability
+     * an upper bound rather than an observation.
+     */
+    truncated: boolean;
+    /**
+     * The labels whose `raw_logprobs` entry is an upper bound rather than an observation. Empty
+     * unless `truncated`. A server predating this field omits it; `Answers.truncatedLabels` reads
+     * that as empty.
+     */
+    truncated_labels?: string[];
+}
+export interface NoulAnswer extends AnswerBase {
+    type: "noul";
+    /** Probability that the answer is yes. */
+    noul: number;
+}
+export interface ChoiceAnswer extends AnswerBase {
+    type: "choice";
+    choice: string;
+    /** How peaked the distribution was, in 0..=1. */
+    confidence: number;
+    /** The winning option's position in the request. */
+    index: number;
+    probabilities: OptionProbability[];
+}
+export interface ScoreAnswer extends AnswerBase {
+    type: "score";
+    /** The most likely level, 1-based. */
+    score: number;
+    /** The probability-weighted mean level — often more useful than the argmax. */
+    expected_score: number;
+    legend: string;
+    /** How peaked the distribution was, in 0..=1. */
+    confidence: number;
+    probabilities: LevelProbability[];
+}
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface Usage {
+    input_tokens: number;
+    questions: number;
+}
+export interface SystemOneResponse {
+    answers: Record<string, Answer>;
+    model: string;
+    usage: Usage;
+    timing_ms: {
+        total: number;
+    };
+}
+export type ErrorCode = "too_many_options" | "too_many_questions" | "invalid_request" | "too_few_options" | "invalid_levels" | "empty_state" | "empty_question" | "duplicate_question_id" | "no_questions" | "unknown_model" | "invalid_calibration" | "no_label_matched" | "host_unavailable" | "host_timeout" | "internal";
+export interface ErrorResponse {
+    code: ErrorCode;
+    message: string;
+    question_id?: string;
+}
+export interface ModelInfo {
+    alias: string;
+    model: string;
+    calibration: Calibration;
+}
+export interface ModelsResponse {
+    models: ModelInfo[];
+    default: string;
+}
+export {};

package/dist/cjs/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Wire types for the cerno API.
+ *
+ * These mirror `spec/openapi.json` exactly. A change here without a change there is a bug.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/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/esm/answers.js

@@ -0,0 +1,87 @@
+import { MissingAnswer, WrongAnswerType } from "./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.
+ */
+export 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 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 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 WrongAnswerType(id, expected, answer.type);
+        }
+        return answer;
+    }
+}

package/dist/esm/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/esm/builder.js

@@ -0,0 +1,49 @@
+/** A request under construction. Chain questions onto it, then `send()`. */
+export 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;
+    }
+}

package/dist/esm/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/esm/client.js

@@ -0,0 +1,94 @@
+import { Answers } from "./answers.js";
+import { SystemOneBuilder } from "./builder.js";
+import { ApiError, TransportError, UnexpectedResponse } from "./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();
+ * ```
+ */
+export 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 SystemOneBuilder(state, async (body) => {
+            const response = await this.request("POST", "/v1/systemone", body);
+            return new 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 TransportError(`could not reach cerno: ${String(err)}`, err);
+        }
+        if (response.ok) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new 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 UnexpectedResponse(response.status, text);
+        throw new ApiError(response.status, parsed);
+    }
+}

package/dist/esm/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/esm/errors.js

@@ -0,0 +1,60 @@
+export 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 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;
+    }
+}
+/**
+ * The service could not be reached, or did not answer within the timeout. The error `fetch`
+ * threw is kept as `cause`.
+ */
+export class TransportError extends CernoError {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = "TransportError";
+    }
+}
+/** A non-2xx response that was not shaped like a cerno error — a proxy, most likely. */
+export 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;
+    }
+}
+export class MissingAnswer extends CernoError {
+    questionId;
+    constructor(questionId) {
+        super(`no answer for question ${JSON.stringify(questionId)}`);
+        this.name = "MissingAnswer";
+        this.questionId = questionId;
+    }
+}
+export 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;
+    }
+}

package/dist/esm/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/esm/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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.js";
+export { SystemOneBuilder } from "./builder.js";
+export { Client } from "./client.js";
+export { ApiError, CernoError, MissingAnswer, TransportError, UnexpectedResponse, WrongAnswerType, } from "./errors.js";