localm-web 0.2.0 → 0.4.0

package/dist/index.js

@@ -30,6 +30,43 @@ class QuotaExceededError extends LocalmWebError {
 }
 class BackendNotAvailableError extends LocalmWebError {
 }
+class StructuredOutputError extends LocalmWebError {
+}
+function assertJsonSchema(schema) {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new StructuredOutputError("jsonSchema must be a plain object describing a JSON Schema.");
+  }
+  const keys = Object.keys(schema);
+  const recognized = [
+    "type",
+    "$ref",
+    "oneOf",
+    "anyOf",
+    "allOf",
+    "enum",
+    "const",
+    "properties"
+  ];
+  if (!keys.some((key) => recognized.includes(key))) {
+    throw new StructuredOutputError(
+      "jsonSchema does not look like a JSON Schema (missing type/$ref/oneOf/anyOf/allOf/enum/const/properties)."
+    );
+  }
+}
+function serializeJsonSchema(schema) {
+  assertJsonSchema(schema);
+  return JSON.stringify(schema);
+}
+function parseStructuredOutput(text) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new StructuredOutputError(
+      "Engine output is not valid JSON. The model may have ignored the constrained decoding directive.",
+      err
+    );
+  }
+}
 let webllmModulePromise = null;
 async function loadWebLLM() {
   if (!webllmModulePromise) {
@@ -47,6 +84,15 @@ function buildSamplingParams(options) {
   if (options.topP !== void 0) params.top_p = options.topP;
   return params;
 }
+function buildResponseFormat(options) {
+  if (options.jsonSchema !== void 0) {
+    return { type: "json_object", schema: serializeJsonSchema(options.jsonSchema) };
+  }
+  if (options.json) {
+    return { type: "json_object" };
+  }
+  return void 0;
+}
 function toChatMessages(messages) {
   return messages.map((m) => {
     switch (m.role) {
@@ -101,10 +147,12 @@ class WebLLMEngine {
     if (options.signal?.aborted) {
       throw new GenerationAbortedError("Generation aborted before start.");
     }
+    const responseFormat = buildResponseFormat(options);
     const completion = await engine.chat.completions.create({
       ...buildSamplingParams(options),
       messages: toChatMessages(messages),
-      stream: false
+      stream: false,
+      ...responseFormat ? { response_format: responseFormat } : {}
     });
     return completion.choices[0]?.message?.content ?? "";
   }
@@ -113,10 +161,12 @@ class WebLLMEngine {
     if (options.signal?.aborted) {
       throw new GenerationAbortedError("Generation aborted before start.");
     }
+    const responseFormat = buildResponseFormat(options);
     const completion = await engine.chat.completions.create({
       ...buildSamplingParams(options),
       messages: toChatMessages(messages),
-      stream: true
+      stream: true,
+      ...responseFormat ? { response_format: responseFormat } : {}
     });
     let index = 0;
     let finished = false;
@@ -150,10 +200,12 @@ class WebLLMEngine {
     if (options.signal?.aborted) {
       throw new GenerationAbortedError("Generation aborted before start.");
     }
+    const responseFormat = buildResponseFormat(options);
     const completion = await engine.completions.create({
       ...buildSamplingParams(options),
       prompt,
-      stream: false
+      stream: false,
+      ...responseFormat ? { response_format: responseFormat } : {}
     });
     return completion.choices[0]?.text ?? "";
   }
@@ -162,10 +214,12 @@ class WebLLMEngine {
     if (options.signal?.aborted) {
       throw new GenerationAbortedError("Generation aborted before start.");
     }
+    const responseFormat = buildResponseFormat(options);
     const completion = await engine.completions.create({
       ...buildSamplingParams(options),
       prompt,
-      stream: true
+      stream: true,
+      ...responseFormat ? { response_format: responseFormat } : {}
     });
     let index = 0;
     let finished = false;
@@ -524,10 +578,66 @@ function resolveModelPreset(modelId) {
 function listSupportedModels() {
   return Object.keys(MODEL_PRESETS);
 }
+const EMBEDDING_PRESETS = Object.freeze({
+  "bge-small-en-v1.5": {
+    id: "bge-small-en-v1.5",
+    family: "BGE",
+    dimension: 384,
+    maxTokens: 512,
+    transformersId: "Xenova/bge-small-en-v1.5",
+    quantization: "fp32",
+    description: "BAAI BGE small English v1.5, 384-dim sentence embeddings."
+  },
+  "bge-base-en-v1.5": {
+    id: "bge-base-en-v1.5",
+    family: "BGE",
+    dimension: 768,
+    maxTokens: 512,
+    transformersId: "Xenova/bge-base-en-v1.5",
+    quantization: "fp32",
+    description: "BAAI BGE base English v1.5, 768-dim sentence embeddings."
+  }
+});
+function resolveEmbeddingPreset(modelId) {
+  const preset = EMBEDDING_PRESETS[modelId];
+  if (!preset) {
+    const available = Object.keys(EMBEDDING_PRESETS).join(", ");
+    throw new UnknownModelError(
+      `Unknown embedding model "${modelId}". Available models: ${available}.`
+    );
+  }
+  return preset;
+}
+function listSupportedEmbeddingModels() {
+  return Object.keys(EMBEDDING_PRESETS);
+}
+const RERANKER_PRESETS = Object.freeze({
+  "bge-reranker-base": {
+    id: "bge-reranker-base",
+    family: "BGE Reranker",
+    maxTokens: 512,
+    transformersId: "Xenova/bge-reranker-base",
+    quantization: "fp32",
+    description: "BAAI BGE reranker base — multilingual cross-encoder."
+  }
+});
+function resolveRerankerPreset(modelId) {
+  const preset = RERANKER_PRESETS[modelId];
+  if (!preset) {
+    const available = Object.keys(RERANKER_PRESETS).join(", ");
+    throw new UnknownModelError(
+      `Unknown reranker model "${modelId}". Available models: ${available}.`
+    );
+  }
+  return preset;
+}
+function listSupportedRerankerModels() {
+  return Object.keys(RERANKER_PRESETS);
+}
 function createInferenceWorker() {
   return new Worker(new URL(
     /* @vite-ignore */
-    "/assets/inference.worker-CwvQtobb.js",
+    "/assets/inference.worker-DZbXKJZY.js",
     import.meta.url
   ), {
     type: "module"
@@ -555,7 +665,8 @@ class LMTask {
     return { engine, preset };
   }
   static defaultEngine(options) {
-    if (options.inWorker) {
+    const useWorker = options.inWorker ?? true;
+    if (useWorker) {
       return new WorkerEngine(createInferenceWorker());
     }
     return new WebLLMEngine();
@@ -576,6 +687,20 @@ class ChatReply {
     this.tokensGenerated = tokensGenerated;
     this.finishReason = finishReason;
   }
+  /**
+   * Parse {@link ChatReply.text} as JSON.
+   *
+   * Intended for replies generated with `json: true` or `jsonSchema`.
+   * The result is cast to `T` without runtime validation; pair with Zod /
+   * Ajv on the call site if you need to verify the schema.
+   *
+   * @typeParam T - Expected parsed shape.
+   * @returns The parsed JSON value.
+   * @throws StructuredOutputError if the text is not valid JSON.
+   */
+  json() {
+    return parseStructuredOutput(this.text);
+  }
 }
 class CompletionResult {
   constructor(text, prompt, tokensGenerated, finishReason) {
@@ -584,6 +709,19 @@ class CompletionResult {
     this.tokensGenerated = tokensGenerated;
     this.finishReason = finishReason;
   }
+  /**
+   * Parse {@link CompletionResult.text} as JSON.
+   *
+   * Intended for completions generated with `json: true` or `jsonSchema`.
+   * The result is cast to `T` without runtime validation.
+   *
+   * @typeParam T - Expected parsed shape.
+   * @returns The parsed JSON value.
+   * @throws StructuredOutputError if the text is not valid JSON.
+   */
+  json() {
+    return parseStructuredOutput(this.text);
+  }
 }
 class Chat extends LMTask {
   history = [];
@@ -702,6 +840,230 @@ class Completion extends LMTask {
     }
   }
 }
+let transformersModulePromise$1 = null;
+async function loadTransformers$1() {
+  if (!transformersModulePromise$1) {
+    transformersModulePromise$1 = import("@huggingface/transformers");
+  }
+  return transformersModulePromise$1;
+}
+async function buildDefaultPipeline$1(preset, onProgress) {
+  const transformers = await loadTransformers$1();
+  try {
+    const pipe = await transformers.pipeline("feature-extraction", preset.transformersId, {
+      progress_callback: (report) => {
+        if (!onProgress) return;
+        const r = report;
+        onProgress({
+          progress: typeof r.progress === "number" ? r.progress / 100 : 0,
+          text: r.status ?? "",
+          loaded: 0,
+          total: 0,
+          phase: "downloading"
+        });
+      }
+    });
+    return {
+      async embed(texts, options) {
+        const output = await pipe(texts, {
+          pooling: options.pooling,
+          normalize: options.normalize
+        });
+        return output.tolist();
+      },
+      async unload() {
+        if (typeof pipe.dispose === "function") {
+          await pipe.dispose();
+        }
+      }
+    };
+  } catch (err) {
+    throw new ModelLoadError(`Failed to load embedding model "${preset.id}".`, err);
+  }
+}
+class Embeddings {
+  constructor(pipeline, preset) {
+    this.pipeline = pipeline;
+    this.preset = preset;
+  }
+  /**
+   * Create and load an `Embeddings` task for the given model.
+   *
+   * @param modelId - Friendly id from the embedding registry.
+   * @param options - Optional creation options.
+   * @throws UnknownModelError if `modelId` is not in the registry.
+   * @throws ModelLoadError if the underlying pipeline fails to load.
+   */
+  static async create(modelId, options = {}) {
+    const preset = resolveEmbeddingPreset(modelId);
+    const pipeline = options.pipeline ?? await buildDefaultPipeline$1(preset, options.onProgress);
+    return new Embeddings(pipeline, preset);
+  }
+  /**
+   * Encode an array of strings into dense vectors.
+   *
+   * Returns one vector per input, in the same order. Empty input array
+   * returns an empty array (no error).
+   *
+   * @param texts - Input strings.
+   * @param options - Pooling + normalization. Defaults: `pooling: "mean"`, `normalize: true`.
+   */
+  async embed(texts, options = {}) {
+    if (texts.length === 0) return [];
+    if (!this.pipeline) {
+      throw new ModelNotLoadedError("Embeddings pipeline not initialized.");
+    }
+    const merged = {
+      normalize: options.normalize ?? true,
+      pooling: options.pooling ?? "mean"
+    };
+    return this.pipeline.embed(texts, merged);
+  }
+  /**
+   * Convenience: encode a single string and return its vector.
+   *
+   * @param text - Input string.
+   * @param options - Forwarded to {@link Embeddings.embed}.
+   */
+  async embedSingle(text, options = {}) {
+    const [vec] = await this.embed([text], options);
+    if (!vec) {
+      throw new ModelLoadError("Embedding pipeline returned no result.");
+    }
+    return vec;
+  }
+  /** Embedding dimension exposed by the loaded model. */
+  get dimension() {
+    return this.preset.dimension;
+  }
+  /** Release pipeline resources. Safe to call multiple times. */
+  async unload() {
+    await this.pipeline.unload?.();
+  }
+}
+let transformersModulePromise = null;
+async function loadTransformers() {
+  if (!transformersModulePromise) {
+    transformersModulePromise = import("@huggingface/transformers");
+  }
+  return transformersModulePromise;
+}
+function sigmoidValue(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+async function buildDefaultPipeline(preset, onProgress) {
+  const transformers = await loadTransformers();
+  try {
+    const tokenizer = await transformers.AutoTokenizer.from_pretrained(preset.transformersId, {
+      progress_callback: (report) => {
+        if (!onProgress) return;
+        const r = report;
+        onProgress({
+          progress: typeof r.progress === "number" ? r.progress / 100 : 0,
+          text: r.status ?? "",
+          loaded: 0,
+          total: 0,
+          phase: "downloading"
+        });
+      }
+    });
+    const model = await transformers.AutoModelForSequenceClassification.from_pretrained(
+      preset.transformersId,
+      {
+        progress_callback: (report) => {
+          if (!onProgress) return;
+          const r = report;
+          onProgress({
+            progress: typeof r.progress === "number" ? r.progress / 100 : 0,
+            text: r.status ?? "",
+            loaded: 0,
+            total: 0,
+            phase: "downloading"
+          });
+        }
+      }
+    );
+    return {
+      async score(query, docs) {
+        if (docs.length === 0) return [];
+        const queries = docs.map(() => query);
+        const tokenize = tokenizer;
+        const inputs = tokenize(queries, {
+          text_pair: docs,
+          padding: true,
+          truncation: true,
+          max_length: preset.maxTokens
+        });
+        const callModel = model;
+        const outputs = await callModel(inputs);
+        const logits = outputs.logits.tolist();
+        return logits.map((row) => row[0] ?? 0);
+      },
+      async unload() {
+        const m = model;
+        if (typeof m.dispose === "function") await m.dispose();
+      }
+    };
+  } catch (err) {
+    throw new ModelLoadError(`Failed to load reranker model "${preset.id}".`, err);
+  }
+}
+class Reranker {
+  constructor(pipeline, preset) {
+    this.pipeline = pipeline;
+    this.preset = preset;
+  }
+  /**
+   * Create and load a `Reranker` task for the given model.
+   *
+   * @param modelId - Friendly id from the reranker registry.
+   * @param options - Optional creation options.
+   * @throws UnknownModelError if `modelId` is not in the registry.
+   * @throws ModelLoadError if the underlying pipeline fails to load.
+   */
+  static async create(modelId, options = {}) {
+    const preset = resolveRerankerPreset(modelId);
+    const pipeline = options.pipeline ?? await buildDefaultPipeline(preset, options.onProgress);
+    return new Reranker(pipeline, preset);
+  }
+  /**
+   * Score each document against the query. Returns one score per doc, in
+   * the same order. Empty `docs` returns `[]` (no error).
+   *
+   * @param query - Query string.
+   * @param docs - Documents to score.
+   * @param options - `sigmoid: true` maps logits into `[0, 1]`.
+   */
+  async score(query, docs, options = {}) {
+    if (docs.length === 0) return [];
+    if (!this.pipeline) {
+      throw new ModelNotLoadedError("Reranker pipeline not initialized.");
+    }
+    const raw = await this.pipeline.score(query, docs);
+    return options.sigmoid ? raw.map(sigmoidValue) : raw;
+  }
+  /**
+   * Score and sort documents by score in descending order. Returns a list of
+   * {@link RankedDocument}s carrying the original index.
+   *
+   * @param query - Query string.
+   * @param docs - Documents to rank.
+   * @param options - Forwarded to {@link Reranker.score}.
+   */
+  async rank(query, docs, options = {}) {
+    const scores = await this.score(query, docs, options);
+    const ranked = scores.map((score, index) => {
+      const text = docs[index] ?? "";
+      return { text, score, index };
+    });
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked;
+  }
+  /** Release pipeline resources. Safe to call multiple times. */
+  async unload() {
+    await this.pipeline.unload?.();
+  }
+}
 let webllmCachePromise = null;
 async function loadWebLLMCacheHelpers() {
   if (!webllmCachePromise) {
@@ -823,13 +1185,15 @@ async function* tap(stream, onChunk) {
     yield chunk;
   }
 }
-const VERSION = "0.2.0";
+const VERSION = "0.4.0";
 export {
   BackendNotAvailableError,
   Chat,
   ChatReply,
   Completion,
   CompletionResult,
+  EMBEDDING_PRESETS,
+  Embeddings,
   GenerationAbortedError,
   LMTask,
   LocalmWebError,
@@ -838,14 +1202,24 @@ export {
   ModelLoadError,
   ModelNotLoadedError,
   QuotaExceededError,
+  RERANKER_PRESETS,
+  Reranker,
+  StructuredOutputError,
   UnknownModelError,
   VERSION,
   WebGPUUnavailableError,
   WorkerEngine,
+  assertJsonSchema,
   collectStream,
   createInferenceWorker,
+  listSupportedEmbeddingModels,
   listSupportedModels,
+  listSupportedRerankerModels,
+  parseStructuredOutput,
+  resolveEmbeddingPreset,
   resolveModelPreset,
+  resolveRerankerPreset,
+  serializeJsonSchema,
   tap
 };
 //# sourceMappingURL=index.js.map