semantic-state-estimator 1.1.1 → 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Francisco Rueda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/{SemanticStateEngine-BP5URJOJ.d.cts → SemanticStateEngine-BFMdHvqG.d.cts}

@@ -23,6 +23,17 @@ interface SemanticStateEngineConfig {
      * @param driftScore Drift magnitude: 1 − cosine_similarity ∈ [0, 2].
      */
     onDriftDetected?: (vector: number[], driftScore: number) => void;
+    /**
+     * Optional callback invoked after every successful `update`, once the new
+     * EMA state has been fused and listeners have been notified.
+     *
+     * Use this for observability — logging, metrics, or debugging — without
+     * coupling to the React/Zustand subscription model.
+     *
+     * @param snapshot The updated point-in-time snapshot.
+     * @param text     The raw text that triggered the update.
+     */
+    onStateChange?: (snapshot: Snapshot, text: string) => void;
     /**
      * The embedding provider used to obtain embedding vectors asynchronously.
      * Any object implementing `getEmbedding(text: string): Promise<Float32Array | number[]>`
@@ -54,25 +65,26 @@ interface Snapshot {
  * SemanticStateEngine tracks the implicit semantic intent of an event stream
  * using Exponential Moving Average (EMA) vector fusion.
  *
+ * The computationally intensive vector operations (cosine similarity, EMA
+ * fusion, health calculation) are delegated to a Rust/WebAssembly core
+ * (`WasmStateEngine`) for better performance and type safety, while the
+ * public API surface remains identical.
+ *
  * It fires an optional drift callback when incoming embeddings diverge
  * significantly from the current state, and exposes a healthScore that
  * degrades with both age and volatility.
  */
 declare class SemanticStateEngine {
-    private readonly alpha;
-    private readonly driftThreshold;
     private readonly onDriftDetected?;
+    private readonly onStateChange?;
     private readonly provider;
     readonly modelName: string;
-    private stateVector;
-    private lastUpdatedAt;
-    private lastDrift;
-    private updateCount;
+    private readonly wasmEngine;
     private readonly listeners;
     constructor(config: SemanticStateEngineConfig);
     /**
-     * Obtains an embedding for `text` from the WorkerManager and fuses it into
-     * the rolling semantic state using EMA.
+     * Obtains an embedding for `text` from the provider and fuses it into
+     * the rolling semantic state using EMA (computed in Rust/WASM).
      *
      * On the first call the embedding establishes the baseline.
      * On subsequent calls, if the cosine similarity between the current state
@@ -92,17 +104,6 @@ declare class SemanticStateEngine {
      * Returns a point-in-time snapshot of the current semantic state.
      */
     getSnapshot(): Snapshot;
-    /**
-     * 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].
-     */
-    private calculateHealth;
-    private buildSummary;
 }
 
 export { type EmbeddingProvider as E, SemanticStateEngine as S, type SemanticStateEngineConfig as a, type Snapshot as b };

package/dist/{SemanticStateEngine-BP5URJOJ.d.ts → SemanticStateEngine-BFMdHvqG.d.ts}

@@ -23,6 +23,17 @@ interface SemanticStateEngineConfig {
      * @param driftScore Drift magnitude: 1 − cosine_similarity ∈ [0, 2].
      */
     onDriftDetected?: (vector: number[], driftScore: number) => void;
+    /**
+     * Optional callback invoked after every successful `update`, once the new
+     * EMA state has been fused and listeners have been notified.
+     *
+     * Use this for observability — logging, metrics, or debugging — without
+     * coupling to the React/Zustand subscription model.
+     *
+     * @param snapshot The updated point-in-time snapshot.
+     * @param text     The raw text that triggered the update.
+     */
+    onStateChange?: (snapshot: Snapshot, text: string) => void;
     /**
      * The embedding provider used to obtain embedding vectors asynchronously.
      * Any object implementing `getEmbedding(text: string): Promise<Float32Array | number[]>`
@@ -54,25 +65,26 @@ interface Snapshot {
  * SemanticStateEngine tracks the implicit semantic intent of an event stream
  * using Exponential Moving Average (EMA) vector fusion.
  *
+ * The computationally intensive vector operations (cosine similarity, EMA
+ * fusion, health calculation) are delegated to a Rust/WebAssembly core
+ * (`WasmStateEngine`) for better performance and type safety, while the
+ * public API surface remains identical.
+ *
  * It fires an optional drift callback when incoming embeddings diverge
  * significantly from the current state, and exposes a healthScore that
  * degrades with both age and volatility.
  */
 declare class SemanticStateEngine {
-    private readonly alpha;
-    private readonly driftThreshold;
     private readonly onDriftDetected?;
+    private readonly onStateChange?;
     private readonly provider;
     readonly modelName: string;
-    private stateVector;
-    private lastUpdatedAt;
-    private lastDrift;
-    private updateCount;
+    private readonly wasmEngine;
     private readonly listeners;
     constructor(config: SemanticStateEngineConfig);
     /**
-     * Obtains an embedding for `text` from the WorkerManager and fuses it into
-     * the rolling semantic state using EMA.
+     * Obtains an embedding for `text` from the provider and fuses it into
+     * the rolling semantic state using EMA (computed in Rust/WASM).
      *
      * On the first call the embedding establishes the baseline.
      * On subsequent calls, if the cosine similarity between the current state
@@ -92,17 +104,6 @@ declare class SemanticStateEngine {
      * Returns a point-in-time snapshot of the current semantic state.
      */
     getSnapshot(): Snapshot;
-    /**
-     * 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].
-     */
-    private calculateHealth;
-    private buildSummary;
 }
 
 export { type EmbeddingProvider as E, SemanticStateEngine as S, type SemanticStateEngineConfig as a, type Snapshot as b };