enigma-memory 0.1.17 → 0.1.22

package/packages/inference-runtime/src/model-router.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+
+export const ENIGMA_ROUTE_RECEIPT_SCHEMA = 'enigma.route_receipt.v1';
+const TRUST_LEVELS = new Set(['self-hosted', 'confidential-compute', 'external']);
+
+function requiredString(value, field, maxLength = 16_000) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  if (normalized.length > maxLength) throw new TypeError(`${field} exceeds ${maxLength} characters`);
+  return normalized;
+}
+
+
+function normalizeMessages(messages) {
+  if (!Array.isArray(messages) || !messages.length) throw new TypeError('messages must be a non-empty array');
+  return messages.map((message, index) => {
+    if (!message || typeof message !== 'object') throw new TypeError(`messages[${index}] must be an object`);
+    const role = String(message.role || '');
+    if (!['system', 'user', 'assistant', 'tool'].includes(role)) throw new TypeError(`messages[${index}].role is invalid`);
+    if (typeof message.content !== 'string' && !Array.isArray(message.content)) throw new TypeError(`messages[${index}].content is invalid`);
+
+    return { ...message, role };
+  });
+}
+function normalizeRetentionEvidence(value) {
+  if (!value || typeof value !== 'object') return null;
+  const type = String(value.type || '').slice(0, 64);
+  const reference = String(value.reference || '').slice(0, 512);
+  if (!type || !reference) return null;
+  return Object.freeze({
+    type,
+    reference,
+    ...(value.verifiedAt ? { verifiedAt: String(value.verifiedAt).slice(0, 64) } : {}),
+  });
+}
+
+function normalizeModel(model, provider) {
+  const id = requiredString(model.id, 'model id', 160);
+  return Object.freeze({
+    id,
+    label: String(model.label || id),
+    providerModel: String(model.providerModel || model.provider_model || id),
+    provider: provider.id,
+    trust: provider.trust,
+    retentionPolicy: String(model.retentionPolicy || model.retention_policy || provider.retentionPolicy || 'unknown'),
+    retentionEvidence: normalizeRetentionEvidence(model.retentionEvidence || model.retention_evidence || provider.retentionEvidence),
+    contextWindow: Number.isInteger(model.contextWindow) ? model.contextWindow : 128_000,
+    inputPrice: Number(model.inputPrice || 0),
+    outputPrice: Number(model.outputPrice || 0),
+    latencyClass: model.latencyClass || 'standard',
+    quality: Number.isFinite(model.quality) ? model.quality : 0.7,
+    capabilities: Object.freeze([...new Set(model.capabilities || [])]),
+    inputModalities: Object.freeze([...new Set(model.inputModalities || ['text'])]),
+    tags: Object.freeze([...new Set(model.tags || [])]),
+  });
+}
+
+function modelPublic(model) {
+  return {
+    id: model.id,
+    object: 'model',
+    owned_by: model.provider,
+    label: model.label,
+    trust: model.trust,
+    retention_policy: model.retentionPolicy,
+    retention_evidence: model.retentionEvidence,
+    context_window: model.contextWindow,
+    capabilities: model.capabilities,
+    input_modalities: model.inputModalities,
+    pricing: { input_per_million_tokens: model.inputPrice, output_per_million_tokens: model.outputPrice },
+  };
+}
+
+function taskProfile(messages, options = {}) {
+  const text = messages.map((message) => typeof message.content === 'string' ? message.content : JSON.stringify(message.content)).join('\n').toLowerCase();
+  const estimatedTokens = Math.ceil(text.length / 3.6);
+  const code = /\b(code|repository|repo|debug|function|typescript|javascript|python|rust|compile|test|implementation)\b/.test(text);
+  const current = /\b(today|current|latest|news|weather|price|search|look up|browse|source)\b/.test(text);
+  const reasoning = /\b(prove|derive|analyze|audit|compare|investigate|architecture|security|strategy|reasoning)\b/.test(text);
+  const highRisk = /\b(secret|credential|private key|wallet|payment|medical|legal|identity|personal|confidential)\b/.test(text);
+  const vision = messages.some((message) => Array.isArray(message.content) && message.content.some((part) => /image/.test(part?.type || '')));
+  return {
+    task: code ? 'code' : current ? 'current' : reasoning ? 'reasoning' : 'general',
+    estimatedTokens,
+    needsWeb: options.webSearch === true || current,
+    needsVision: vision,
+    highRisk,
+  };
+}
+
+function routeScore(model, profile, health, options) {
+  if (health.openUntil > Date.now()) return -Infinity;
+  if (profile.estimatedTokens > model.contextWindow) return -Infinity;
+  if (profile.needsVision && !model.capabilities.includes('vision')) return -Infinity;
+  if (profile.needsWeb && !model.capabilities.includes('web-search')) return -Infinity;
+  if (profile.task === 'code' && !model.capabilities.includes('code')) return -Infinity;
+  let score = model.quality * 100;
+  if (model.trust === 'self-hosted') score += profile.highRisk ? 50 : 8;
+  if (model.trust === 'confidential-compute') score += profile.highRisk ? 35 : 5;
+  if (profile.task === 'reasoning' && model.capabilities.includes('reasoning')) score += 20;
+  if (profile.task === 'code' && model.tags.includes('code-specialist')) score += 20;
+  if (model.latencyClass === 'fast') score += options.preferLatency ? 18 : 6;
+  const price = model.inputPrice + model.outputPrice;
+  score -= Math.log10(1 + Math.max(0, price)) * (options.preferCost === false ? 2 : 8);
+  score -= health.failureCount * 10;
+  score -= health.emaLatencyMs / 10_000;
+  return score;
+}
+
+async function parseOpenAIStream(response, callbacks = {}) {
+  if (!response.body) throw new Error('model provider returned no stream body');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let answer = '';
+  let thinking = '';
+  let usage = null;
+  let finishReason = null;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const parts = buffer.split('\n\n');
+    buffer = parts.pop() || '';
+    for (const part of parts) processPart(part);
+  }
+  if (buffer.trim()) processPart(buffer);
+  return { answer, thinking: thinking || null, usage, finishReason, streamed: true };
+
+  function processPart(part) {
+    const values = part.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim());
+    if (!values.length || values[0] === '[DONE]') return;
+    let frame;
+    try { frame = JSON.parse(values.join('\n')); } catch { return; }
+    if (frame.error) throw new Error(frame.error.message || frame.error);
+    if (frame.usage) { usage = frame.usage; callbacks.onEvent?.({ type: 'usage', usage }); }
+    for (const choice of frame.choices || []) {
+      const delta = choice.delta || {};
+      const reasoning = delta.reasoning_content || delta.reasoning || delta.thinking || '';
+      if (reasoning) { thinking += reasoning; callbacks.onEvent?.({ type: 'thinking', delta: reasoning }); }
+      if (typeof delta.content === 'string' && delta.content) {
+        answer += delta.content;
+        callbacks.onEvent?.({ type: 'delta', delta: delta.content });
+      }
+      if (choice.finish_reason) finishReason = choice.finish_reason;
+    }
+  }
+}
+
+export function createOpenAICompatibleProvider(options = {}) {
+  const id = requiredString(options.id, 'provider id', 160);
+  const trust = String(options.trust || 'external');
+  if (!TRUST_LEVELS.has(trust)) throw new TypeError('provider trust must be self-hosted, confidential-compute, or external');
+  const baseUrl = new URL(requiredString(options.baseUrl, 'provider baseUrl', 4_096));
+  const apiKey = options.apiKey ? requiredString(options.apiKey, 'provider apiKey', 4_096) : null;
+  if (!apiKey && options.auth !== 'none') throw new TypeError(`provider ${id} requires apiKey`);
+  const retentionPolicy = String(options.retentionPolicy || 'unknown');
+  const retentionEvidence = normalizeRetentionEvidence(options.retentionEvidence);
+  if (retentionPolicy === 'none' && !retentionEvidence) {
+    throw new TypeError(`provider ${id} requires retentionEvidence before claiming zero retention`);
+  }
+  const provider = { id, trust, retentionPolicy, retentionEvidence };
+  const models = (options.models || []).map((model) => normalizeModel(typeof model === 'string' ? { id: model } : model, provider));
+  if (!models.length) throw new TypeError(`provider ${id} requires models`);
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : 120_000;
+  return Object.freeze({
+    id,
+    trust,
+    models: Object.freeze(models),
+    async complete(request, callbacks = {}) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error(`provider ${id} timed out`)), timeoutMs);
+      const signal = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
+      try {
+        const response = await fetch(new URL('chat/completions', baseUrl), {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            ...(options.headers || {}),
+          },
+          body: JSON.stringify({
+            model: request.model.providerModel,
+            messages: request.messages,
+            temperature: request.temperature,
+            max_tokens: request.maxTokens,
+            stream: request.stream === true,
+            ...(request.reasoningEffort ? { reasoning_effort: request.reasoningEffort } : {}),
+            ...(request.tools ? { tools: request.tools } : {}),
+          }),
+          signal,
+        });
+        if (!response.ok) {
+          const body = await response.text();
+          throw new Error(`provider ${id} failed with HTTP ${response.status}: ${body.slice(0, 500)}`);
+        }
+        if (request.stream === true) return parseOpenAIStream(response, callbacks);
+        const payload = await response.json();
+        const choice = payload.choices?.[0] || {};
+        const answer = choice.message?.content;
+        if (typeof answer !== 'string') throw new Error(`provider ${id} returned no text answer`);
+        return {
+          answer,
+          thinking: choice.message?.reasoning_content || null,
+          usage: payload.usage || null,
+          finishReason: choice.finish_reason || null,
+          providerRequestId: response.headers.get('x-request-id'),
+        };
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  });
+}
+
+export function createModelRouter(options = {}) {
+  const providers = new Map();
+  const models = new Map();
+  const health = new Map();
+  for (const provider of options.providers || []) {
+    if (!provider || typeof provider.complete !== 'function') throw new TypeError('model provider requires complete()');
+    if (providers.has(provider.id)) throw new TypeError(`duplicate model provider: ${provider.id}`);
+    providers.set(provider.id, provider);
+    for (const model of provider.models || []) {
+      if (models.has(model.id)) throw new TypeError(`duplicate model id: ${model.id}`);
+      models.set(model.id, { ...model, providerRef: provider });
+      health.set(model.id, { failureCount: 0, emaLatencyMs: 0, openUntil: 0 });
+    }
+  }
+  if (!models.size) throw new TypeError('model router requires at least one model');
+  const autoModelId = options.autoModelId || 'enigma-auto';
+  const circuitFailures = Number.isInteger(options.circuitFailures) ? options.circuitFailures : 3;
+  const circuitCooldownMs = Number.isInteger(options.circuitCooldownMs) ? options.circuitCooldownMs : 30_000;
+
+  async function select(request) {
+    const messages = normalizeMessages(request.messages);
+    const baseProfile = taskProfile(messages, request);
+    const semanticProfile = options.classifier ? await options.classifier.classify({ messages, profile: baseProfile }) : {};
+    const profile = { ...baseProfile, ...(semanticProfile || {}) };
+    const requestedModel = request.model || autoModelId;
+    if (requestedModel !== autoModelId) {
+      const model = models.get(requestedModel);
+      if (!model) throw new Error(`unknown model: ${requestedModel}`);
+      if (request.requirePrivateRoute && model.trust === 'external') throw new Error(`model ${requestedModel} is not an approved private route`);
+      if (request.safeForExternal === false && model.trust === 'external') throw new Error(`Smart Privacy did not clear model ${requestedModel} for external routing`);
+      return { model, profile, reason: 'explicit model selection' };
+    }
+    const candidates = [...models.values()].filter((model) => {
+      if (request.requirePrivateRoute && model.trust === 'external') return false;
+      if (request.safeForExternal === false && model.trust === 'external') return false;
+      return true;
+    });
+    const scored = candidates.map((model) => ({ model, score: routeScore(model, profile, health.get(model.id), request) }))
+      .filter(({ score }) => Number.isFinite(score)).sort((a, b) => b.score - a.score || a.model.id.localeCompare(b.model.id));
+    if (!scored.length) throw new Error('no healthy model satisfies this request and privacy policy');
+    return { model: scored[0].model, profile, reason: `auto route selected for ${profile.task}` };
+  }
+
+  return Object.freeze({
+    autoModelId,
+    listModels() {
+      return [{ id: autoModelId, object: 'model', owned_by: 'enigma', label: 'Enigma Auto', trust: 'policy-routed' }, ...[...models.values()].map(modelPublic)];
+    },
+    async route(request = {}, callbacks = {}) {
+      const selection = await select(request);
+      callbacks.onEvent?.({ type: 'route', model: selection.model.id, provider: selection.model.provider, reason: selection.reason, trust: selection.model.trust, retentionPolicy: selection.model.retentionPolicy });
+      return selection;
+    },
+    async complete(request = {}, callbacks = {}) {
+      const selection = await select(request);
+      const { model } = selection;
+      callbacks.onEvent?.({ type: 'route', model: model.id, provider: model.provider, reason: selection.reason, trust: model.trust, retentionPolicy: model.retentionPolicy });
+      const startedAt = Date.now();
+      try {
+        const result = await model.providerRef.complete({
+          ...request,
+          messages: normalizeMessages(request.messages),
+          model,
+          temperature: Number.isFinite(request.temperature) ? Math.max(0, Math.min(2, request.temperature)) : 0.7,
+          maxTokens: Number.isInteger(request.maxTokens) ? Math.max(1, Math.min(request.maxTokens, 131_072)) : 2_048,
+        }, callbacks);
+        const elapsedMs = Date.now() - startedAt;
+        const state = health.get(model.id);
+        state.failureCount = 0;
+        state.openUntil = 0;
+        state.emaLatencyMs = state.emaLatencyMs ? state.emaLatencyMs * 0.8 + elapsedMs * 0.2 : elapsedMs;
+        return {
+          ...result,
+          route: {
+            model: model.id,
+            provider: model.provider,
+            trust: model.trust,
+            retentionPolicy: model.retentionPolicy || 'unknown',
+            retentionEvidence: model.retentionEvidence || null,
+            reason: selection.reason,
+            profile: selection.profile,
+          },
+          receipt: {
+            schema: ENIGMA_ROUTE_RECEIPT_SCHEMA,
+            model: model.id,
+            provider: model.provider,
+            trust: model.trust,
+            retentionPolicy: model.retentionPolicy || 'unknown',
+            retentionEvidence: model.retentionEvidence || null,
+            receiptId: randomUUID(),
+            elapsedMs,
+          },
+        };
+      } catch (error) {
+        const state = health.get(model.id);
+        state.failureCount += 1;
+        if (state.failureCount >= circuitFailures) state.openUntil = Date.now() + circuitCooldownMs;
+        throw error;
+      }
+    },
+    health() {
+      return [...health].map(([model, state]) => ({ model, ...state, available: state.openUntil <= Date.now() }));
+    },
+  });
+}

package/packages/inference-runtime/src/platform.js

@@ -0,0 +1,125 @@
+import { createChatBackend } from './chat.js';
+import { createCodeSandboxRuntime } from './code.js';
+import { createImageBackend, createOpenAIImageProvider } from './image.js';
+import { createModelRouter, createOpenAICompatibleProvider } from './model-router.js';
+import { createLocalEmbeddingSemanticClassifier, createSemanticPrivacyEngine } from './privacy.js';
+import { createHttpVideoProvider, createVideoBackend } from './video.js';
+import { createDisposableBrowserRuntime, createEgressAttestationVerifier, createRemoteBrowserBrokerProvider } from './browser.js';
+
+function parseJsonEnvironment(environment, name, fallback) {
+  const raw = environment[name];
+  if (!raw) return fallback;
+  try { return JSON.parse(raw); }
+  catch { throw new Error(`${name} must contain valid JSON`); }
+}
+
+function configuredApiKey(config, environment) {
+  if (config.apiKey !== undefined) throw new Error(`provider ${config.id || 'unknown'} must reference apiKeyEnv instead of embedding a key in configuration`);
+  const name = String(config.apiKeyEnv || '');
+  if (!name) return null;
+  const value = environment[name];
+  if (!value) throw new Error(`provider ${config.id || 'unknown'} requires environment variable ${name}`);
+  return value;
+}
+
+function createTextProviders(configs, environment) {
+  return configs.map((config) => createOpenAICompatibleProvider({
+    id: config.id,
+    baseUrl: config.baseUrl,
+    apiKey: configuredApiKey(config, environment),
+    auth: config.auth,
+    trust: config.trust,
+    retentionPolicy: config.retentionPolicy,
+    retentionEvidence: config.retentionEvidence,
+    models: config.models,
+    headers: config.headers,
+    timeoutMs: config.timeoutMs,
+  }));
+}
+
+function createImageProviders(configs, environment) {
+  return configs.map((config) => createOpenAIImageProvider({
+    id: config.id,
+    baseUrl: config.baseUrl,
+    apiKey: configuredApiKey(config, environment),
+    models: config.models,
+  }));
+}
+
+function createVideoProviders(configs, environment) {
+  return configs.map((config) => createHttpVideoProvider({
+    id: config.id,
+    baseUrl: config.baseUrl,
+    apiKey: configuredApiKey(config, environment),
+    models: config.models,
+    queuePath: config.queuePath,
+    retrievePath: config.retrievePath,
+    cancelPath: config.cancelPath,
+    headers: config.headers,
+  }));
+}
+
+export function createPlatformRuntime(options = {}) {
+  const textProviders = options.textProviders || [];
+  const imageProviders = options.imageProviders || [];
+  const videoProviders = options.videoProviders || [];
+  const privacyClassifier = options.privacyClassifier || createLocalEmbeddingSemanticClassifier(options.privacyClassifierOptions);
+  const privacy = options.privacy || createSemanticPrivacyEngine({ classifier: privacyClassifier, ...(options.privacyOptions || {}) });
+  const router = options.router || (textProviders.length ? createModelRouter({ providers: textProviders, ...(options.routerOptions || {}) }) : null);
+  const usage = options.usage || null;
+  const chat = options.chat || (router ? createChatBackend({ router, privacy, onUsage: usage ? (entry) => usage.record(entry) : undefined }) : null);
+  const images = options.images || (imageProviders.length ? createImageBackend({ providers: imageProviders, onUsage: usage ? (entry) => usage.record(entry) : undefined }) : null);
+  const videos = options.videos || (videoProviders.length ? createVideoBackend({ providers: videoProviders, onUsage: usage ? (entry) => usage.record(entry) : undefined }) : null);
+  const code = options.code === false ? null : options.code || createCodeSandboxRuntime({ oci: options.oci });
+  const browser = options.browser || null;
+
+  return Object.freeze({
+    chat,
+    images,
+    videos,
+    code,
+    browser,
+    async close() {
+      const settled = await Promise.allSettled([
+        browser?.close?.(),
+        code?.close?.(),
+        privacyClassifier?.dispose?.(),
+      ]);
+      const errors = settled.filter((result) => result.status === 'rejected').map((result) => result.reason);
+      if (errors.length) throw new AggregateError(errors, 'platform runtime cleanup failed');
+    },
+  });
+}
+
+export function createEnvironmentPlatformRuntime(options = {}) {
+  const environment = options.environment || process.env;
+  const textConfigs = parseJsonEnvironment(environment, 'ENIGMA_MODEL_PROVIDERS_JSON', []);
+  const imageConfigs = parseJsonEnvironment(environment, 'ENIGMA_IMAGE_PROVIDERS_JSON', []);
+  const videoConfigs = parseJsonEnvironment(environment, 'ENIGMA_VIDEO_PROVIDERS_JSON', []);
+  if (!Array.isArray(textConfigs) || !Array.isArray(imageConfigs) || !Array.isArray(videoConfigs)) {
+    throw new Error('Enigma provider configuration values must be JSON arrays');
+  }
+  let browser = null;
+  if (environment.ENIGMA_BROWSER_BROKER_URL) {
+    if (!environment.ENIGMA_BROWSER_EGRESS_PUBLIC_KEY || !environment.ENIGMA_BROWSER_VIEWER_ORIGIN) {
+      throw new Error('ENIGMA_BROWSER_EGRESS_PUBLIC_KEY and ENIGMA_BROWSER_VIEWER_ORIGIN are required before interactive browser streaming can be enabled');
+    }
+    const provider = createRemoteBrowserBrokerProvider({
+      baseUrl: environment.ENIGMA_BROWSER_BROKER_URL,
+      viewerOrigin: environment.ENIGMA_BROWSER_VIEWER_ORIGIN,
+      apiKey: environment.ENIGMA_BROWSER_BROKER_API_KEY || null,
+    });
+    browser = createDisposableBrowserRuntime({
+      provider,
+      viewerOrigin: environment.ENIGMA_BROWSER_VIEWER_ORIGIN,
+      verifyEgressAttestation: createEgressAttestationVerifier({ publicKey: environment.ENIGMA_BROWSER_EGRESS_PUBLIC_KEY }),
+    });
+  }
+  return createPlatformRuntime({
+    ...options,
+    textProviders: options.textProviders || createTextProviders(textConfigs, environment),
+    imageProviders: options.imageProviders || createImageProviders(imageConfigs, environment),
+    videoProviders: options.videoProviders || createVideoProviders(videoConfigs, environment),
+    browser,
+  });
+}