@tryhamster/gerbil 1.0.0-rc.9 → 1.0.0

package/dist/index-Dgmb2kE3.d.mts

@@ -0,0 +1,245 @@
+import { c as MemorySearchResult, d as RecallOptions, f as RecallResult, g as StoreSearchOptions, i as MemoryExport, l as MemoryStore, m as SearchOptions, n as ChunkOptions, o as MemoryOptions, p as Redactor, r as Embedder, s as MemoryRecord, t as AddOptions, u as MetadataFilter } from "./types-DQBe2lFo.mjs";
+
+//#region src/memory/chunking.d.ts
+
+/**
+ * Split `text` into overlapping character windows.
+ *
+ * Chunks are `chunkSize` characters with `overlap` characters shared between
+ * consecutive chunks, which preserves context across boundaries. Whitespace
+ * is trimmed and empty chunks are dropped. Short text returns a single chunk.
+ *
+ * @throws if `overlap` is not less than `chunkSize` (would loop forever).
+ */
+declare function chunkText(text: string, options?: ChunkOptions): string[];
+//#endregion
+//#region src/memory/gerbil-embedder.d.ts
+
+/** Minimal shape of a batch embedder returning `{ vector }` records. */
+type BatchEmbedderLike = {
+  embedBatch(texts: string[]): Promise<{
+    vector: number[];
+  }[]>;
+};
+/**
+ * Build an {@link Embedder} from a Gerbil instance (or any object exposing a
+ * compatible `embedBatch`). Vectors are converted to {@link Float32Array}.
+ *
+ * @example
+ * ```ts
+ * import { Gerbil } from "@tryhamster/gerbil";
+ * import { createMemory, createGerbilEmbedder } from "@tryhamster/gerbil/memory";
+ *
+ * const g = new Gerbil();
+ * await g.loadModel("embeddinggemma-300m");
+ * const mem = createMemory({ embed: createGerbilEmbedder(g) });
+ * ```
+ */
+declare function createGerbilEmbedder(engine: BatchEmbedderLike): Embedder;
+//#endregion
+//#region src/memory/memory.d.ts
+/**
+ * On-device persistent memory with semantic recall.
+ *
+ * Construct via {@link createMemory}. Engine-agnostic: bring any
+ * {@link Embedder} (Gerbil's native embeddings by default) and any
+ * {@link MemoryStore} backend.
+ */
+declare class Memory {
+  private readonly embedder;
+  private readonly store;
+  private readonly redact?;
+  private readonly defaultChunk?;
+  constructor(options: MemoryOptions);
+  /** The underlying store, for advanced use (custom queries, swapping). */
+  get backend(): MemoryStore;
+  /**
+   * Add text to memory. Long text can be split into overlapping chunks
+   * (one record per chunk). Returns the ids of the created record(s).
+   */
+  add(text: string, options?: AddOptions): Promise<string[]>;
+  private resolveChunking;
+  /** Fetch a record by id. */
+  get(id: string): Promise<MemoryRecord | undefined>;
+  /** Semantic search: returns the top-k records by cosine similarity. */
+  search(query: string, options?: SearchOptions): Promise<MemorySearchResult[]>;
+  /**
+   * Retrieve relevant memories and greedily pack them into a token-budgeted
+   * context block, highest-scoring first, stopping before the budget is
+   * exceeded. This is the per-turn context-rebuild step that turns the store
+   * into agent memory. Token counts are approximate (see {@link estimateTokens}).
+   */
+  recall(query: string, options?: RecallOptions): Promise<RecallResult>;
+  /** Delete a record by id. Returns `true` if it existed. */
+  delete(id: string): Promise<boolean>;
+  /** List all records, optionally filtered by metadata. */
+  list(filter?: MetadataFilter): Promise<MemoryRecord[]>;
+  /** Remove all records. */
+  clear(): Promise<void>;
+  /** Total number of stored records. */
+  size(): Promise<number>;
+  /** Export the full corpus as a JSON-serializable snapshot. */
+  export(): Promise<MemoryExport>;
+  /**
+   * Import records from a snapshot produced by {@link Memory.export}.
+   * Existing records with the same id are overwritten.
+   */
+  import(snapshot: MemoryExport): Promise<void>;
+}
+/**
+ * Create a {@link Memory} instance.
+ *
+ * @example
+ * ```ts
+ * const mem = createMemory({ embed, store });
+ * await mem.add("Paris is the capital of France", { metadata: { topic: "geo" } });
+ * const hits = await mem.search("French capital", { k: 3 });
+ * const { context } = await mem.recall("French capital", { tokenBudget: 512 });
+ * ```
+ */
+declare function createMemory(options: MemoryOptions): Memory;
+//#endregion
+//#region src/memory/redaction.d.ts
+/**
+ * Apply a {@link Redactor} to `text`.
+ *
+ * - A {@link RegExp} replaces all matches with `[REDACTED]` (the `g` flag is
+ *   forced so replacement is global regardless of the supplied flags).
+ * - A function is invoked and its return value used.
+ * - `undefined` returns the text unchanged.
+ */
+declare function applyRedaction(text: string, redact?: Redactor): string;
+//#endregion
+//#region src/memory/stores/file-store.d.ts
+/** JSON-on-disk vector store for Node. */
+declare class FileStore implements MemoryStore {
+  private readonly path;
+  private records;
+  private loaded;
+  private writeQueue;
+  constructor(path: string);
+  private ensureLoaded;
+  private persist;
+  add(record: MemoryRecord): Promise<void>;
+  addMany(records: MemoryRecord[]): Promise<void>;
+  get(id: string): Promise<MemoryRecord | undefined>;
+  search(queryVector: Float32Array, options?: StoreSearchOptions): Promise<MemorySearchResult[]>;
+  delete(id: string): Promise<boolean>;
+  list(filter?: MetadataFilter): Promise<MemoryRecord[]>;
+  clear(): Promise<void>;
+  size(): Promise<number>;
+}
+/** Create a {@link FileStore} backed by `path` (JSON). */
+declare function createFileStore(path: string): MemoryStore;
+//#endregion
+//#region src/memory/stores/indexeddb-store.d.ts
+/** Options for {@link createIndexedDBStore}. */
+type IndexedDBStoreOptions = {
+  /** Database name (default "gerbil-memory"). */
+  dbName?: string;
+  /** Object store name (default "records"). */
+  storeName?: string;
+  /**
+   * IndexedDB factory. Defaults to the global `indexedDB` in browsers.
+   * Inject a shim (e.g. fake-indexeddb) to use this store under Node.
+   */
+  indexedDB?: IDBFactory;
+};
+/** Durable IndexedDB vector store. */
+declare class IndexedDBStore implements MemoryStore {
+  private readonly dbName;
+  private readonly storeName;
+  private readonly factory;
+  private dbPromise;
+  constructor(options?: IndexedDBStoreOptions);
+  private openDb;
+  private tx;
+  add(record: MemoryRecord): Promise<void>;
+  addMany(records: MemoryRecord[]): Promise<void>;
+  get(id: string): Promise<MemoryRecord | undefined>;
+  private all;
+  search(queryVector: Float32Array, options?: StoreSearchOptions): Promise<MemorySearchResult[]>;
+  delete(id: string): Promise<boolean>;
+  list(filter?: MetadataFilter): Promise<MemoryRecord[]>;
+  clear(): Promise<void>;
+  size(): Promise<number>;
+}
+/** Create an {@link IndexedDBStore}. */
+declare function createIndexedDBStore(options?: IndexedDBStoreOptions): MemoryStore;
+//#endregion
+//#region src/memory/stores/memory-store.d.ts
+/** Brute-force, embedding-agnostic in-memory vector store. */
+declare class InMemoryStore implements MemoryStore {
+  private readonly records;
+  add(record: MemoryRecord): Promise<void>;
+  addMany(records: MemoryRecord[]): Promise<void>;
+  get(id: string): Promise<MemoryRecord | undefined>;
+  search(queryVector: Float32Array, options?: StoreSearchOptions): Promise<MemorySearchResult[]>;
+  delete(id: string): Promise<boolean>;
+  list(filter?: MetadataFilter): Promise<MemoryRecord[]>;
+  clear(): Promise<void>;
+  size(): Promise<number>;
+}
+/** Create an {@link InMemoryStore}. */
+declare function createInMemoryStore(): MemoryStore;
+//#endregion
+//#region src/memory/tokens.d.ts
+/**
+ * Approximate token counting for context packing.
+ *
+ * We deliberately avoid a real tokenizer dependency here. The heuristic is
+ * the widely used "~4 characters per token" rule for English-ish text, with
+ * a small floor so very short strings still cost at least one token. This is
+ * an estimate used only for budgeting — slightly conservative is fine, since
+ * the goal is to stay under a model's context window, not to be exact.
+ */
+/**
+ * Estimate the number of tokens in `text`.
+ *
+ * Uses the ~4-chars-per-token heuristic. Returns 0 for empty strings.
+ */
+declare function estimateTokens(text: string): number;
+//#endregion
+//#region src/memory/vector.d.ts
+/**
+ * Vector math for cosine similarity search.
+ *
+ * Vectors are stored L2-normalized so cosine similarity is a plain dot
+ * product. Normalization happens once on insert via {@link normalize}.
+ */
+/**
+ * Return an L2-normalized copy of `vector`.
+ *
+ * A zero vector is returned unchanged (its norm is 0).
+ */
+declare function normalize(vector: Float32Array): Float32Array;
+/**
+ * Dot product of two equal-length vectors.
+ *
+ * For L2-normalized inputs this equals cosine similarity.
+ */
+declare function dot(a: Float32Array, b: Float32Array): number;
+/**
+ * Cosine similarity of two vectors, normalizing on the fly.
+ *
+ * Prefer {@link dot} when both inputs are already normalized.
+ */
+declare function cosine(a: Float32Array, b: Float32Array): number;
+/** A scored item used by {@link topK}. */
+type Scored<T> = {
+  item: T;
+  score: number;
+};
+/**
+ * Score every candidate against `query` (dot product) and return the top `k`
+ * by descending score, optionally filtering by a minimum score.
+ *
+ * Inputs are assumed normalized; this keeps the hot path branch-free.
+ */
+declare function topK<T>(query: Float32Array, candidates: {
+  item: T;
+  vector: Float32Array;
+}[], k: number, minScore?: number): Scored<T>[];
+//#endregion
+export { createGerbilEmbedder as _, estimateTokens as a, IndexedDBStore as c, FileStore as d, createFileStore as f, BatchEmbedderLike as g, createMemory as h, topK as i, IndexedDBStoreOptions as l, Memory as m, dot as n, InMemoryStore as o, applyRedaction as p, normalize as r, createInMemoryStore as s, cosine as t, createIndexedDBStore as u, chunkText as v };
+//# sourceMappingURL=index-Dgmb2kE3.d.mts.map

package/dist/index-Dgmb2kE3.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Dgmb2kE3.d.mts","names":[],"sources":["../src/memory/chunking.ts","../src/memory/gerbil-embedder.ts","../src/memory/memory.ts","../src/memory/redaction.ts","../src/memory/stores/file-store.ts","../src/memory/stores/indexeddb-store.ts","../src/memory/stores/memory-store.ts","../src/memory/tokens.ts","../src/memory/vector.ts"],"sourcesContent":[],"mappings":"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"}