agentdb 1.6.1 → 2.0.0-alpha.2

package/dist/malp/wasm_bindings.d.ts

@@ -0,0 +1,344 @@
+/**
+ * MALP WASM Bindings - TypeScript Interface
+ *
+ * Provides TypeScript bindings for the MALP WASM module with SIMD acceleration.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Configuration for MALP regressor
+ *
+ * @public
+ */
+export interface MalpConfig {
+    /**
+     * L2 regularization parameter
+     * @defaultValue 0.0 (no regularization)
+     * @remarks Higher values reduce overfitting but may underfit
+     */
+    alpha?: number;
+    /**
+     * Maximum solver iterations
+     * @defaultValue 1000
+     */
+    maxIterations?: number;
+    /**
+     * Convergence tolerance
+     * @defaultValue 1e-6
+     */
+    tolerance?: number;
+    /**
+     * Enable WASM acceleration
+     * @defaultValue true (if available)
+     */
+    useWasm?: boolean;
+    /**
+     * Enable SIMD vectorization
+     * @defaultValue Auto-detected based on platform
+     */
+    useSIMD?: boolean;
+}
+/**
+ * MALP Regressor - Monotone Additive Linear Predictor
+ *
+ * @remarks
+ * Fits a monotone increasing function to data using isotonic regression.
+ * Guarantees that predictions are non-decreasing for ordered inputs.
+ *
+ * @example
+ * ```typescript
+ * import { MalpRegressor } from 'agentdb/malp';
+ *
+ * const malp = new MalpRegressor({ alpha: 0.01 });
+ *
+ * const X = [0.1, 0.3, 0.5, 0.7, 0.9];
+ * const y = [0.2, 0.4, 0.6, 0.75, 0.95];
+ *
+ * await malp.fit(X, y);
+ *
+ * const predictions = await malp.predict([0.2, 0.6]);
+ * console.log(predictions); // [~0.3, ~0.675]
+ * ```
+ *
+ * @public
+ */
+export declare class MalpRegressor {
+    /**
+     * Create a new MALP regressor
+     *
+     * @param config - Configuration options
+     */
+    constructor(config?: MalpConfig);
+    /**
+     * Fit the MALP model to training data
+     *
+     * @remarks
+     * Trains a monotone increasing function f such that f(x[i]) ≤ f(x[i+1]).
+     *
+     * Time Complexity: O(n log n) where n = number of samples
+     *
+     * @param X - Input features (must be sorted in ascending order)
+     * @param y - Target values
+     * @returns Promise that resolves when fitting is complete
+     *
+     * @throws {@link MalpError}
+     * - `LengthMismatch` if X and y have different lengths
+     * - `UnsortedInput` if X is not sorted
+     * - `InvalidInput` if data contains NaN or Infinity
+     * - `InsufficientSamples` if fewer than 2 samples provided
+     *
+     * @example
+     * ```typescript
+     * const malp = new MalpRegressor();
+     *
+     * const X = [0.1, 0.3, 0.5, 0.7, 0.9];
+     * const y = [0.2, 0.4, 0.6, 0.75, 0.95];
+     *
+     * await malp.fit(X, y);
+     * ```
+     */
+    fit(X: number[] | Float32Array, y: number[] | Float32Array): Promise<void>;
+    /**
+     * Make predictions for new inputs
+     *
+     * @remarks
+     * Uses linear interpolation between fitted breakpoints.
+     *
+     * Time Complexity: O(m log n) where m = predictions, n = training samples
+     *
+     * @param X - Input features to predict
+     * @returns Promise that resolves to predicted values
+     *
+     * @throws {@link MalpError}
+     * - `NotFitted` if model has not been trained (call {@link fit} first)
+     *
+     * @example
+     * ```typescript
+     * const predictions = await malp.predict([0.2, 0.4, 0.6]);
+     * console.log(predictions); // Float32Array [0.3, 0.5, 0.675]
+     * ```
+     */
+    predict(X: number[] | Float32Array): Promise<Float32Array>;
+    /**
+     * Calculate R² (coefficient of determination) score
+     *
+     * @remarks
+     * Formula:
+     * ```
+     * R² = 1 - (SS_res / SS_tot)
+     * where:
+     *   SS_res = Σ(y_true - y_pred)²
+     *   SS_tot = Σ(y_true - mean(y_true))²
+     * ```
+     *
+     * Interpretation:
+     * - R² > 0.9: Excellent fit
+     * - 0.7 < R² ≤ 0.9: Good fit
+     * - 0.5 < R² ≤ 0.7: Moderate fit
+     * - R² ≤ 0.5: Poor fit
+     *
+     * @param X - Input features
+     * @param y - True target values
+     * @returns R² score (0.0 to 1.0, higher is better)
+     *
+     * @example
+     * ```typescript
+     * const r2 = malp.score(X, y);
+     * console.log(`R² Score: ${r2.toFixed(4)}`); // e.g., 0.9523
+     * ```
+     */
+    score(X: number[] | Float32Array, y: number[] | Float32Array): number;
+    /**
+     * Check if predictions are monotone increasing
+     *
+     * @returns `true` if model guarantees monotonicity (always `true` for MALP)
+     *
+     * @remarks
+     * MALP always enforces monotonicity by construction, so this method
+     * always returns `true`. It's provided for API consistency.
+     *
+     * @example
+     * ```typescript
+     * const isMonotone = malp.checkMonotonicity();
+     * console.log(isMonotone); // true
+     * ```
+     */
+    checkMonotonicity(): boolean;
+    /**
+     * Get trained model weights
+     *
+     * @remarks
+     * Returns the piecewise linear breakpoints learned during fitting.
+     * Useful for model inspection, serialization, or debugging.
+     *
+     * @returns Model weights if fitted, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const weights = malp.getWeights();
+     * if (weights) {
+     *   console.log('Model weights:', weights);
+     *   // Save to file: fs.writeFileSync('weights.bin', Buffer.from(weights.buffer));
+     * }
+     * ```
+     */
+    getWeights(): Float32Array | undefined;
+    /**
+     * Set model weights (for deserialization)
+     *
+     * @remarks
+     * Allows loading a pre-trained model without calling {@link fit}.
+     *
+     * @param weights - Pre-trained model weights
+     *
+     * @example
+     * ```typescript
+     * // Load weights from file
+     * const buffer = fs.readFileSync('weights.bin');
+     * const weights = new Float32Array(buffer.buffer);
+     *
+     * malp.setWeights(weights);
+     *
+     * // Model is now ready for predictions
+     * const predictions = await malp.predict([0.5, 0.7]);
+     * ```
+     */
+    setWeights(weights: Float32Array): void;
+    /**
+     * Reset model to untrained state
+     *
+     * @remarks
+     * Clears all trained parameters. The model must be re-trained with
+     * {@link fit} before making predictions.
+     *
+     * @example
+     * ```typescript
+     * malp.reset();
+     * // Model is now untrained
+     * // await malp.predict([0.5]); // Would throw NotFitted error
+     * ```
+     */
+    reset(): void;
+}
+/**
+ * MALP Error Types
+ *
+ * @public
+ */
+export type MalpError = {
+    code: 'MALP_001';
+    message: 'Invalid input';
+    reason: string;
+} | {
+    code: 'MALP_002';
+    message: 'Unsorted input';
+    reason: string;
+} | {
+    code: 'MALP_003';
+    message: 'Length mismatch';
+    xLen: number;
+    yLen: number;
+} | {
+    code: 'MALP_004';
+    message: 'Insufficient samples';
+    n: number;
+} | {
+    code: 'MALP_005';
+    message: 'Not fitted';
+} | {
+    code: 'MALP_006';
+    message: 'WASM not supported';
+} | {
+    code: 'MALP_007';
+    message: 'Convergence error';
+    iterations: number;
+};
+/**
+ * Initialize WASM module
+ *
+ * @remarks
+ * Must be called before using WASM-accelerated features.
+ * Only needs to be called once per application lifecycle.
+ *
+ * @returns Promise that resolves when WASM is initialized
+ *
+ * @example
+ * ```typescript
+ * import { initWasm } from 'agentdb/wasm';
+ *
+ * await initWasm();
+ * console.log('WASM initialized');
+ * ```
+ *
+ * @public
+ */
+export declare function initWasm(): Promise<void>;
+/**
+ * Check if WASM is supported in current environment
+ *
+ * @returns `true` if WASM is available, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { checkWasmSupport } from 'agentdb/wasm';
+ *
+ * const supported = await checkWasmSupport();
+ * if (supported) {
+ *   console.log('✅ WASM supported');
+ * } else {
+ *   console.warn('⚠️ WASM not supported, using JavaScript fallback');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function checkWasmSupport(): Promise<boolean>;
+/**
+ * Check if SIMD is supported
+ *
+ * @returns `true` if SIMD is available, `false` otherwise
+ *
+ * @remarks
+ * SIMD (Single Instruction Multiple Data) provides 2-4x speedup for
+ * large datasets by processing multiple values simultaneously.
+ *
+ * @example
+ * ```typescript
+ * import { checkSimdSupport } from 'agentdb/wasm';
+ *
+ * const simdSupported = await checkSimdSupport();
+ * console.log(`SIMD: ${simdSupported ? 'enabled' : 'not available'}`);
+ * ```
+ *
+ * @public
+ */
+export declare function checkSimdSupport(): Promise<boolean>;
+/**
+ * WASM-accelerated MALP regressor
+ *
+ * @remarks
+ * Same API as {@link MalpRegressor}, but uses WASM implementation
+ * with optional SIMD acceleration for 2-4x performance improvement.
+ *
+ * @example
+ * ```typescript
+ * import { initWasm, MalpWasm } from 'agentdb/wasm';
+ *
+ * await initWasm();
+ *
+ * const malp = new MalpWasm();
+ *
+ * const X = new Float32Array([0.1, 0.3, 0.5, 0.7, 0.9]);
+ * const y = new Float32Array([0.2, 0.4, 0.6, 0.75, 0.95]);
+ *
+ * await malp.fit(X, y);
+ *
+ * const predictions = await malp.predict(new Float32Array([0.2, 0.6]));
+ * console.log(predictions); // Float32Array [0.3, 0.675]
+ * ```
+ *
+ * @public
+ */
+export declare class MalpWasm extends MalpRegressor {
+}
+//# sourceMappingURL=wasm_bindings.d.ts.map

package/dist/malp/wasm_bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm_bindings.d.ts","sourceRoot":"","sources":["../../src/malp/wasm_bindings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IAChC;;;;OAIG;gBACS,MAAM,CAAC,EAAE,UAAU;IAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,MAAM;IAErE;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,IAAI,OAAO;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,IAAI,YAAY,GAAG,SAAS;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAEvC;;;;;;;;;;;;;OAaG;IACH,KAAK,IAAI,IAAI;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,aAAa;CAAG"}

package/dist/malp/wasm_bindings.js

@@ -0,0 +1,9 @@
+/**
+ * MALP WASM Bindings - TypeScript Interface
+ *
+ * Provides TypeScript bindings for the MALP WASM module with SIMD acceleration.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=wasm_bindings.js.map

package/dist/malp/wasm_bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm_bindings.js","sourceRoot":"","sources":["../../src/malp/wasm_bindings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}