@librechat/agents 4.0.1 → 4.0.2

package/src/decisions/dialect.ts

@@ -0,0 +1,200 @@
+import type {
+  DecisionAnswer,
+  DecisionDialect,
+  DecisionQuestion,
+} from './types';
+import { isDecisionObject } from './types';
+
+interface WireQuestion {
+  type: string;
+  instructions: DecisionQuestion['instructions'];
+  criteria?: DecisionQuestion['criteria'];
+}
+
+interface WireAnswer {
+  type?: unknown;
+  probability?: unknown;
+  noul?: unknown;
+  choice?: unknown;
+  score?: unknown;
+  confidence?: unknown;
+  probabilities?: unknown;
+}
+
+/** System One calls a yes/no question a `noul`; both dialects use a `{true, false}` criterion. */
+export function toWireQuestion(
+  question: DecisionQuestion,
+  dialect: DecisionDialect
+): WireQuestion {
+  const type =
+    dialect === 'systemone' && question.type === 'boolean'
+      ? 'noul'
+      : question.type;
+  if (question.criteria == null) {
+    return { type, instructions: question.instructions };
+  }
+  const criteria =
+    question.type === 'boolean' && typeof question.criteria === 'string'
+      ? { true: question.criteria }
+      : question.criteria;
+  return { type, instructions: question.instructions, criteria };
+}
+
+function isProbability(value: unknown): value is number {
+  return (
+    typeof value === 'number' &&
+    Number.isFinite(value) &&
+    value >= 0 &&
+    value <= 1
+  );
+}
+
+/** `undefined` means malformed; `null` means no distribution was reported. */
+function probabilitiesOf(
+  raw: unknown,
+  answerType: 'choice' | 'score',
+  question?: DecisionQuestion,
+  selectedChoice?: string
+): Record<string, number> | null | undefined {
+  if (raw == null) {
+    return null;
+  }
+  if (!isDecisionObject(raw)) {
+    return undefined;
+  }
+  const entries = Object.entries(raw);
+  if (entries.length === 0) {
+    return null;
+  }
+  if (
+    (question?.type === 'choice' &&
+      entries.length !== Object.keys(question.criteria).length) ||
+    (question?.type === 'score' && entries.length !== question.criteria.length)
+  ) {
+    return undefined;
+  }
+  const probabilities: Record<string, number> = Object.create(null);
+  let total = 0;
+  let maximum = 0;
+  for (const [key, value] of entries) {
+    if (!isProbability(value)) {
+      return undefined;
+    }
+    if (question?.type === 'choice' && !Object.hasOwn(question.criteria, key)) {
+      return undefined;
+    }
+    if (
+      answerType === 'score' &&
+      (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= entries.length)
+    ) {
+      return undefined;
+    }
+    probabilities[key] = value;
+    total += value;
+    maximum = Math.max(maximum, value);
+  }
+  if (
+    selectedChoice !== undefined &&
+    (!Object.hasOwn(probabilities, selectedChoice) ||
+      probabilities[selectedChoice] < maximum)
+  ) {
+    return undefined;
+  }
+  const roundingTolerance = Math.min(
+    0.02,
+    Math.max(0.01, entries.length * 0.00005 + 0.001)
+  );
+  return Math.abs(total - 1) <= roundingTolerance ? probabilities : undefined;
+}
+
+/** A validated answer, or `null` for one that cannot safely be read. */
+export function readAnswer(
+  answer: unknown,
+  dialect: DecisionDialect,
+  question?: DecisionQuestion
+): DecisionAnswer | null {
+  if (!isDecisionObject(answer)) {
+    return null;
+  }
+  const record: WireAnswer = answer;
+  const booleanType = dialect === 'systemone' ? 'noul' : 'boolean';
+  const probability =
+    dialect === 'systemone' ? record.noul : record.probability;
+  if (record.type === booleanType) {
+    if (
+      !isProbability(probability) ||
+      (question != null && question.type !== 'boolean')
+    ) {
+      return null;
+    }
+    return { type: 'boolean', probability };
+  }
+  if (record.type !== 'choice' && record.type !== 'score') {
+    return null;
+  }
+  const confidence = record.confidence;
+  if (confidence != null && !isProbability(confidence)) {
+    return null;
+  }
+  const probabilities = probabilitiesOf(
+    record.probabilities,
+    record.type,
+    question,
+    record.type === 'choice' && typeof record.choice === 'string'
+      ? record.choice
+      : undefined
+  );
+  if (probabilities === undefined) {
+    return null;
+  }
+  if (record.type === 'choice') {
+    if (
+      typeof record.choice !== 'string' ||
+      (question != null &&
+        (question.type !== 'choice' ||
+          !Object.hasOwn(question.criteria, record.choice)))
+    ) {
+      return null;
+    }
+    return {
+      type: 'choice',
+      choice: record.choice,
+      confidence: confidence ?? null,
+      probabilities,
+    };
+  }
+  if (
+    typeof record.score !== 'number' ||
+    !Number.isFinite(record.score) ||
+    record.score < 0 ||
+    (question != null &&
+      (question.type !== 'score' ||
+        record.score > question.criteria.length - 1))
+  ) {
+    return null;
+  }
+  if (probabilities !== null) {
+    let weightedScore = 0;
+    let levels = 0;
+    for (const [level, probability] of Object.entries(probabilities)) {
+      weightedScore += Number(level) * probability;
+      levels += 1;
+    }
+    const roundingTolerance = Math.min(
+      0.02,
+      0.00005 * (1 + (levels * (levels - 1)) / 2) + 0.001
+    );
+    if (
+      !Number.isFinite(weightedScore) ||
+      Math.abs(record.score - weightedScore) > roundingTolerance
+    ) {
+      return null;
+    }
+  }
+  return {
+    type: 'score',
+    score: record.score,
+    confidence: confidence ?? null,
+    probabilities,
+  };
+}

package/src/decisions/http.ts

@@ -0,0 +1,175 @@
+import type {
+  DecisionModel,
+  DecisionAnswer,
+  DecisionResult,
+  DecisionRequest,
+  DecisionDialect,
+  DecisionCredential,
+  DecisionQuestion,
+} from './types';
+import type { DecisionFetch } from './transport';
+import { DecisionError, isDecisionObject, readDecisionUsage } from './types';
+import { validateDecisionQuestions } from './questions';
+import { toWireQuestion, readAnswer } from './dialect';
+import { createTransport } from './transport';
+
+export const HTTP_PROVIDER_ID = 'http';
+
+export interface HttpDecisionModelOptions {
+  providerId?: string;
+  apiKey?: DecisionCredential;
+  requiresAuth?: boolean;
+  /** Full URL, not a base path. */
+  endpoint: string;
+  model?: string;
+  dialect?: DecisionDialect;
+  requestKey?: string;
+  responseKey?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetch?: DecisionFetch;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  onAnswered?: (label: string, ms: number) => void;
+}
+
+export function parseEnvelope(
+  body: string,
+  providerId: string,
+  readOne: (
+    answer: unknown,
+    question?: DecisionQuestion
+  ) => DecisionAnswer | null,
+  responseKey?: string,
+  expected?: Record<string, DecisionQuestion>
+): DecisionResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new DecisionError('malformed_response', 'response was not JSON', {
+      provider: providerId,
+    });
+  }
+  if (!isDecisionObject(parsed)) {
+    throw new DecisionError(
+      'malformed_response',
+      'response was not an object',
+      {
+        provider: providerId,
+      }
+    );
+  }
+  const unwrapped =
+    responseKey != null && responseKey !== '' ? parsed[responseKey] : parsed;
+  if (
+    !isDecisionObject(unwrapped) ||
+    !isDecisionObject(unwrapped.answers) ||
+    Object.keys(unwrapped.answers).length === 0
+  ) {
+    throw new DecisionError(
+      'malformed_response',
+      'response carried no answers',
+      {
+        provider: providerId,
+      }
+    );
+  }
+
+  const answers: DecisionResult['answers'] = Object.create(null);
+  for (const [id, answer] of Object.entries(unwrapped.answers)) {
+    if (expected && !Object.hasOwn(expected, id)) {
+      throw new DecisionError(
+        'malformed_response',
+        'response carried an unknown answer',
+        {
+          provider: providerId,
+        }
+      );
+    }
+    const mapped = readOne(answer, expected?.[id]);
+    if (!mapped) {
+      throw new DecisionError(
+        'malformed_response',
+        'response carried an invalid answer',
+        {
+          provider: providerId,
+        }
+      );
+    }
+    answers[id] = mapped;
+  }
+
+  return {
+    model: typeof unwrapped.model === 'string' ? unwrapped.model : 'unknown',
+    answers,
+    usage: readDecisionUsage(unwrapped.usage),
+  };
+}
+
+/** Jev and Laya use the same System One HTTP dialect, but may report different confidence metrics. */
+export function createHttpDecisionModel(
+  options: HttpDecisionModelOptions
+): DecisionModel {
+  const providerId = options.providerId ?? HTTP_PROVIDER_ID;
+  const send = createTransport({ ...options, providerId });
+  const model = options.model ?? '';
+  const dialect: DecisionDialect = options.dialect ?? 'port';
+  const { requestKey, responseKey } = options;
+
+  return {
+    id: providerId,
+    model,
+    async decide(request: DecisionRequest): Promise<DecisionResult> {
+      return send(
+        () => {
+          const entries = validateDecisionQuestions(
+            request.questions,
+            providerId
+          );
+          const questions: Record<
+            string,
+            ReturnType<typeof toWireQuestion>
+          > = Object.create(null);
+          const expected: Record<string, DecisionQuestion> =
+            Object.create(null);
+          for (const [id, question] of entries) {
+            questions[id] = toWireQuestion(question, dialect);
+            expected[id] = question;
+          }
+          const inner = { state: request.state, questions };
+          let payload: string;
+          try {
+            payload = JSON.stringify({
+              ...(model !== '' ? { model } : {}),
+              ...(requestKey != null && requestKey !== ''
+                ? { [requestKey]: inner }
+                : inner),
+            });
+          } catch {
+            throw new DecisionError(
+              'bad_request',
+              'invalid decision model request',
+              {
+                provider: providerId,
+              }
+            );
+          }
+          return {
+            payload,
+            parse: (body: string) =>
+              parseEnvelope(
+                body,
+                providerId,
+                (answer, question) => readAnswer(answer, dialect, question),
+                responseKey,
+                expected
+              ),
+          };
+        },
+        request.signal,
+        request.label ?? 'decide',
+        request.timeoutMs
+      );
+    },
+  };
+}

package/src/decisions/index.ts

@@ -0,0 +1,14 @@
+export * from './types';
+export * from './questions';
+export * from './presets';
+export {
+  createHttpDecisionModel,
+  parseEnvelope,
+  HTTP_PROVIDER_ID,
+} from './http';
+export { createStructuredChatDecisionModel } from './structuredChat';
+export type { HttpDecisionModelOptions } from './http';
+export type { StructuredChatDecisionModelOptions } from './structuredChat';
+export { toWireQuestion, readAnswer } from './dialect';
+export { createTransport } from './transport';
+export type { DecisionFetch, Transport, TransportOptions } from './transport';

package/src/decisions/presets.ts

@@ -0,0 +1,111 @@
+import type {
+  DecisionModel,
+  DecisionCredential,
+  DecisionProviderSettings,
+} from './types';
+import type { DecisionFetch } from './transport';
+import { createHttpDecisionModel } from './http';
+
+export const DEFAULT_API_KEY_ENV = 'DECISION_API_KEY';
+
+/**
+ * Known HTTP hosts as settings, not new decision model implementations. Jev and Laya speak the
+ * same wire protocol, but their confidence measures and checkpoint calibration differ.
+ */
+export const DECISION_PRESETS: Readonly<
+  Record<string, Readonly<DecisionProviderSettings>>
+> = Object.freeze({
+  http: Object.freeze({
+    dialect: 'port',
+    requiresAuth: true,
+    apiKeyEnv: DEFAULT_API_KEY_ENV,
+  }),
+  typesafe: Object.freeze({
+    baseURL: 'https://api.typesafe.ai/v1/systemone',
+    model: 'jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'TYPESAFE_API_KEY',
+  }),
+  laya: Object.freeze({
+    /** Supply the server's full /v1/systemone URL; no model lets Laya route by language. */
+    dialect: 'systemone',
+    requiresAuth: false,
+  }),
+  clickhouse: Object.freeze({
+    /** ClickHouse's inference gateway; the token is what `dataplanectl chai auth token` prints, hourly. */
+    baseURL: 'https://inference-internal.clickhouse.cloud/v1/systemone',
+    model: 'jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'CHAI_AUTH_TOKEN',
+  }),
+  openrouter: Object.freeze({
+    baseURL: 'https://openrouter.ai/api/alpha/decisions',
+    model: '~typesafe/jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'OPENROUTER_KEY',
+  }),
+  cloudflare: Object.freeze({
+    /** No default URL: the account id is part of it. */
+    model: 'typesafe/jev',
+    dialect: 'systemone',
+    requestKey: 'input',
+    responseKey: 'result',
+    requiresAuth: true,
+    apiKeyEnv: 'CLOUDFLARE_API_TOKEN',
+  }),
+});
+
+export function decisionPreset(
+  name: string | undefined
+): DecisionProviderSettings | null {
+  if (name == null || name === '') {
+    return null;
+  }
+  return Object.hasOwn(DECISION_PRESETS, name)
+    ? { ...DECISION_PRESETS[name] }
+    : null;
+}
+
+/** Caller settings win except that required preset authentication cannot be weakened. */
+export function mergeDecisionSettings(
+  preset: DecisionProviderSettings | null,
+  configured: DecisionProviderSettings | undefined
+): DecisionProviderSettings {
+  return {
+    ...(preset ?? {}),
+    ...(configured ?? {}),
+    ...(preset?.requiresAuth === true ? { requiresAuth: true } : {}),
+  };
+}
+
+export function decisionProviderNames(): string[] {
+  return Object.keys(DECISION_PRESETS);
+}
+
+export function createDecisionModel(
+  settings: DecisionProviderSettings,
+  apiKey?: DecisionCredential,
+  options?: {
+    fetch?: DecisionFetch;
+    providerId?: string;
+    onAnswered?: (label: string, ms: number) => void;
+  }
+): DecisionModel {
+  return createHttpDecisionModel({
+    providerId: options?.providerId,
+    apiKey,
+    requiresAuth: settings.requiresAuth,
+    endpoint: settings.baseURL ?? '',
+    model: settings.model,
+    dialect: settings.dialect,
+    requestKey: settings.requestKey,
+    responseKey: settings.responseKey,
+    timeoutMs: settings.timeoutMs,
+    maxRetries: settings.maxRetries,
+    fetch: options?.fetch,
+    onAnswered: options?.onAnswered,
+  });
+}

package/src/decisions/questions.ts

@@ -0,0 +1,128 @@
+import type {
+  BooleanCriteria,
+  BooleanQuestion,
+  ChoiceQuestion,
+  ScoreQuestion,
+  DecisionText,
+  DecisionQuestion,
+} from './types';
+import { DecisionError, isDecisionObject } from './types';
+
+function validQuestionId(id: string): boolean {
+  if (id.length === 0 || id.length > 128) {
+    return false;
+  }
+  for (let index = 0; index < id.length; index++) {
+    if (id.charCodeAt(index) < 32) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function validBooleanCriteria(criteria: BooleanQuestion['criteria']): boolean {
+  if (criteria === undefined || typeof criteria === 'string') {
+    return true;
+  }
+  if (!isDecisionObject(criteria)) {
+    return false;
+  }
+  for (const [side, description] of Object.entries(criteria)) {
+    if (
+      (side !== 'true' && side !== 'false') ||
+      (description !== undefined &&
+        typeof description !== 'string' &&
+        !Array.isArray(description) &&
+        !isDecisionObject(description))
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function validateDecisionQuestions(
+  questions: Record<string, DecisionQuestion>,
+  provider: string
+): Array<[string, DecisionQuestion]> {
+  if (!isDecisionObject(questions)) {
+    throw new DecisionError('bad_request', 'invalid decision model questions', {
+      provider,
+    });
+  }
+  const supplied = Object.entries(questions);
+  if (supplied.length === 0) {
+    throw new DecisionError(
+      'bad_request',
+      'decision model requires questions',
+      {
+        provider,
+      }
+    );
+  }
+  const entries: Array<[string, DecisionQuestion]> = [];
+  for (const [id, question] of supplied) {
+    if (
+      !validQuestionId(id) ||
+      !isDecisionObject(question) ||
+      !['boolean', 'choice', 'score'].includes(question.type) ||
+      (question.type === 'boolean' &&
+        !validBooleanCriteria(question.criteria)) ||
+      (question.type === 'choice' &&
+        (!isDecisionObject(question.criteria) ||
+          Object.keys(question.criteria).length === 0)) ||
+      (question.type === 'score' &&
+        (!Array.isArray(question.criteria) || question.criteria.length < 2))
+    ) {
+      throw new DecisionError(
+        'bad_request',
+        'invalid decision model question',
+        {
+          provider,
+        }
+      );
+    }
+    if (question.type === 'choice') {
+      entries.push([id, { ...question, criteria: { ...question.criteria } }]);
+    } else if (question.type === 'score') {
+      entries.push([id, { ...question, criteria: [...question.criteria] }]);
+    } else {
+      entries.push([
+        id,
+        {
+          ...question,
+          ...(isDecisionObject(question.criteria)
+            ? { criteria: { ...question.criteria } }
+            : {}),
+        },
+      ]);
+    }
+  }
+  return entries;
+}
+
+/** A yes/no question; `criteria` describes what counts as yes (a string) or both sides. */
+export function booleanQuestion(
+  instructions: DecisionText,
+  criteria?: BooleanCriteria | string
+): BooleanQuestion {
+  return criteria == null
+    ? { type: 'boolean', instructions }
+    : { type: 'boolean', instructions, criteria };
+}
+
+/** Pick one of the named options; a `null` description means the name speaks for itself. */
+export function choiceQuestion(
+  instructions: DecisionText,
+  criteria: Record<string, DecisionText | null>
+): ChoiceQuestion {
+  return { type: 'choice', instructions, criteria };
+}
+
+/** Rate against an ordered rubric, level 0 first. */
+export function scoreQuestion(
+  instructions: DecisionText,
+  levels: DecisionText[]
+): ScoreQuestion {
+  return { type: 'score', instructions, criteria: levels };
+}