Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

8.8 KB
Raw Blame
import {
  LayaAbortError, LayaAPIError, LayaConnectionError, LayaError, LayaResponseError,
  LayaTimeoutError, LayaValidationError,
} from './errors.js';
import type { Health, Prediction, PredictOptions, Questions, RequestOptions, State } from './types.js';
import { isMinConfidenceKey } from './buckets.js';
import { isRecord, validateJson, validateQuestions, validateTimeout } from './validation.js';
import { validateHealth, validatePrediction } from './response.js';

/** One threshold in `[0, 1]`: booleans are not thresholds even though they read as 0/1. */
function isThreshold(value: unknown): value is number {
  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
}

/** Mirror core's `check_min_confidence`: one threshold for every answer, or a non-empty
 *  per-bucket map whose keys core can produce and whose values are all thresholds. Anything else
 *  is refused before the request goes out, so a caller cannot pay for inference with a gate the
 *  server would 422. */
function validateMinConfidence(value: unknown): asserts value is number | Record<string, number> {
  if (isThreshold(value)) return;
  if (isRecord(value) && Object.keys(value).length > 0
      && Object.keys(value).every(isMinConfidenceKey)
      && Object.values(value).every(isThreshold)) return;
  throw new LayaValidationError(
    'minConfidence must be a number between 0 and 1, or a non-empty map of bucket to threshold');
}

export interface LayaOptions {
  /** Server root URL, optionally including a reverse-proxy path prefix. */
  baseURL?: string;
  apiKey?: string;
  /** Optional local checkpoint or alias to send with every prediction. */
  model?: string;
  /** Default 120000 ms; cold checkpoint downloads may require more. Zero disables. */
  timeoutMs?: number;
  headers?: HeadersInit;
  /** Supply a Fetch-compatible implementation for tests or a custom transport. */
  fetch?: typeof globalThis.fetch;
}

export class Laya {
  private readonly baseURL: string;
  private readonly timeoutMs: number;
  private readonly headers: Headers;
  private readonly fetcher: typeof globalThis.fetch;
  private readonly model: string | undefined;

  constructor(options: LayaOptions = {}) {
    let url: URL;
    try { url = new URL(options.baseURL ?? 'http://127.0.0.1:8000'); }
    catch { throw new LayaValidationError('baseURL must be an absolute HTTP(S) URL'); }
    if (!['http:', 'https:'].includes(url.protocol) || url.search || url.hash || url.username || url.password) {
      throw new LayaValidationError('baseURL must be HTTP(S), without credentials, query, or fragment');
    }
    this.baseURL = url.href.replace(/\/+$/, '');
    this.model = options.model;
    if (this.model !== undefined && (typeof this.model !== 'string' || !this.model.trim())) {
      throw new LayaValidationError('model must be a nonempty string');
    }
    this.timeoutMs = options.timeoutMs ?? 120_000;
    validateTimeout(this.timeoutMs);
    this.headers = new Headers(options.headers);
    this.headers.set('Accept', 'application/json');
    if (options.apiKey !== undefined) this.headers.set('Authorization', `Bearer ${options.apiKey}`);
    const fetcher = options.fetch ?? globalThis.fetch;
    if (typeof fetcher !== 'function') throw new LayaValidationError('A Fetch implementation is required');
    this.fetcher = fetcher;
  }

  async predict<const Q extends Questions>(state: State, questions: Q, options: PredictOptions = {}): Promise<Prediction<Q>> {
    validateQuestions(questions);
    const result = await this.request<Prediction<Q>>('/v1/systemone', this.body(state, questions, options), options);
    validatePrediction(result, questions);
    return result;
  }

  /** Query the self-hosted Laya server's health probe. */
  async health(options: RequestOptions = {}): Promise<Health> {
    const result = await this.request<Health>('/health', undefined, options);
    validateHealth(result);
    return result;
  }

  private body(state: State, questions: Questions, options: PredictOptions): string {
    if (state !== null && typeof state !== 'string' && !Array.isArray(state) && !isRecord(state)) {
      throw new LayaValidationError('state must be text, a JSON object, an array, or null');
    }
    if (options.task !== undefined && (typeof options.task !== 'string' || !options.task.trim())) {
      throw new LayaValidationError('task must be a nonempty string');
    }
    for (const key of ['lang', 'langGuess'] as const) {
      const value = options[key];
      if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
        throw new LayaValidationError(`${key} must be a nonempty language code string`);
      }
    }
    for (const key of ['maxLen', 'headMaxLen'] as const) {
      const value = options[key];
      if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
        throw new LayaValidationError(`${key} must be a positive integer`);
      }
    }
    if (options.minConfidence !== undefined) validateMinConfidence(options.minConfidence);
    const model = options.model ?? this.model;
    if (model !== undefined && (typeof model !== 'string' || !model.trim())) {
      throw new LayaValidationError('model must be a nonempty string');
    }
    const wireQuestions = Object.fromEntries(Object.entries(questions).map(([id, question]) => [id,
      question.type === 'choice' && Array.isArray(question.criteria)
        ? { ...question, criteria: Object.fromEntries(question.criteria.map(label => [label, null])) }
        : question,
    ]));
    const body: {
      state: State; questions: typeof wireQuestions; model?: string; task?: string;
      lang?: string; lang_guess?: string; max_len?: number; head_max_len?: number;
      min_confidence?: number | Record<string, number>;
    } = { state, questions: wireQuestions };
    if (model !== undefined) body.model = model;
    // The per-request controls `/v1/systemone` forwards when the request sends them (see
    // docs/http-api.md); absent options stay absent so the deployment's own Router
    // settings remain in charge.
    if (options.task !== undefined) body.task = options.task;
    if (options.lang !== undefined) body.lang = options.lang;
    if (options.langGuess !== undefined) body.lang_guess = options.langGuess;
    if (options.maxLen !== undefined) body.max_len = options.maxLen;
    if (options.headMaxLen !== undefined) body.head_max_len = options.headMaxLen;
    if (options.minConfidence !== undefined) body.min_confidence = options.minConfidence;
    validateJson(body);
    return JSON.stringify(body);
  }

  private async request<T>(path: string, body: string | undefined, options: RequestOptions): Promise<T> {
    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
    validateTimeout(timeoutMs);
    const controller = new AbortController();
    const abort = () => controller.abort(new LayaAbortError('Request aborted', { cause: options.signal?.reason }));
    options.signal?.addEventListener('abort', abort, { once: true });
    if (options.signal?.aborted) abort();
    const timer = timeoutMs > 0 ? setTimeout(() => {
      controller.abort(new LayaTimeoutError(`Request timed out after ${timeoutMs} ms`));
    }, timeoutMs) : undefined;

    try {
      controller.signal.throwIfAborted();
      const headers = new Headers(this.headers);
      if (body !== undefined) headers.set('Content-Type', 'application/json');
      const init: RequestInit = { method: body === undefined ? 'GET' : 'POST', headers, signal: controller.signal };
      if (body !== undefined) init.body = body;
      // Never retry automatically: repeating an expensive inference request is surprising.
      const response = await this.fetcher.call(globalThis, this.baseURL + path, init);
      const raw = await response.text();
      let payload: unknown;
      try { payload = JSON.parse(raw); }
      catch {
        if (response.ok) throw new LayaResponseError('Server returned invalid JSON');
      }
      if (!response.ok) {
        const error = isRecord(payload) && isRecord(payload.error) ? payload.error : undefined;
        const detail = isRecord(payload) ? payload.detail : undefined;
        throw new LayaAPIError(
          typeof error?.message === 'string' ? error.message
            : typeof detail === 'string' ? detail : `Laya returned HTTP ${response.status}`,
          response.status,
          typeof error?.code === 'string' ? error.code : 'http_error',
          error?.details ?? detail ?? payload ?? raw,
        );
      }
      if (!isRecord(payload)) throw new LayaResponseError('Server returned a non-object JSON response');
      return payload as T;
    } catch (error) {
      if (controller.signal.aborted) throw controller.signal.reason;
      if (error instanceof LayaError) throw error;
      throw new LayaConnectionError('Could not reach the Laya server', { cause: error });
    } finally {
      if (timer !== undefined) clearTimeout(timer);
      options.signal?.removeEventListener('abort', abort);
    }
  }
}