@euconform/core 1.0.0

package/src/inference/index.ts

@@ -0,0 +1,156 @@
+/**
+ * Inference Factory
+ * Auto-detects available inference engines and provides unified interface
+ */
+
+import {
+  BROWSER_MODELS,
+  BrowserInference,
+  type BrowserModel,
+  checkWebGPU,
+} from "./browser-inference";
+import { OllamaClient, type OllamaModel, detectOllama, listOllamaModels } from "./ollama-client";
+
+export type InferenceEngine = "ollama" | "browser" | "demo";
+
+export interface InferenceCapabilities {
+  ollama: {
+    available: boolean;
+    models: OllamaModel[];
+  };
+  browser: {
+    available: boolean;
+    webgpu: boolean;
+    models: BrowserModel[];
+  };
+  recommended: InferenceEngine;
+}
+
+export interface InferenceClient {
+  engine: InferenceEngine;
+  modelId: string;
+  generate(prompt: string): Promise<string>;
+  getLogProb(prompt: string): Promise<number>;
+}
+
+/**
+ * Detect all available inference capabilities
+ */
+export async function detectCapabilities(): Promise<InferenceCapabilities> {
+  const [ollamaAvailable, webgpuAvailable, ollamaModels] = await Promise.all([
+    detectOllama(),
+    checkWebGPU(),
+    detectOllama().then((ok) => (ok ? listOllamaModels() : [])),
+  ]);
+
+  // Determine recommended engine
+  let recommended: InferenceEngine = "demo";
+  if (ollamaAvailable && ollamaModels.length > 0) {
+    recommended = "ollama";
+  } else if (webgpuAvailable) {
+    recommended = "browser";
+  }
+
+  return {
+    ollama: {
+      available: ollamaAvailable,
+      models: ollamaModels,
+    },
+    browser: {
+      available: webgpuAvailable || true, // CPU fallback always available
+      webgpu: webgpuAvailable,
+      models: BROWSER_MODELS,
+    },
+    recommended,
+  };
+}
+
+/**
+ * Create an inference client for the specified engine
+ */
+export function createInferenceClient(
+  engine: InferenceEngine,
+  modelId: string,
+  statusCallback?: (status: string) => void
+): InferenceClient {
+  switch (engine) {
+    case "ollama": {
+      const ollamaClient = new OllamaClient(modelId);
+      return {
+        engine: "ollama",
+        modelId,
+        generate: (prompt: string) => ollamaClient.generate(prompt),
+        getLogProb: (prompt: string) => ollamaClient.getLogProb(prompt),
+      };
+    }
+
+    case "browser": {
+      const browserClient = new BrowserInference(modelId, statusCallback);
+      return {
+        engine: "browser",
+        modelId,
+        generate: (prompt: string) => browserClient.generate(prompt),
+        getLogProb: (prompt: string) => browserClient.getLogProb(prompt),
+      };
+    }
+    default:
+      // Demo mode returns simulated results
+      return {
+        engine: "demo",
+        modelId: "demo-model",
+        generate: async (prompt: string) => {
+          await new Promise((r) => setTimeout(r, 500)); // Simulate latency
+          return `[Demo] Response to: ${prompt.slice(0, 50)}...`;
+        },
+        getLogProb: async () => {
+          await new Promise((r) => setTimeout(r, 100));
+          // Return random value between -5 and 0 for demo
+          return -Math.random() * 5;
+        },
+      };
+  }
+}
+
+/**
+ * Auto-select the best available inference client
+ */
+export async function createAutoInferenceClient(preferredModel?: string): Promise<InferenceClient> {
+  const capabilities = await detectCapabilities();
+
+  if (capabilities.recommended === "ollama") {
+    // Use preferred model if available, otherwise first model
+    const model = preferredModel || capabilities.ollama.models[0]?.name || "llama3.2:3b";
+    return createInferenceClient("ollama", model);
+  }
+
+  if (capabilities.recommended === "browser") {
+    const model = preferredModel || BROWSER_MODELS[0]?.id || "Xenova/distilgpt2";
+    return createInferenceClient("browser", model);
+  }
+
+  return createInferenceClient("demo", "demo-model");
+}
+
+// Re-export types and utilities
+export { detectOllama, listOllamaModels, OllamaClient } from "./ollama-client";
+export { BrowserInference, checkWebGPU, BROWSER_MODELS } from "./browser-inference";
+export {
+  InferenceFactory,
+  createInferenceFactory,
+  detectBestMethodForConfig,
+  type InferenceResult,
+} from "./inference-factory";
+export {
+  createCapabilityDetectionService,
+  DefaultCapabilityDetectionService,
+  EnhancedCapabilityDetectionService,
+  type CapabilityDetectionService,
+  type ModelCapability,
+  type ModelSelectionState,
+  type CapabilityCacheEntry,
+  type DetectionProgress,
+  type UserPreferences,
+  type EnhancedModelSelectionState,
+  type CapabilityDetectionStatus,
+} from "./capability-detection";
+export type { OllamaModel, BrowserModel };

package/src/inference/inference-factory.ts

@@ -0,0 +1,222 @@
+/**
+ * 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 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 class InferenceFactory {
+  private browserClient: BrowserInference | null = null;
+  private ollamaClient: OllamaClient | null = null;
+  private statusCallback: ((status: string) => void) | null = null;
+  private selectedCapability: ModelCapability | null = null;
+
+  constructor(statusCallback?: (status: string) => void) {
+    this.statusCallback = statusCallback || null;
+  }
+
+  /**
+   * Set the selected model capability for enhanced metadata tracking
+   */
+  setSelectedCapability(capability: ModelCapability): void {
+    this.selectedCapability = capability;
+  }
+
+  /**
+   * Create a bias calculation with automatic method detection
+   * Returns InferenceResult with both data and method metadata
+   */
+  async createBiasCalculation(
+    config: BiasTestConfig
+  ): Promise<InferenceResult<CrowsPairsBiasResult>> {
+    const { engine, model } = config;
+
+    this.validateConfiguration(config);
+
+    const inferenceClient = await this.getInferenceClient(engine, model);
+    let _detectedMethod: BiasCalculationMethod;
+
+    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
+   */
+  private async detectBestMethod(
+    client: BrowserInference | OllamaClient
+  ): Promise<BiasCalculationMethod> {
+    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: string): BrowserInference {
+    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: string): OllamaClient {
+    if (!this.ollamaClient || this.ollamaClient.model !== model) {
+      this.ollamaClient = new OllamaClient(model);
+    }
+    return this.ollamaClient;
+  }
+
+  private validateConfiguration(config: BiasTestConfig): void {
+    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})`
+      );
+    }
+  }
+
+  private async getInferenceClient(engine: "browser" | "ollama", model: string) {
+    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<T>(
+    data: T,
+    engine: "browser" | "ollama",
+    model: string,
+    client?: BrowserInference | OllamaClient
+  ): Promise<InferenceResult<T>> {
+    let method: BiasCalculationMethod;
+
+    // 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(): void {
+    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?: (status: string) => void
+): InferenceFactory {
+  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: BiasTestConfig
+): Promise<BiasCalculationMethod> {
+  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}`);
+}