Upload js/src/types.ts with huggingface_hub

js/src/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Public type surface for @cp500/infon-coref.
+ *
+ * Most consumers only need {@link CorefResult}; the rest are exposed
+ * so power users can wire individual pipeline stages on their own.
+ */
+
+/** A single wordpiece token, with its char-level alignment back into
+ * the source text. ``start`` and ``end`` are byte offsets into the
+ * UTF-8 string (the same convention Python uses).
+ */
+export interface Token {
+  /** Token-vocabulary id. */
+  id: number;
+  /** The decoded string for this token (includes ▁ for SentencePiece
+   * word-initial pieces). */
+  text: string;
+  /** Inclusive char offset where this token starts. */
+  start: number;
+  /** Exclusive char offset where this token ends. */
+  end: number;
+}
+
+/** A detected mention span, in wordpiece coordinates and char
+ * coordinates. ``start``/``end`` are inclusive **wordpiece** indices;
+ * ``charStart``/``charEnd`` are exclusive **char** offsets. */
+export interface Mention {
+  /** First wordpiece in the mention (inclusive). */
+  start: number;
+  /** Last wordpiece in the mention (inclusive). */
+  end: number;
+  /** Char offset where the mention begins. */
+  charStart: number;
+  /** Char offset just past the last char of the mention. */
+  charEnd: number;
+  /** The literal substring of the source text covered by this mention. */
+  text: string;
+  /** Cluster index this mention was assigned to. -1 if singleton. */
+  cluster: number;
+  /** Index of the most recent earlier mention sharing this cluster, or
+   * -1 if this mention starts a new cluster. */
+  antecedent: number;
+}
+
+/** End-to-end coreference resolution output. */
+export interface CorefResult {
+  /** Original input text, unchanged. */
+  text: string;
+  /** Wordpiece tokenization with offsets. */
+  tokens: Token[];
+  /** Mentions in document order, with cluster + antecedent assignments. */
+  mentions: Mention[];
+  /** clusters[c] is a list of mention indices belonging to cluster c.
+   * Only multi-mention clusters are listed; singletons are marked
+   * with ``cluster: -1`` on the {@link Mention}. */
+  clusters: number[][];
+  /** Per-stage timing in milliseconds. */
+  timing: {
+    tokenize: number;
+    backbone: number;
+    bioDecode: number;
+    scorer: number;
+    total: number;
+  };
+}
+
+/** Quantization variant + execution device picked at load time. The
+ * library auto-falls-back when a requested combination isn't
+ * available (e.g. WebGPU + FP16 → WASM + FP16 → WASM + FP32). */
+export interface ModelOptions {
+  /** ``'fp16'`` halves the download (235 MB vs 470 MB) and runs
+   * faster on WebGPU. ``'fp32'`` is the safe default for debugging.
+   * @default 'fp16' */
+  precision?: 'fp32' | 'fp16';
+  /** Execution provider for ORT. Browser values: ``'webgpu'`` |
+   * ``'wasm'``. Node values: ``'cpu'`` | ``'cuda'``. ``'auto'`` picks
+   * the fastest available.
+   * @default 'auto' */
+  device?: 'auto' | 'webgpu' | 'wasm' | 'cpu' | 'cuda';
+  /** Hard cap on input wordpieces; longer inputs get truncated.
+   * @default 256 */
+  maxLength?: number;
+  /** Threshold over the BIO ``B``/``I`` softmax (vs ``O``) for span
+   * detection. Higher = stricter, fewer mentions.
+   * @default 0.5 */
+  bioThreshold?: 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;
+  scorer: import('./ort.js').OrtSession;
+  tokenizer: import('./tokenizer.js').Tokenizer;
+  meta: {
+    hiddenSize: number;
+    nBioClasses: number;
+    maxLength: number;
+    precision: 'fp32' | 'fp16';
+    device: string;
+  };
+}