@xsai/decide 0.0.0-stage → 1.0.0-beta.1

package/LICENSE.md

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

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @xsai/decide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- automd:file src="/docs/snippets/decide.md" -->
+
+```sh
+pnpm add @xsai/decide
+```
+
+```ts
+import { decide, decisions } from '@xsai/decide'
+
+const model = decisions({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.openai.com/v1/',
+  model: 'gpt-6-luna',
+})
+
+const { answers } = await decide(model, {
+  input: 'The package arrived with a broken screen.',
+  questions: {
+    damaged: { instructions: 'Does the customer report a damaged item?', type: 'boolean' },
+  },
+})
+console.log(answers.damaged.probability)
+```
+
+<!-- /automd -->
+
+Read the [documentation](https://xsai.js.org/decide).

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { Promisable, XSAIError, HttpOptions } from '@xsai/shared';
+import { LanguageModelOptions, LanguageModel } from '@xsai/text';
+
+interface DecideResult<Q extends DecisionQuestions> extends Omit<DecisionModelResult, 'answers'> {
+    answers: {
+        readonly [K in keyof Q]: DecisionAnswerFor<Q[K]>;
+    };
+}
+type DecisionAnswer = DecisionBooleanAnswer | DecisionChoiceAnswer | DecisionScoreAnswer;
+type DecisionAnswerFor<Q extends DecisionQuestion> = Q extends {
+    type: 'choice';
+} ? DecisionChoiceAnswer<Q['choices'][number]['value']> : Q extends {
+    type: 'score';
+} ? DecisionScoreAnswer : DecisionBooleanAnswer;
+interface DecisionBooleanAnswer {
+    /** The probability of true. */
+    probability: number;
+    type: 'boolean';
+}
+interface DecisionChoice {
+    description?: string;
+    value: string;
+}
+interface DecisionChoiceAnswer<V extends string = string> {
+    choice: V;
+    confidence?: number;
+    probabilities?: readonly {
+        probability: number;
+        value: V;
+    }[];
+    type: 'choice';
+}
+type DecisionContent = Record<string, unknown> | string;
+type DecisionModel = (options: DecisionModelOptions) => Promisable<DecisionModelResult>;
+interface DecisionModelOptions {
+    input: DecisionContent;
+    providerOptions?: DecisionModelProviderOptions;
+    questions: DecisionQuestions;
+    signal?: AbortSignal;
+}
+interface DecisionModelProviderOptions {
+}
+interface DecisionModelResult {
+    answers: Readonly<Record<string, DecisionAnswer | DecisionRefusal>>;
+    usage: DecisionUsage;
+}
+type DecisionQuestion = {
+    readonly choices: readonly DecisionChoice[];
+    readonly instructions: DecisionContent;
+    readonly type: 'choice';
+} | {
+    readonly instructions: DecisionContent;
+    readonly levels: readonly DecisionScoreLevel[];
+    readonly type: 'score';
+} | {
+    readonly instructions: DecisionContent;
+    readonly type: 'boolean';
+};
+type DecisionQuestions = Readonly<Record<string, DecisionQuestion>>;
+interface DecisionRefusal {
+    type: 'refusal';
+}
+interface DecisionScoreAnswer {
+    confidence?: number;
+    probabilities?: Readonly<Record<string, number>>;
+    score: number;
+    type: 'score';
+}
+interface DecisionScoreLevel {
+    readonly description?: DecisionContent;
+    readonly label: string;
+}
+interface DecisionUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+
+declare module '@xsai/shared' {
+    interface XSAIErrorCauseMap {
+        'decision-refusal': undefined;
+    }
+}
+declare class DecisionRefusalError extends XSAIError<'decision-refusal'> {
+    readonly questionIds: readonly string[];
+    constructor(questionIds: readonly string[]);
+}
+declare const decide: <const Q extends DecisionQuestions>(model: DecisionModel, options: Omit<DecisionModelOptions, "questions"> & {
+    questions: Q;
+}) => Promise<DecideResult<Q>>;
+
+type OpenAIDecisionsInput = readonly {
+    content: readonly ({
+        detail?: 'auto' | 'high' | 'low' | 'original' | null;
+        image_url: string;
+        type: 'input_image';
+    } | {
+        text: string;
+        type: 'input_text';
+    })[] | string;
+    role: 'user';
+    type?: 'message';
+}[] | string;
+declare module '@xsai/decide' {
+    interface DecisionModelProviderOptions {
+        decisions?: {
+            overrideInput?: OpenAIDecisionsInput;
+        };
+    }
+}
+declare const decisions: (options: HttpOptions) => DecisionModel;
+
+declare module '@xsai/decide' {
+    interface DecisionModelProviderOptions {
+        systemone?: {
+            images?: readonly (string | {
+                base64: string;
+                content_type: 'image/jpeg' | 'image/png' | 'image/webp';
+            })[];
+        };
+    }
+}
+declare const systemone: (options: HttpOptions) => DecisionModel;
+
+type ToDecisionModelOptions = Pick<LanguageModelOptions, 'maxOutputTokens' | 'providerOptions' | 'reasoningEffort' | 'temperature' | 'topP'>;
+declare const toDecisionModel: (model: LanguageModel, options?: ToDecisionModelOptions) => DecisionModel;
+
+export { DecisionRefusalError, decide, decisions, systemone, toDecisionModel };
+export type { DecideResult, DecisionAnswer, DecisionAnswerFor, DecisionBooleanAnswer, DecisionChoice, DecisionChoiceAnswer, DecisionContent, DecisionModel, DecisionModelOptions, DecisionModelProviderOptions, DecisionModelResult, DecisionQuestion, DecisionQuestions, DecisionRefusal, DecisionScoreAnswer, DecisionScoreLevel, DecisionUsage, OpenAIDecisionsInput, ToDecisionModelOptions };

package/dist/index.js

@@ -0,0 +1,133 @@
+import { XSAIError, sendRequest } from '@xsai/shared';
+import { collect } from '@xsai/text';
+
+class DecisionRefusalError extends XSAIError {
+  questionIds;
+  constructor(questionIds) {
+    super("decision-refusal", `Model refused questions: ${JSON.stringify(questionIds)}`);
+    this.questionIds = questionIds;
+  }
+}
+const decide = async (model, options) => {
+  const result = await model(options);
+  const refused = Object.keys(options.questions).filter((id) => result.answers[id]?.type === "refusal");
+  if (refused.length > 0)
+    throw new DecisionRefusalError(refused);
+  return result;
+};
+
+const toText = (content) => typeof content === "string" ? content : JSON.stringify(content);
+const toDecisionUsage = (usage) => ({
+  inputTokens: usage.input_tokens ?? void 0,
+  outputTokens: usage.output_tokens ?? void 0,
+  totalTokens: usage.total_tokens ?? (usage.input_tokens != null && usage.output_tokens != null ? usage.input_tokens + usage.output_tokens : void 0)
+});
+
+const decisions = (options) => async (modelOptions) => {
+  const response = await sendRequest({
+    body: {
+      input: modelOptions.providerOptions?.decisions?.overrideInput ?? toText(modelOptions.input),
+      model: options.model,
+      questions: Object.entries(modelOptions.questions).map(([name, question]) => ({
+        choices: question.type === "choice" ? question.choices : void 0,
+        instructions: toText(question.instructions),
+        levels: question.type === "score" ? question.levels.map((level) => ({
+          description: level.description === void 0 ? void 0 : toText(level.description),
+          label: level.label
+        })) : void 0,
+        name,
+        type: question.type === "boolean" ? "predicate" : question.type
+      }))
+    },
+    path: "decisions",
+    signal: modelOptions.signal
+  }, options);
+  const json = await response.json();
+  return {
+    answers: Object.fromEntries(json.answers.flatMap((answer) => {
+      if (answer.type === "refusal")
+        return (answer.name === null ? Object.keys(modelOptions.questions) : [answer.name]).map((id) => [id, { type: "refusal" }]);
+      if (answer.type === "predicate")
+        return [[answer.name, { probability: answer.probability, type: "boolean" }]];
+      if (answer.type === "score") {
+        return [[answer.name, {
+          confidence: answer.confidence ?? void 0,
+          probabilities: Object.fromEntries(answer.probabilities.map((entry) => [entry.value, entry.probability])),
+          score: answer.score,
+          type: "score"
+        }]];
+      }
+      return [[answer.name, { choice: answer.choice, confidence: answer.confidence ?? void 0, probabilities: answer.probabilities, type: "choice" }]];
+    })),
+    usage: toDecisionUsage(json.usage)
+  };
+};
+
+const systemone = (options) => async (modelOptions) => {
+  const response = await sendRequest({
+    body: {
+      images: modelOptions.providerOptions?.systemone?.images,
+      model: options.model,
+      questions: Object.fromEntries(Object.entries(modelOptions.questions).map(([id, question]) => [id, {
+        criteria: question.type === "choice" ? Object.fromEntries(question.choices.map((choice) => [choice.value, choice.description ?? null])) : question.type === "score" ? question.levels.map((level) => level.description === void 0 ? level.label : `${level.label}: ${toText(level.description)}`) : void 0,
+        instructions: question.instructions,
+        type: question.type === "boolean" ? "noul" : question.type
+      }])),
+      state: modelOptions.input
+    },
+    path: "systemone",
+    signal: modelOptions.signal
+  }, options);
+  const json = await response.json();
+  return {
+    answers: Object.fromEntries(Object.entries(json.answers).map(([id, answer]) => {
+      if (answer.type === "noul")
+        return [id, { probability: answer.noul, type: "boolean" }];
+      if (answer.type === "choice") {
+        const question = modelOptions.questions[id];
+        return [id, {
+          choice: answer.choice,
+          confidence: answer.confidence,
+          probabilities: question.choices.map((choice) => ({ probability: answer.probabilities[choice.value], value: choice.value })),
+          type: "choice"
+        }];
+      }
+      return [id, { confidence: answer.confidence, probabilities: answer.probabilities, score: answer.score, type: "score" }];
+    })),
+    usage: toDecisionUsage(json.usage)
+  };
+};
+
+const toDecisionModel = (model, options = {}) => async (modelOptions) => {
+  const questions = Object.entries(modelOptions.questions);
+  const properties = Object.fromEntries(questions.map(([id, question]) => [id, question.type === "choice" ? { enum: question.choices.map((choice) => choice.value), type: "string" } : { maximum: question.type === "score" ? question.levels.length - 1 : 1, minimum: 0, type: "number" }]));
+  const result = await collect(await model({
+    ...options,
+    input: toText(modelOptions.input),
+    instructions: `Answer every question using the supplied input. For choice questions, return the selected value. For score questions, return a numeric rating from 0 to levels.length - 1, allowing fractions. For boolean questions, estimate P(true) between 0 and 1. Return only the JSON object required by the output schema.
+Questions:
+${JSON.stringify(modelOptions.questions)}`,
+    outputFormat: { additionalProperties: false, properties, required: questions.map(([id]) => id), type: "object" },
+    signal: modelOptions.signal
+  }));
+  if (result.reason === "refusal" || typeof result.message.content !== "string" && result.message.content.some((part) => part.type === "refusal"))
+    throw new DecisionRefusalError(questions.map(([id]) => id));
+  if (result.status !== "completed" || result.toolCalls.length > 0)
+    throw new XSAIError("invalid-response", "LanguageModel did not complete a structured decision output");
+  const output = JSON.parse(result.text);
+  const invalid = questions.filter(([id, question]) => {
+    const value = output[id];
+    if (question.type === "choice")
+      return !question.choices.some((choice) => choice.value === value);
+    const max = question.type === "score" ? question.levels.length - 1 : 1;
+    return typeof value !== "number" || value < 0 || value > max;
+  });
+  if (invalid.length > 0)
+    throw new XSAIError("invalid-response", `LanguageModel returned out-of-range answers: ${JSON.stringify(invalid.map(([id]) => id))}`);
+  return {
+    answers: Object.fromEntries(questions.map(([id, question]) => [id, question.type === "choice" ? { choice: output[id], type: "choice" } : question.type === "score" ? { score: output[id], type: "score" } : { probability: output[id], type: "boolean" }])),
+    usage: result.usage ?? {}
+  };
+};
+
+export { DecisionRefusalError, decide, decisions, systemone, toDecisionModel };

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@xsai/decide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-beta.1",
+  "description": "extra-small AI SDK: classify input by answering yes/no questions with probabilities.",
+  "author": "Moeru AI",
+  "license": "MIT",
+  "homepage": "https://xsai.js.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moeru-ai/xsai.git",
+    "directory": "packages/decide"
+  },
+  "bugs": "https://github.com/moeru-ai/xsai/issues",
+  "keywords": [
+    "xsai",
+    "ai",
+    "openai",
+    "decide",
+    "classification",
+    "logprobs"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@xsai/shared": "1.0.0-beta.1",
+    "@xsai/text": "1.0.0-beta.1"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "test": "vitest run --exclude e2e/**",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }