semantic-state-estimator 1.0.0

package/dist/embedding.worker.js

@@ -0,0 +1,64 @@
+// src/worker/embedding.worker.ts
+import { pipeline, env } from "@huggingface/transformers";
+env.allowLocalModels = false;
+var PipelineSingleton = class {
+  static async getInstance(modelName, progressCallback) {
+    if (this.instance === null || this.modelName !== modelName) {
+      this.modelName = modelName;
+      this.instance = pipeline("feature-extraction", modelName, {
+        dtype: "q8",
+        progress_callback: progressCallback
+      });
+    }
+    return this.instance;
+  }
+};
+PipelineSingleton.instance = null;
+PipelineSingleton.modelName = null;
+var currentModelName = "Xenova/all-MiniLM-L6-v2";
+function getModelName() {
+  return currentModelName;
+}
+async function handleInitMessage(event) {
+  currentModelName = event.data.modelName;
+  self.postMessage({ type: "STATUS", status: "loading" });
+  try {
+    await PipelineSingleton.getInstance(currentModelName, (data) => {
+      if (data.status === "progress" && data.file && data.progress !== void 0) {
+        self.postMessage({ type: "PROGRESS", file: data.file, progress: data.progress });
+      }
+    });
+    self.postMessage({ type: "STATUS", status: "ready" });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: "STATUS", status: "failed", error });
+  }
+}
+async function handleMessage(event) {
+  const { id, text } = event.data;
+  try {
+    const extractor = await PipelineSingleton.getInstance(currentModelName);
+    const output = await extractor(text, { pooling: "mean", normalize: true });
+    const response = { type: "EMBED_RES", id, vector: output.data };
+    self.postMessage(response);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    const response = { type: "EMBED_RES", id, vector: null, error };
+    self.postMessage(response);
+  }
+}
+self.addEventListener("message", (event) => {
+  const msg = event.data;
+  if (msg.type === "INIT") {
+    handleInitMessage(event);
+  } else {
+    handleMessage(event);
+  }
+});
+export {
+  PipelineSingleton,
+  getModelName,
+  handleInitMessage,
+  handleMessage
+};
+//# sourceMappingURL=embedding.worker.js.map

package/dist/embedding.worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/worker/embedding.worker.ts"],"sourcesContent":["import { pipeline, env } from \"@huggingface/transformers\";\nimport type { EmbeddingRequest, EmbeddingResponse, WorkerIncomingMessage, WorkerInitMessage } from \"./types.js\";\n\n// Disable local models; always load from the HuggingFace Hub.\nenv.allowLocalModels = false;\n\nexport class PipelineSingleton {\n  static instance: Promise<any> | null = null;\n  static modelName: string | null = null;\n\n  static async getInstance(modelName: string, progressCallback?: (data: any) => void) {\n    if (this.instance === null || this.modelName !== modelName) {\n      this.modelName = modelName;\n      this.instance = pipeline('feature-extraction', modelName, {\n        dtype: 'q8',\n        progress_callback: progressCallback,\n      });\n    }\n    return this.instance;\n  }\n}\n\nlet currentModelName: string = \"Xenova/all-MiniLM-L6-v2\";\n\n/** Returns the model name currently configured in the worker. */\nexport function getModelName(): string {\n  return currentModelName;\n}\n\n/**\n * Handles an INIT message: saves the model name and starts loading the pipeline,\n * broadcasting STATUS events so the main thread can track the model lifecycle.\n */\nexport async function handleInitMessage(event: MessageEvent<WorkerInitMessage>): Promise<void> {\n  currentModelName = event.data.modelName;\n  self.postMessage({ type: 'STATUS', status: 'loading' });\n  try {\n    await PipelineSingleton.getInstance(currentModelName, (data: any) => {\n      if (data.status === 'progress' && data.file && data.progress !== undefined) {\n        self.postMessage({ type: 'PROGRESS', file: data.file, progress: data.progress });\n      }\n    });\n    self.postMessage({ type: 'STATUS', status: 'ready' });\n  } catch (err) {\n    const error = err instanceof Error ? err.message : String(err);\n    self.postMessage({ type: 'STATUS', status: 'failed', error });\n  }\n}\n\n/**\n * Handles an EMBED message: runs the text through the pipeline and posts back\n * the resulting normalized 1D Float32Array.\n */\nexport async function handleMessage(event: MessageEvent<EmbeddingRequest>): Promise<void> {\n  const { id, text } = event.data;\n  try {\n    const extractor = await PipelineSingleton.getInstance(currentModelName);\n    const output = await extractor(text, { pooling: 'mean', normalize: true });\n    const response: EmbeddingResponse = { type: \"EMBED_RES\", id, vector: output.data as Float32Array };\n    self.postMessage(response);\n  } catch (err) {\n    const error = err instanceof Error ? err.message : String(err);\n    const response: EmbeddingResponse = { type: \"EMBED_RES\", id, vector: null, error };\n    self.postMessage(response);\n  }\n}\n\nself.addEventListener(\"message\", (event: Event) => {\n  const msg = (event as MessageEvent<WorkerIncomingMessage>).data;\n  if (msg.type === \"INIT\") {\n    handleInitMessage(event as MessageEvent<WorkerInitMessage>);\n  } else {\n    handleMessage(event as MessageEvent<EmbeddingRequest>);\n  }\n});\n"],"mappings":";AAAA,SAAS,UAAU,WAAW;AAI9B,IAAI,mBAAmB;AAEhB,IAAM,oBAAN,MAAwB;AAAA,EAI7B,aAAa,YAAY,WAAmB,kBAAwC;AAClF,QAAI,KAAK,aAAa,QAAQ,KAAK,cAAc,WAAW;AAC1D,WAAK,YAAY;AACjB,WAAK,WAAW,SAAS,sBAAsB,WAAW;AAAA,QACxD,OAAO;AAAA,QACP,mBAAmB;AAAA,MACrB,CAAC;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AACF;AAda,kBACJ,WAAgC;AAD5B,kBAEJ,YAA2B;AAcpC,IAAI,mBAA2B;AAGxB,SAAS,eAAuB;AACrC,SAAO;AACT;AAMA,eAAsB,kBAAkB,OAAuD;AAC7F,qBAAmB,MAAM,KAAK;AAC9B,OAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,UAAU,CAAC;AACtD,MAAI;AACF,UAAM,kBAAkB,YAAY,kBAAkB,CAAC,SAAc;AACnE,UAAI,KAAK,WAAW,cAAc,KAAK,QAAQ,KAAK,aAAa,QAAW;AAC1E,aAAK,YAAY,EAAE,MAAM,YAAY,MAAM,KAAK,MAAM,UAAU,KAAK,SAAS,CAAC;AAAA,MACjF;AAAA,IACF,CAAC;AACD,SAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,QAAQ,CAAC;AAAA,EACtD,SAAS,KAAK;AACZ,UAAM,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC7D,SAAK,YAAY,EAAE,MAAM,UAAU,QAAQ,UAAU,MAAM,CAAC;AAAA,EAC9D;AACF;AAMA,eAAsB,cAAc,OAAsD;AACxF,QAAM,EAAE,IAAI,KAAK,IAAI,MAAM;AAC3B,MAAI;AACF,UAAM,YAAY,MAAM,kBAAkB,YAAY,gBAAgB;AACtE,UAAM,SAAS,MAAM,UAAU,MAAM,EAAE,SAAS,QAAQ,WAAW,KAAK,CAAC;AACzE,UAAM,WAA8B,EAAE,MAAM,aAAa,IAAI,QAAQ,OAAO,KAAqB;AACjG,SAAK,YAAY,QAAQ;AAAA,EAC3B,SAAS,KAAK;AACZ,UAAM,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC7D,UAAM,WAA8B,EAAE,MAAM,aAAa,IAAI,QAAQ,MAAM,MAAM;AACjF,SAAK,YAAY,QAAQ;AAAA,EAC3B;AACF;AAEA,KAAK,iBAAiB,WAAW,CAAC,UAAiB;AACjD,QAAM,MAAO,MAA8C;AAC3D,MAAI,IAAI,SAAS,QAAQ;AACvB,sBAAkB,KAAwC;AAAA,EAC5D,OAAO;AACL,kBAAc,KAAuC;AAAA,EACvD;AACF,CAAC;","names":[]}

package/dist/index.cjs

@@ -0,0 +1,236 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  SemanticStateEngine: () => SemanticStateEngine,
+  WorkerManager: () => WorkerManager,
+  add: () => add,
+  cosineSimilarity: () => cosineSimilarity,
+  emaFusion: () => emaFusion,
+  normalize: () => normalize,
+  scale: () => scale
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/math/vector.ts
+function assertSameDimension(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(
+      `Vector dimension mismatch: a=${a.length}, b=${b.length}`
+    );
+  }
+}
+function add(a, b) {
+  assertSameDimension(a, b);
+  return a.map((val, i) => val + b[i]);
+}
+function scale(v, scalar) {
+  return v.map((val) => val * scalar);
+}
+function normalize(v) {
+  const mag = Math.sqrt(v.reduce((sum, val) => sum + val * val, 0));
+  if (mag === 0) {
+    return v.map(() => 0);
+  }
+  return v.map((val) => val / mag);
+}
+function cosineSimilarity(a, b) {
+  assertSameDimension(a, b);
+  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
+  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
+  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
+  if (magA === 0 || magB === 0) {
+    return 0;
+  }
+  return dot / (magA * magB);
+}
+function emaFusion(current, previous, alpha) {
+  assertSameDimension(current, previous);
+  if (alpha <= 0 || alpha > 1) {
+    throw new Error(`Alpha must be in the range (0, 1], got ${alpha}`);
+  }
+  return current.map((val, i) => alpha * val + (1 - alpha) * previous[i]);
+}
+
+// src/engine/SemanticStateEngine.ts
+var AGE_DECAY_RATE = 1e-4;
+var DRIFT_WEIGHT = 0.5;
+var SemanticStateEngine = class {
+  constructor(config) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.alpha = config.alpha;
+    this.driftThreshold = config.driftThreshold;
+    this.onDriftDetected = config.onDriftDetected;
+    this.provider = config.provider;
+    this.modelName = config.modelName ?? "Xenova/all-MiniLM-L6-v2";
+    this.stateVector = [];
+    this.lastUpdatedAt = Date.now();
+    this.lastDrift = 0;
+    this.updateCount = 0;
+  }
+  /**
+   * Obtains an embedding for `text` from the WorkerManager and fuses it into
+   * the rolling semantic state using EMA.
+   *
+   * On the first call the embedding establishes the baseline.
+   * On subsequent calls, if the cosine similarity between the current state
+   * and the new embedding falls below {@link SemanticStateEngineConfig.driftThreshold},
+   * the {@link SemanticStateEngineConfig.onDriftDetected} callback is fired
+   * *before* the EMA fusion is applied.
+   *
+   * @param text Raw text whose embedding will be fused into the state.
+   */
+  async update(text) {
+    const raw = await this.provider.getEmbedding(text);
+    if (raw === null) {
+      return;
+    }
+    const embedding = Array.from(raw);
+    if (this.updateCount === 0) {
+      const zero = new Array(embedding.length).fill(0);
+      this.stateVector = emaFusion(embedding, zero, this.alpha);
+      this.lastDrift = 0;
+    } else {
+      if (embedding.length !== this.stateVector.length) {
+        throw new Error(
+          `Embedding dimension mismatch: expected ${this.stateVector.length}, got ${embedding.length}`
+        );
+      }
+      const similarity = cosineSimilarity(this.stateVector, embedding);
+      const drift = 1 - similarity;
+      if (similarity < this.driftThreshold) {
+        this.onDriftDetected?.(embedding, drift);
+      }
+      this.stateVector = emaFusion(embedding, this.stateVector, this.alpha);
+      this.lastDrift = drift;
+    }
+    this.lastUpdatedAt = Date.now();
+    this.updateCount++;
+    this.listeners.forEach((l) => l());
+  }
+  /**
+   * Subscribes to state changes. Returns an unsubscribe function.
+   * The listener is called after every successful `update`.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Returns a point-in-time snapshot of the current semantic state.
+   */
+  getSnapshot() {
+    const healthScore = this.calculateHealth();
+    return {
+      vector: [...this.stateVector],
+      healthScore,
+      timestamp: this.lastUpdatedAt,
+      semanticSummary: this.buildSummary(healthScore)
+    };
+  }
+  /**
+   * Computes the current healthScore.
+   *
+   * Starts at 1.0 and subtracts:
+   * - An age penalty proportional to milliseconds elapsed since the last update.
+   * - A drift penalty proportional to the most recent drift magnitude.
+   *
+   * The result is clamped to [0, 1].
+   */
+  calculateHealth() {
+    const timeSinceUpdate = Date.now() - this.lastUpdatedAt;
+    const agePenalty = timeSinceUpdate * AGE_DECAY_RATE;
+    const driftPenalty = this.lastDrift * DRIFT_WEIGHT;
+    return Math.max(0, Math.min(1, 1 - agePenalty - driftPenalty));
+  }
+  buildSummary(healthScore) {
+    if (healthScore > 0.8) return "stable";
+    if (healthScore > 0.5) return "drifting";
+    return "volatile";
+  }
+};
+
+// src/worker/WorkerManager.ts
+var import_meta = {};
+var WorkerManager = class {
+  constructor(workerUrl = new URL("./embedding.worker.js", import_meta.url), modelName = "Xenova/all-MiniLM-L6-v2") {
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.isReady = false;
+    this.worker = new Worker(workerUrl, { type: "module" });
+    this.worker.onmessage = (event) => {
+      const data = event.data;
+      switch (data.type) {
+        case "STATUS":
+          this.isReady = data.status === "ready";
+          return;
+        case "PROGRESS":
+          return;
+        case "EMBED_RES": {
+          const { id, vector, error } = data;
+          const pending = this.pendingRequests.get(id);
+          if (!pending) return;
+          this.pendingRequests.delete(id);
+          if (error !== void 0) {
+            pending.reject(new Error(error));
+          } else if (vector !== null) {
+            pending.resolve(vector);
+          } else {
+            pending.reject(new Error("Worker returned null vector without an error message"));
+          }
+          return;
+        }
+      }
+    };
+    const initMessage = { type: "INIT", modelName };
+    this.worker.postMessage(initMessage);
+  }
+  /**
+   * Sends `text` to the worker and returns a Promise that resolves with the
+   * resulting embedding vector, or rejects if the worker reports an error.
+   *
+   * If the worker is not yet ready (model still loading), the request is
+   * silently dropped and the Promise resolves with `null` to avoid
+   * unhandled promise rejections during the initial page load.
+   */
+  getEmbedding(text) {
+    if (!this.isReady) {
+      console.warn("SemanticStateEngine: Worker still loading, dropping early event.");
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve, reject) => {
+      const id = crypto.randomUUID();
+      this.pendingRequests.set(id, { resolve, reject });
+      const request = { type: "EMBED", id, text };
+      this.worker.postMessage(request);
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SemanticStateEngine,
+  WorkerManager,
+  add,
+  cosineSimilarity,
+  emaFusion,
+  normalize,
+  scale
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/math/vector.ts","../src/engine/SemanticStateEngine.ts","../src/worker/WorkerManager.ts"],"sourcesContent":["/**\n * semantic-state-estimator\n *\n * A TypeScript library that acts as an event-stream middleware to track\n * the implicit semantic intent, emotional state, or \"vibe\" of a user/system.\n */\n\nexport { emaFusion, cosineSimilarity, normalize, add, scale } from \"./math/vector.js\";\nexport {\n  SemanticStateEngine,\n  type EmbeddingProvider,\n  type SemanticStateEngineConfig,\n  type Snapshot,\n} from \"./engine/SemanticStateEngine.js\";\nexport { WorkerManager } from \"./worker/WorkerManager.js\";\n","/**\n * Pure vector math utilities for semantic state estimation.\n *\n * Provides vector addition, scalar multiplication, normalization,\n * cosine similarity, and EMA (Exponential Moving Average) fusion.\n */\n\n/** Asserts that two vectors have the same length, throwing otherwise. */\nfunction assertSameDimension(a: number[], b: number[]): void {\n  if (a.length !== b.length) {\n    throw new Error(\n      `Vector dimension mismatch: a=${a.length}, b=${b.length}`,\n    );\n  }\n}\n\n/**\n * Adds two vectors element-wise.\n *\n * @param a First vector\n * @param b Second vector\n * @returns  Element-wise sum\n */\nexport function add(a: number[], b: number[]): number[] {\n  assertSameDimension(a, b);\n  return a.map((val, i) => val + b[i]!);\n}\n\n/**\n * Multiplies every element of a vector by a scalar.\n *\n * @param v      Input vector\n * @param scalar Scalar multiplier\n * @returns      Scaled vector\n */\nexport function scale(v: number[], scalar: number): number[] {\n  return v.map((val) => val * scalar);\n}\n\n/**\n * Normalizes a vector to unit length (L2 normalization).\n *\n * @param v Input vector\n * @returns  Unit vector, or zero vector if input magnitude is 0\n */\nexport function normalize(v: number[]): number[] {\n  const mag = Math.sqrt(v.reduce((sum, val) => sum + val * val, 0));\n  if (mag === 0) {\n    return v.map(() => 0);\n  }\n  return v.map((val) => val / mag);\n}\n\n/**\n * Computes the cosine similarity between two vectors.\n *\n * @param a First vector\n * @param b Second vector\n * @returns  Cosine similarity in [-1, 1], or 0 if either vector has zero magnitude\n */\nexport function cosineSimilarity(a: number[], b: number[]): number {\n  assertSameDimension(a, b);\n  const dot = a.reduce((sum, val, i) => sum + val * b[i]!, 0);\n  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));\n  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));\n  if (magA === 0 || magB === 0) {\n    return 0;\n  }\n  return dot / (magA * magB);\n}\n\n/**\n * Computes the Exponential Moving Average (EMA) fusion of two vectors.\n *\n * Formula: S_t = α · E_t + (1 − α) · S_{t-1}\n *\n * @param current  New embedding vector E_t\n * @param previous Previous state vector S_{t-1}\n * @param alpha    Decay factor α ∈ (0, 1]. Higher values weight recent events more.\n * @returns        Updated state vector S_t\n */\nexport function emaFusion(\n  current: number[],\n  previous: number[],\n  alpha: number,\n): number[] {\n  assertSameDimension(current, previous);\n  if (alpha <= 0 || alpha > 1) {\n    throw new Error(`Alpha must be in the range (0, 1], got ${alpha}`);\n  }\n  return current.map((val, i) => alpha * val + (1 - alpha) * previous[i]!);\n}\n","import { emaFusion, cosineSimilarity } from \"../math/vector.js\";\n\n/**\n * A generic embedding provider contract.\n * Any object that can return an embedding vector for a given text satisfies this interface.\n * This includes `WorkerManager` (on-device WebWorker) as well as custom OpenAI, Ollama,\n * or other remote-inference wrappers.\n */\nexport interface EmbeddingProvider {\n  getEmbedding(text: string): Promise<Float32Array | number[]>;\n}\n\n/**\n * Age-based health decay rate: health lost per millisecond of inactivity.\n * At this rate, age alone reduces health to 0 after ~10 seconds of inactivity.\n */\nconst AGE_DECAY_RATE = 0.0001;\n\n/**\n * Weight applied to the most-recent drift value when computing healthScore.\n * A drift of 1.0 (orthogonal vectors) reduces health by 0.5.\n */\nconst DRIFT_WEIGHT = 0.5;\n\n/**\n * Configuration for the SemanticStateEngine.\n */\nexport interface SemanticStateEngineConfig {\n  /** EMA decay factor α ∈ (0, 1]. Higher values weight recent embeddings more. */\n  alpha: number;\n\n  /** Minimum cosine similarity below which drift is detected and the callback fires. */\n  driftThreshold: number;\n\n  /**\n   * Optional callback invoked when the incoming embedding drifts beyond the threshold.\n   * Fired *before* the EMA fusion is applied.\n   *\n   * @param vector    The incoming embedding that triggered the drift.\n   * @param driftScore Drift magnitude: 1 − cosine_similarity ∈ [0, 2].\n   */\n  onDriftDetected?: (vector: number[], driftScore: number) => void;\n  /**\n   * The embedding provider used to obtain embedding vectors asynchronously.\n   * Any object implementing `getEmbedding(text: string): Promise<Float32Array | number[]>`\n   * satisfies this interface — including `WorkerManager`, or a custom OpenAI / Ollama wrapper.\n   */\n  provider: EmbeddingProvider;\n\n  /**\n   * The name of the embedding model to use.\n   * Must match the modelName passed to the WorkerManager so the worker\n   * loads the correct model.\n   * @default \"Xenova/all-MiniLM-L6-v2\"\n   */\n  modelName?: string;\n}\n\n/**\n * A point-in-time snapshot of the current semantic state.\n */\nexport interface Snapshot {\n  /** The current EMA state vector. */\n  vector: number[];\n\n  /** Reliability indicator in [0, 1]. Degrades with age and high drift. */\n  healthScore: number;\n\n  /** Unix timestamp (ms) of the last state update. */\n  timestamp: number;\n\n  /** Human-readable description of the current state quality. */\n  semanticSummary: string;\n}\n\n/**\n * SemanticStateEngine tracks the implicit semantic intent of an event stream\n * using Exponential Moving Average (EMA) vector fusion.\n *\n * It fires an optional drift callback when incoming embeddings diverge\n * significantly from the current state, and exposes a healthScore that\n * degrades with both age and volatility.\n */\nexport class SemanticStateEngine {\n  private readonly alpha: number;\n  private readonly driftThreshold: number;\n  private readonly onDriftDetected?: (\n    vector: number[],\n    driftScore: number,\n  ) => void;\n  private readonly provider: EmbeddingProvider;\n  readonly modelName: string;\n\n  private stateVector: number[];\n  private lastUpdatedAt: number;\n  private lastDrift: number;\n  private updateCount: number;\n  private readonly listeners = new Set<() => void>();\n\n  constructor(config: SemanticStateEngineConfig) {\n    this.alpha = config.alpha;\n    this.driftThreshold = config.driftThreshold;\n    this.onDriftDetected = config.onDriftDetected;\n    this.provider = config.provider;\n    this.modelName = config.modelName ?? \"Xenova/all-MiniLM-L6-v2\";\n\n    this.stateVector = [];\n    this.lastUpdatedAt = Date.now();\n    this.lastDrift = 0;\n    this.updateCount = 0;\n  }\n\n  /**\n   * Obtains an embedding for `text` from the WorkerManager and fuses it into\n   * the rolling semantic state using EMA.\n   *\n   * On the first call the embedding establishes the baseline.\n   * On subsequent calls, if the cosine similarity between the current state\n   * and the new embedding falls below {@link SemanticStateEngineConfig.driftThreshold},\n   * the {@link SemanticStateEngineConfig.onDriftDetected} callback is fired\n   * *before* the EMA fusion is applied.\n   *\n   * @param text Raw text whose embedding will be fused into the state.\n   */\n  async update(text: string): Promise<void> {\n    const raw = await this.provider.getEmbedding(text);\n    if (raw === null) {\n      return;\n    }\n    const embedding = Array.from(raw);\n\n    if (this.updateCount === 0) {\n      // First call: establish baseline from a zero-vector origin.\n      const zero = new Array(embedding.length).fill(0) as number[];\n      this.stateVector = emaFusion(embedding, zero, this.alpha);\n      this.lastDrift = 0;\n    } else {\n      if (embedding.length !== this.stateVector.length) {\n        throw new Error(\n          `Embedding dimension mismatch: expected ${this.stateVector.length}, got ${embedding.length}`,\n        );\n      }\n\n      const similarity = cosineSimilarity(this.stateVector, embedding);\n      const drift = 1 - similarity;\n\n      if (similarity < this.driftThreshold) {\n        this.onDriftDetected?.(embedding, drift);\n      }\n\n      this.stateVector = emaFusion(embedding, this.stateVector, this.alpha);\n      this.lastDrift = drift;\n    }\n\n    this.lastUpdatedAt = Date.now();\n    this.updateCount++;\n    this.listeners.forEach((l) => l());\n  }\n\n  /**\n   * Subscribes to state changes. Returns an unsubscribe function.\n   * The listener is called after every successful `update`.\n   */\n  subscribe(listener: () => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  /**\n   * Returns a point-in-time snapshot of the current semantic state.\n   */\n  getSnapshot(): Snapshot {\n    const healthScore = this.calculateHealth();\n    return {\n      vector: [...this.stateVector],\n      healthScore,\n      timestamp: this.lastUpdatedAt,\n      semanticSummary: this.buildSummary(healthScore),\n    };\n  }\n\n  /**\n   * Computes the current healthScore.\n   *\n   * Starts at 1.0 and subtracts:\n   * - An age penalty proportional to milliseconds elapsed since the last update.\n   * - A drift penalty proportional to the most recent drift magnitude.\n   *\n   * The result is clamped to [0, 1].\n   */\n  private calculateHealth(): number {\n    const timeSinceUpdate = Date.now() - this.lastUpdatedAt;\n    const agePenalty = timeSinceUpdate * AGE_DECAY_RATE;\n    const driftPenalty = this.lastDrift * DRIFT_WEIGHT;\n    return Math.max(0, Math.min(1, 1.0 - agePenalty - driftPenalty));\n  }\n\n  private buildSummary(healthScore: number): string {\n    if (healthScore > 0.8) return \"stable\";\n    if (healthScore > 0.5) return \"drifting\";\n    return \"volatile\";\n  }\n}\n","import type { EmbeddingRequest, EmbeddingResponse, WorkerInitMessage, WorkerStatusEvent } from \"./types.js\";\n\ntype PendingRequest = {\n  resolve: (value: Float32Array) => void;\n  reject: (reason: Error) => void;\n};\n\n/**\n * WorkerManager wraps a browser Worker in a clean async/await API.\n *\n * It maintains a Map of pending Promises keyed by request UUID so that\n * out-of-order worker responses are still dispatched to the correct caller.\n *\n * Calls to `getEmbedding()` while the worker is not yet ready are silently\n * dropped (returning null) to avoid unhandled promise rejections during the\n * model loading phase, which is acceptable for probabilistic semantic state.\n */\nexport class WorkerManager {\n  private readonly worker: Worker;\n  private readonly pendingRequests = new Map<string, PendingRequest>();\n  private isReady: boolean = false;\n\n  constructor(\n    workerUrl: string | URL = new URL(\"./embedding.worker.js\", import.meta.url),\n    modelName: string = \"Xenova/all-MiniLM-L6-v2\",\n  ) {\n    this.worker = new Worker(workerUrl, { type: \"module\" });\n    this.worker.onmessage = (event: MessageEvent<EmbeddingResponse | WorkerStatusEvent>) => {\n      const data = event.data;\n      switch (data.type) {\n        case 'STATUS':\n          this.isReady = data.status === 'ready';\n          return;\n        case 'PROGRESS':\n          return;\n        case 'EMBED_RES': {\n          const { id, vector, error } = data;\n          const pending = this.pendingRequests.get(id);\n          if (!pending) return;\n          this.pendingRequests.delete(id);\n          if (error !== undefined) {\n            pending.reject(new Error(error));\n          } else if (vector !== null) {\n            pending.resolve(vector);\n          } else {\n            pending.reject(new Error(\"Worker returned null vector without an error message\"));\n          }\n          return;\n        }\n      }\n    };\n\n    const initMessage: WorkerInitMessage = { type: \"INIT\", modelName };\n    this.worker.postMessage(initMessage);\n  }\n\n  /**\n   * Sends `text` to the worker and returns a Promise that resolves with the\n   * resulting embedding vector, or rejects if the worker reports an error.\n   *\n   * If the worker is not yet ready (model still loading), the request is\n   * silently dropped and the Promise resolves with `null` to avoid\n   * unhandled promise rejections during the initial page load.\n   */\n  getEmbedding(text: string): Promise<Float32Array | null> {\n    if (!this.isReady) {\n      console.warn(\"SemanticStateEngine: Worker still loading, dropping early event.\");\n      return Promise.resolve(null);\n    }\n    return new Promise<Float32Array>((resolve, reject) => {\n      const id = crypto.randomUUID();\n      this.pendingRequests.set(id, { resolve, reject });\n      const request: EmbeddingRequest = { type: \"EMBED\", id, text };\n      this.worker.postMessage(request);\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,78 @@
+export { E as EmbeddingProvider, S as SemanticStateEngine, a as SemanticStateEngineConfig, b as Snapshot } from './SemanticStateEngine-BP5URJOJ.cjs';
+
+/**
+ * Pure vector math utilities for semantic state estimation.
+ *
+ * Provides vector addition, scalar multiplication, normalization,
+ * cosine similarity, and EMA (Exponential Moving Average) fusion.
+ */
+/**
+ * Adds two vectors element-wise.
+ *
+ * @param a First vector
+ * @param b Second vector
+ * @returns  Element-wise sum
+ */
+declare function add(a: number[], b: number[]): number[];
+/**
+ * Multiplies every element of a vector by a scalar.
+ *
+ * @param v      Input vector
+ * @param scalar Scalar multiplier
+ * @returns      Scaled vector
+ */
+declare function scale(v: number[], scalar: number): number[];
+/**
+ * Normalizes a vector to unit length (L2 normalization).
+ *
+ * @param v Input vector
+ * @returns  Unit vector, or zero vector if input magnitude is 0
+ */
+declare function normalize(v: number[]): number[];
+/**
+ * Computes the cosine similarity between two vectors.
+ *
+ * @param a First vector
+ * @param b Second vector
+ * @returns  Cosine similarity in [-1, 1], or 0 if either vector has zero magnitude
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Computes the Exponential Moving Average (EMA) fusion of two vectors.
+ *
+ * Formula: S_t = α · E_t + (1 − α) · S_{t-1}
+ *
+ * @param current  New embedding vector E_t
+ * @param previous Previous state vector S_{t-1}
+ * @param alpha    Decay factor α ∈ (0, 1]. Higher values weight recent events more.
+ * @returns        Updated state vector S_t
+ */
+declare function emaFusion(current: number[], previous: number[], alpha: number): number[];
+
+/**
+ * WorkerManager wraps a browser Worker in a clean async/await API.
+ *
+ * It maintains a Map of pending Promises keyed by request UUID so that
+ * out-of-order worker responses are still dispatched to the correct caller.
+ *
+ * Calls to `getEmbedding()` while the worker is not yet ready are silently
+ * dropped (returning null) to avoid unhandled promise rejections during the
+ * model loading phase, which is acceptable for probabilistic semantic state.
+ */
+declare class WorkerManager {
+    private readonly worker;
+    private readonly pendingRequests;
+    private isReady;
+    constructor(workerUrl?: string | URL, modelName?: string);
+    /**
+     * Sends `text` to the worker and returns a Promise that resolves with the
+     * resulting embedding vector, or rejects if the worker reports an error.
+     *
+     * If the worker is not yet ready (model still loading), the request is
+     * silently dropped and the Promise resolves with `null` to avoid
+     * unhandled promise rejections during the initial page load.
+     */
+    getEmbedding(text: string): Promise<Float32Array | null>;
+}
+
+export { WorkerManager, add, cosineSimilarity, emaFusion, normalize, scale };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+export { E as EmbeddingProvider, S as SemanticStateEngine, a as SemanticStateEngineConfig, b as Snapshot } from './SemanticStateEngine-BP5URJOJ.js';
+
+/**
+ * Pure vector math utilities for semantic state estimation.
+ *
+ * Provides vector addition, scalar multiplication, normalization,
+ * cosine similarity, and EMA (Exponential Moving Average) fusion.
+ */
+/**
+ * Adds two vectors element-wise.
+ *
+ * @param a First vector
+ * @param b Second vector
+ * @returns  Element-wise sum
+ */
+declare function add(a: number[], b: number[]): number[];
+/**
+ * Multiplies every element of a vector by a scalar.
+ *
+ * @param v      Input vector
+ * @param scalar Scalar multiplier
+ * @returns      Scaled vector
+ */
+declare function scale(v: number[], scalar: number): number[];
+/**
+ * Normalizes a vector to unit length (L2 normalization).
+ *
+ * @param v Input vector
+ * @returns  Unit vector, or zero vector if input magnitude is 0
+ */
+declare function normalize(v: number[]): number[];
+/**
+ * Computes the cosine similarity between two vectors.
+ *
+ * @param a First vector
+ * @param b Second vector
+ * @returns  Cosine similarity in [-1, 1], or 0 if either vector has zero magnitude
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Computes the Exponential Moving Average (EMA) fusion of two vectors.
+ *
+ * Formula: S_t = α · E_t + (1 − α) · S_{t-1}
+ *
+ * @param current  New embedding vector E_t
+ * @param previous Previous state vector S_{t-1}
+ * @param alpha    Decay factor α ∈ (0, 1]. Higher values weight recent events more.
+ * @returns        Updated state vector S_t
+ */
+declare function emaFusion(current: number[], previous: number[], alpha: number): number[];
+
+/**
+ * WorkerManager wraps a browser Worker in a clean async/await API.
+ *
+ * It maintains a Map of pending Promises keyed by request UUID so that
+ * out-of-order worker responses are still dispatched to the correct caller.
+ *
+ * Calls to `getEmbedding()` while the worker is not yet ready are silently
+ * dropped (returning null) to avoid unhandled promise rejections during the
+ * model loading phase, which is acceptable for probabilistic semantic state.
+ */
+declare class WorkerManager {
+    private readonly worker;
+    private readonly pendingRequests;
+    private isReady;
+    constructor(workerUrl?: string | URL, modelName?: string);
+    /**
+     * Sends `text` to the worker and returns a Promise that resolves with the
+     * resulting embedding vector, or rejects if the worker reports an error.
+     *
+     * If the worker is not yet ready (model still loading), the request is
+     * silently dropped and the Promise resolves with `null` to avoid
+     * unhandled promise rejections during the initial page load.
+     */
+    getEmbedding(text: string): Promise<Float32Array | null>;
+}
+
+export { WorkerManager, add, cosineSimilarity, emaFusion, normalize, scale };