@ponraaj/dimple-sdk 0.0.0-alpha.1 → 0.0.0-alpha.2

package/README.md

@@ -0,0 +1,334 @@
+# @ponraaj/dimple-sdk
+
+A local-first memory system for AI agents. Store text memories (and whole
+codebases), retrieve them with hybrid semantic + lexical search, and let a
+**self-organizing topic tree + artifact graph + concepts** keep everything
+structured as it grows. Everything runs locally: ONNX embeddings on your
+CPU, SQLite files on disk.
+
+This is the programmatic SDK — the
+[`@ponraaj/dimple`](https://www.npmjs.com/package/@ponraaj/dimple) CLI is a
+thin facade over it.
+
+> **Status**: alpha (`0.0.0-alpha.n`). The API is stabilizing but may change.
+
+## Install
+
+```bash
+npm install @ponraaj/dimple-sdk
+```
+
+Runtime dependencies are the only things installed (Effect, libSQL,
+Transformers.js, drizzle) — the workspace internals are bundled into the
+package.
+
+## Quickstart
+
+```ts
+import { makeDimple } from "@ponraaj/dimple-sdk";
+
+const dimple = await makeDimple({ config: "./dimple.jsonc" });
+
+// write a memory (embeds + topic-routes it)
+const mem = await dimple.write({
+  logicalKey: "deploy-1",
+  content: "the deploy pipeline runs on every push",
+});
+
+// hybrid semantic + FTS search
+const results = await dimple.query("how does the pipeline deploy", { limit: 3 });
+
+// index real code — files + extracted functions/classes/methods become memories
+const indexed = await dimple.index({ paths: ["./src"] });
+
+await dimple.dispose(); // stop the worker, close DBs (idempotent)
+```
+
+## The problem & the approach
+
+**Problem**: naive memory stores scan every vector per query (cost grows
+with memory count), return flat results with no structure, and give the
+agent no notion of _why_ a memory is relevant, what supersedes it, or what
+contradicts it.
+
+**Approach** — three structures maintained automatically by a durable
+background worker:
+
+1. **Topic tree** — memories are routed by embedding similarity into tree
+   leaves. Queries descend the tree (beam search on centroids) and only
+   score the reached leaves: **search cost grows with depth, not with
+   memory count**. A durable worker splits overflowing leaves and merges
+   underflowing ones with deterministic algorithms (CF-triplet k-means) —
+   same embeddings ⇒ same tree, anywhere.
+2. **Hybrid retrieval** — vector (cosine) + FTS5 lexical legs fused with
+   Reciprocal Rank Fusion, optional recency boost, and per-result graph
+   context.
+3. **Artifact graph + concepts** — directed `memory_supports` /
+   `memory_supersedes` / `memory_contradicts` edges written by structural
+   rules, code indexing, the agent, and the optional **dream** job (LLM
+   classification of candidates + deterministic concept clustering).
+   Retrieval consumes the graph: superseded memories demote, conflicts
+   surface, supports ride along as provenance; concept filters give the
+   query sovereignty.
+
+All structural decisions are **deterministic**; everything is **durable**
+(two SQLite files, resume-safe jobs).
+
+## Configuration
+
+Pass a config file path or an inline object:
+
+```ts
+const dimple = await makeDimple({ config: "./dimple.jsonc" });
+// or
+const dimple = await makeDimple({
+  config: {
+    storeUrl: "file:./.dimple/dimple.db",
+    jobs: { dbUrl: "file:./.dimple/jobs.db" },
+    embedding: {
+      defaultModel: "minilm",
+      models: [
+        {
+          id: "minilm",
+          provider: "transformers",
+          model: "Xenova/all-MiniLM-L6-v2",
+          dimensions: 384,
+        },
+      ],
+    },
+  },
+});
+```
+
+### Config sections (`dimple.jsonc`)
+
+| Section                     | Fields                                                                                                                          | Notes                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `storeUrl`                  | string                                                                                                                          | memory store DB (`file:` or remote libSQL) |
+| `jobs`                      | `dbUrl`, `execution` (reserved), `concurrency`, `leaseTimeoutMs` (reserved), `maxAttempts` (1–100), `pollIntervalMs` (reserved) | separate DB for the durable queue          |
+| `embedding`                 | `defaultModel` + `models[]`                                                                                                     | **required** — see Models below            |
+| `topics`                    | tree shape (`minLeafItems`, `maxLeafItems`, …)                                                                                  | optional, defaults apply                   |
+| `graph`                     | graph config                                                                                                                    | optional                                   |
+| `llm`                       | `baseURL`, `apiKey`, `modelId`, `temperature`                                                                                   | enables `dream`/`repair`                   |
+| `logging`                   | `enabled`, `level`, `format` (`jsonl`\|`pretty`), `file`, `scopes`, `ringSize`                                                  | silent by default; `file` = durable JSONL  |
+| `defaultK` / `defaultLimit` | numbers                                                                                                                         | retrieval defaults                         |
+| `defaultTtlSecs`            | number                                                                                                                          | write TTL default                          |
+
+### Embedding models
+
+Config-swappable — any Transformers.js ONNX model (the only tested
+provider):
+
+```jsonc
+"embedding": {
+  "defaultModel": "bge",
+  "models": [
+    { "id": "minilm", "provider": "transformers",
+      "model": "Xenova/all-MiniLM-L6-v2", "dimensions": 384 },
+    { "id": "bge", "provider": "transformers",
+      "model": "Xenova/bge-small-en-v1.5", "dimensions": 384 },
+    { "id": "bge-base", "provider": "transformers",
+      "model": "Xenova/bge-base-en-v1.5", "dimensions": 768 }
+  ]
+}
+```
+
+- `dimensions` must match the model's real output — a mismatch fails typed
+  on first use
+- Multiple models coexist: each gets its own vector tables
+  (`vec_<dims>_<model>`) and its own topic tree; queries route per model
+- **Per-model runtime options** (transformers provider, all optional):
+  `device` (`auto` | `gpu` | `cpu` | `wasm` | `webgpu` | `cuda` | `dml` |
+  `coreml` | `webnn` — `cpu`/`wasm` tested; GPU/CUDA needs the onnxruntime
+  CUDA libs, fails typed without them), `dtype` (`fp32` | `fp16` | `q8` |
+  `int8` | `uint8` | `q4` | `bnb4` | `q4f16` | `q2` | `q2f16` | `q1` |
+  `q1f16` — quantizes model WEIGHTS only, never the output vectors;
+  `fp32`/`q8`/`int8`/`q4`/`fp16` verified end-to-end, others depend on the
+  HF repo shipping that ONNX variant), `pooling` (`mean` | `cls` | `none`),
+  `normalize` (boolean), `cacheDir`
+- **DB-level vector quantization** via `vectorType` (`float32` |
+  `float16` | `float8` | `float1bit`): the per-memory search vectors are
+  stored as int8/bfloat16/binary blobs and searched with libSQL's native
+  `vector_distance_cos` — `float8` verified end-to-end at **395 B vs
+  1536 B (4× smaller)** for 384-dim. The topic tree's centroid math and
+  `memories.embedding` always stay float32.
+- **Switching models**: set `defaultModel` to a configured model (multi-
+  model configs coexist — each model gets its own tree + `vec_<dims>_<model>`
+  tables). After a restart the new default handles all writes/queries;
+  the old model's tree stays intact. Existing memories are backfilled via
+  the durable `memory.embed` job (re-embed + re-route into the new tree,
+  idempotent/resume-safe) — the store-level switch (`setActiveModel` +
+  `findStale`) drives it, reachable through the `{ core: … }` path. Until
+  backfilled, old memories remain in the old tree (queries descend the
+  ACTIVE model's tree), and the runtime is bound to one active model at a
+  time (per-model reads for another model fail typed with
+  `topics.ModelMismatch`).
+- Vectors are always stored as float32 (`F32_BLOB`, 4 B/dim: 384 = 1536 B,
+  768 = 3072 B) regardless of `dtype`
+
+### Power users: `{ core: … }`
+
+Instead of a config, pass full `CoreOptions` (store/jobs URLs, models,
+`defaultModelId`, `embedderFor` factory, topics/graph/logging/llm,
+`concurrency`, `maxAttempts`, `extraDefs`/`extraHandlers` for custom durable
+jobs — register `{ name: "my.job", handler }` and enqueue it via the
+runtime; `extraHandlers` entries override built-ins by name). This is the
+injection seam used by tests (synthetic embedders).
+
+## API surface
+
+### `write(input, options?)`
+
+```ts
+await dimple.write({
+  logicalKey: "deploy-1",        // required, non-empty
+  content: "…",                   // required
+  namespace?: "default",
+  contentType?: "text/plain",
+  ttlSecs?: 604800,
+  metadata?: "{\"json\":true}",   // JSON string
+  typedMetadata?: { … },
+}, { embed: true });              // embed + topic-route (default); false for externally-managed embeddings
+```
+
+Returns the persisted `MemoryUnit`: `{ id, logicalKey, content,
+contentType, state: "active" | "superseded" | …, createdAt, ttlSecs,
+namespace, metadata, embedding? }` (re-fetched after embedding). Duplicate
+active `logicalKey` → `Sdk.DuplicateKey` (carries `logicalKey`/`namespace`).
+
+**Memory expiry**: `ttlSecs` (or the config `defaultTtlSecs`) schedules
+expiry; a sweep job retires expired memories in the background.
+
+### `get(id)` / `forget(id)`
+
+Fetch one memory; soft-delete (cascades edges, rebalances the tree).
+
+### `query(text, options?)`
+
+```ts
+await dimple.query("how does the pipeline deploy", {
+  limit?: 10,
+  k?: 60,                          // RRF smoothing
+  namespace?: "default",
+  profile?: {
+    recencyBoost?: 0,              // 0 = off; hyperbolically decays with age
+    modeWeights?: { vector?: 0.5, fts?: 0.5 },
+    conceptFilter?: string[],      // concept ids (query sovereignty)
+  } | "hybrid" | "semantic" | "keyword",
+  topics?: { topicKeys?: string[] },
+});
+```
+
+Returns `AugmentedMemory[]` — each entry carries the memory, the fused
+score, its 1-based `rank`, and the graph context (`supersededBy`,
+`conflicts`, `supportedBy`). Zero-result queries resolve to `[]` (the
+absent-vector-table case is an empty dense leg, never an error).
+
+### `index(options)` — codebase ingestion
+
+```ts
+await dimple.index({
+  paths: ["./src", "./packages"],  // dirs (recursive) and/or files
+  keyPrefix?: "code-",
+  namespace?: "default",
+  embed?: true,
+  maxFileBytes?: 64 * 1024,
+  maxChunkBytes?: 8 * 1024,
+  extensions?: [".ts", ".tsx", ".js", ".jsx", …],
+});
+// → { files, indexed, skipped, unsupported, failed: [{ filePath, message }] }
+```
+
+- Tree-sitter parse (TypeScript/JavaScript/TSX/JSX) → the extractor
+  produces one **file unit** per file (with its import graph in metadata)
+  and one **chunk unit** per definition (function/class/method/interface/
+  type/enum/variable, with kind/name/line-range/docstring metadata)
+- Every unit embeds + topic-routes (unless `embed: false`)
+- AST-derived graph: relative imports resolve to indexed files and
+  class→method containment become **confirmed `memory_supports` edges**
+  (`source: "rule"`)
+- **Idempotent**: keys are cwd-anchored + deterministic — re-indexing the
+  same tree skips existing units
+- Per-file failures are collected, never fatal
+
+### `updateEmbedding(id, embedding, modelKey?)` / `embed(text)`
+
+Attach an externally-computed embedding (completes the `{ embed: false }`
+workflow — the memory becomes semantically retrievable + topic-routed), or
+embed text with the SDK's own pipeline.
+
+### `dream(modelKey)` / `repair(modelKey)`
+
+Run the consolidation job (concept clustering + LLM edge classification;
+requires the `llm` config section) or the graph repair pass. Each call
+gets a fresh run id (always executes). Failures are typed:
+`Sdk.LLMNotConfigured`, `Sdk.JobFailed`.
+
+### `explain({ kind: "memory" | "topic" | "concept", id })`
+
+Graph neighborhood traversal — `{ nodes: [{ kind, id, depth, edgeKind }] }`.
+
+### `health(modelKey)` / `graph.*`
+
+- `health` — topic-tree invariant sweep (`warnCount` + violation strings)
+- `graph.addEdge({ fromMemoryId, toMemoryId, edgeKind: "memory_supports" |
+"memory_supersedes" | "memory_contradicts", source: "rule" | "llm" |
+"agent", weight?, confidence?, confirmed? })` — explicit edges; typed
+  validation (no self-loops, known kinds, weight > 0, confidence ∈ [0,1])
+- `graph.candidates()` — pending structural candidates + isolated count
+- `graph.coverage(modelKey)` — coverage %, pending, concept count
+
+### `dispose()`
+
+Stops the worker, closes sinks + the store. Idempotent; post-dispose calls
+reject with a closed `Sdk.StoreFailure`.
+
+## Errors — the closed hierarchy
+
+Every promise rejects with typed errors from one family (never raw Effect
+internals). Export surface: `ConfigError`, `NotFoundError`,
+`DuplicateKeyError` (with `logicalKey`/`namespace`), `DuplicateEdgeError`,
+`LLMNotConfiguredError`, `JobFailedError`, `StoreFailure`, `InputError`,
+plus the `remapError` helper (maps unknown failures onto the hierarchy).
+Also importable from the `@ponraaj/dimple-sdk/errors` subpath.
+
+**Type exports** (all importable from the package root): `Dimple` (the
+facade interface), `MakeDimpleOptions`, `ConfigInput`, `QueryOptions`,
+`IndexOptions`, `IndexResult`, plus the error classes and the `DimpleError`
+union type. Errors also carry stable `_tag` values (`Sdk.DuplicateKey`,
+`Sdk.NotFound`, `Sdk.InputError`, `Sdk.JobFailed`, `Sdk.LLMNotConfigured`,
+`Sdk.StoreFailure`, …) — the recommended discriminator.
+
+## Background jobs (what runs while you work)
+
+| Job                                               | Trigger             | Work                                                                                                                       |
+| ------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `topic.split` / `topic.merge` / `topic.rebalance` | automatic per write | keep every leaf within its size budget (deterministic splits, donor borrow, nearest-sibling merge, uneven-split rebalance) |
+| `memory.embed`                                    | model backfill      | re-embed a memory with a target model + route into its tree                                                                |
+| `memory.dream`                                    | `dream()`           | concept clustering + LLM edge classification                                                                               |
+| `graph.repair`                                    | `repair()`          | graph invariant repair                                                                                                     |
+| `audit.write`                                     | query path          | async audit-log writes (never blocks queries) — one FUSED row per hybrid query with the per-leg breakdown                  |
+
+Jobs are durable (leased, retried up to `maxAttempts`, resume-safe across
+processes). Every `makeDimple` boots the worker; `dispose` stops it.
+
+Every `query` also writes a retrieval audit row (query, namespace, mode,
+per-leg counts/scores, sources) into `retrieval_log` — machine-readable
+query history, persisted asynchronously (never blocks the query).
+
+## Storage & logs
+
+| What                           | Where                                                                                        |
+| ------------------------------ | -------------------------------------------------------------------------------------------- |
+| Memories, tree, graph, audit   | `storeUrl` (`file:…`)                                                                        |
+| Durable queue + workflow state | `jobs.dbUrl` (separate DB)                                                                   |
+| Logs                           | stdout + in-memory ring (4096) by default; durable JSONL **only** when `logging.file` is set |
+| Grammar WASMs                  | `~/.cache/dimple/tree-sitter/` (downloaded once, offline after)                              |
+| ONNX model                     | bun/npm cache (~90 MB, first use)                                                            |
+
+## Notes
+
+- Determinism: same data + same config ⇒ same tree, same clusters, same
+  audit hashes — reproducible across machines and runs
+- `migrationFolder` is accepted in `makeDimple` options for advanced users;
+  the default path uses migrations embedded at build time (nothing to ship)

package/dist/index.js

@@ -659,7 +659,35 @@ var EmbeddingModelConfig = Schema6.Struct({
   dimensions: Schema6.Number,
   vectorType: Schema6.optional(Schema6.String),
   apiKey: Schema6.optional(Schema6.String),
-  indexConfig: Schema6.optional(IndexConfig)
+  indexConfig: Schema6.optional(IndexConfig),
+  device: Schema6.optional(Schema6.Literals([
+    "auto",
+    "gpu",
+    "cpu",
+    "wasm",
+    "webgpu",
+    "cuda",
+    "dml",
+    "coreml",
+    "webnn"
+  ])),
+  dtype: Schema6.optional(Schema6.Literals([
+    "fp32",
+    "fp16",
+    "q8",
+    "int8",
+    "uint8",
+    "q4",
+    "bnb4",
+    "q4f16",
+    "q2",
+    "q2f16",
+    "q1",
+    "q1f16"
+  ])),
+  pooling: Schema6.optional(Schema6.Literals(["mean", "cls", "none"])),
+  normalize: Schema6.optional(Schema6.Boolean),
+  cacheDir: Schema6.optional(Schema6.String)
 });
 var EmbeddingConfig = Schema6.Struct({
   defaultModel: Schema6.String,
@@ -1410,13 +1438,11 @@ var makeBackend = (url, client, db, migrationFolder) => ({
   ensureTopicVectorTable: (model) => Effect9.tryPromise({
     try: () => {
       const tableName = topicVectorTableName(model);
-      const vecType = model.vectorType ?? "float32";
-      const sqlType = VECTOR_SQL_TYPES[vecType] ?? "F32_BLOB";
       const dims = model.dimensions;
       const sql3 = `
           CREATE TABLE IF NOT EXISTS ${tableName} (
             topic_key TEXT PRIMARY KEY,
-            sum_vector ${sqlType}(${dims}) NOT NULL,
+            sum_vector F32_BLOB(${dims}) NOT NULL,
             model_key TEXT NOT NULL
           );
         `;
@@ -1428,9 +1454,8 @@ var makeBackend = (url, client, db, migrationFolder) => ({
     try: () => {
       const tableName = topicVectorTableName(model);
       const vecJson = JSON.stringify([...sumVector]);
-      const convertFn = VECTOR_CONVERT_FNS[model.vectorType ?? "float32"] ?? "vector32";
       return client.execute({
-        sql: `INSERT OR REPLACE INTO ${tableName} (topic_key, sum_vector, model_key) VALUES (?, ${convertFn}(?), ?)`,
+        sql: `INSERT OR REPLACE INTO ${tableName} (topic_key, sum_vector, model_key) VALUES (?, vector32(?), ?)`,
         args: [topicKey, vecJson, model.id]
       });
     },
@@ -1462,16 +1487,18 @@ var makeBackend = (url, client, db, migrationFolder) => ({
       return [];
     const tableName = vectorTableName(model);
     const placeholders = memoryIds.map(() => "?").join(", ");
+    const quantized = (model.vectorType ?? "float32") !== "float32";
+    const extractCol = quantized ? "vector_extract(embedding) AS embedding" : "embedding";
     const rows = yield* Effect9.tryPromise({
       try: () => client.execute({
-        sql: `SELECT memory_id, embedding FROM ${tableName} WHERE memory_id IN (${placeholders})`,
+        sql: `SELECT memory_id, ${extractCol} FROM ${tableName} WHERE memory_id IN (${placeholders})`,
         args: [...memoryIds]
       }).then((rs) => rs.rows),
       catch: (cause) => new StoreError({ message: `DbBackend.fetchMemoryVectors: ${cause}` })
     });
     return rows.map((row) => ({
       memoryId: row.memory_id,
-      vector: decodeVectorBlob(row.embedding)
+      vector: quantized ? JSON.parse(String(row.embedding)) : decodeVectorBlob(row.embedding)
     }));
   }),
   listMemoryIds: (model) => Effect9.gen(function* () {
@@ -3237,22 +3264,15 @@ import { and as and4, asc as asc3, eq as eq4, inArray as inArray2, sql as sql4 }
 // ../store/src/topics/topic-vectors.ts
 import { sql as sql3 } from "drizzle-orm";
 var topicVectorTableName2 = (model) => `topic_vec_${model.dimensions}_${model.id.replace(/[^a-zA-Z0-9_]/g, "_")}`;
-var VECTOR_CONVERT_FNS2 = {
-  float32: "vector32",
-  float16: "vector16",
-  float8: "vector8",
-  float1bit: "vector1bit"
-};
 var deleteTopicVectorRow = async (runner, model, topicKey) => {
   const table = topicVectorTableName2(model);
   await runner.run(sql3`DELETE FROM ${sql3.raw(table)} WHERE topic_key = ${topicKey}`);
 };
 var writeTopicVector = async (runner, model, topicKey, ls) => {
   const table = topicVectorTableName2(model);
-  const convertFn = VECTOR_CONVERT_FNS2[model.vectorType ?? "float32"] ?? "vector32";
   await runner.run(sql3`
     INSERT OR REPLACE INTO ${sql3.raw(table)} (topic_key, sum_vector, model_key)
-    VALUES (${topicKey}, ${sql3.raw(convertFn)}(${JSON.stringify([...ls])}), ${model.id})
+    VALUES (${topicKey}, vector32(${JSON.stringify([...ls])}), ${model.id})
   `);
 };
 
@@ -6807,7 +6827,15 @@ var DISABLED_LOGGING2 = {
   format: "jsonl",
   ringSize: 4096
 };
-var embedderFromConfig = (model) => model.provider === "transformers" ? Effect39.succeed(makeTransformersModel({ modelId: model.model, dimensions: model.dimensions })) : model.provider === "openai" ? model.apiKey === undefined ? Effect39.fail(new EmbeddingError({ message: `OpenAI model ${model.id} requires an apiKey` })) : Effect39.succeed(makeOpenAIModel({
+var embedderFromConfig = (model) => model.provider === "transformers" ? Effect39.succeed(makeTransformersModel({
+  modelId: model.model,
+  dimensions: model.dimensions,
+  ...model.device !== undefined ? { device: model.device } : {},
+  ...model.dtype !== undefined ? { dtype: model.dtype } : {},
+  ...model.pooling !== undefined ? { pooling: model.pooling } : {},
+  ...model.normalize !== undefined ? { normalize: model.normalize } : {},
+  ...model.cacheDir !== undefined ? { cacheDir: model.cacheDir } : {}
+})) : model.provider === "openai" ? model.apiKey === undefined ? Effect39.fail(new EmbeddingError({ message: `OpenAI model ${model.id} requires an apiKey` })) : Effect39.succeed(makeOpenAIModel({
   modelId: model.id,
   model: model.model,
   dimensions: model.dimensions,

package/dist/internal/config/schema.d.ts

@@ -18,6 +18,15 @@ export declare const EmbeddingModelConfig: Schema.Struct<{
         readonly maxNeighbors: Schema.optional<Schema.Number>;
         readonly searchL: Schema.optional<Schema.Number>;
     }>>;
+    /** Transformers.js runtime options — per-model, all optional (defaults:
+     * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+     * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+     * output vectors; unsupported devices fail typed at first use. */
+    readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+    readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+    readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+    readonly normalize: Schema.optional<Schema.Boolean>;
+    readonly cacheDir: Schema.optional<Schema.String>;
 }>;
 export interface EmbeddingModelConfig extends Schema.Schema.Type<typeof EmbeddingModelConfig> {
 }
@@ -35,6 +44,15 @@ export declare const EmbeddingConfig: Schema.Struct<{
             readonly maxNeighbors: Schema.optional<Schema.Number>;
             readonly searchL: Schema.optional<Schema.Number>;
         }>>;
+        /** Transformers.js runtime options — per-model, all optional (defaults:
+         * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+         * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+         * output vectors; unsupported devices fail typed at first use. */
+        readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+        readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+        readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+        readonly normalize: Schema.optional<Schema.Boolean>;
+        readonly cacheDir: Schema.optional<Schema.String>;
     }>>;
 }>;
 export interface EmbeddingConfig extends Schema.Schema.Type<typeof EmbeddingConfig> {
@@ -115,6 +133,15 @@ export declare const DimpleConfig: Schema.Struct<{
                 readonly maxNeighbors: Schema.optional<Schema.Number>;
                 readonly searchL: Schema.optional<Schema.Number>;
             }>>;
+            /** Transformers.js runtime options — per-model, all optional (defaults:
+             * device "cpu", dtype "q8", pooling "mean", normalize true). `dtype`
+             * quantizes the MODEL WEIGHTS (inference memory/speed), never the
+             * output vectors; unsupported devices fail typed at first use. */
+            readonly device: Schema.optional<Schema.Literals<readonly ["auto", "gpu", "cpu", "wasm", "webgpu", "cuda", "dml", "coreml", "webnn"]>>;
+            readonly dtype: Schema.optional<Schema.Literals<readonly ["fp32", "fp16", "q8", "int8", "uint8", "q4", "bnb4", "q4f16", "q2", "q2f16", "q1", "q1f16"]>>;
+            readonly pooling: Schema.optional<Schema.Literals<readonly ["mean", "cls", "none"]>>;
+            readonly normalize: Schema.optional<Schema.Boolean>;
+            readonly cacheDir: Schema.optional<Schema.String>;
         }>>;
     }>>;
     readonly jobs: Schema.optional<Schema.Struct<{

package/dist/internal/embedder/transformers.d.ts

@@ -4,7 +4,7 @@ import { Service, type EmbeddingModel } from "./provider.ts";
 interface TransformersOptions {
     readonly modelId?: string;
     readonly device?: DeviceType;
-    readonly dtype?: "fp32" | "fp16" | "q8" | "q4";
+    readonly dtype?: "fp32" | "fp16" | "q8" | "int8" | "uint8" | "q4" | "bnb4" | "q4f16" | "q2" | "q2f16" | "q1" | "q1f16";
     readonly pooling?: "mean" | "cls" | "none";
     readonly normalize?: boolean;
     readonly cacheDir?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponraaj/dimple-sdk",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.2",
   "private": false,
   "files": [
     "dist"
@@ -39,6 +39,16 @@
     "web-tree-sitter": "^0.26.9",
     "zod": "^4.4.3"
   },
+  "devDependencies": {
+    "@dimple/config": "0.0.0-alpha.1",
+    "@dimple/core": "0.0.0-alpha.1",
+    "@dimple/embedder": "0.0.0-alpha.1",
+    "@dimple/extractor": "0.0.0-alpha.1",
+    "@dimple/parser": "0.0.0-alpha.1",
+    "@dimple/retriever": "0.0.0-alpha.1",
+    "@dimple/store": "0.0.0-alpha.1",
+    "@dimple/workflow": "0.0.0-alpha.1"
+  },
   "peerDependencies": {
     "typescript": "^5"
   }