Differential Privacy

import { gaussianNoise, laplacianNoise, addNoise } from '@localmode/core';

// Gaussian noise: 384-dimensional, sigma = 0.1
const gNoise = gaussianNoise(384, 0.1);

// Laplacian noise: 384-dimensional, scale = 0.5
const lNoise = laplacianNoise(384, 0.5);

// Add noise to an embedding (element-wise addition)
const noisyEmbedding = addNoise(originalEmbedding, gNoise);

import { createPrivacyBudget } from '@localmode/core';

const budget = await createPrivacyBudget({
  maxEpsilon: 10.0,
  persistKey: 'my-app-budget',
  onExhausted: 'block',
});

// Consume epsilon manually or via middleware
budget.consume(1.0);
console.log(budget.remaining());   // 9.0
console.log(budget.consumed());    // 1.0
console.log(budget.isExhausted()); // false

// Reset when privacy period expires
budget.reset();

// Clean up persisted state
await budget.destroy();

// Session 1
const budget = await createPrivacyBudget({
  maxEpsilon: 10.0,
  persistKey: 'user-vectors',
});
budget.consume(3.0);
// Page closes — state is persisted

// Session 2
const budget2 = await createPrivacyBudget({
  maxEpsilon: 10.0,
  persistKey: 'user-vectors',
});
console.log(budget2.consumed());  // 3.0 (restored from IndexedDB)
console.log(budget2.remaining()); // 7.0

import { getSensitivity } from '@localmode/core';

getSensitivity('Xenova/bge-small-en-v1.5');  // 2.0
getSensitivity('Xenova/all-MiniLM-L6-v2');   // 2.0
getSensitivity('unknown-model');              // 2.0 (default for normalized models)

import { calibrateSensitivity } from '@localmode/core';

const sensitivity = await calibrateSensitivity(model);
console.log(`Empirical sensitivity: ${sensitivity}`);

// With custom samples
const sensitivity2 = await calibrateSensitivity(model, [
  'First sample text',
  'Second sample text',
  'Third very different text',
]);

// Auto-detect from the wrapped model's ID
const privateModel = wrapEmbeddingModel({
  model: transformers.embedding('Xenova/bge-small-en-v1.5'),
  middleware: dpEmbeddingMiddleware({ epsilon: 1.0 }), // sensitivity auto-resolved to 2.0
});

// Override with explicit sensitivity
const customModel = wrapEmbeddingModel({
  model: myCustomModel,
  middleware: dpEmbeddingMiddleware({
    epsilon: 1.0,
    sensitivity: 1.5, // Explicit value from your own calibration
  }),
});

import { randomizedResponse } from '@localmode/core';

// High epsilon = low privacy, high utility (true label almost always returned)
const label1 = randomizedResponse(
  'positive',                              // true label
  ['positive', 'negative', 'neutral'],     // all possible labels
  10.0                                     // epsilon
);
// label1 is almost certainly 'positive'

// Low epsilon = high privacy, low utility (label is nearly uniform random)
const label2 = randomizedResponse(
  'positive',
  ['positive', 'negative', 'neutral'],
  0.5
);
// label2 could be any of the three labels

import { dpClassificationMiddleware } from '@localmode/core';

const middleware = dpClassificationMiddleware({
  epsilon: 2.0,
  labels: ['positive', 'negative', 'neutral'],
});

import {
  wrapEmbeddingModel,
  composeEmbeddingMiddleware,
  piiRedactionMiddleware,
  dpEmbeddingMiddleware,
} from '@localmode/core';

const secureModel = wrapEmbeddingModel({
  model: baseModel,
  middleware: composeEmbeddingMiddleware([
    piiRedactionMiddleware({ patterns: ['email', 'phone', 'ssn'] }),
    dpEmbeddingMiddleware({ epsilon: 1.0 }),
  ]),
});

// Input text is PII-redacted, then the embedding has calibrated noise added
const { embedding } = await embed({
  model: secureModel,
  value: 'Patient John Doe, email john@example.com, diagnosed with...',
});

import {
  wrapEmbeddingModel,
  composeEmbeddingMiddleware,
  piiRedactionMiddleware,
  dpEmbeddingMiddleware,
  createPrivacyBudget,
  createVectorDB,
  embed,
} from '@localmode/core';
import { transformers } from '@localmode/transformers';

// 1. Create a privacy budget that persists across sessions
const budget = await createPrivacyBudget({
  maxEpsilon: 50.0,
  persistKey: 'patient-records',
  onExhausted: 'block',
});

// 2. Wrap the model with PII redaction + DP noise
const secureModel = wrapEmbeddingModel({
  model: transformers.embedding('Xenova/bge-small-en-v1.5'),
  middleware: composeEmbeddingMiddleware([
    piiRedactionMiddleware({ patterns: ['email', 'phone', 'ssn'] }),
    dpEmbeddingMiddleware({ epsilon: 1.0, mechanism: 'gaussian' }, budget),
  ]),
});

// 3. Create a vector database
const db = await createVectorDB({ name: 'records', dimensions: 384 });

// 4. Embed and store — budget is consumed automatically
const { embedding } = await embed({
  model: secureModel,
  value: 'Patient record: diagnosed with condition X',
});

await db.add({ id: 'rec-1', vector: embedding, metadata: { type: 'diagnosis' } });

console.log(`Budget remaining: ${budget.remaining()}`); // 49.0

import { PrivacyBudgetExhaustedError } from '@localmode/core';

try {
  budget.consume(1.0);
} catch (error) {
  if (error instanceof PrivacyBudgetExhaustedError) {
    console.log(error.code);            // 'PRIVACY_BUDGET_EXHAUSTED'
    console.log(error.maxEpsilon);      // Total budget
    console.log(error.consumedEpsilon); // Amount consumed before the failed call
    console.log(error.hint);            // Actionable guidance
  }
}