@euconform/core 1.0.0

package/dist/inference/browser-inference.js

@@ -0,0 +1,221 @@
+/**
+ * Browser-based inference using transformers.js
+ * For small models (≤3B params) that can run via WebGPU
+ *
+ * STRICT MODE: Real inference only. No demo data.
+ */
+// Supported models for browser inference
+export const BROWSER_MODELS = [
+    {
+        id: "Xenova/phi-3-mini-4k-instruct",
+        name: "Phi-3 Mini",
+        size: "3.8B",
+        supported: true,
+    },
+    {
+        id: "Xenova/Phi-3.5-mini-instruct",
+        name: "Phi-3.5 Mini",
+        size: "3.8B",
+        supported: true,
+    },
+    {
+        id: "Xenova/gpt2",
+        name: "GPT-2",
+        size: "124M",
+        supported: true,
+    },
+    {
+        id: "Xenova/distilgpt2",
+        name: "DistilGPT-2",
+        size: "82M",
+        supported: true,
+    },
+];
+/**
+ * Check if WebGPU is available in the browser
+ */
+export async function checkWebGPU() {
+    if (typeof navigator === "undefined")
+        return false;
+    if (typeof window === "undefined")
+        return false;
+    try {
+        // Check for WebGPU support
+        const gpu = navigator.gpu;
+        if (!gpu)
+            return false;
+        // Try to get adapter
+        const adapter = await gpu.requestAdapter();
+        return adapter !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if transformers.js is available
+ */
+export async function checkTransformersAvailable() {
+    try {
+        // Try dynamic import - this will fail if package not installed
+        await import("@xenova/transformers");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Browser inference engine using transformers.js
+ * STRICT MODE: Throws error if package not installed.
+ */
+export class BrowserInference {
+    modelId;
+    model = null;
+    tokenizer = null;
+    pipeline = null; // Keep pipeline for generation
+    loadingPromise = null;
+    loadError = null;
+    statusCallback = null;
+    constructor(modelId = "Xenova/distilgpt2", statusCallback = null) {
+        this.modelId = modelId;
+        this.statusCallback = statusCallback;
+    }
+    /**
+     * Check if browser inference is available
+     */
+    async isAvailable() {
+        const hasTransformers = await checkTransformersAvailable();
+        return hasTransformers;
+    }
+    /**
+     * Load the model (lazy loading)
+     * Handles concurrency with loadingPromise
+     */
+    async load() {
+        if (this.model && this.tokenizer)
+            return;
+        if (this.loadingPromise)
+            return this.loadingPromise;
+        if (this.loadError)
+            throw this.loadError;
+        this.loadingPromise = this.performLoad().finally(() => {
+            this.loadingPromise = null;
+        });
+        return this.loadingPromise;
+    }
+    async performLoad() {
+        if (this.statusCallback)
+            this.statusCallback("loading");
+        try {
+            const { AutoTokenizer, AutoModelForCausalLM, pipeline } = await import("@xenova/transformers");
+            const hasWebGPU = await checkWebGPU();
+            const device = hasWebGPU ? "webgpu" : "cpu";
+            if (this.statusCallback)
+                this.statusCallback("loading-tokenizer");
+            this.tokenizer = await AutoTokenizer.from_pretrained(this.modelId);
+            if (this.statusCallback)
+                this.statusCallback("loading-model");
+            // biome-ignore lint/suspicious/noExplicitAny: library internal
+            this.model = await AutoModelForCausalLM.from_pretrained(this.modelId, {
+                device,
+                quantized: true,
+            });
+            if (this.statusCallback)
+                this.statusCallback("loading-pipeline");
+            // biome-ignore lint/suspicious/noExplicitAny: library internal
+            this.pipeline = await pipeline("text-generation", this.modelId, {
+                device,
+                model: this.model,
+                tokenizer: this.tokenizer,
+            });
+            if (this.statusCallback)
+                this.statusCallback("ready");
+        }
+        catch (err) {
+            this.loadError = err instanceof Error ? err : new Error(String(err));
+            if (this.statusCallback)
+                this.statusCallback("error");
+            throw this.loadError;
+        }
+    }
+    /**
+     * Generate text
+     */
+    async generate(prompt, maxTokens = 50) {
+        await this.load();
+        if (!this.pipeline) {
+            throw new Error("Model not loaded");
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: library internal
+        const result = await this.pipeline(prompt, {
+            max_new_tokens: maxTokens,
+            temperature: 0.7,
+            do_sample: true,
+        });
+        return result[0]?.generated_text || "";
+    }
+    /**
+     * Calculate Log-Probability for a given text
+     * This is the "Gold Standard" for bias testing.
+     * We calculate the loss (negative log likelihood) of the text.
+     */
+    async getLogProb(text) {
+        await this.load();
+        if (!this.tokenizer || !this.model) {
+            throw new Error("Model not loaded");
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: internal transformers.js types
+        const inputs = await this.tokenizer(text, { return_tensors: "pt" });
+        const inputIds = inputs.input_ids;
+        // biome-ignore lint/suspicious/noExplicitAny: internal transformers.js types
+        const outputs = await this.model(inputs);
+        const logits = outputs.logits;
+        // 3. Compute Log Likelihood
+        // We want to calculate P(text) = P(t1) * P(t2|t1) * ...
+        // LogProb = sum( log( P(ti | t_<i) ) )
+        // logits shape: [batch_size, seq_len, vocab_size]
+        // inputIds shape: [batch_size, seq_len]
+        // We are interested in the probability of the *next* token given previous tokens.
+        // So we look at logits[0, i, :] to predict inputIds[0, i+1]
+        const data = logits.data; // Float32Array
+        const dims = logits.dims; // [batch, seq, vocab]
+        const vocabSize = dims[2];
+        const seqLen = dims[1];
+        let totalLogProb = 0;
+        // Helper to get logit value
+        const getLogit = (seqIdx, vocabIdx) => {
+            return data[seqIdx * vocabSize + vocabIdx];
+        };
+        // Helper for softmax/logsoftmax
+        // We only need the log_prob of the target token
+        // log_softmax(x_i) = x_i - log(sum(exp(x_j)))
+        // To avoid overflow: x_i - max(x) - log(sum(exp(x_j - max(x))))
+        for (let i = 0; i < seqLen - 1; i++) {
+            const targetTokenId = Number(inputIds.data[i + 1]);
+            // Calculate max logit for numerical stability
+            let maxLogit = Number.NEGATIVE_INFINITY;
+            for (let j = 0; j < vocabSize; j++) {
+                const val = getLogit(i, j);
+                if (val > maxLogit)
+                    maxLogit = val;
+            }
+            // Calculate sum of exp
+            let sumExp = 0;
+            for (let j = 0; j < vocabSize; j++) {
+                sumExp += Math.exp(getLogit(i, j) - maxLogit);
+            }
+            const logSumExp = maxLogit + Math.log(sumExp);
+            const targetLogit = getLogit(i, targetTokenId);
+            const logProb = targetLogit - logSumExp;
+            totalLogProb += logProb;
+        }
+        return totalLogProb;
+    }
+    /**
+     * Get list of supported browser models
+     */
+    static getSupportedModels() {
+        return BROWSER_MODELS.filter((m) => m.supported);
+    }
+}

package/dist/inference/capability-detection.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Model Capability Detection Service
+ * Real-time detection of model capabilities with smart caching
+ */
+import type { BiasCalculationMethod } from "../types";
+/**
+ * Detection status for model capabilities
+ */
+export type CapabilityDetectionStatus = "detecting" | "available" | "unavailable" | "error";
+/**
+ * Model capability information
+ */
+export interface ModelCapability {
+    modelId: string;
+    engine: "browser" | "ollama";
+    method: BiasCalculationMethod;
+    status: CapabilityDetectionStatus;
+    lastTested?: string;
+    error?: string;
+    recommended?: boolean;
+}
+/**
+ * Model selection state for UI components
+ */
+export interface ModelSelectionState {
+    models: ModelCapability[];
+    selectedModel?: string;
+    isLoading: boolean;
+    showExplanations: boolean;
+}
+/**
+ * Cache entry structure with expiration and version tracking
+ */
+export interface CapabilityCacheEntry {
+    modelId: string;
+    capability: ModelCapability;
+    cachedAt: string;
+    expiresAt: string;
+    ollamaVersion?: string;
+}
+/**
+ * Detection progress tracking
+ */
+export interface DetectionProgress {
+    total: number;
+    completed: number;
+    inProgress: string[];
+}
+/**
+ * User preferences for model selection
+ */
+export interface UserPreferences {
+    showExplanations: boolean;
+    preferExactMethods: boolean;
+    hideUnavailableModels: boolean;
+}
+/**
+ * Enhanced model selection state with preferences
+ */
+export interface EnhancedModelSelectionState extends ModelSelectionState {
+    detectionProgress: DetectionProgress;
+    userPreferences: UserPreferences;
+    lastRefresh: string;
+}
+/**
+ * Service interface for capability detection
+ */
+export interface CapabilityDetectionService {
+    detectAllCapabilities(): Promise<ModelCapability[]>;
+    detectModelCapability(modelId: string, engine: "browser" | "ollama"): Promise<ModelCapability>;
+    getCachedCapability(modelId: string): CapabilityCacheEntry | null;
+    setCachedCapability(capability: ModelCapability): void;
+    clearCache(): void;
+    refreshCapabilities(): Promise<ModelCapability[]>;
+}
+/**
+ * Implementation of capability detection service
+ */
+export declare class DefaultCapabilityDetectionService implements CapabilityDetectionService {
+    private cache;
+    private readonly CACHE_DURATION_MS;
+    private readonly CACHE_KEY_PREFIX;
+    constructor();
+    /**
+     * Detect capabilities for all available models
+     * Includes browser inference and parallel Ollama model testing
+     */
+    detectAllCapabilities(): Promise<ModelCapability[]>;
+    /**
+     * Detect capability for a specific model
+     * Uses cache-first strategy with live fallback
+     */
+    detectModelCapability(modelId: string, engine: "browser" | "ollama"): Promise<ModelCapability>;
+    /**
+     * Get cached capability result
+     */
+    getCachedCapability(modelId: string): CapabilityCacheEntry | null;
+    /**
+     * Cache capability result with optional custom duration
+     */
+    setCachedCapability(capability: ModelCapability, durationMs?: number): void;
+    /**
+     * Clear all cached capabilities
+     */
+    clearCache(): void;
+    /**
+     * Refresh all capabilities by clearing cache and re-detecting
+     */
+    refreshCapabilities(): Promise<ModelCapability[]>;
+    /**
+     * Check if cache entry is still valid
+     */
+    protected isCacheValid(cacheEntry: CapabilityCacheEntry): boolean;
+    /**
+     * Load cache from localStorage
+     */
+    private loadCacheFromStorage;
+    /**
+     * Save cache entry to localStorage
+     */
+    private saveCacheToStorage;
+    /**
+     * Sort capabilities by recommendation score
+     */
+    protected sortByRecommendation(capabilities: ModelCapability[]): ModelCapability[];
+    /**
+     * Calculate recommendation score for a capability
+     */
+    protected getRecommendationScore(capability: ModelCapability): number;
+}
+/**
+ * Enhanced capability detection service with timeout and retry logic
+ */
+export declare class EnhancedCapabilityDetectionService extends DefaultCapabilityDetectionService {
+    private readonly DETECTION_TIMEOUT_MS;
+    private readonly MAX_RETRIES;
+    private readonly RETRY_DELAY_BASE_MS;
+    /**
+     * Detect model capability with timeout and retry logic
+     */
+    detectModelCapability(modelId: string, engine: "browser" | "ollama"): Promise<ModelCapability>;
+    /**
+     * Detect Ollama capability with retry logic and exponential backoff
+     */
+    private detectOllamaCapabilityWithRetry;
+    /**
+     * Detect Ollama capability with timeout
+     */
+    private detectOllamaCapabilityWithTimeout;
+    /**
+     * Enhanced detectAllCapabilities with better error handling
+     */
+    detectAllCapabilities(): Promise<ModelCapability[]>;
+    /**
+     * Utility function to add timeout to any promise
+     */
+    private withTimeout;
+    /**
+     * Sleep utility for retry delays
+     */
+    private sleep;
+    /**
+     * Check if error should not be retried
+     */
+    private isNonRetryableError;
+    /**
+     * Check if error indicates Ollama is unavailable
+     */
+    private isOllamaUnavailableError;
+    /**
+     * Get user-friendly error message
+     */
+    private getErrorMessage;
+    /**
+     * Check if cache entry is still valid (override to handle version tracking)
+     */
+    protected isCacheValid(cacheEntry: CapabilityCacheEntry): boolean;
+}
+/**
+ * Create a capability detection service instance
+ */
+export declare function createCapabilityDetectionService(): CapabilityDetectionService;
+//# sourceMappingURL=capability-detection.d.ts.map

package/dist/inference/capability-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-detection.d.ts","sourceRoot":"","sources":["../../src/inference/capability-detection.ts"],"names":[],"mappings":"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"}