@supersoniks/concorde 4.9.98-visual-stack.1 → 5.0.1

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

@@ -1,202 +0,0 @@
-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

@@ -1,282 +0,0 @@
-/**
- * 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";