@supersoniks/concorde 4.9.95 → 4.9.97-visual-stack.0

package/src/core/components/functional/infer/hugging-face/hf-engine.ts

@@ -0,0 +1,178 @@
+/**
+ * Moteur d'inférence vu du thread principal.
+ *
+ * `HfEngine` est l'interface ; `HfWorkerEngine` la réalise avec un Web Worker
+ * (le seul endroit où Transformers.js est chargé). Les tests, ou une
+ * application qui veut son propre transport, peuvent fournir un autre moteur.
+ */
+import type {
+  HfErrorCode,
+  HfInspectResult,
+  HfLoadResult,
+  HfModelRef,
+  HfProgress,
+  HfRunRequest,
+  HfWorkerEnv,
+  HfWorkerRequest,
+  HfWorkerResponse,
+} from "./hf-protocol";
+import type { HfDevice } from "./types";
+import { buildHfWorkerSource } from "./hf-worker-runtime";
+
+export interface HfEngine {
+  configure(env: HfWorkerEnv): Promise<void>;
+  inspect(model: HfModelRef): Promise<HfInspectResult>;
+  load(
+    model: HfModelRef,
+    devices: HfDevice[],
+    onProgress: (progress: HfProgress) => void,
+  ): Promise<HfLoadResult>;
+  run(request: HfRunRequest): Promise<unknown[]>;
+  clear(model?: HfModelRef): Promise<void>;
+  dispose(): void;
+}
+
+export class HfEngineError extends Error {
+  constructor(
+    public readonly code: HfErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HfEngineError";
+  }
+}
+
+type Pending = {
+  resolve: (value: unknown) => void;
+  reject: (reason: unknown) => void;
+};
+
+type WorkerRequestBody = HfWorkerRequest extends infer R
+  ? R extends { id: number }
+    ? Omit<R, "id">
+    : never
+  : never;
+
+export class HfWorkerEngine implements HfEngine {
+  private worker: Worker | null = null;
+  private nextId = 1;
+  private readonly pending = new Map<number, Pending>();
+  private readonly progressListeners = new Map<
+    string,
+    (progress: HfProgress) => void
+  >();
+  private fatal: HfEngineError | null = null;
+
+  constructor(private readonly createWorker: () => Worker) {}
+
+  /** Worker « blob » qui importe Transformers.js depuis une URL figée. */
+  static fromUrl(libraryUrl: string): HfWorkerEngine {
+    let blobUrl: string | null = null;
+    const engine = new HfWorkerEngine(() => {
+      const source = buildHfWorkerSource(libraryUrl);
+      blobUrl = URL.createObjectURL(
+        new Blob([source], { type: "text/javascript" }),
+      );
+      return new Worker(blobUrl, { type: "module", name: "concorde-hf" });
+    });
+    const dispose = engine.dispose.bind(engine);
+    engine.dispose = () => {
+      dispose();
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+    };
+    return engine;
+  }
+
+  private ensureWorker(): Worker {
+    if (this.fatal) throw this.fatal;
+    if (this.worker) return this.worker;
+    const worker = this.createWorker();
+    worker.addEventListener("message", (event: MessageEvent) =>
+      this.onMessage(event.data as HfWorkerResponse),
+    );
+    worker.addEventListener("error", (event: ErrorEvent) => {
+      this.failAll(
+        new HfEngineError(
+          "runtime",
+          `Worker Hugging Face : ${event.message || "erreur de chargement (CSP worker-src / script-src ?)"}`,
+        ),
+      );
+    });
+    this.worker = worker;
+    return worker;
+  }
+
+  private onMessage(msg: HfWorkerResponse): void {
+    if ("type" in msg) {
+      if (msg.type === "progress") {
+        this.progressListeners.get(msg.alias)?.(msg.progress);
+      } else if (msg.type === "fatal") {
+        this.failAll(new HfEngineError("runtime", msg.message));
+      }
+      return;
+    }
+    const pending = this.pending.get(msg.id);
+    if (!pending) return;
+    this.pending.delete(msg.id);
+    if (msg.ok) pending.resolve(msg.result);
+    else pending.reject(new HfEngineError(msg.error.code, msg.error.message));
+  }
+
+  private failAll(error: HfEngineError): void {
+    this.fatal = error;
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+
+  private request<R>(body: WorkerRequestBody): Promise<R> {
+    let worker: Worker;
+    try {
+      worker = this.ensureWorker();
+    } catch (err) {
+      return Promise.reject(err);
+    }
+    const id = this.nextId++;
+    return new Promise<R>((resolve, reject) => {
+      this.pending.set(id, {
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+      worker.postMessage({ ...body, id });
+    });
+  }
+
+  async configure(env: HfWorkerEnv): Promise<void> {
+    await this.request({ type: "configure", env });
+  }
+
+  inspect(model: HfModelRef): Promise<HfInspectResult> {
+    return this.request({ type: "inspect", model });
+  }
+
+  async load(
+    model: HfModelRef,
+    devices: HfDevice[],
+    onProgress: (progress: HfProgress) => void,
+  ): Promise<HfLoadResult> {
+    this.progressListeners.set(model.alias, onProgress);
+    try {
+      return await this.request({ type: "load", model, devices });
+    } finally {
+      this.progressListeners.delete(model.alias);
+    }
+  }
+
+  run(request: HfRunRequest): Promise<unknown[]> {
+    return this.request({ type: "run", request });
+  }
+
+  async clear(model?: HfModelRef): Promise<void> {
+    await this.request({ type: "clear", model });
+  }
+
+  dispose(): void {
+    this.failAll(new HfEngineError("runtime", "Moteur arrêté."));
+    this.worker?.terminate();
+    this.worker = null;
+  }
+}

package/src/core/components/functional/infer/hugging-face/hf-input.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { compileTextExtractor, normalizeInput, realign } from "./hf-input";
+
+const text = { kind: "text" as const, maxItems: 100, maxChars: 50 };
+
+describe("normalizeInput", () => {
+  it("entrée absente ou vide → empty (rien à charger)", () => {
+    for (const value of [undefined, null, "", "   ", [], {}]) {
+      expect(normalizeInput(value, text).kind).toBe("empty");
+    }
+  });
+
+  it("texte seul", () => {
+    const r = normalizeInput("  un spectacle drôle  ", text);
+    expect(r).toMatchObject({ kind: "ok", many: false, payloads: ["un spectacle drôle"] });
+  });
+
+  it("refuse les nombres et booléens (pas de coercition silencieuse)", () => {
+    const r = normalizeInput(42, text);
+    expect(r).toMatchObject({ kind: "invalid", code: "invalid-input" });
+    if (r.kind === "invalid") expect(r.message).toContain("texte attendu, reçu number");
+  });
+
+  it("objet sans options.text → invalid avec un message explicite", () => {
+    const r = normalizeInput({ label: "A" }, text);
+    expect(r.kind).toBe("invalid");
+    if (r.kind === "invalid") expect(r.message).toContain("options.text");
+  });
+
+  it("liste partiellement valide → positions conservées, sortie alignée", () => {
+    const r = normalizeInput(["a", 3, "", "b"], text);
+    expect(r).toMatchObject({
+      kind: "ok",
+      many: true,
+      length: 4,
+      payloads: ["a", "b"],
+      positions: [0, 3],
+      skipped: 2,
+    });
+    if (r.kind !== "ok") throw new Error();
+    expect(realign(r, ["A", "B"])).toEqual(["A", null, null, "B"]);
+  });
+
+  it("liste entièrement invalide → invalid", () => {
+    expect(normalizeInput([1, true], text).kind).toBe("invalid");
+  });
+
+  it("trop d'éléments → too-large", () => {
+    const r = normalizeInput(["a", "b", "c"], { ...text, maxItems: 2 });
+    expect(r).toMatchObject({ kind: "invalid", code: "too-large" });
+  });
+
+  it("texte trop long → tronqué et signalé", () => {
+    const r = normalizeInput("x".repeat(80), text);
+    if (r.kind !== "ok") throw new Error();
+    expect((r.payloads[0] as string).length).toBe(50);
+    expect(r.truncated).toBe(1);
+    expect(r.warnings[0]).toContain("tronqué");
+  });
+
+  it("objets + chemins pointés (tableaux aplatis)", () => {
+    const events = [
+      {
+        label: "Pierre et le Loup",
+        edito: { sub_title: "Conte musical" },
+        categories: [{ title: "Jeune public" }, { title: "Musique" }],
+      },
+      { label: "Sans catégorie", categories: [] },
+      { nope: true },
+    ];
+    const r = normalizeInput(events, {
+      ...text,
+      maxChars: 500,
+      text: "label + edito.sub_title + categories.title",
+    });
+    if (r.kind !== "ok") throw new Error(JSON.stringify(r));
+    expect(r.payloads).toEqual([
+      "Pierre et le Loup — Conte musical — Jeune public, Musique",
+      "Sans catégorie",
+    ]);
+    expect(r.positions).toEqual([0, 1]);
+    expect(r.skipped).toBe(1);
+  });
+
+  it("extracteur fonction (API TypeScript)", () => {
+    const extract = compileTextExtractor((e: unknown) => (e as { t: string }).t.toUpperCase());
+    expect(extract?.({ t: "abc" })).toBe("ABC");
+  });
+
+  it("images : URL ou Blob ; audio : Float32Array ou URL", () => {
+    const image = { kind: "image" as const, maxItems: 10, maxChars: 10 };
+    expect(normalizeInput("https://x/y.png", image).kind).toBe("ok");
+    expect(normalizeInput(new Blob(["x"]), image).kind).toBe("ok");
+    expect(normalizeInput(12, image).kind).toBe("invalid");
+    const audio = { kind: "audio" as const, maxItems: 10, maxChars: 10 };
+    expect(normalizeInput(new Float32Array([0.1, 0.2]), audio).kind).toBe("ok");
+    expect(normalizeInput({ samples: [] }, audio).kind).toBe("invalid");
+  });
+});

package/src/core/components/functional/infer/hugging-face/hf-input.ts

@@ -0,0 +1,218 @@
+/**
+ * Normalisation et validation des entrées, AVANT tout téléchargement ou calcul.
+ *
+ * Règles :
+ * - absente / vide → `empty` (pas d'erreur, rien n'est chargé) ;
+ * - mauvais type → `invalid` avec un message précis, pas de coercition silencieuse ;
+ * - liste partiellement valide → les éléments inexploitables deviennent `null`
+ *   à leur position (la sortie reste alignée sur l'entrée) ;
+ * - trop grosse → `invalid` (`too-large`) ; texte trop long → tronqué + averti.
+ */
+import type { HfInputKind } from "./types";
+
+/** Chemins pointés séparés par `+` (`"label + edito.sub_title"`), liste de chemins, ou fonction. */
+export type HfTextExtractor<Item = unknown> =
+  | string
+  | readonly string[]
+  | ((item: Item) => string | null | undefined);
+
+export type HfNormalizeOptions = {
+  kind: HfInputKind;
+  text?: HfTextExtractor;
+  maxItems: number;
+  maxChars: number;
+};
+
+export type HfNormalizedInput =
+  | { kind: "empty" }
+  | { kind: "invalid"; code: "invalid-input" | "too-large"; message: string }
+  | {
+      kind: "ok";
+      /** L'entrée était une liste : la sortie sera une liste alignée. */
+      many: boolean;
+      /** Longueur de l'entrée d'origine. */
+      length: number;
+      /** Charges utiles valides, dans l'ordre. */
+      payloads: unknown[];
+      /** Position d'origine de chaque charge utile valide. */
+      positions: number[];
+      skipped: number;
+      truncated: number;
+      warnings: string[];
+    };
+
+function describe(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (value instanceof Blob) return "Blob";
+  if (ArrayBuffer.isView(value)) return value.constructor.name;
+  return typeof value;
+}
+
+/** Compile un extracteur de texte (chemins pointés) une fois pour toutes. */
+export function compileTextExtractor(
+  text: HfTextExtractor | undefined,
+): ((item: unknown) => string | null) | null {
+  if (text === undefined || text === null || text === "") return null;
+  if (typeof text === "function") {
+    return (item) => {
+      const value = text(item);
+      return typeof value === "string" ? value : null;
+    };
+  }
+  const paths = (typeof text === "string" ? text.split("+") : [...text])
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => p.split("."));
+  if (!paths.length) return null;
+
+  const read = (value: unknown, parts: string[]): string[] => {
+    if (value === null || value === undefined) return [];
+    if (!parts.length) {
+      if (typeof value === "string") return value.trim() ? [value.trim()] : [];
+      if (typeof value === "number") return [String(value)];
+      if (Array.isArray(value)) return value.flatMap((v) => read(v, []));
+      return [];
+    }
+    if (Array.isArray(value)) return value.flatMap((v) => read(v, parts));
+    if (typeof value !== "object") return [];
+    const [head, ...rest] = parts;
+    return read((value as Record<string, unknown>)[head], rest);
+  };
+
+  return (item) => {
+    const parts = paths
+      .map((p) => read(item, p).join(", "))
+      .filter((s) => s.length > 0);
+    return parts.length ? parts.join(" — ") : null;
+  };
+}
+
+function isEmptyValue(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "string") return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object" && !(value instanceof Blob) && !ArrayBuffer.isView(value))
+    return Object.keys(value as object).length === 0;
+  return false;
+}
+
+type ItemResult = { ok: true; payload: unknown; truncated: boolean } | { ok: false; reason: string };
+
+function normalizeItem(
+  item: unknown,
+  options: HfNormalizeOptions,
+  extract: ((item: unknown) => string | null) | null,
+): ItemResult {
+  switch (options.kind) {
+    case "text": {
+      let text: string | null = null;
+      if (typeof item === "string") text = item.trim();
+      else if (item && typeof item === "object" && !Array.isArray(item)) {
+        if (!extract)
+          return {
+            ok: false,
+            reason: "objet reçu sans `options.text` pour en extraire le texte",
+          };
+        text = extract(item);
+      } else {
+        return { ok: false, reason: `texte attendu, reçu ${describe(item)}` };
+      }
+      if (!text) return { ok: false, reason: "texte vide" };
+      if (text.length > options.maxChars)
+        return { ok: true, payload: text.slice(0, options.maxChars), truncated: true };
+      return { ok: true, payload: text, truncated: false };
+    }
+    case "image": {
+      if (typeof item === "string" && item.trim())
+        return { ok: true, payload: item.trim(), truncated: false };
+      if (item instanceof Blob) return { ok: true, payload: item, truncated: false };
+      return {
+        ok: false,
+        reason: `image attendue (URL, data URL ou Blob), reçu ${describe(item)}`,
+      };
+    }
+    case "audio": {
+      if (item instanceof Float32Array || item instanceof Float64Array)
+        return { ok: true, payload: item, truncated: false };
+      if (typeof item === "string" && item.trim())
+        return { ok: true, payload: item.trim(), truncated: false };
+      return {
+        ok: false,
+        reason: `audio attendu (Float32Array, Float64Array ou URL), reçu ${describe(item)}`,
+      };
+    }
+  }
+}
+
+export function normalizeInput(
+  value: unknown,
+  options: HfNormalizeOptions,
+): HfNormalizedInput {
+  if (isEmptyValue(value)) return { kind: "empty" };
+  const extract = compileTextExtractor(options.text);
+  const many = Array.isArray(value);
+  const items = many ? (value as unknown[]) : [value];
+
+  if (items.length > options.maxItems) {
+    return {
+      kind: "invalid",
+      code: "too-large",
+      message: `Entrée trop grosse : ${items.length} éléments (maximum ${options.maxItems}).`,
+    };
+  }
+
+  const payloads: unknown[] = [];
+  const positions: number[] = [];
+  const reasons: string[] = [];
+  let truncated = 0;
+  items.forEach((item, index) => {
+    const result = normalizeItem(item, options, extract);
+    if (result.ok) {
+      payloads.push(result.payload);
+      positions.push(index);
+      if (result.truncated) truncated++;
+    } else {
+      reasons.push(many ? `[${index}] ${result.reason}` : result.reason);
+    }
+  });
+
+  if (!payloads.length) {
+    return {
+      kind: "invalid",
+      code: "invalid-input",
+      message: `Entrée invalide : ${reasons.slice(0, 3).join(" ; ")}${reasons.length > 3 ? ` (+${reasons.length - 3})` : ""}.`,
+    };
+  }
+
+  const warnings: string[] = [];
+  if (truncated)
+    warnings.push(`${truncated} texte(s) tronqué(s) à ${options.maxChars} caractères.`);
+  if (reasons.length)
+    warnings.push(
+      `${reasons.length} élément(s) ignoré(s) : ${reasons.slice(0, 3).join(" ; ")}.`,
+    );
+
+  return {
+    kind: "ok",
+    many,
+    length: items.length,
+    payloads,
+    positions,
+    skipped: items.length - payloads.length,
+    truncated,
+    warnings,
+  };
+}
+
+/** Replace les résultats à leur position d'origine (`null` pour les éléments ignorés). */
+export function realign<T>(
+  input: Extract<HfNormalizedInput, { kind: "ok" }>,
+  results: T[],
+): (T | null)[] {
+  const out: (T | null)[] = new Array(input.length).fill(null);
+  input.positions.forEach((position, i) => {
+    out[position] = results[i] ?? null;
+  });
+  return out;
+}

package/src/core/components/functional/infer/hugging-face/hf-protocol.ts

@@ -0,0 +1,76 @@
+/**
+ * Protocole entre le thread principal et le worker qui exécute Transformers.js.
+ * Uniquement des données sérialisables (structured clone).
+ */
+import type { HfDevice, HfLoadOptions, HfTask } from "./types";
+
+export type HfWorkerEnv = {
+  /** Hôte des modèles (CDN Supersoniks, ou le Hub par défaut). */
+  remoteHost?: string;
+  remotePathTemplate?: string;
+  /** Clé du cache navigateur (Cache API) des modèles et du WASM. */
+  cacheKey: string;
+  /** Emplacement des binaires ONNX Runtime (`.wasm` / `.mjs`) de la version figée. */
+  wasmPaths?: string | { mjs: string; wasm: string };
+  logLevel?: "error" | "warning" | "info" | "debug";
+};
+
+export type HfModelRef = {
+  alias: string;
+  task: HfTask;
+  repo: string;
+  revision: string;
+  options: HfLoadOptions;
+};
+
+export type HfInspectResult = {
+  /** Taille totale à télécharger (octets) si le serveur la donne. */
+  totalBytes: number | null;
+  cached: boolean;
+};
+
+export type HfLoadResult = {
+  backend: HfDevice;
+  loadMs: number;
+};
+
+export type HfProgress = {
+  file?: string;
+  loadedBytes: number;
+  totalBytes: number;
+  percent: number;
+};
+
+export type HfRunRequest = {
+  alias: string;
+  /** Entrées valides uniquement (le thread principal réaligne ensuite). */
+  inputs: unknown[];
+  call: Record<string, unknown>;
+  /** Nom de l'argument positionnel à extraire de `call` (`candidate_labels`, `context`). */
+  positional?: string;
+  /** Regrouper les entrées en un seul appel (embeddings de textes). */
+  batch: boolean;
+};
+
+export type HfErrorCode =
+  | "unsupported"
+  | "network"
+  | "quota"
+  | "timeout"
+  | "not-allowed"
+  | "runtime"
+  | "declined";
+
+export type HfWorkerRequest =
+  | { id: number; type: "configure"; env: HfWorkerEnv }
+  | { id: number; type: "inspect"; model: HfModelRef }
+  | { id: number; type: "load"; model: HfModelRef; devices: HfDevice[] }
+  | { id: number; type: "run"; request: HfRunRequest }
+  | { id: number; type: "clear"; model?: HfModelRef };
+
+export type HfWorkerResponse =
+  | { id: number; ok: true; result: unknown }
+  | { id: number; ok: false; error: { code: HfErrorCode; message: string } }
+  | { type: "progress"; alias: string; progress: HfProgress }
+  /** Le worker n'a pas pu démarrer (moteur introuvable, CSP…). */
+  | { type: "fatal"; message: string };