@localmode/core

The core package contains all functions, interfaces, types, and utilities for building local-first AI applications. It has zero external dependencies — everything is implemented using native browser APIs.

Zero Dependencies

@localmode/core has no dependencies in its package.json. All functionality uses native Web APIs: IndexedDB, Web Crypto, Web Workers, BroadcastChannel, and more.

Installation

bash pnpm install @localmode/core

bash npm install @localmode/core

bash yarn add @localmode/core

Quick Start

Install Dependencies

pnpm install @localmode/core @localmode/transformers

Create an Embedding Model

import { transformers } from '@localmode/transformers';

const model = transformers.embedding('Xenova/all-MiniLM-L6-v2');

Generate Embeddings

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

const { embedding, usage } = await embed({
  model,
  value: 'Hello, world!',
});

Store and Search

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

const db = await createVectorDB({ name: 'docs', dimensions: 384 });

await db.add({ id: 'doc-1', vector: embedding, metadata: { text: 'Hello' } });

const results = await db.search(queryVector, { k: 5 });

Features

✅ Production Ready

These features are stable and ready for production use:

Feature	Description
Vector Database	HNSW index for fast approximate nearest neighbor search
Embeddings	`embed()`, `embedMany()`, `semanticSearch()` functions
Reranking	`rerank()` for improved RAG accuracy
RAG Utilities	Text chunking (recursive, markdown, code-aware)
Text Generation	`streamText()` with async iteration
Storage	IndexedDB persistence with memory fallback
Capabilities	WebGPU, IndexedDB, Workers detection
Security	Encryption, PII redaction
Middleware	Caching, logging, retry, validation

🚧 Coming Soon

Feature	Description
Classification	`classify()`, `classifyZeroShot()`
NER	`extractEntities()`
Audio	`transcribe()`, `synthesizeSpeech()`
Vision	Image classification, captioning, segmentation
Translation	`translate()`
Summarization	`summarize()`
OCR	`extractText()`
Document QA	`askDocument()`, `askTable()`

Architecture

LocalMode follows a function-first API design:

// ✅ Top-level functions (correct)
const { embedding } = await embed({ model, value: 'Hello' });

// ❌ Class methods (wrong)
const embedder = new Embedder(model);
await embedder.embed('Hello');

All functions accept a single options object and return structured results:

interface EmbedResult {
  embedding: Float32Array;
  usage: { tokens: number };
  response: { modelId: string; timestamp: Date };
}

Quick Reference

Embeddings

Generate embeddings, batch processing, semantic search.

Reranking

Improve RAG accuracy by reranking retrieved documents.

Vector Database

Create, query, and persist vector databases.

RAG

Chunking, ingestion, hybrid search.

Storage

IndexedDB, memory storage, persistence.

Middleware

Caching, logging, retry, validation.

Security

Encryption, PII redaction, key management.

Cross-Tab Sync

Locks and BroadcastChannel for multi-tab apps.

Events

Type-safe event system for reactive updates.

Testing

Mock utilities for testing LocalMode applications.

Core Exports

Embeddings

import {
  embed,
  embedMany,
  streamEmbedMany,
  semanticSearch,
  wrapEmbeddingModel,
} from '@localmode/core';

Vector Database

import {
  createVectorDB,
  createVectorDBWithWorker,
  HNSWIndex,
  cosineSimilarity,
  euclideanDistance,
  dotProduct,
} from '@localmode/core';

RAG Utilities

import {
  chunk,
  recursiveChunk,
  markdownChunk,
  codeChunk,
  ingest,
  createBM25,
  hybridFuse,
  reciprocalRankFusion,
} from '@localmode/core';

Text Generation

import { streamText, generateText } from '@localmode/core';

Classification

import {
  classify,
  classifyMany,
  classifyZeroShot,
  extractEntities,
  extractEntitiesMany,
  rerank,
} from '@localmode/core';

Storage

import {
  IndexedDBStorage,
  MemoryStorage,
  createStorage,
  getStorageQuota,
  requestPersistence,
  cleanup,
} from '@localmode/core';

Capabilities

import {
  detectCapabilities,
  isWebGPUSupported,
  isIndexedDBSupported,
  checkModelSupport,
  getRecommendedFallbacks,
} from '@localmode/core';

Middleware

import {
  wrapEmbeddingModel,
  wrapVectorDB,
  cachingMiddleware,
  loggingMiddleware,
  retryMiddleware,
  rateLimitMiddleware,
  validationMiddleware,
  piiRedactionMiddleware,
  encryptionMiddleware,
} from '@localmode/core';

Security

import { encrypt, decrypt, deriveKey, isCryptoSupported, redactPII } from '@localmode/core';

Cross-Tab Sync

import { createBroadcaster, createLockManager, isWebLocksSupported } from '@localmode/core';

Network

import {
  getNetworkStatus,
  onNetworkChange,
  isOnline,
  isOffline,
  waitForOnline,
} from '@localmode/core';

Events

import { createEventEmitter, globalEventBus } from '@localmode/core';

Errors

import {
  LocalModeError,
  EmbeddingError,
  ModelNotFoundError,
  StorageError,
  QuotaExceededError,
  ValidationError,
  formatErrorForUser,
} from '@localmode/core';

Testing Utilities

import {
  createMockEmbeddingModel,
  createMockStorage,
  createMockVectorDB,
  createTestVector,
  createSeededRandom,
} from '@localmode/core';

Type Definitions

All interfaces are exported for implementing custom providers:

import type {
  // Models
  EmbeddingModel,
  ClassificationModel,
  ZeroShotClassificationModel,
  NERModel,
  RerankerModel,
  LanguageModel,
  SpeechToTextModel,
  TextToSpeechModel,
  ImageClassificationModel,
  ImageCaptionModel,
  SegmentationModel,
  ObjectDetectionModel,
  TranslationModel,
  SummarizationModel,
  FillMaskModel,
  QuestionAnsweringModel,
  OCRModel,
  DocumentQAModel,

  // Storage
  Storage,
  StoredDocument,

  // Vector DB
  VectorDB,
  VectorDBConfig,
  SearchResult,

  // Middleware
  EmbeddingModelMiddleware,
  VectorDBMiddleware,
} from '@localmode/core';

Overview

Embeddings

Reranking

Vector Database

RAG

Storage

Middleware

Security

Cross-Tab Sync

Events

Testing

Embeddings

Vector Database

On this page