{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/adapter-embeddings",
  "slug": "adapters/adapter-embeddings",
  "kind": "capabilities",
  "bucket": "package",
  "title": "@leumas/adapter-embeddings",
  "name": "@leumas/adapter-embeddings",
  "eyebrow": null,
  "chip": null,
  "summary": "Deterministic local embedding capability pack — hash-bucket / TF-weighted 128-dim vectors for text, JSON, CSV, HTML, Markdown, code, email, YAML, signals, and files/folders. Pure JS, no ML runtime...",
  "keywords": [
    "adapter-embeddings",
    "yaml",
    "hash-bucket",
    "tf-weighted",
    "embedding",
    "adapter embeddings api",
    "leumas adapter embeddings",
    "128-dim"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# @leumas/adapter-embeddings\n\nDeterministic local embedding pack, ported from `tools/a.embeddings`. Pure JS hash-bucket /\nTF-weighted vectors (default 128-dim) — **no ML models, no external APIs, no keys**: the same\ninput always produces the exact same vector, so vectors are comparable across machines and time.\n\nFollows the standard adapter contract (`export default { metadata, adapters }`), loaded by\n`shared/engines/middleware`'s registry and callable via `/api/adapters`, MCP, and chatbot\nfunctioncalls. Every tool takes ONE args object.\n\n## Tools\n\nContent → vector (`{ vector, dims }`):\n\n| Tool | Args | Notes |\n|---|---|---|\n| `embedText` | `{ text, options? }` | Tokenize + bigrams, TF-weighted (stop words down-weighted), hashed into 128 buckets, L2-normalized. |\n| `embedJson` | `{ json }` | Object/array or JSON string; flattened keys hashed into buckets. |\n| `embedCsv` | `{ csv, options? }` | Each row embedded as text, summed, normalized. |\n| `embedHtml` | `{ html }` or `{ path }` | Tags/scripts/styles stripped, then text-embedded. |\n| `embedMarkdown` | `{ markdown }` or `{ path }` | Returns `{ sections: [{ type, content, vector }], count }` — one vector per heading/code/text section. |\n| `embedCode` | `{ code }`, `{ path }` file, or `{ path }` folder | Comments stripped, then text-embedded. Folder path embeds every code file (`filters`, `maxFiles`). |\n| `embedEmail` | `{ eml }` or `{ path }` | Minimal pure `.eml` parse (subject/from/to/body), then text-embedded. |\n| `embedYaml` | `{ yaml }` or `{ path }` | Parsed with js-yaml, JSON-stringified, then text-embedded. |\n| `embedTimeSeries` | `{ series, options? }` | Statistical feature vector (mean/std/min/max/median/first/last/length). |\n| `embedObjectArray` | `{ items, options? }` | One aggregated vector for the whole array. |\n| `embedJsonIndex` | `{ items }` or `{ path }` | One vector **per item** — `{ vectors, count }`. |\n| `embedEeg` | `{ signal }` | First 64 samples → 64-dim normalized vector. |\n| `embedAudio` | `{ samples }` | DFT magnitude spectrum of first 1024 samples. |\n\nFilesystem (path-taking, like a-file-actions):\n\n| Tool | Args | Notes |\n|---|---|---|\n| `embedImage` | `{ path }` | Size + byte-hash fingerprint vector (rudimentary, no ML). |\n| `embedFile` | `{ path, options? }` | Extension-dispatched: json/csv/yaml/html/eml/code/image/text; unknown binaries get a stat-metadata fingerprint. Returns `{ file, kind, vector, dims }`. |\n| `embedFolder` | `{ path, filters?, maxFiles? }` | Recursive walk (skips node_modules/dist/.git/build), embeds every file. Returns `{ folder, results, count, truncated }`. |\n| `embedMatchingFolders` | `{ path, folders, maxFiles? }` | Finds folders by name under `path`, embeds their immediate files. |\n\nPrimitives:\n\n| Tool | Args | Notes |\n|---|---|---|\n| `tokenize` | `{ text, ngrams? }` | Lowercase alphanumeric tokens (+ optional n-grams). |\n| `normalizeVector` | `{ vector }` | L2 normalization. |\n| `cosineSimilarity` | `{ a, b }` | Two same-length numeric vectors → `{ similarity }`. |\n| `compare` | `{ a, b }` | Embeds two **texts** and returns their cosine similarity (identical texts → 1). |\n| `reduceTo3d` | `{ vector }` | First-3-dims reduction for quick 3D visualization. |\n\n## Usage\n\n```js\nconst { default: embeddings } = await import('@leumas/adapter-embeddings');\n\nconst { vector } = await embeddings.adapters.embedText({ text: 'hello world' });\nconst { similarity } = await embeddings.adapters.compare({ a: 'the cat sat', b: 'a cat sat' });\nconst { results } = await embeddings.adapters.embedFolder({ path: 'C:/docs', filters: ['.md'] });\n```\n\n## DRY boundary\n\n- **No generic vector math here.** `dot`, `l2Norm`, add/scale, etc. belong to\n  a-transformation's `vector.*` tools. This pack only exposes the embedding-workflow\n  primitives `cosineSimilarity` and `normalizeVector`.\n- **Deterministic by design.** No ML runtime, no API keys, no network. For semantic-quality\n  embeddings, use a model-backed service; this pack is for cheap, reproducible, offline\n  similarity/fingerprinting.\n- Dropped from the source: `pdfAdapter` (pdf-parse) and `spreadsheetAdapter` (xlsx) — heavy\n  undeclared deps; `mailparser` replaced with a pure `.eml` parser. Only dep: `js-yaml`.\n",
  "source": {
    "path": "shared/engines/adapters/domain/embeddings/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 4489,
    "hash": "ff942d2a0dd0132a3d8332f7996de90b9dd3ec75"
  },
  "urls": {
    "html": "/p/adapters/adapter-embeddings",
    "json": "/docs/adapters/adapter-embeddings.json",
    "md": "/docs/adapters/adapter-embeddings.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  },
  "exports": null
}