js/src/types.ts

/**
 * Public type surface for @cp500/infon-heads.
 *
 * The classifier outputs are denormalized — every field is present
 * for every input — so downstream code can branch on the labels
 * without null-checking. Sentences with no detectable signal for a
 * given head still get the head's "none"/"no" class, never `null`.
 */

/** A wordpiece token with char-level alignment back into source text.
 * Surfaced from the tokenizer; not part of the classifier output but
 * exported for downstream callers that want to highlight tokens. */
export interface Token {
  /** Token-vocabulary id. */
  id: number;
  /** Decoded string for this token. */
  text: string;
  /** Inclusive char offset where this token starts. */
  start: number;
  /** Exclusive char offset where this token ends. */
  end: number;
}

/** All six classifier outputs for one sentence. */
export interface ClassifyResult {
  /** Original sentence, unchanged. */
  text: string;
  /** Affirmed / negated / uncertain assertion stance. */
  polarity: 'affirmed' | 'negated' | 'uncertain';
  /** Past / present / future / conditional tense. */
  tense: 'past' | 'present' | 'future' | 'conditional';
  /** Whether this sentence is a conditional clause. */
  conditional: boolean;
  /** Causal / temporal / spatial / attributive / none relation. */
  relationType:
    | 'causal'
    | 'temporal'
    | 'spatial'
    | 'attributive'
    | 'none';
  /** Spatial-relation kind (independent of ``relationType``). */
  spatialRelation:
    | 'containment'
    | 'proximity'
    | 'direction'
    | 'movement'
    | 'none';
  /** Increase / decrease / stable / target / none — change semantics
   * that pair with numeric quantities. */
  comparativeDirection:
    | 'increase'
    | 'decrease'
    | 'stable'
    | 'target'
    | 'none';
  /** Per-head softmax probability of the chosen class. Useful for
   * downstream callers that want to threshold low-confidence
   * classifications. */
  confidence: {
    polarity: number;
    tense: number;
    conditional: number;
    relationType: number;
    spatialRelation: number;
    comparativeDirection: number;
  };
  /** Per-stage timing in milliseconds. */
  timing: {
    tokenize: number;
    backbone: number;
    heads: number;
    total: number;
  };
}

/** Quantization variant + execution device. */
export interface ModelOptions {
  /** ``'fp16'`` halves the download. ``'fp32'`` is safer for
   * debugging.
   * @default 'fp16' */
  precision?: 'fp32' | 'fp16';
  /** Execution provider for ORT.
   * @default 'auto' */
  device?: 'auto' | 'webgpu' | 'wasm' | 'cpu' | 'cuda';
  /** Hard cap on input wordpieces; longer inputs get truncated.
   * Heads operate on single sentences so 96 is plenty.
   * @default 96 */
  maxLength?: number;
  /** Print timing + per-stage shapes to ``console.debug``.
   * @default false */
  debug?: boolean;
}

/** Loaded ONNX session pair + tokenizer + metadata. */
export interface LoadedModel {
  backbone: import('./ort.js').OrtSession;
  classifier: import('./ort.js').OrtSession;
  tokenizer: import('./tokenizer.js').Tokenizer;
  meta: {
    hiddenSize: number;
    maxLength: number;
    precision: 'fp32' | 'fp16';
    device: string;
  };
}