@butlerbot/sdk 0.0.46 → 0.0.47

package/dist/config.d.ts

@@ -69,6 +69,10 @@ export declare const CONFIG: {
             /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
             base: string;
         };
+        judge: {
+            /** A decision on stated facts, by a decision model. */
+            base: string;
+        };
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;

package/dist/config.js

@@ -60,7 +60,11 @@ exports.CONFIG = {
         outreach: {
             /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
             base: "/api/outreach",
-        }
+        },
+        judge: {
+            /** A decision on stated facts, by a decision model. */
+            base: "/api/judge",
+        },
     }
 };
 const withoutTrailingSlash = (url) => url.replace(/\/+$/, "");

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
 import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type SetPhaseModelOptions, type ListJobsOptions, type ResumeJobOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
 import { type AnswerDeliveryOptions, type ListDeliveriesOptions } from "./modules/outreach";
+import { type JudgeOptions } from "./modules/judge";
+import type { JudgeQuestions } from "./types/judge";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
     /** Optional API key, defaults to API key specified in client */
     apiKey?: string;
@@ -64,6 +66,13 @@ export declare class ButlerBotClient {
     listDeliveries(config?: OptionalApiKey<ListDeliveriesOptions>): Promise<import("./types/type_registry").DeliveryListResponse>;
     /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
     answerDelivery(config: OptionalApiKey<AnswerDeliveryOptions>): Promise<import("./types/type_registry").DeliveryAnswerResponse>;
+    /**
+     * Asks the judge: a yes/no, pick-one or score decision on facts you state, by a decision
+     * model, in well under a second for a fraction of a cent. Answers come back keyed by
+     * question id and typed by the question. Throws a `ButlerBotAPIError` with `isBadRequest`
+     * on a question the judge cannot ask, carrying its message
+     */
+    judge<Q extends JudgeQuestions>(config: OptionalApiKey<JudgeOptions<Q>>): Promise<import("./types/judge").JudgeVerdict<Q>>;
     /** The client's own server and key underneath whatever the call named itself. */
     private forRequest;
 }
@@ -78,6 +87,8 @@ export { listJobs, getJob, cancelJob, resumeJob, updateJob, updateJobSettings }
 export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, ResumeJobOptions, UpdateJobOptions, UpdateJobSettingsOptions, } from "./modules/jobs";
 export { listDeliveries, answerDelivery } from "./modules/outreach";
 export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptions, } from "./modules/outreach";
+export { judge } from "./modules/judge";
+export type { JudgeRequestOptions, JudgeOptions } from "./modules/judge";
 export { LinkConversationTransport } from "./modules/transport_link";
 export { SSEConversationTransport } from "./modules/transport_sse";
 export type { SteerResult, TurnStopMode, TurnStopped } from "./modules/transport";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESERVED_TURN_FIELDS = exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
+exports.RESERVED_TURN_FIELDS = exports.SSEConversationTransport = exports.LinkConversationTransport = exports.judge = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
 const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
@@ -22,6 +22,7 @@ Object.defineProperty(exports, "Conversation", { enumerable: true, get: function
 const usage_1 = require("./modules/usage");
 const jobs_1 = require("./modules/jobs");
 const outreach_1 = require("./modules/outreach");
+const judge_1 = require("./modules/judge");
 /**
  * The options a caller actually gave, with the keys they left out removed.
  *
@@ -112,6 +113,15 @@ class ButlerBotClient {
     answerDelivery(config) {
         return (0, outreach_1.answerDelivery)(this.forRequest(config));
     }
+    /**
+     * Asks the judge: a yes/no, pick-one or score decision on facts you state, by a decision
+     * model, in well under a second for a fraction of a cent. Answers come back keyed by
+     * question id and typed by the question. Throws a `ButlerBotAPIError` with `isBadRequest`
+     * on a question the judge cannot ask, carrying its message
+     */
+    judge(config) {
+        return (0, judge_1.judge)(this.forRequest(config));
+    }
     /** The client's own server and key underneath whatever the call named itself. */
     forRequest(config) {
         return { serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...given(config) };
@@ -133,6 +143,8 @@ Object.defineProperty(exports, "updateJobSettings", { enumerable: true, get: fun
 var outreach_2 = require("./modules/outreach");
 Object.defineProperty(exports, "listDeliveries", { enumerable: true, get: function () { return outreach_2.listDeliveries; } });
 Object.defineProperty(exports, "answerDelivery", { enumerable: true, get: function () { return outreach_2.answerDelivery; } });
+var judge_2 = require("./modules/judge");
+Object.defineProperty(exports, "judge", { enumerable: true, get: function () { return judge_2.judge; } });
 var transport_link_1 = require("./modules/transport_link");
 Object.defineProperty(exports, "LinkConversationTransport", { enumerable: true, get: function () { return transport_link_1.LinkConversationTransport; } });
 var transport_sse_1 = require("./modules/transport_sse");

package/dist/modules/judge.d.ts

@@ -0,0 +1,32 @@
+import type { JudgeQuestions, JudgeState, JudgeVerdict } from "../types/judge";
+/** What a judge call needs: where the server is, and who is asking. */
+export type JudgeRequestOptions = {
+    serverURL?: string;
+    /** The path of the judge route, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type JudgeOptions<Q extends JudgeQuestions = JudgeQuestions> = JudgeRequestOptions & {
+    /**
+     * The facts the questions are answered from: the message, who sent it, the rules, numbers
+     * and dates already worked out in code. Never a transcript or an argument for an answer.
+     */
+    state: JudgeState;
+    /** The questions, by the id the answer is read back under. All are judged against the same state in one call. */
+    questions: Q;
+};
+/**
+ * Asks the judge: a yes/no, pick-one or score decision on the facts given, made by a decision
+ * model in well under a second for a fraction of a cent.
+ *
+ * The answers come back keyed by question id and typed by the question: a boolean's `value` and
+ * `probability`, a choice's `choice` (one of its criteria's keys), `confidence` and
+ * `probabilities`, a score's `level`, `score` and `confidence`. The model writes no text and
+ * gives no reason.
+ *
+ * A question the judge cannot ask (a boolean missing one side, a choice with one label, a score
+ * with more than ten levels) is a 400 carrying the judge's own message, and a judgement not
+ * reached is a 503: the call throws a `ButlerBotAPIError` either way, never a guess.
+ */
+export declare function judge<Q extends JudgeQuestions>(options: JudgeOptions<Q>): Promise<JudgeVerdict<Q>>;

package/dist/modules/judge.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.judge = judge;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+/**
+ * Asks the judge: a yes/no, pick-one or score decision on the facts given, made by a decision
+ * model in well under a second for a fraction of a cent.
+ *
+ * The answers come back keyed by question id and typed by the question: a boolean's `value` and
+ * `probability`, a choice's `choice` (one of its criteria's keys), `confidence` and
+ * `probabilities`, a score's `level`, `score` and `confidence`. The model writes no text and
+ * gives no reason.
+ *
+ * A question the judge cannot ask (a boolean missing one side, a choice with one label, a score
+ * with more than ten levels) is a 400 carrying the judge's own message, and a judgement not
+ * reached is a 503: the call throws a `ButlerBotAPIError` either way, never a guess.
+ */
+async function judge(options) {
+    const url = (0, url_formatter_1.formatURL)((options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.judge.base), {}, { apiKey: options.apiKey, debug: options.debug });
+    const response = await (0, api_request_1.requestAPI)({
+        url,
+        method: "POST",
+        body: { state: options.state, questions: options.questions },
+        action: "ask the judge",
+    });
+    return { answers: response.answers, model: response.model, costUsd: response.costUsd };
+}

package/dist/types/conversation/v3/conversation_v3.d.ts

@@ -52,6 +52,14 @@ export type ToolStatus = {
     content?: ToolStatusContent[];
     /** Whether this tool call is ending the conversation */
     endingConvo?: boolean;
+    /** The tool that ran: its id, or a raw (MCP) tool's key. A fact for clients to present, never a label. */
+    toolId?: string;
+    /** Epoch ms of the first status emitted for this id; the same on every later status for it. */
+    startedAt?: number;
+    /** Epoch ms at which this id reached `completed` or `failed`. */
+    endedAt?: number;
+    /** The id of an earlier failed call of the same tool, in the same turn, that this call retries. */
+    retryOf?: string;
 };
 export type TokenUsage = {
     /**

package/dist/types/judge/index.d.ts

@@ -0,0 +1 @@
+export * from "./judge";

package/dist/types/judge/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./judge"), exports);

package/dist/types/judge/judge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The judge: a yes/no, pick-one or score decision made by a decision model, on facts the caller
+ * states.
+ *
+ * Not a conversation. It writes no text and gives no reason: one call, every question judged
+ * against the same state, and typed answers back with probabilities. The state is facts (the
+ * message, who sent it, the rules, numbers and dates already worked out in code), never a
+ * transcript or an argument for an answer. State and the longest question together fit in about
+ * 32,000 tokens.
+ */
+/**
+ * A yes/no question.
+ *
+ * Both sides are described, because the model weighs the state against each description rather
+ * than against the question alone, and the server refuses a question that leaves one out.
+ */
+export type JudgeBooleanQuestion = {
+    type: "boolean";
+    /** What is being decided about the state, in one or two sentences. */
+    instructions: string;
+    criteria: {
+        /** What a yes looks like in the state. */
+        true: string;
+        /** What a no looks like in the state. */
+        false: string;
+    };
+    /** The probability of yes (between 0 and 1, exclusive) at which `value` is true. 0.5 when unset. */
+    threshold?: number;
+};
+/**
+ * Pick one label.
+ *
+ * Every label the answer may be is a key of `criteria`, described by its value; at least two.
+ * There is no automatic "none": when the state may fit no label, add one ("none": "Nothing above
+ * fits"), or the nearest label is picked however poor the fit.
+ */
+export type JudgeChoiceQuestion<L extends string = string> = {
+    type: "choice";
+    instructions: string;
+    criteria: Record<L, string>;
+};
+/**
+ * A place on an ordered scale.
+ *
+ * `criteria[0]` describes the bottom of the scale and each entry after it one level up; at most
+ * ten levels.
+ */
+export type JudgeScoreQuestion = {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+export type JudgeQuestion = JudgeBooleanQuestion | JudgeChoiceQuestion | JudgeScoreQuestion;
+/** The questions of one call, by an id (1-64 letters, digits, `_` or `-`) the answer is read back under. */
+export type JudgeQuestions = Record<string, JudgeQuestion>;
+/** The facts the questions are answered from: text, or an object the server renders. */
+export type JudgeState = string | Record<string, unknown>;
+export type JudgeBooleanAnswer = {
+    type: "boolean";
+    /** True when `probability` reached the question's threshold. */
+    value: boolean;
+    /** How likely yes is, 0 to 1. */
+    probability: number;
+};
+export type JudgeChoiceAnswer<L extends string = string> = {
+    type: "choice";
+    /** The label picked: one of the question's criteria keys. */
+    choice: L;
+    /** How sure, 0 to 1. */
+    confidence: number;
+    /** Every label's probability, keyed by label. */
+    probabilities?: Partial<Record<L, number>>;
+};
+export type JudgeScoreAnswer = {
+    type: "score";
+    /** The probability-weighted mean of the levels, 0-based; a fraction when the model is torn. */
+    score: number;
+    /** The single most likely level, 0-based: an index into the question's `criteria`. */
+    level: number;
+    /** How sure of `level`, 0 to 1. */
+    confidence: number;
+    /** Each level's probability, keyed by its index as a string. */
+    probabilities?: Record<string, number>;
+};
+export type JudgeAnswer = JudgeBooleanAnswer | JudgeChoiceAnswer | JudgeScoreAnswer;
+/** The answer a question gets, typed by the question: a choice's label is one of its criteria's keys. */
+export type JudgeAnswerFor<Q extends JudgeQuestion> = Q extends JudgeBooleanQuestion ? JudgeBooleanAnswer : Q extends JudgeChoiceQuestion ? JudgeChoiceAnswer<Extract<keyof Q["criteria"], string>> : Q extends JudgeScoreQuestion ? JudgeScoreAnswer : never;
+export type JudgeAnswers<Q extends JudgeQuestions> = {
+    [K in keyof Q]: JudgeAnswerFor<Q[K]>;
+};
+/** What a decision comes back as. */
+export type JudgeVerdict<Q extends JudgeQuestions = JudgeQuestions> = {
+    /** One answer per question, under the question's id. */
+    answers: JudgeAnswers<Q>;
+    /** The decision model that answered. */
+    model: string;
+    /** What the judgement cost, USD. It is already on the account's ledger. */
+    costUsd: number;
+};
+/** The route's whole answer. */
+export type JudgeResponse<Q extends JudgeQuestions = JudgeQuestions> = JudgeVerdict<Q> & {
+    success: true;
+};

package/dist/types/judge/judge.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * The judge: a yes/no, pick-one or score decision made by a decision model, on facts the caller
+ * states.
+ *
+ * Not a conversation. It writes no text and gives no reason: one call, every question judged
+ * against the same state, and typed answers back with probabilities. The state is facts (the
+ * message, who sent it, the rules, numbers and dates already worked out in code), never a
+ * transcript or an argument for an answer. State and the longest question together fit in about
+ * 32,000 tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/response/v5/ai_response_v5.d.ts

@@ -39,6 +39,14 @@ export type ToolStatus = {
     content?: ToolStatusContent[];
     /** Whether this tool call is ending the conversation */
     endingConvo?: boolean;
+    /** The tool that ran: its id, or a raw (MCP) tool's key. A fact for clients to present, never a label. */
+    toolId?: string;
+    /** Epoch ms of the first status emitted for this id; the same on every later status for it. */
+    startedAt?: number;
+    /** Epoch ms at which this id reached `completed` or `failed`. */
+    endedAt?: number;
+    /** The id of an earlier failed call of the same tool, in the same turn, that this call retries. */
+    retryOf?: string;
 };
 export type BaseResponseMetadata = {
     /** Unique response ID */

package/dist/types/type_registry.d.ts

@@ -7,4 +7,5 @@ export * from "./conversation/address";
 export * from "./conversation/context";
 export * from "./jobs";
 export * from "./outreach";
+export * from "./judge";
 export * from "./error";

package/dist/types/type_registry.js

@@ -23,4 +23,5 @@ __exportStar(require("./conversation/address"), exports);
 __exportStar(require("./conversation/context"), exports);
 __exportStar(require("./jobs"), exports);
 __exportStar(require("./outreach"), exports);
+__exportStar(require("./judge"), exports);
 __exportStar(require("./error"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.46",
+	"version": "0.0.47",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -387,10 +387,63 @@ one, and answering it is refused with a 409 just as one already answered is. `so
 wrote a delivery: `shift` for a question a job's shift asked, `runtime` for the job's own
 status tells, `gate` for an approval the autonomy gate asked for.
 
+## Judge
+
+A yes/no, pick-one or score decision on facts you state, made by a decision model: well under
+a second and a fraction of a cent, so an app can ask it per event. It is Alfred's own judge,
+the one his jobs and reflexes decide with, for your code to decide with too.
+
+```typescript
+const { answers, model, costUsd } = await client.judge({
+  state: { message: text, author: "bot: false", channel: "general", rules },
+  questions: {
+    hostile: {
+      type: "boolean",
+      instructions: "Is the message hostile?",
+      criteria: { true: "It attacks or insults someone", false: "It is civil, however blunt" },
+    },
+    rule: {
+      type: "choice",
+      instructions: "Which server rule does the message break?",
+      criteria: { spam: "Promotional or repeated", abuse: "Insults a person", none: "No rule is broken" },
+    },
+    heat: {
+      type: "score",
+      instructions: "How heated is the message?",
+      criteria: ["Calm", "Annoyed", "Furious"],
+    },
+  },
+});
+
+answers.hostile.value;        // boolean: value, probability
+answers.rule.choice;          // "spam" | "abuse" | "none", with confidence and every label's probability
+answers.heat.level;           // 0..2, with score (the weighted mean) and confidence
+```
+
+Every question is judged against the same `state` in one call, and the answers come back keyed
+by question id and typed by the question: a choice's `choice` is one of its own criteria keys.
+It is a decision model, not a chat model: it writes no text and does no reasoning, so
+
+- state facts, never a transcript or an argument for an answer;
+- work out numbers and dates in code and state the result;
+- describe both sides of a boolean, since the model weighs the state against each;
+- add a `none` label to a choice when nothing may fit, or the nearest label is picked however
+  poor the fit;
+- keep a score to ten levels, `criteria[0]` the bottom.
+
+State and the longest question together fit in about 32,000 tokens. A question the judge cannot
+ask is a 400 carrying its message, and a judgement it could not reach is a 503: both throw
+`ButlerBotAPIError`, never a guess. Needs `judge.run`.
+
+The judge is for a decision your app makes itself. For Alfred to react to something, do not
+judge first: report it as a [hook event](#hooks-emit-or-report-what-matched) and the user's
+reflex decides, with the judge inside it when it needs one. That keeps what Alfred reacts to,
+and what it costs, in the user's hands.
+
 ### When a call fails
 
-Every jobs and outreach call throws `ButlerBotAPIError` when the server does not answer with a
-success. The status is on the error, so the cases worth branching on are told apart without
+Every jobs, outreach and judge call throws `ButlerBotAPIError` when the server does not answer
+with a success. The status is on the error, so the cases worth branching on are told apart without
 reading a message, and the parsed body is kept — a rejected cancel still carries the job, a
 rejected answer still carries the delivery: