@speedydb/core

Headless, on-device RAG core for the browser — the SpeedyDb wasm retrieval engine, the approved on-device embedder, an on-device RAG agent, and durable IndexedDB persistence — as a framework-agnostic package. Nothing leaves the device.

Status: Phase 1 complete (P0–P8). packages/core/src is the canonical home of the browser stack: typed exports (types/), the assetBase/vendorBase seam, the speedydb-copy-assets CLI with its integrity manifest, SSR-safe imports, version-lock CI, the staged static site, and (Phase 2) the React binding + component registry + starters. See docs/browser-components/phase-1-packaging.md.

Entry points

Import	What
`@speedydb/core`	barrel — `SpeedyDbClient` + the pure utilities (`chunkText`, `mergeSemantic`, `DEFAULTS`, …)
`@speedydb/core/engine`	the wasm-bindgen engine glue (`WasmBrowserDb`, `WasmDurableStaging`, `default` init)
`@speedydb/core/engine/wasm`	the raw `speedydb_bg.wasm` — resolve via `new URL(..., import.meta.url)`
`@speedydb/core/agent` · `/agent-worker`	on-device RAG agent host + its module worker
`@speedydb/core/embedder`	approved on-device embedder host (`nomic-embed-text-v1.5`, 768-dim)
`@speedydb/core/durable` · `/extract`	IndexedDB write-behind persistence · on-device PDF/docx→text
`@speedydb/core/react`	the React binding — `SpeedyDbProvider` + `useSpeedyDb()` via `useSyncExternalStore` (react is an optional peer; see `registry/react` for the copy-paste component kit)
`@speedydb/core/vue`	Vue 3 composable — `provideSpeedyDb` + `useSpeedyDb()` (shallowRef + markRaw; vue is an optional peer)
`@speedydb/core/svelte`	Svelte store — `createSpeedyDb()` (the store contract, synchronous first emit; svelte is an optional peer)
`@speedydb/core/solid`	Solid store — `createSpeedyDb()` → `[store, methods]` (createStore + reconcile; solid-js is an optional peer)
`@speedydb/core/angular`	Angular service — `SpeedyDbService` + `provideSpeedyDb()` (read-only signal, zoneless-ready; @angular/core is an optional peer)

SpeedyDbClient (from the barrel) orchestrates all of the above — warm() → ingest → loadSemantic() → search() / ask() — behind one subscribe() / getSnapshot() store. It is browser-only, but importing the barrel under Node/SSR never throws (all browser globals are read lazily), so SSR framework bindings stay clean.

The staging model (post-P8)

packages/core/src is the single source of truth for the browser stack. The live site's copies (site/*.js, site/pkg/, site/vendor/) are generated, committed artifacts staged by scripts/stage-site.mjs — committed because the static Cloudflare deploy serves the repo with no build step, generated because nobody may edit them (each staged module carries a DO-NOT-EDIT banner, and stage-site.mjs --check fails the test suite on any stale or hand-edited copy). Edit here, then re-run npm run stage-site.

Getting started in an app

# @speedydb/core is distributed from speedydb.org, not a public registry — npm takes a
# tarball URL directly. Pin the version: the URL is the version.
npm i https://speedydb.org/packages/speedydb-core-0.2.1.tgz
npx speedydb-copy-assets        # puts the runtime wasm in your public dir, prints assetBase

import { SpeedyDbClient } from "@speedydb/core";
const client = new SpeedyDbClient({ assetBase: "/speedydb/" }); // the printed base
await client.warm();            // engine up (durable-first, in-memory fallback)

See examples/vite-headless and examples/webpack-headless.

Using an AI coding assistant? Point it at the LLM-optimized integration guide — site/llms.txt in the SpeedyDBSite repo, served live at speedydb.org/llms.txt. It's a self-contained, copy-paste recipe (boot → ingest → search/ask) plus the full API, options, and hard rules.

Runtime assets & peer deps

The ~59 MB of runtime wasm (the engine bundle, the vendored ONNX Runtime, and the vendored wllama) ships inside the tarball — offline / air-gapped, no CDN, no postinstall. Model weights are never bundled (fetched from a CDN into the Cache API on first use).

Peer dependencies pin the runtimes the vendored bundles were built against: @huggingface/transformers 4.2.0 and @wllama/wllama 3.5.1 (the vendored wllama is the -compat build of that version). A later slice adds a CI check that locks these to the committed bytes.

@speedydb/core

Entry points

The staging model (post-P8)

Getting started in an app

Runtime assets & peer deps

License