{"_id":"@aicacia/local-embeddings","name":"@aicacia/local-embeddings","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aicacia/local-embeddings","version":"0.1.0","description":"local embeddings library","repository":{"type":"git","url":"git+https://github.com/aicacia/ts-local-embeddings.git"},"type":"module","module":"esm/index.js","main":"esm/index.js","types":"types/index.d.ts","keywords":["local","wasm","embeddings","browser","similarity","search","vector","database"],"author":{"name":"Nathan Faucett"},"license":"(MIT OR Apache-2.0)","devDependencies":{"@biomejs/biome":"^1.9.4","@rollup/plugin-commonjs":"^28.0.9","@rollup/plugin-node-resolve":"^15.3.1","@rollup/plugin-terser":"^0.4.4","@types/tape":"^5.8.1","c8":"^11.0.0","fake-indexeddb":"^6.2.5","husky":"^9.1.7","nyc":"^17.1.0","rollup":"^4.60.1","rollup-plugin-esm-import-to-url":"^2.1.0","tap-nyc":"^1.0.3","tap-spec":"^5.0.0","tape":"^5.9.0","ts-node":"^10.9.2","tslib":"^2.8.1","typedoc":"^0.28.18","typescript":"^5.9.3"},"peerDependencies":{"tslib":"2"},"dependencies":{"@huggingface/transformers":"^4.0.1","@langchain/core":"^1.1.39"},"nyc":{"include":["src"],"exclude":["src/**/*.test.*","src/**/*.benchmark.*"],"extension":[".ts",".tsx"]},"scripts":{"tape:runner":"node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' node_modules/tape/bin/tape","buildTS":"tsc -p tsconfig.json","buildBrowser":"rollup -c","build:docs":"typedoc","build":"pnpm run clean && pnpm run buildTS && pnpm run buildBrowser","doc":"pnpm run build:docs","test":"pnpm run -s tape:runner -- src/**/*.test.{ts,tsx} | pnpm exec tap-spec","bench":"pnpm run -s tape:runner -- src/**/*.benchmark.{ts,tsx} | pnpm exec tap-spec","coverage":"c8 --check-coverage --lines 75 --reporter=lcov --reporter=text pnpm run -s tape:runner -- src/**/*.test.{ts,tsx} | pnpm exec tap-spec","coverageHTML":"c8 --check-coverage --lines 75 --reporter=lcov --reporter=html pnpm run -s tape:runner -- src/**/*.test.{ts,tsx} | pnpm exec tap-spec","clean":"rm -rf esm browser types .nyc_output coverage","lint":"biome lint ./src","format":"biome format --write .","format:check":"biome format .","ci:lint":"pnpm -r lint","ci:format":"pnpm -r format","ci:format:check":"pnpm -r format:check","github-pages:dev":"pnpm --filter @aicacia/local-embeddings-github-pages dev","preCommit":"pnpm run ci:format && pnpm run ci:lint && pnpm run coverage"},"_id":"@aicacia/local-embeddings@0.1.0","bugs":{"url":"https://github.com/aicacia/ts-local-embeddings/issues"},"homepage":"https://github.com/aicacia/ts-local-embeddings#readme","_integrity":"sha512-iVAcALPab7N1zqL4k+8FHXHPXDu/fIKiWtJxkc8IH7lN4T3/kXUSkSUJMAHhjZvxSnBS0gktUZD/oHjM3l8jag==","_resolved":"/tmp/1565c846fd74ae9c1dc494664a173d73/aicacia-local-embeddings-0.1.0.tgz","_from":"file:aicacia-local-embeddings-0.1.0.tgz","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-iVAcALPab7N1zqL4k+8FHXHPXDu/fIKiWtJxkc8IH7lN4T3/kXUSkSUJMAHhjZvxSnBS0gktUZD/oHjM3l8jag==","shasum":"b802de20941149ba3f3e403868144b7f3481397b","tarball":"https://registry.npmjs.org/@aicacia/local-embeddings/-/local-embeddings-0.1.0.tgz","fileCount":36,"unpackedSize":2975196,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEjjlOrQ8z4ZJV5RgBrMsaF7efCQqSrOX5GowBD7Il33AiA8ptAonhHTmzFJxqBEPLsEz7Ytd3gfun5RDYTLPV1FBQ=="}]},"_npmUser":{"name":"nathanfaucett","email":"nathanfaucett@gmail.com"},"directories":{},"maintainers":[{"name":"nathanfaucett","email":"nathanfaucett@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/local-embeddings_0.1.0_1775991668311_0.8100162557461348"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T11:01:08.133Z","0.1.0":"2026-04-12T11:01:08.557Z","modified":"2026-04-12T11:01:08.852Z"},"maintainers":[{"name":"nathanfaucett","email":"nathanfaucett@gmail.com"}],"description":"local embeddings library","homepage":"https://github.com/aicacia/ts-local-embeddings#readme","keywords":["local","wasm","embeddings","browser","similarity","search","vector","database"],"repository":{"type":"git","url":"git+https://github.com/aicacia/ts-local-embeddings.git"},"author":{"name":"Nathan Faucett"},"bugs":{"url":"https://github.com/aicacia/ts-local-embeddings/issues"},"license":"(MIT OR Apache-2.0)","readme":"# ts-local-embeddings\n\n[![license](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)](LICENSE-MIT)\n[![docs](https://img.shields.io/badge/docs-typescript-blue.svg)](https://aicacia.github.io/ts-local-embeddings/docs/)\n[![npm (scoped)](https://img.shields.io/npm/v/@aicacia/local-embeddings)](https://www.npmjs.com/package/@aicacia/local-embeddings)\n[![build](https://github.com/aicacia/ts-local-embeddings/workflows/Test/badge.svg)](https://github.com/aicacia/ts-local-embeddings/actions?query=workflow%3ATest)\n\nBrowser-first local embedding utilities for:\n\n- Loading a local ONNX embedding model with fallbacks\n- Embedding documents in-process or via Web Worker\n- Storing vectors in IndexedDB with similarity search and MMR\n\n## Documentation\n\nHosted API docs: https://aicacia.github.io/ts-local-embeddings/docs/\n\n## Install\n\n```bash\npnpm add @aicacia/local-embeddings @huggingface/transformers @langchain/core\n```\n\n## Quick start (Web Worker + IndexedDB)\n\n```ts\nimport { IndexedDBVectorStore, WorkerEmbeddings } from '@aicacia/local-embeddings';\nimport { Document } from '@langchain/core/documents';\n\nconst embeddings = new WorkerEmbeddings({\n\truntime: {\n\t\tmodelPath: '/models/'\n\t}\n});\n\nconst store = new IndexedDBVectorStore(embeddings);\n\nawait store.addDocuments([\n\tnew Document({ pageContent: 'TypeScript is strongly typed JavaScript' }),\n\tnew Document({ pageContent: 'Transformers can run in the browser with ONNX' })\n]);\n\nconst matches = await store.similaritySearchWithScore('browser embeddings', 3);\nconsole.log(matches);\n```\n\nWhen finished, terminate worker resources:\n\n```ts\nembeddings.terminate();\n```\n\n## Runtime options\n\n`loadEmbeddingRuntime` and `WorkerEmbeddings` runtime options support:\n\n- `modelId`: model repo id (default: `onnx-community/embeddinggemma-300m-ONNX`)\n- `modelFallbacks`: preferred `dtype` / file fallback order\n- `allowRemoteModels`: when `false`, require local files only\n- `modelPath`: path passed to transformers as `cache_dir`; in browser apps this is typically a served model base path like `'/models/'` or `'/my-base/models/'`\n\n`WorkerEmbeddings` also supports:\n\n- `onProgress`: callback fired during `embedDocuments` batching with `processedAfterBatch` and `totalDocuments` values for UI progress indicators.\n\nTo enable internal debug logs while diagnosing runtime/model loading issues, set:\n\n```ts\n(globalThis as { __LOCAL_EMBEDDINGS_DEBUG__?: boolean }).__LOCAL_EMBEDDINGS_DEBUG__ = true;\n```\n\nExample `modelFallbacks`:\n\n```ts\nconst embeddings = new WorkerEmbeddings({\n\truntime: {\n\t\tmodelFallbacks: [\n\t\t\t{ dtype: 'q4', model_file_name: 'model_no_gather' },\n\t\t\t{ dtype: 'q4' },\n\t\t\t{ dtype: 'fp16' }\n\t\t]\n\t}\n});\n```\n\n## Architecture\n\nThe library now uses deep internal boundary modules while keeping the public API unchanged:\n\n- `embeddingPipeline`: owns token limit resolution, adaptive batching, tokenizer/model invocation compatibility, and embedding output validation.\n- `workerChannel`: owns worker request ids, pending promise lifecycle, timeout handling, and failure fan-out semantics.\n- `vectorWritePipeline`: owns write-path dedup policy, cache reuse, deterministic guard behavior, and record mapping.\n- `indexedDbStoreGateway`: owns IndexedDB lifecycle/open-upgrade flow, schema checks, and low-level read/write/query operations.\n- `runtimePolicy` + `runtimeLoader`: separates fallback-selection policy from the Hugging Face runtime adapter.\n\n## Local model files\n\nIf you run fully local, host model assets under your configured `modelPath`, typically:\n\n```text\n<public-or-static-root>/models/onnx-community/<model-id>/onnx/*\n```\n\nFor SvelteKit, files in `static/` are served at the app base path.\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm lint\npnpm coverage\npnpm github-pages:dev\n```\n","readmeFilename":"README.md","_rev":"1-9677472aa22df8ac439847975ba736fb"}