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

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

@@ -0,0 +1,457 @@
+/**
+ * Registre des modèles (thread principal, un seul par page).
+ *
+ * - un seul chargement par alias, partagé par toutes les instances ;
+ * - taille et présence en cache connues AVANT téléchargement ;
+ * - consentement (mémorisé par alias + révision, révocable) ;
+ * - garde-fous : économie de données, réseau lent, gros modèle, quota ;
+ * - choix WebGPU / WASM selon le plafond `allowWasmUpToMB`.
+ */
+import {
+  getHuggingFaceConfig,
+  onHuggingFaceConfig,
+  type HfLoadPolicy,
+  type HfResolvedConfig,
+} from "./hf-config";
+import { HfEngineError, HfWorkerEngine, type HfEngine } from "./hf-engine";
+import type {
+  HfErrorCode,
+  HfModelRef,
+  HfProgress,
+  HfRunRequest,
+} from "./hf-protocol";
+import type { HfDevice } from "./types";
+
+export type HfModelPhase =
+  | "idle"
+  | "checking"
+  | "awaiting-consent"
+  | "declined"
+  | "downloading"
+  | "loading"
+  | "ready"
+  | "error"
+  | "unsupported";
+
+export type HfModelState = {
+  phase: HfModelPhase;
+  /** Connue avant téléchargement (serveur, sinon `sizeBytes` déclarée). */
+  size: { totalBytes: number | null; fromCache: boolean } | null;
+  progress?: HfProgress;
+  backend?: HfDevice;
+  persisted?: boolean;
+  loadMs?: number;
+  error?: { code: HfErrorCode; message: string };
+};
+
+type Entry = {
+  state: HfModelState;
+  listeners: Set<(state: HfModelState) => void>;
+  inspect?: Promise<HfModelState["size"]>;
+  loading?: Promise<void>;
+  consent?: { promise: Promise<boolean>; resolve: (accepted: boolean) => void };
+};
+
+const CONSENT_PREFIX = "concorde-hf-consent:";
+const MB = 1024 * 1024;
+
+function storage(): Storage | null {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage : null;
+  } catch {
+    return null;
+  }
+}
+
+type NetworkInformationLike = { saveData?: boolean; effectiveType?: string };
+
+function constrainedNetwork(): boolean {
+  const connection = (
+    globalThis.navigator as Navigator & { connection?: NetworkInformationLike }
+  )?.connection;
+  if (!connection) return false;
+  return (
+    connection.saveData === true ||
+    connection.effectiveType === "slow-2g" ||
+    connection.effectiveType === "2g"
+  );
+}
+
+export class HfError extends Error {
+  constructor(
+    public readonly code: HfErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HfError";
+  }
+}
+
+export class HuggingFaceRegistry {
+  private readonly entries = new Map<string, Entry>();
+  private engine: HfEngine | null = null;
+  private configured: Promise<void> | null = null;
+
+  constructor(private config: HfResolvedConfig) {}
+
+  /* ---------------- configuration / moteur ---------------- */
+
+  get resolvedConfig(): HfResolvedConfig {
+    return this.config;
+  }
+
+  private getEngine(): HfEngine {
+    if (this.engine) return this.engine;
+    const runtime = this.config.runtime;
+    if (runtime.source === "engine") this.engine = runtime.engine;
+    else if (runtime.source === "worker")
+      this.engine = new HfWorkerEngine(runtime.createWorker);
+    else this.engine = HfWorkerEngine.fromUrl(runtime.url);
+    return this.engine;
+  }
+
+  private async ready(): Promise<HfEngine> {
+    const engine = this.getEngine();
+    if (!this.configured) {
+      const runtime = this.config.runtime;
+      const wasmPaths =
+        runtime.source === "engine"
+          ? undefined
+          : (runtime.wasmPaths ??
+            (runtime.source === "cdn"
+              ? new URL(".", runtime.url).href
+              : undefined));
+      this.configured = engine.configure({
+        cacheKey: `concorde-hf-${runtime.version}`,
+        remoteHost: this.config.remoteHost,
+        remotePathTemplate: this.config.remotePathTemplate,
+        wasmPaths,
+        logLevel: this.config.logLevel,
+      });
+    }
+    await this.configured;
+    return engine;
+  }
+
+  dispose(): void {
+    this.engine?.dispose();
+    this.engine = null;
+    this.configured = null;
+    this.entries.clear();
+  }
+
+  /* ---------------- modèles ---------------- */
+
+  hasModel(alias: string): boolean {
+    return Object.prototype.hasOwnProperty.call(this.config.models, alias);
+  }
+
+  model(alias: string): HfModelRef & {
+    devices: readonly HfDevice[];
+    sizeBytes?: number;
+    label?: string;
+    description?: string;
+    defaults?: Record<string, unknown>;
+  } {
+    if (!this.hasModel(alias)) {
+      const known = Object.keys(this.config.models);
+      throw new HfError(
+        "not-allowed",
+        `[sonic-hugging-face-infer] modèle "${alias}" hors liste blanche` +
+          (known.length ? ` (disponibles : ${known.join(", ")}).` : "."),
+      );
+    }
+    const def = this.config.models[alias];
+    return {
+      alias,
+      task: def.task,
+      repo: def.repo,
+      revision: def.revision,
+      options: def.options ?? {},
+      devices: def.devices ?? ["webgpu", "wasm"],
+      sizeBytes: def.sizeBytes,
+      label: def.label,
+      description: def.description,
+      defaults: def.defaults as Record<string, unknown> | undefined,
+    };
+  }
+
+  private entry(alias: string): Entry {
+    let entry = this.entries.get(alias);
+    if (!entry) {
+      entry = { state: { phase: "idle", size: null }, listeners: new Set() };
+      this.entries.set(alias, entry);
+    }
+    return entry;
+  }
+
+  state(alias: string): HfModelState {
+    return this.entry(alias).state;
+  }
+
+  subscribe(alias: string, listener: (state: HfModelState) => void): () => void {
+    const entry = this.entry(alias);
+    entry.listeners.add(listener);
+    listener(entry.state);
+    return () => entry.listeners.delete(listener);
+  }
+
+  private update(alias: string, patch: Partial<HfModelState>): void {
+    const entry = this.entry(alias);
+    entry.state = { ...entry.state, ...patch };
+    for (const listener of entry.listeners) listener(entry.state);
+  }
+
+  /** Taille et présence en cache, sans rien télécharger d'autre que des en-têtes. */
+  inspect(alias: string): Promise<HfModelState["size"]> {
+    const entry = this.entry(alias);
+    if (!entry.inspect) {
+      const model = this.model(alias);
+      entry.inspect = (async () => {
+        this.update(alias, { phase: "checking" });
+        let totalBytes: number | null = model.sizeBytes ?? null;
+        let fromCache = false;
+        try {
+          const engine = await this.ready();
+          const result = await engine.inspect(model);
+          totalBytes = result.totalBytes ?? totalBytes;
+          fromCache = result.cached;
+        } catch {
+          /* taille déclarée à défaut */
+        }
+        const size = { totalBytes, fromCache };
+        this.update(alias, { size, phase: "idle" });
+        return size;
+      })();
+    }
+    return entry.inspect;
+  }
+
+  /* ---------------- consentement ---------------- */
+
+  private consentKey(alias: string): string {
+    return `${CONSENT_PREFIX}${alias}@${this.model(alias).revision}`;
+  }
+
+  storedConsent(alias: string): "accepted" | "declined" | null {
+    const value = storage()?.getItem(this.consentKey(alias));
+    return value === "accepted" || value === "declined" ? value : null;
+  }
+
+  accept(alias: string): void {
+    try {
+      storage()?.setItem(this.consentKey(alias), "accepted");
+    } catch {
+      /* stockage indisponible : consentement pour la session seulement */
+    }
+    const entry = this.entry(alias);
+    entry.consent?.resolve(true);
+    entry.consent = undefined;
+    if (entry.state.phase === "declined") this.update(alias, { phase: "idle" });
+  }
+
+  decline(alias: string): void {
+    try {
+      storage()?.setItem(this.consentKey(alias), "declined");
+    } catch {
+      /* idem */
+    }
+    const entry = this.entry(alias);
+    entry.consent?.resolve(false);
+    entry.consent = undefined;
+    this.update(alias, { phase: "declined" });
+  }
+
+  revokeConsent(alias: string): void {
+    try {
+      storage()?.removeItem(this.consentKey(alias));
+    } catch {
+      /* idem */
+    }
+    if (this.entry(alias).state.phase === "declined")
+      this.update(alias, { phase: "idle" });
+  }
+
+  private askConsent(alias: string): Promise<boolean> {
+    const stored = this.storedConsent(alias);
+    if (stored) return Promise.resolve(stored === "accepted");
+    const entry = this.entry(alias);
+    if (!entry.consent) {
+      let resolve!: (accepted: boolean) => void;
+      const promise = new Promise<boolean>((r) => (resolve = r));
+      entry.consent = { promise, resolve };
+    }
+    this.update(alias, { phase: "awaiting-consent" });
+    return entry.consent.promise;
+  }
+
+  /* ---------------- chargement ---------------- */
+
+  /**
+   * Charge le modèle selon la politique. Résout quand il est prêt ; rejette
+   * (`HfError`) si refusé, non supporté, quota insuffisant ou erreur.
+   * `policy = "manual"` signifie « appel explicite » : pas de demande de consentement.
+   */
+  ensureLoaded(alias: string, policy: HfLoadPolicy): Promise<void> {
+    const entry = this.entry(alias);
+    if (entry.state.phase === "ready") return Promise.resolve();
+    if (entry.loading) return entry.loading;
+    const loading = this.load(alias, policy).finally(() => {
+      if (this.entry(alias).loading === loading) entry.loading = undefined;
+    });
+    entry.loading = loading;
+    return loading;
+  }
+
+  private async load(alias: string, policy: HfLoadPolicy): Promise<void> {
+    const model = this.model(alias);
+    const defaults = this.config.defaults;
+    const size = await this.inspect(alias);
+    const cached = size?.fromCache === true;
+    const totalBytes = size?.totalBytes ?? null;
+
+    if (!cached && policy !== "manual") {
+      const stored = this.storedConsent(alias);
+      // Refus mémorisé, ou refus de la session si le stockage est indisponible.
+      if (stored === "declined" || this.entry(alias).state.phase === "declined") {
+        this.update(alias, { phase: "declined" });
+        throw new HfError("declined", "Chargement du modèle refusé par l'utilisateur.");
+      }
+      const tooBig = totalBytes !== null && totalBytes > defaults.consentAboveMB * MB;
+      const mustAsk = policy === "consent" || tooBig || constrainedNetwork();
+      if (mustAsk && stored !== "accepted") {
+        const accepted = await this.askConsent(alias);
+        if (!accepted) {
+          this.update(alias, { phase: "declined" });
+          throw new HfError("declined", "Chargement du modèle refusé par l'utilisateur.");
+        }
+      }
+    }
+
+    const knownSize = totalBytes ?? model.sizeBytes ?? null;
+    const devices = model.devices.filter(
+      (d) =>
+        d !== "wasm" ||
+        knownSize === null ||
+        knownSize <= defaults.allowWasmUpToMB * MB,
+    );
+    if (!devices.length) {
+      this.update(alias, {
+        phase: "unsupported",
+        error: { code: "unsupported", message: "Aucune exécution autorisée pour ce modèle." },
+      });
+      throw new HfError("unsupported", "Aucune exécution autorisée pour ce modèle.");
+    }
+
+    if (!cached && totalBytes) {
+      const estimate = await globalThis.navigator?.storage
+        ?.estimate?.()
+        .catch(() => null);
+      if (estimate?.quota !== undefined) {
+        const free = estimate.quota - (estimate.usage ?? 0);
+        if (free < totalBytes * 1.2) {
+          const message = `Espace de stockage insuffisant (${Math.round(free / MB)} Mo libres, ${Math.round(totalBytes / MB)} Mo nécessaires).`;
+          this.update(alias, { phase: "error", error: { code: "quota", message } });
+          throw new HfError("quota", message);
+        }
+      }
+    }
+
+    this.update(alias, {
+      phase: cached ? "loading" : "downloading",
+      error: undefined,
+      progress: undefined,
+    });
+    try {
+      const engine = await this.ready();
+      const result = await engine.load(model, devices, (progress) =>
+        this.update(alias, { phase: "downloading", progress }),
+      );
+      let persisted: boolean | undefined;
+      if (defaults.persist && !cached) {
+        persisted = await globalThis.navigator?.storage
+          ?.persist?.()
+          .catch(() => false);
+      }
+      this.update(alias, {
+        phase: "ready",
+        backend: result.backend,
+        loadMs: result.loadMs,
+        persisted,
+        size: { totalBytes: knownSize, fromCache: cached },
+      });
+    } catch (err) {
+      const code: HfErrorCode =
+        err instanceof HfEngineError ? err.code : "runtime";
+      const message = err instanceof Error ? err.message : String(err);
+      this.update(alias, {
+        phase: code === "unsupported" ? "unsupported" : "error",
+        error: { code, message },
+      });
+      throw new HfError(code, message);
+    }
+  }
+
+  /* ---------------- calcul ---------------- */
+
+  async run(request: HfRunRequest, timeoutMs: number): Promise<unknown[]> {
+    const engine = await this.ready();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () =>
+          reject(
+            new HfError("timeout", `Calcul trop long (> ${timeoutMs} ms), abandonné.`),
+          ),
+        timeoutMs,
+      );
+    });
+    try {
+      return await Promise.race([engine.run(request), timeout]);
+    } catch (err) {
+      if (err instanceof HfError) throw err;
+      if (err instanceof HfEngineError) throw new HfError(err.code, err.message);
+      throw new HfError("runtime", err instanceof Error ? err.message : String(err));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /* ---------------- nettoyage ---------------- */
+
+  async clearModel(alias: string): Promise<void> {
+    const model = this.model(alias);
+    const engine = await this.ready();
+    await engine.clear(model);
+    const entry = this.entry(alias);
+    entry.inspect = undefined;
+    this.update(alias, { phase: "idle", size: null, backend: undefined, progress: undefined });
+  }
+
+  async clearAll(): Promise<void> {
+    const engine = await this.ready();
+    await engine.clear();
+    for (const alias of this.entries.keys()) {
+      this.entry(alias).inspect = undefined;
+      this.update(alias, { phase: "idle", size: null, backend: undefined, progress: undefined });
+    }
+  }
+}
+
+/* ---------------- singleton ---------------- */
+
+let registry: HuggingFaceRegistry | null = null;
+
+onHuggingFaceConfig((config) => {
+  registry?.dispose();
+  registry = new HuggingFaceRegistry(config);
+});
+
+/** Registre de la page (null tant que `configureHuggingFace` n'a pas été appelé). */
+export function getHuggingFaceRegistry(): HuggingFaceRegistry | null {
+  if (!registry) {
+    const config = getHuggingFaceConfig();
+    if (config) registry = new HuggingFaceRegistry(config);
+  }
+  return registry;
+}

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

@@ -0,0 +1,124 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import {
+  HF_CALL_OPTION_SCHEMAS,
+  HfOptionsError,
+  hfCallOptionsJsonSchema,
+  validateCallOptions,
+} from "./hf-schema";
+import { HF_TASKS, type HfCallOptions, type HfItemOutput, type HfSingleInput } from "./types";
+import { defineHuggingFaceModels } from "./hf-config";
+
+describe("validateCallOptions (entrées non fiables : SDUI, attributs)", () => {
+  it("accepte des options valides", () => {
+    expect(
+      validateCallOptions("feature-extraction", { pooling: "mean", normalize: true }),
+    ).toEqual({ pooling: "mean", normalize: true });
+  });
+
+  it("refuse une clé inconnue en listant les clés autorisées", () => {
+    expect(() => validateCallOptions("feature-extraction", { top_k: 3 })).toThrow(
+      /option "top_k" inconnue.*pooling, normalize/,
+    );
+  });
+
+  it("vérifie les énumérations, types et bornes", () => {
+    expect(() => validateCallOptions("feature-extraction", { pooling: "max" })).toThrow(
+      HfOptionsError,
+    );
+    expect(() => validateCallOptions("translation", { max_new_tokens: "12" })).toThrow(
+      /nombre attendu/,
+    );
+    expect(() => validateCallOptions("translation", { max_new_tokens: 100_000 })).toThrow(
+      /maximum 1024/,
+    );
+    expect(() => validateCallOptions("translation", { num_beams: 2.5 })).toThrow(/entier/);
+  });
+
+  it("argument positionnel replié dans les options (candidate_labels)", () => {
+    expect(
+      validateCallOptions("zero-shot-classification", {
+        candidate_labels: ["jeune public", "humour"],
+        multi_label: true,
+      }),
+    ).toBeTruthy();
+    expect(() =>
+      validateCallOptions("zero-shot-classification", { candidate_labels: [1, 2] }),
+    ).toThrow();
+  });
+
+  it("chaque tâche prise en charge a un schéma", () => {
+    for (const task of HF_TASKS) expect(HF_CALL_OPTION_SCHEMAS[task]).toBeDefined();
+  });
+
+  it("produit un JSON Schema pour le catalogue MCP", () => {
+    const schema = hfCallOptionsJsonSchema("feature-extraction");
+    expect(schema).toMatchObject({
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        pooling: { enum: ["none", "mean", "cls", "first_token", "eos", "last_token"] },
+        normalize: { type: "boolean" },
+      },
+    });
+    expect(hfCallOptionsJsonSchema("translation").properties).toMatchObject({
+      max_new_tokens: { type: "integer", minimum: 1, maximum: 1024 },
+    });
+  });
+});
+
+describe("types dérivés de Transformers.js", () => {
+  it("entrées", () => {
+    expectTypeOf<HfSingleInput<"feature-extraction">>().toEqualTypeOf<string>();
+    expectTypeOf<HfSingleInput<"image-classification">>().toEqualTypeOf<string | Blob>();
+  });
+
+  it("options d'appel : uniquement sérialisables, typées par tâche", () => {
+    expectTypeOf<HfCallOptions<"feature-extraction">>().toHaveProperty("pooling");
+    expectTypeOf<HfCallOptions<"zero-shot-classification">>().toHaveProperty(
+      "candidate_labels",
+    );
+    // Les options non sérialisables (streamer, logits_processor…) sont exclues.
+    expectTypeOf<HfCallOptions<"translation">>().not.toHaveProperty("streamer");
+    expectTypeOf<HfCallOptions<"translation">>().toHaveProperty("max_new_tokens");
+  });
+
+  it("sorties par élément", () => {
+    expectTypeOf<HfItemOutput<"feature-extraction", { pooling: "mean" }>>().toEqualTypeOf<
+      number[]
+    >();
+    expectTypeOf<HfItemOutput<"feature-extraction", object>>().toEqualTypeOf<number[][]>();
+    expectTypeOf<HfItemOutput<"translation">>().toEqualTypeOf<
+      { translation_text: string }[]
+    >();
+    expectTypeOf<HfItemOutput<"zero-shot-classification">>().toEqualTypeOf<{
+      sequence: string;
+      labels: string[];
+      scores: number[];
+    }>();
+  });
+
+  it("defineHuggingFaceModels : defaults vérifiés selon la tâche", () => {
+    defineHuggingFaceModels({
+      ok: {
+        task: "feature-extraction",
+        repo: "r",
+        revision: "sha",
+        defaults: { pooling: "mean" },
+      },
+    });
+    defineHuggingFaceModels({
+      ko: {
+        task: "feature-extraction",
+        repo: "r",
+        revision: "sha",
+        // @ts-expect-error top_k n'existe pas pour feature-extraction
+        defaults: { top_k: 3 },
+      },
+    });
+    defineHuggingFaceModels({
+      // @ts-expect-error revision obligatoire
+      ko: { task: "translation", repo: "r" },
+    });
+    expect(true).toBe(true);
+  });
+});