@euconform/core 1.0.0

package/dist/inference/inference-factory.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Inference Factory with Method Detection
+ * Provides unified interface for bias calculations across engines with automatic method detection
+ */
+import type { BiasCalculationMethod, BiasTestConfig, CrowsPairsBiasResult } from "../types";
+import { BrowserInference } from "./browser-inference";
+import type { ModelCapability } from "./capability-detection";
+import { OllamaClient } from "./ollama-client";
+/**
+ * Result wrapper that includes method metadata for all inference operations
+ */
+export interface InferenceResult<T> {
+    data: T;
+    method: BiasCalculationMethod;
+    engine: "browser" | "ollama";
+    model: string;
+    capability?: ModelCapability;
+}
+/**
+ * Inference Factory class that manages inference clients and provides unified interface
+ * Automatically detects best available calculation method and returns metadata
+ */
+export declare class InferenceFactory {
+    private browserClient;
+    private ollamaClient;
+    private statusCallback;
+    private selectedCapability;
+    constructor(statusCallback?: (status: string) => void);
+    /**
+     * Set the selected model capability for enhanced metadata tracking
+     */
+    setSelectedCapability(capability: ModelCapability): void;
+    /**
+     * Create a bias calculation with automatic method detection
+     * Returns InferenceResult with both data and method metadata
+     */
+    createBiasCalculation(config: BiasTestConfig): Promise<InferenceResult<CrowsPairsBiasResult>>;
+    /**
+     * Detect the best available calculation method for the given client
+     * Returns the method that should be used for bias calculations
+     */
+    private detectBestMethod;
+    /**
+     * Get browser inference client (creates if needed)
+     */
+    getBrowserClient(model: string): BrowserInference;
+    /**
+     * Get Ollama client (creates if needed)
+     */
+    getOllamaClient(model: string): OllamaClient;
+    private validateConfiguration;
+    private getInferenceClient;
+    /**
+     * Create inference result wrapper for any data with method detection
+     * Useful for wrapping existing inference operations with metadata
+     */
+    createInferenceResult<T>(data: T, engine: "browser" | "ollama", model: string, client?: BrowserInference | OllamaClient): Promise<InferenceResult<T>>;
+    /**
+     * Cleanup resources
+     */
+    dispose(): void;
+}
+/**
+ * Create a global inference factory instance
+ * Provides convenient access to factory methods
+ */
+export declare function createInferenceFactory(statusCallback?: (status: string) => void): InferenceFactory;
+/**
+ * Utility function to detect best method for a given configuration
+ * Useful for pre-flight checks without creating full factory
+ */
+export declare function detectBestMethodForConfig(config: BiasTestConfig): Promise<BiasCalculationMethod>;
+//# sourceMappingURL=inference-factory.d.ts.map

package/dist/inference/inference-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-factory.d.ts","sourceRoot":"","sources":["../../src/inference/inference-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,kBAAkB,CAAgC;gBAE9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI;IAIrD;;OAEG;IACH,qBAAqB,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAIxD;;;OAGG;IACG,qBAAqB,CACzB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,eAAe,CAAC,oBAAoB,CAAC,CAAC;IA6BjD;;;OAGG;YACW,gBAAgB;IAe9B;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAOjD;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAO5C,OAAO,CAAC,qBAAqB;YAgBf,kBAAkB;IAUhC;;;OAGG;IACG,qBAAqB,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,SAAS,GAAG,QAAQ,EAC5B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,GACvC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IA8B9B;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GACxC,gBAAgB,CAElB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAYhC"}

package/dist/inference/inference-factory.js

@@ -0,0 +1,175 @@
+/**
+ * Inference Factory with Method Detection
+ * Provides unified interface for bias calculations across engines with automatic method detection
+ */
+import { calculateCrowsPairsBias } from "../metrics/crows-pairs-bias";
+import { BrowserInference } from "./browser-inference";
+import { OllamaClient } from "./ollama-client";
+/**
+ * Inference Factory class that manages inference clients and provides unified interface
+ * Automatically detects best available calculation method and returns metadata
+ */
+export class InferenceFactory {
+    browserClient = null;
+    ollamaClient = null;
+    statusCallback = null;
+    selectedCapability = null;
+    constructor(statusCallback) {
+        this.statusCallback = statusCallback || null;
+    }
+    /**
+     * Set the selected model capability for enhanced metadata tracking
+     */
+    setSelectedCapability(capability) {
+        this.selectedCapability = capability;
+    }
+    /**
+     * Create a bias calculation with automatic method detection
+     * Returns InferenceResult with both data and method metadata
+     */
+    async createBiasCalculation(config) {
+        const { engine, model } = config;
+        this.validateConfiguration(config);
+        const inferenceClient = await this.getInferenceClient(engine, model);
+        let _detectedMethod;
+        if (engine === "browser") {
+            _detectedMethod = "logprobs_exact";
+        }
+        else {
+            // Use capability method if available, otherwise detect
+            _detectedMethod =
+                this.selectedCapability?.method ?? (await this.detectBestMethod(inferenceClient));
+        }
+        // Perform bias calculation
+        const biasResult = await calculateCrowsPairsBias(config, inferenceClient);
+        // Return result with metadata including capability information
+        return {
+            data: biasResult,
+            method: biasResult.method, // Use the method determined during calculation
+            engine,
+            model,
+            capability: this.selectedCapability || undefined,
+        };
+    }
+    /**
+     * Detect the best available calculation method for the given client
+     * Returns the method that should be used for bias calculations
+     */
+    async detectBestMethod(client) {
+        if (client instanceof BrowserInference) {
+            // Browser inference always supports exact log-probabilities
+            return "logprobs_exact";
+        }
+        if (client instanceof OllamaClient) {
+            // Check Ollama's log-probability support
+            const supportsLogProbs = await client.detectLogProbSupport();
+            return supportsLogProbs ? "logprobs_exact" : "logprobs_fallback_latency";
+        }
+        throw new Error("Unknown inference client type");
+    }
+    /**
+     * Get browser inference client (creates if needed)
+     */
+    getBrowserClient(model) {
+        if (!this.browserClient || this.browserClient.modelId !== model) {
+            this.browserClient = new BrowserInference(model, this.statusCallback);
+        }
+        return this.browserClient;
+    }
+    /**
+     * Get Ollama client (creates if needed)
+     */
+    getOllamaClient(model) {
+        if (!this.ollamaClient || this.ollamaClient.model !== model) {
+            this.ollamaClient = new OllamaClient(model);
+        }
+        return this.ollamaClient;
+    }
+    validateConfiguration(config) {
+        const { engine, model } = config;
+        if (!this.selectedCapability)
+            return;
+        if (this.selectedCapability.status !== "available") {
+            throw new Error(`Selected model ${model} is not available (status: ${this.selectedCapability.status})`);
+        }
+        if (this.selectedCapability.modelId !== model || this.selectedCapability.engine !== engine) {
+            throw new Error(`Configuration mismatch: expected ${this.selectedCapability.modelId} (${this.selectedCapability.engine}), got ${model} (${engine})`);
+        }
+    }
+    async getInferenceClient(engine, model) {
+        if (engine === "browser") {
+            return this.getBrowserClient(model);
+        }
+        if (engine === "ollama") {
+            return this.getOllamaClient(model);
+        }
+        throw new Error(`Unsupported engine: ${engine}`);
+    }
+    /**
+     * Create inference result wrapper for any data with method detection
+     * Useful for wrapping existing inference operations with metadata
+     */
+    async createInferenceResult(data, engine, model, client) {
+        let method;
+        // Use capability method if available, otherwise detect
+        const selectedMethod = this.selectedCapability?.method;
+        if (selectedMethod) {
+            method = selectedMethod;
+        }
+        else if (engine === "browser") {
+            method = "logprobs_exact";
+        }
+        else if (engine === "ollama") {
+            if (client instanceof OllamaClient) {
+                method = await this.detectBestMethod(client);
+            }
+            else {
+                // Create temporary client for method detection
+                const tempClient = new OllamaClient(model);
+                method = await this.detectBestMethod(tempClient);
+            }
+        }
+        else {
+            throw new Error(`Unsupported engine: ${engine}`);
+        }
+        return {
+            data,
+            method,
+            engine,
+            model,
+            capability: this.selectedCapability || undefined,
+        };
+    }
+    /**
+     * Cleanup resources
+     */
+    dispose() {
+        this.browserClient = null;
+        this.ollamaClient = null;
+        this.statusCallback = null;
+        this.selectedCapability = null;
+    }
+}
+/**
+ * Create a global inference factory instance
+ * Provides convenient access to factory methods
+ */
+export function createInferenceFactory(statusCallback) {
+    return new InferenceFactory(statusCallback);
+}
+/**
+ * Utility function to detect best method for a given configuration
+ * Useful for pre-flight checks without creating full factory
+ */
+export async function detectBestMethodForConfig(config) {
+    const { engine, model } = config;
+    if (engine === "browser") {
+        return "logprobs_exact";
+    }
+    if (engine === "ollama") {
+        const client = new OllamaClient(model);
+        const supportsLogProbs = await client.detectLogProbSupport();
+        return supportsLogProbs ? "logprobs_exact" : "logprobs_fallback_latency";
+    }
+    throw new Error(`Unsupported engine: ${engine}`);
+}

package/dist/inference/ollama-client.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Ollama Client for local LLM inference
+ * Connects to Ollama running on localhost:11434
+ */
+import type { BiasCalculationMethod } from "../types";
+export interface OllamaModel {
+    name: string;
+    size: number;
+    digest: string;
+    modified_at: string;
+}
+export interface OllamaGenerateOptions {
+    model: string;
+    prompt: string;
+    stream?: boolean;
+    logprobs?: boolean | number;
+    options?: {
+        temperature?: number;
+        top_p?: number;
+        num_predict?: number;
+    };
+}
+export interface OllamaGenerateResponse {
+    model: string;
+    response: string;
+    done: boolean;
+    context?: number[];
+    total_duration?: number;
+    eval_count?: number;
+    logprobs?: Array<{
+        token: string;
+        logprob: number;
+    }>;
+}
+export interface OllamaLogProbResponse {
+    model: string;
+    prompt: string;
+    logprob: number;
+}
+export interface OllamaLogProbsOptions {
+    logprobs?: boolean | number;
+}
+export interface OllamaLogProbsResponse extends OllamaGenerateResponse {
+    logprobs?: Array<{
+        token: string;
+        logprob: number;
+    }>;
+}
+/**
+ * Check if Ollama is running and accessible
+ */
+export declare function detectOllama(): Promise<boolean>;
+/**
+ * Get list of available models from Ollama
+ */
+export declare function listOllamaModels(): Promise<OllamaModel[]>;
+/**
+ * Generate text with Ollama
+ */
+export declare function ollamaGenerate(options: OllamaGenerateOptions): Promise<OllamaGenerateResponse>;
+/**
+ * Get log probability for a prompt (for bias scoring)
+ * Uses the /api/generate endpoint with num_predict: 0 to get prompt logprobs
+ */
+export declare function getLogProb(model: string, prompt: string): Promise<number>;
+/**
+ * Calculate perplexity for a text (alternative bias metric)
+ */
+export declare function getPerplexity(model: string, text: string): Promise<number>;
+/**
+ * Ollama client class for stateful operations
+ */
+export declare class OllamaClient {
+    private baseUrl;
+    readonly model: string;
+    private capabilityCache;
+    constructor(model: string, baseUrl?: string);
+    /**
+     * Ensures the model is available in Ollama before proceeding
+     * Throws an error if the model is not found
+     */
+    ensureModelLoaded(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+    generate(prompt: string): Promise<string>;
+    getLogProb(prompt: string): Promise<number>;
+    getPerplexity(text: string): Promise<number>;
+    /**
+     * Test if the current model supports log-probabilities
+     * Sends a test request with "Der" prompt to detect capability
+     */
+    private testLogProbCapability;
+    /**
+     * Get cached capability result from localStorage
+     */
+    private getCachedCapability;
+    /**
+     * Cache capability result in localStorage
+     */
+    private setCachedCapability;
+    /**
+     * Detect if the current model supports log-probabilities
+     * Checks cache first, then runs test if needed
+     */
+    detectLogProbSupport(): Promise<boolean>;
+    /**
+     * Get log-probability with automatic fallback to latency method
+     * Returns both the calculated value and the method used
+     */
+    getLogProbWithFallback(prompt: string): Promise<{
+        logprob: number;
+        method: BiasCalculationMethod;
+    }>;
+}
+//# sourceMappingURL=ollama-client.d.ts.map

package/dist/inference/ollama-client.d.ts.map

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