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

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

@@ -0,0 +1,202 @@
+import { LitElement, html, css } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { onHuggingFaceConfig, type HfLoadPolicy, type HfTrigger } from "./hf-config";
+import {
+  createHfInferController,
+  type HfInferHandle,
+} from "./hf-controller";
+import type { HfTextExtractor } from "./hf-input";
+import { getHuggingFaceRegistry } from "./hf-registry";
+
+type ElementOptions = {
+  /** Champs à concaténer quand l'entrée est une liste d'objets : `"label + edito.sub_title"`. */
+  text?: string | string[];
+  /** Options d'appel du pipeline (validées selon la tâche du modèle). */
+  call?: Record<string, unknown>;
+};
+
+/**
+ * `sonic-hugging-face-infer` : 1 entrée → modèle Hugging Face (Transformers.js,
+ * dans un worker) → 1 sortie (readonly).
+ *
+ * Le composant ne contient pas le moteur : Transformers.js n'est chargé qu'au
+ * premier besoin, dans un worker, depuis une version figée (voir
+ * `configureHuggingFace`). Le modèle doit figurer dans la liste blanche de
+ * l'application (attribut `model` = alias).
+ */
+@customElement("sonic-hugging-face-infer")
+export default class SonicHuggingFaceInfer extends LitElement {
+  static styles = [
+    css`
+      :host {
+        display: contents;
+      }
+    `,
+  ];
+
+  /** Alias du modèle (liste blanche de l'application). */
+  @property({ type: String })
+  model = "";
+
+  /** DataProvider d'entrée : texte, liste de textes, liste d'objets (+ `options.text`), image, audio. */
+  @property({ type: String })
+  inputProvider = "";
+
+  /** DataProvider de sortie (readonly). */
+  @property({ type: String })
+  outputProvider = "";
+
+  /** DataProvider optionnel où publier le statut détaillé (taille, progression, backend…). */
+  @property({ type: String })
+  statusProvider = "";
+
+  /** Mode `demand` : chaque changement de ce DataProvider lance un calcul. */
+  @property({ type: String })
+  triggerProvider = "";
+
+  /** DataProvider (ex. case à cocher d'un formulaire) qui donne le consentement. */
+  @property({ type: String })
+  consentProvider = "";
+
+  /** `{"text": …, "call": {…}}` */
+  @property({ type: Object })
+  options: ElementOptions | null = null;
+
+  /** `auto` | `idle` | `visible` | `first-use` | `consent` | `manual` */
+  @property({ type: String })
+  load: HfLoadPolicy | "" = "";
+
+  /** `mutation` | `demand` */
+  @property({ type: String })
+  trigger: HfTrigger | "" = "";
+
+  @property({ type: Number })
+  debounce: number | null = null;
+
+  /** Valeur publiée quand l'entrée est vide (JSON). Défaut : `null`. */
+  @property({ type: Object })
+  emptyValue: unknown = null;
+
+  /** Entrée invalide : garder le dernier résultat (`keep`) ou vider (`clear`). */
+  @property({ type: String })
+  onInvalid: "keep" | "clear" = "keep";
+
+  @property({ type: Number })
+  maxItems: number | null = null;
+
+  @property({ type: Number })
+  maxChars: number | null = null;
+
+  @property({ type: Number })
+  timeoutMs: number | null = null;
+
+  /** Mémoriser les résultats en IndexedDB (ex. embeddings d'un catalogue stable). */
+  @property({ type: Boolean })
+  persistResults = false;
+
+  /** Durée de validité des résultats mémorisés (ms). */
+  @property({ type: Number })
+  resultsTtl: number | null = null;
+
+  private handle: HfInferHandle | null = null;
+  private offConfig: (() => void) | null = null;
+  private visible: Promise<void> | null = null;
+
+  connectedCallback(): void {
+    super.connectedCallback();
+    this.offConfig = onHuggingFaceConfig(() => this.restart());
+    // Premier branchement : `updated()` s'en charge (toutes les propriétés sont connues).
+    if (this.hasUpdated) this.restart();
+  }
+
+  disconnectedCallback(): void {
+    this.handle?.stop();
+    this.handle = null;
+    this.offConfig?.();
+    this.offConfig = null;
+    super.disconnectedCallback();
+  }
+
+  protected updated(changed: Map<string | number | symbol, unknown>): void {
+    if (changed.size && this.isConnected) this.restart();
+  }
+
+  /** Calcule maintenant sur l'entrée courante. */
+  run(): Promise<void> {
+    return this.handle?.run() ?? Promise.resolve();
+  }
+
+  /** Charge le modèle maintenant. */
+  loadModel(): Promise<void> {
+    return this.handle?.load() ?? Promise.resolve();
+  }
+
+  accept(): void {
+    this.handle?.accept();
+  }
+
+  decline(): void {
+    this.handle?.decline();
+  }
+
+  private whenVisible = (): Promise<void> => {
+    if (!this.visible) {
+      this.visible = new Promise((resolve) => {
+        // `display: contents` : on observe le parent.
+        const target = this.parentElement ?? this;
+        if (typeof IntersectionObserver === "undefined") return resolve();
+        const observer = new IntersectionObserver((entries) => {
+          if (entries.some((e) => e.isIntersecting)) {
+            observer.disconnect();
+            resolve();
+          }
+        });
+        observer.observe(target);
+      });
+    }
+    return this.visible;
+  };
+
+  private restart(): void {
+    this.handle?.stop();
+    this.handle = null;
+    if (!this.isConnected) return;
+    if (!this.model || !this.inputProvider || !this.outputProvider) return;
+    if (!getHuggingFaceRegistry()) {
+      console.warn(
+        "[sonic-hugging-face-infer] configureHuggingFace() n'a pas été appelé : composant inactif.",
+      );
+      return;
+    }
+    try {
+      this.handle = createHfInferController({
+        model: this.model,
+        input: this.inputProvider,
+        output: this.outputProvider,
+        status: this.statusProvider || undefined,
+        triggerProvider: this.triggerProvider || undefined,
+        consentProvider: this.consentProvider || undefined,
+        text: this.options?.text as HfTextExtractor | undefined,
+        call: this.options?.call,
+        untrusted: true,
+        load: this.load || undefined,
+        trigger: this.trigger || undefined,
+        debounceMs: this.debounce ?? undefined,
+        emptyValue: this.emptyValue,
+        onInvalid: this.onInvalid,
+        maxItems: this.maxItems ?? undefined,
+        maxChars: this.maxChars ?? undefined,
+        timeoutMs: this.timeoutMs ?? undefined,
+        persistResults: this.persistResults,
+        resultsTtlMs: this.resultsTtl ?? undefined,
+        whenVisible: this.whenVisible,
+      });
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : err);
+    }
+  }
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}

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

@@ -0,0 +1,282 @@
+/**
+ * API publique de l'inférence Hugging Face dans Concorde.
+ *
+ * ```ts
+ * import { configureHuggingFace, defineHuggingFaceModels } from "@supersoniks/concorde/hugging-face";
+ *
+ * export const hf = configureHuggingFace({
+ *   runtime: { source: "cdn", version: "4.3.0", url: "https://cdn…/hf-transformers/4.3.0/transformers.min.js" },
+ *   models: defineHuggingFaceModels({
+ *     "multilingual-mini": {
+ *       task: "feature-extraction",
+ *       repo: "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
+ *       revision: "<sha>",
+ *       options: { dtype: "q8" },
+ *       defaults: { pooling: "mean", normalize: true },
+ *     },
+ *   }),
+ * });
+ *
+ * hf.infer({ model: "multilingual-mini", input: events, text: (e) => e.label, output: eventVectors });
+ * ```
+ *
+ * Ce module ne contient pas Transformers.js (uniquement des `import type`).
+ */
+import type { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+import {
+  setHuggingFaceConfig,
+  type HfLoadPolicy,
+  type HfModels,
+  type HfTrigger,
+  type HuggingFaceConfig,
+} from "./hf-config";
+import {
+  createHfInferController,
+  type HfInferHandle,
+  type HfInferStatus,
+} from "./hf-controller";
+import { normalizeInput, realign, type HfTextExtractor } from "./hf-input";
+import {
+  getHuggingFaceRegistry,
+  HfError,
+  type HfModelState,
+  type HuggingFaceRegistry,
+} from "./hf-registry";
+import { clearResults } from "./hf-cache";
+import type { HF_CALL_OPTION_SCHEMAS } from "./hf-schema";
+import {
+  HF_POSITIONAL_ARGS,
+  HF_TASK_INPUT_KIND,
+  type HfCallOptions,
+  type HfExact,
+  type HfOutput,
+  type HfSingleInput,
+  type HfTask,
+} from "./types";
+
+/* ------------------------------------------------------------------ */
+/* Types liés à la liste blanche                                       */
+/* ------------------------------------------------------------------ */
+
+export type HfAlias<M extends HfModels> = Extract<keyof M, string>;
+export type HfTaskOf<M extends HfModels, A extends HfAlias<M>> = M[A]["task"];
+type DefaultsOf<M extends HfModels, A extends HfAlias<M>> = M[A] extends {
+  defaults: infer D;
+}
+  ? D
+  : unknown;
+
+/** Options effectives = défauts du modèle, surchargés par ceux de l'appel. */
+export type HfMergedOptions<D, C> = Omit<D, keyof C> & C;
+
+/** Entrée acceptée pour une tâche : un élément, une liste, ou (texte) des objets + `text`. */
+export type HfAcceptedInput<T extends HfTask> =
+  | HfSingleInput<T>
+  | readonly HfSingleInput<T>[]
+  | (T extends HfTask
+      ? (typeof HF_TASK_INPUT_KIND)[T] extends "text"
+        ? object | readonly object[]
+        : never
+      : never)
+  | null
+  | undefined;
+
+/**
+ * Clés d'options d'une tâche, lues sur la table de schémas (identique aux
+ * clés de `HfCallOptions<T>`, garanti à la compilation par `hf-schema.ts`) :
+ * beaucoup moins coûteux à évaluer pour le compilateur.
+ */
+type HfCallKeys<T extends HfTask> = Record<
+  keyof (typeof HF_CALL_OPTION_SCHEMAS)[T],
+  unknown
+>;
+
+type ItemOf<In> = In extends readonly (infer E)[] ? E : In;
+type IsMany<In> = [NonNullable<In>] extends [readonly unknown[]] ? true : false;
+
+/** Sortie publiée pour un alias, des options d'appel et un type d'entrée. */
+export type HfResult<
+  M extends HfModels,
+  A extends HfAlias<M>,
+  C,
+  In,
+> = HfOutput<HfTaskOf<M, A>, HfMergedOptions<DefaultsOf<M, A>, C>, IsMany<In>>;
+
+export type HfInferOptions<
+  M extends HfModels,
+  A extends HfAlias<M>,
+  In,
+  C,
+> = {
+  model: A;
+  input: DataProviderKey<In> | string;
+  output: DataProviderKey<HfResult<M, A, C, In> | null> | string;
+  status?: DataProviderKey<HfInferStatus | null> | string;
+  triggerProvider?: DataProviderKey<unknown> | string;
+  consentProvider?: DataProviderKey<unknown> | string;
+  /** Pour une entrée faite d'objets : chemins (`"label + edito.sub_title"`) ou fonction typée. */
+  text?: HfTextExtractor<NonNullable<ItemOf<In>>>;
+  /** Options d'appel de la tâche du modèle (surchargent `defaults`). */
+  call?: HfExact<C, HfCallKeys<HfTaskOf<M, A>>>;
+  load?: HfLoadPolicy;
+  trigger?: HfTrigger;
+  debounceMs?: number;
+  emptyValue?: HfResult<M, A, C, In> | null;
+  onInvalid?: "keep" | "clear";
+  maxItems?: number;
+  maxChars?: number;
+  timeoutMs?: number;
+  persistResults?: boolean;
+  resultsTtlMs?: number;
+};
+
+export type HuggingFace<M extends HfModels> = {
+  readonly models: M;
+  /** Relie des DataProviders à un modèle (équivalent TypeScript de l'élément). */
+  infer<
+    A extends HfAlias<M>,
+    In extends HfAcceptedInput<HfTaskOf<M, A>>,
+    const C extends HfCallOptions<HfTaskOf<M, A>> = Record<never, never>,
+  >(
+    options: HfInferOptions<M, A, In, C>,
+  ): HfInferHandle;
+  /**
+   * Calcul ponctuel (sans DataProvider). À utiliser comme `compute` de
+   * `derive()` pour des dérivations à plusieurs entrées.
+   * Résout `null` si l'entrée est vide.
+   */
+  run<
+    A extends HfAlias<M>,
+    In extends HfAcceptedInput<HfTaskOf<M, A>>,
+    const C extends HfCallOptions<HfTaskOf<M, A>> = Record<never, never>,
+  >(
+    model: A,
+    input: In,
+    call?: HfExact<C, HfCallKeys<HfTaskOf<M, A>>>,
+    options?: {
+      text?: HfTextExtractor<NonNullable<ItemOf<In>>>;
+      load?: HfLoadPolicy;
+      timeoutMs?: number;
+    },
+  ): Promise<HfResult<M, A, C, In> | null>;
+  /** Charge un modèle maintenant (préchargement, politique `manual`). */
+  load(model: HfAlias<M>): Promise<void>;
+  state(model: HfAlias<M>): HfModelState;
+  subscribe(model: HfAlias<M>, listener: (state: HfModelState) => void): () => void;
+  accept(model: HfAlias<M>): void;
+  decline(model: HfAlias<M>): void;
+  revokeConsent(model: HfAlias<M>): void;
+  /** Supprime un modèle du cache du navigateur. */
+  clearModel(model: HfAlias<M>): Promise<void>;
+  /** Supprime tous les modèles, le WASM et les résultats mémorisés. */
+  clearAll(): Promise<void>;
+  readonly registry: HuggingFaceRegistry;
+};
+
+/* ------------------------------------------------------------------ */
+/* Mise en place                                                       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Configure l'inférence pour la page (à appeler une fois, au démarrage).
+ * Rend une API typée par la liste blanche de modèles.
+ */
+export function configureHuggingFace<const M extends HfModels>(
+  config: HuggingFaceConfig<M>,
+): HuggingFace<M> {
+  setHuggingFaceConfig(config);
+  const registry = getHuggingFaceRegistry()!;
+
+  return {
+    models: config.models,
+    registry,
+
+    infer(options) {
+      return createHfInferController(
+        {
+          ...options,
+          input: options.input as DataProviderKey<unknown> | string,
+          output: options.output as DataProviderKey<unknown> | string,
+          text: options.text as HfTextExtractor | undefined,
+          call: options.call as Record<string, unknown> | undefined,
+          untrusted: false,
+        },
+        registry,
+      );
+    },
+
+    async run(alias, value, callOptions, options = {}) {
+      const model = registry.model(alias);
+      const defaults = registry.resolvedConfig.defaults;
+      const input = normalizeInput(value, {
+        kind: HF_TASK_INPUT_KIND[model.task],
+        text: options.text as HfTextExtractor | undefined,
+        maxItems: defaults.maxItems,
+        maxChars: defaults.maxChars,
+      });
+      if (input.kind === "empty") return null;
+      if (input.kind === "invalid") throw new HfError("runtime", input.message);
+      const call = { ...(model.defaults ?? {}), ...(callOptions ?? {}) } as Record<
+        string,
+        unknown
+      >;
+      const positional = (HF_POSITIONAL_ARGS as Partial<Record<HfTask, string>>)[
+        model.task
+      ];
+      await registry.ensureLoaded(alias, options.load ?? "first-use");
+      const results = await registry.run(
+        {
+          alias,
+          inputs: input.payloads,
+          call,
+          positional,
+          batch:
+            model.task === "feature-extraction" &&
+            !!call.pooling &&
+            call.pooling !== "none",
+        },
+        options.timeoutMs ?? defaults.timeoutMs,
+      );
+      return (input.many ? realign(input, results) : results[0]) as never;
+    },
+
+    load: (alias) => registry.ensureLoaded(alias, "manual"),
+    state: (alias) => registry.state(alias),
+    subscribe: (alias, listener) => registry.subscribe(alias, listener),
+    accept: (alias) => registry.accept(alias),
+    decline: (alias) => registry.decline(alias),
+    revokeConsent: (alias) => registry.revokeConsent(alias),
+    clearModel: (alias) => registry.clearModel(alias),
+    async clearAll() {
+      await registry.clearAll();
+      await clearResults();
+    },
+  };
+}
+
+export { defineHuggingFaceModels, HF_DEFAULTS } from "./hf-config";
+export type {
+  HfDefaults,
+  HfLoadPolicy,
+  HfModelDefinition,
+  HfModels,
+  HfRuntime,
+  HfTrigger,
+  HuggingFaceConfig,
+} from "./hf-config";
+export type { HfInferHandle, HfInferState, HfInferStatus } from "./hf-controller";
+export type { HfModelPhase, HfModelState } from "./hf-registry";
+export { HfError } from "./hf-registry";
+export type { HfEngine } from "./hf-engine";
+export { HfWorkerEngine, HfEngineError } from "./hf-engine";
+export { hfCallOptionsJsonSchema, validateCallOptions, HF_CALL_OPTION_SCHEMAS } from "./hf-schema";
+export { HF_TASKS } from "./types";
+export type {
+  HfCallOptions,
+  HfEmbedding,
+  HfItemOutput,
+  HfOutput,
+  HfSingleInput,
+  HfTask,
+} from "./types";
+export { cosine, rankBySimilarity } from "@supersoniks/concorde/core/utils/similarity";