@staticn0va/wigolo 0.1.0 → 0.1.1

package/dist/cache/sqlite-vec-store.js

@@ -0,0 +1,176 @@
+import { createLogger } from "../logger.js";
+const log = createLogger("cache");
+class SqliteVecStore {
+  constructor(db) {
+    this.db = db;
+    this.upsertSelectStmt = db.prepare(
+      "SELECT rowid FROM vec_id_map WHERE external_id = ?"
+    );
+    this.upsertInsertIdMapStmt = db.prepare(
+      "INSERT INTO vec_id_map (external_id) VALUES (?)"
+    );
+    this.upsertDeleteDocStmt = db.prepare(
+      "DELETE FROM vec_documents WHERE rowid = ?"
+    );
+    this.upsertInsertDocStmt = db.prepare(
+      "INSERT INTO vec_documents (rowid, embedding) VALUES (?, ?)"
+    );
+    this.upsertUpsertMetadataStmt = db.prepare(`
+      INSERT INTO vec_metadata (rowid, url, content_hash, model_id, created_at, extra_json)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(rowid) DO UPDATE SET
+        url = excluded.url,
+        content_hash = excluded.content_hash,
+        model_id = excluded.model_id,
+        created_at = excluded.created_at,
+        extra_json = excluded.extra_json
+    `);
+    this.deleteIdMapStmt = db.prepare("DELETE FROM vec_id_map WHERE external_id = ?");
+    this.deleteDocStmt = db.prepare("DELETE FROM vec_documents WHERE rowid = ?");
+    this.sizeStmt = db.prepare("SELECT COUNT(*) AS c FROM vec_id_map");
+  }
+  db;
+  upsertSelectStmt;
+  upsertInsertIdMapStmt;
+  upsertDeleteDocStmt;
+  upsertInsertDocStmt;
+  upsertUpsertMetadataStmt;
+  deleteIdMapStmt;
+  deleteDocStmt;
+  sizeStmt;
+  async upsert(records) {
+    if (records.length === 0) return;
+    const tx = this.db.transaction((items) => {
+      for (const record of items) {
+        const existing = this.upsertSelectStmt.get(record.id);
+        let rowid;
+        if (existing) {
+          rowid = existing.rowid;
+          this.upsertDeleteDocStmt.run(BigInt(rowid));
+        } else {
+          const info = this.upsertInsertIdMapStmt.run(record.id);
+          rowid = Number(info.lastInsertRowid);
+        }
+        const vec = record.vector;
+        const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+        this.upsertInsertDocStmt.run(BigInt(rowid), buf);
+        const extra = record.metadata.extra ? JSON.stringify(record.metadata.extra) : null;
+        this.upsertUpsertMetadataStmt.run(
+          rowid,
+          record.metadata.url,
+          record.metadata.contentHash,
+          record.metadata.modelId,
+          Date.now(),
+          extra
+        );
+      }
+    });
+    try {
+      tx(records);
+    } catch (err) {
+      log.error("SqliteVecStore.upsert failed", {
+        count: records.length,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
+  }
+  async search(queryVector, limit, filter) {
+    if (limit <= 0) return [];
+    const queryBuf = Buffer.from(
+      queryVector.buffer,
+      queryVector.byteOffset,
+      queryVector.byteLength
+    );
+    const knnLimit = filter ? Math.max(limit * 5, 50) : limit;
+    const candidateStmt = this.db.prepare(`
+      SELECT rowid, distance
+      FROM vec_documents
+      WHERE embedding MATCH ?
+      ORDER BY distance
+      LIMIT ?
+    `);
+    let candidates;
+    try {
+      candidates = candidateStmt.all(queryBuf, knnLimit);
+    } catch (err) {
+      log.error("SqliteVecStore.search KNN failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
+    if (candidates.length === 0) return [];
+    const rowids = candidates.map((c) => c.rowid);
+    const placeholders = rowids.map(() => "?").join(",");
+    const metaRows = this.db.prepare(`
+        SELECT m.rowid AS rowid, m.external_id AS external_id,
+               meta.url AS url, meta.content_hash AS content_hash,
+               meta.model_id AS model_id, meta.extra_json AS extra_json
+        FROM vec_id_map m
+        JOIN vec_metadata meta ON m.rowid = meta.rowid
+        WHERE m.rowid IN (${placeholders})
+      `).all(...rowids);
+    const metaByRowid = /* @__PURE__ */ new Map();
+    for (const r of metaRows) metaByRowid.set(r.rowid, r);
+    const results = [];
+    for (const cand of candidates) {
+      const meta = metaByRowid.get(cand.rowid);
+      if (!meta) continue;
+      const extra = meta.extra_json ? JSON.parse(meta.extra_json) : void 0;
+      const metadata = {
+        url: meta.url,
+        contentHash: meta.content_hash,
+        modelId: meta.model_id,
+        ...extra ? { extra } : {}
+      };
+      if (filter && !matchesFilter(metadata, filter)) continue;
+      results.push({
+        id: meta.external_id,
+        score: 1 / (1 + cand.distance),
+        metadata
+      });
+      if (results.length >= limit) break;
+    }
+    return results;
+  }
+  async delete(ids) {
+    if (ids.length === 0) return;
+    const tx = this.db.transaction((items) => {
+      for (const id of items) {
+        const existing = this.upsertSelectStmt.get(id);
+        if (!existing) continue;
+        this.deleteDocStmt.run(BigInt(existing.rowid));
+        this.deleteIdMapStmt.run(id);
+      }
+    });
+    try {
+      tx(ids);
+    } catch (err) {
+      log.error("SqliteVecStore.delete failed", {
+        count: ids.length,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
+  }
+  async size() {
+    const row = this.sizeStmt.get();
+    return row.c;
+  }
+}
+function matchesFilter(meta, filter) {
+  if (filter.url !== void 0 && meta.url !== filter.url) return false;
+  if (filter.contentHash !== void 0 && meta.contentHash !== filter.contentHash) return false;
+  if (filter.modelId !== void 0 && meta.modelId !== filter.modelId) return false;
+  if (filter.extra !== void 0) {
+    const have = meta.extra ?? {};
+    for (const [k, v] of Object.entries(filter.extra)) {
+      if (have[k] !== v) return false;
+    }
+  }
+  return true;
+}
+export {
+  SqliteVecStore
+};
+//# sourceMappingURL=sqlite-vec-store.js.map

package/dist/cache/sqlite-vec-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cache/sqlite-vec-store.ts"],"sourcesContent":["import type Database from 'better-sqlite3';\nimport type {\n  VectorStore,\n  VectorRecord,\n  VectorSearchResult,\n  VectorMetadata,\n} from '../providers/vector-store.js';\nimport { createLogger } from '../logger.js';\n\nconst log = createLogger('cache');\n\n/**\n * VectorStore backed by the sqlite-vec extension loaded into the shared\n * better-sqlite3 cache database.\n *\n * Storage layout (see src/cache/migrations/001-sqlite-vec.sql):\n *   - vec_documents (virtual, vec0)   integer rowid -> float[384] embedding\n *   - vec_id_map                       integer rowid -> external string id\n *   - vec_metadata                     integer rowid -> full VectorMetadata\n *\n * vec0 only accepts integer rowid values, so external string ids (URLs in\n * the legacy world) are mapped to AUTOINCREMENT rowids via vec_id_map.\n *\n * vec0 rejects `INSERT OR REPLACE`, so upsert deletes any existing vector\n * row for an id before inserting the new one (within a single transaction).\n *\n * Search returns sqlite-vec's native L2 distance converted to a similarity\n * score as `1 / (1 + distance)`. Higher score = closer match.\n *\n * Filter semantics match VectorStore: when `filter` is provided we\n * over-fetch from the KNN side (oversample = limit * 5) then post-filter\n * against vec_metadata before truncating to `limit`. Filters never relax\n * — every populated filter field must match.\n */\nexport class SqliteVecStore implements VectorStore {\n  private upsertSelectStmt: Database.Statement;\n  private upsertInsertIdMapStmt: Database.Statement;\n  private upsertDeleteDocStmt: Database.Statement;\n  private upsertInsertDocStmt: Database.Statement;\n  private upsertUpsertMetadataStmt: Database.Statement;\n  private deleteIdMapStmt: Database.Statement;\n  private deleteDocStmt: Database.Statement;\n  private sizeStmt: Database.Statement;\n\n  constructor(private db: Database.Database) {\n    this.upsertSelectStmt = db.prepare(\n      'SELECT rowid FROM vec_id_map WHERE external_id = ?',\n    );\n    this.upsertInsertIdMapStmt = db.prepare(\n      'INSERT INTO vec_id_map (external_id) VALUES (?)',\n    );\n    this.upsertDeleteDocStmt = db.prepare(\n      'DELETE FROM vec_documents WHERE rowid = ?',\n    );\n    this.upsertInsertDocStmt = db.prepare(\n      'INSERT INTO vec_documents (rowid, embedding) VALUES (?, ?)',\n    );\n    this.upsertUpsertMetadataStmt = db.prepare(`\n      INSERT INTO vec_metadata (rowid, url, content_hash, model_id, created_at, extra_json)\n      VALUES (?, ?, ?, ?, ?, ?)\n      ON CONFLICT(rowid) DO UPDATE SET\n        url = excluded.url,\n        content_hash = excluded.content_hash,\n        model_id = excluded.model_id,\n        created_at = excluded.created_at,\n        extra_json = excluded.extra_json\n    `);\n    this.deleteIdMapStmt = db.prepare('DELETE FROM vec_id_map WHERE external_id = ?');\n    this.deleteDocStmt = db.prepare('DELETE FROM vec_documents WHERE rowid = ?');\n    this.sizeStmt = db.prepare('SELECT COUNT(*) AS c FROM vec_id_map');\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    if (records.length === 0) return;\n\n    const tx = this.db.transaction((items: VectorRecord[]) => {\n      for (const record of items) {\n        const existing = this.upsertSelectStmt.get(record.id) as { rowid: number } | undefined;\n        let rowid: number;\n        if (existing) {\n          rowid = existing.rowid;\n          this.upsertDeleteDocStmt.run(BigInt(rowid));\n        } else {\n          const info = this.upsertInsertIdMapStmt.run(record.id);\n          rowid = Number(info.lastInsertRowid);\n        }\n\n        const vec = record.vector;\n        const buf = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);\n        this.upsertInsertDocStmt.run(BigInt(rowid), buf);\n\n        const extra = record.metadata.extra\n          ? JSON.stringify(record.metadata.extra)\n          : null;\n        this.upsertUpsertMetadataStmt.run(\n          rowid,\n          record.metadata.url,\n          record.metadata.contentHash,\n          record.metadata.modelId,\n          Date.now(),\n          extra,\n        );\n      }\n    });\n\n    try {\n      tx(records);\n    } catch (err) {\n      log.error('SqliteVecStore.upsert failed', {\n        count: records.length,\n        error: err instanceof Error ? err.message : String(err),\n      });\n      throw err;\n    }\n  }\n\n  async search(\n    queryVector: Float32Array,\n    limit: number,\n    filter?: Partial<VectorMetadata>,\n  ): Promise<VectorSearchResult[]> {\n    if (limit <= 0) return [];\n\n    const queryBuf = Buffer.from(\n      queryVector.buffer,\n      queryVector.byteOffset,\n      queryVector.byteLength,\n    );\n\n    // When a filter is present we over-fetch from the KNN side and apply\n    // the filter post-hoc, since vec0 MATCH cannot be combined with JOIN\n    // predicates inside a single WHERE clause.\n    const knnLimit = filter ? Math.max(limit * 5, 50) : limit;\n\n    const candidateStmt = this.db.prepare(`\n      SELECT rowid, distance\n      FROM vec_documents\n      WHERE embedding MATCH ?\n      ORDER BY distance\n      LIMIT ?\n    `);\n\n    let candidates: Array<{ rowid: number; distance: number }>;\n    try {\n      candidates = candidateStmt.all(queryBuf, knnLimit) as Array<{\n        rowid: number;\n        distance: number;\n      }>;\n    } catch (err) {\n      log.error('SqliteVecStore.search KNN failed', {\n        error: err instanceof Error ? err.message : String(err),\n      });\n      throw err;\n    }\n\n    if (candidates.length === 0) return [];\n\n    const rowids = candidates.map(c => c.rowid);\n    const placeholders = rowids.map(() => '?').join(',');\n    const metaRows = this.db\n      .prepare(`\n        SELECT m.rowid AS rowid, m.external_id AS external_id,\n               meta.url AS url, meta.content_hash AS content_hash,\n               meta.model_id AS model_id, meta.extra_json AS extra_json\n        FROM vec_id_map m\n        JOIN vec_metadata meta ON m.rowid = meta.rowid\n        WHERE m.rowid IN (${placeholders})\n      `)\n      .all(...rowids) as Array<{\n        rowid: number;\n        external_id: string;\n        url: string;\n        content_hash: string;\n        model_id: string;\n        extra_json: string | null;\n      }>;\n\n    const metaByRowid = new Map<number, typeof metaRows[number]>();\n    for (const r of metaRows) metaByRowid.set(r.rowid, r);\n\n    const results: VectorSearchResult[] = [];\n    for (const cand of candidates) {\n      const meta = metaByRowid.get(cand.rowid);\n      if (!meta) continue;\n\n      const extra = meta.extra_json\n        ? (JSON.parse(meta.extra_json) as Record<string, unknown>)\n        : undefined;\n\n      const metadata: VectorMetadata = {\n        url: meta.url,\n        contentHash: meta.content_hash,\n        modelId: meta.model_id,\n        ...(extra ? { extra } : {}),\n      };\n\n      if (filter && !matchesFilter(metadata, filter)) continue;\n\n      results.push({\n        id: meta.external_id,\n        score: 1 / (1 + cand.distance),\n        metadata,\n      });\n\n      if (results.length >= limit) break;\n    }\n\n    return results;\n  }\n\n  async delete(ids: string[]): Promise<void> {\n    if (ids.length === 0) return;\n\n    const tx = this.db.transaction((items: string[]) => {\n      for (const id of items) {\n        const existing = this.upsertSelectStmt.get(id) as { rowid: number } | undefined;\n        if (!existing) continue;\n        this.deleteDocStmt.run(BigInt(existing.rowid));\n        this.deleteIdMapStmt.run(id);\n        // vec_metadata cascades via ON DELETE CASCADE on the id_map FK.\n      }\n    });\n\n    try {\n      tx(ids);\n    } catch (err) {\n      log.error('SqliteVecStore.delete failed', {\n        count: ids.length,\n        error: err instanceof Error ? err.message : String(err),\n      });\n      throw err;\n    }\n  }\n\n  async size(): Promise<number> {\n    const row = this.sizeStmt.get() as { c: number };\n    return row.c;\n  }\n}\n\nfunction matchesFilter(meta: VectorMetadata, filter: Partial<VectorMetadata>): boolean {\n  if (filter.url !== undefined && meta.url !== filter.url) return false;\n  if (filter.contentHash !== undefined && meta.contentHash !== filter.contentHash) return false;\n  if (filter.modelId !== undefined && meta.modelId !== filter.modelId) return false;\n  if (filter.extra !== undefined) {\n    const have = meta.extra ?? {};\n    for (const [k, v] of Object.entries(filter.extra)) {\n      if (have[k] !== v) return false;\n    }\n  }\n  return true;\n}\n"],"mappings":"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","names":[]}

package/dist/cache/store.d.ts

@@ -1,26 +1,71 @@
 import type { RawFetchResult, ExtractionResult, CachedContent, SearchResultItem, CacheStats } from '../types.js';
+/**
+ * Sanitize a user query for sqlite FTS5 MATCH.
+ *
+ * Why: bare tokens with `.` / `-` / `/` / `:` / digits-with-dot
+ * (e.g. "5.4", "x-y", "https://foo") raise `fts5: syntax error near "."`.
+ * Quoting tokens that aren't pure word-chars lets FTS5 treat them as phrases.
+ * Already-quoted phrases and explicit operators (AND/OR/NOT/parens) pass through.
+ */
+export declare function sanitizeFtsQuery(q: string): string;
 export declare function normalizeUrl(url: string): string;
 export declare function cacheContent(result: RawFetchResult, extraction: ExtractionResult): void;
 export declare function getCachedContent(url: string): CachedContent | null;
+export declare function getCachedContentByNormalizedUrl(normalizedUrl: string): CachedContent | null;
+export declare function getHashForNormalizedUrl(normalizedUrl: string): string | null;
+export declare function getMarkdownForNormalizedUrl(normalizedUrl: string): string | null;
 export declare function isExpired(cached: CachedContent): boolean;
+export interface CacheLookupOptions {
+    staleMaxSeconds?: number;
+}
+export declare function isCacheUsable(cached: CachedContent, opts?: CacheLookupOptions): {
+    usable: boolean;
+    stale: boolean;
+};
 export declare function searchCache(query: string): CachedContent[];
 export interface CachedSearchResult {
     query: string;
     results: SearchResultItem[];
     engines_used: string[];
     searched_at: string;
+    stale?: boolean;
 }
 export declare function cacheSearchResults(query: string, results: SearchResultItem[], enginesUsed: string[]): void;
-export declare function getCachedSearchResults(query: string): CachedSearchResult | null;
+export declare function getCachedSearchResults(query: string, opts?: CacheLookupOptions): CachedSearchResult | null;
 export declare function searchCacheFiltered(options: {
     query?: string;
     urlPattern?: string;
     since?: string;
 }): CachedContent[];
+/**
+ * BM25-ranked FTS5 search across cached pages. Returns normalized URLs
+ * paired with their rank score. `rank` from FTS5 is negative (lower is
+ * better in sqlite ordering), so we flip the sign to surface a "higher is
+ * better" score for consumers (e.g. RRF input).
+ */
+export declare function ftsSearchRanked(query: string, limit: number): Array<{
+    url: string;
+    score: number;
+}>;
 export declare function clearCacheEntries(options: {
     query?: string;
     urlPattern?: string;
     since?: string;
 }): number;
+export declare function countCachedUrlsForDomain(domain: string): number;
 export declare function getCacheStats(): CacheStats;
+export declare function updateCacheEmbedding(url: string, embedding: Buffer, model: string, dims: number): boolean;
+export interface EmbeddingData {
+    embedding: Buffer;
+    model: string;
+    dims: number;
+}
+export declare function getEmbeddingForUrl(url: string, modelId?: string): EmbeddingData | null;
+export interface StoredEmbedding {
+    normalizedUrl: string;
+    embedding: Buffer;
+    model: string;
+    dims: number;
+}
+export declare function getAllEmbeddings(modelId?: string): StoredEmbedding[];
 //# sourceMappingURL=store.d.ts.map

package/dist/cache/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBjH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA0BhD;AAMD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAsCvF;AAsCD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CASlE;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAGxD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAY1D;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EAAE,EAC3B,WAAW,EAAE,MAAM,EAAE,GACpB,IAAI,CAqBN;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAgB/E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,aAAa,EAAE,CA4BlB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CA0BT;AAED,wBAAgB,aAAa,IAAI,UAAU,CAiB1C"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"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"}