ralph-hero-knowledge-index 0.1.0

package/src/traverse.ts

@@ -0,0 +1,130 @@
+import type { KnowledgeDB } from "./db.js";
+
+export interface TraverseOptions {
+  type?: string;
+  depth?: number;
+}
+
+export interface TraverseResult {
+  sourceId: string;
+  targetId: string;
+  type: string;
+  depth: number;
+  doc: { title: string; status: string | null; date: string | null } | null;
+}
+
+export class Traverser {
+  private readonly db: KnowledgeDB;
+
+  constructor(db: KnowledgeDB) {
+    this.db = db;
+  }
+
+  traverse(fromId: string, options: TraverseOptions = {}): TraverseResult[] {
+    const { type, depth = 3 } = options;
+    const typeFilter = type ? "AND r.type = @type" : "";
+
+    const sql = `
+      WITH RECURSIVE chain AS (
+        SELECT r.source_id, r.target_id, r.type, 1 AS depth
+        FROM relationships r
+        WHERE r.source_id = @fromId ${typeFilter}
+
+        UNION ALL
+
+        SELECT r.source_id, r.target_id, r.type, c.depth + 1
+        FROM relationships r
+        JOIN chain c ON r.source_id = c.target_id
+        WHERE c.depth < @depth ${typeFilter}
+      )
+      SELECT
+        chain.source_id AS sourceId,
+        chain.target_id AS targetId,
+        chain.type,
+        chain.depth,
+        d.title AS docTitle,
+        d.status AS docStatus,
+        d.date AS docDate
+      FROM chain
+      LEFT JOIN documents d ON d.id = chain.target_id
+      ORDER BY chain.depth, chain.target_id
+    `;
+
+    const params: Record<string, unknown> = { fromId, depth };
+    if (type) params.type = type;
+
+    const rows = this.db.db.prepare(sql).all(params) as Array<{
+      sourceId: string;
+      targetId: string;
+      type: string;
+      depth: number;
+      docTitle: string | null;
+      docStatus: string | null;
+      docDate: string | null;
+    }>;
+
+    return rows.map((r) => ({
+      sourceId: r.sourceId,
+      targetId: r.targetId,
+      type: r.type,
+      depth: r.depth,
+      doc: r.docTitle != null
+        ? { title: r.docTitle, status: r.docStatus, date: r.docDate }
+        : null,
+    }));
+  }
+
+  traverseIncoming(toId: string, options: TraverseOptions = {}): TraverseResult[] {
+    const { type, depth = 3 } = options;
+    const typeFilter = type ? "AND r.type = @type" : "";
+
+    const sql = `
+      WITH RECURSIVE chain AS (
+        SELECT r.source_id, r.target_id, r.type, 1 AS depth
+        FROM relationships r
+        WHERE r.target_id = @toId ${typeFilter}
+
+        UNION ALL
+
+        SELECT r.source_id, r.target_id, r.type, c.depth + 1
+        FROM relationships r
+        JOIN chain c ON r.target_id = c.source_id
+        WHERE c.depth < @depth ${typeFilter}
+      )
+      SELECT
+        chain.source_id AS sourceId,
+        chain.target_id AS targetId,
+        chain.type,
+        chain.depth,
+        d.title AS docTitle,
+        d.status AS docStatus,
+        d.date AS docDate
+      FROM chain
+      LEFT JOIN documents d ON d.id = chain.source_id
+      ORDER BY chain.depth, chain.target_id
+    `;
+
+    const params: Record<string, unknown> = { toId, depth };
+    if (type) params.type = type;
+
+    const rows = this.db.db.prepare(sql).all(params) as Array<{
+      sourceId: string;
+      targetId: string;
+      type: string;
+      depth: number;
+      docTitle: string | null;
+      docStatus: string | null;
+      docDate: string | null;
+    }>;
+
+    return rows.map((r) => ({
+      sourceId: r.sourceId,
+      targetId: r.targetId,
+      type: r.type,
+      depth: r.depth,
+      doc: r.docTitle != null
+        ? { title: r.docTitle, status: r.docStatus, date: r.docDate }
+        : null,
+    }));
+  }
+}

package/src/vector-search.ts

@@ -0,0 +1,64 @@
+import * as sqliteVec from "sqlite-vec";
+import type { KnowledgeDB } from "./db.js";
+
+export interface VectorResult {
+  id: string;
+  distance: number;
+}
+
+function float32ToBuffer(arr: Float32Array): Buffer {
+  return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+
+export class VectorSearch {
+  private vecLoaded = false;
+
+  constructor(private knowledgeDb: KnowledgeDB) {}
+
+  private ensureVecLoaded(): void {
+    if (!this.vecLoaded) {
+      sqliteVec.load(this.knowledgeDb.db);
+      this.vecLoaded = true;
+    }
+  }
+
+  createIndex(): void {
+    this.ensureVecLoaded();
+    this.knowledgeDb.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS documents_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding float[384] distance_metric=cosine
+      )
+    `);
+  }
+
+  dropIndex(): void {
+    this.knowledgeDb.db.exec("DROP TABLE IF EXISTS documents_vec");
+  }
+
+  upsertEmbedding(id: string, embedding: Float32Array): void {
+    this.ensureVecLoaded();
+    const buf = float32ToBuffer(embedding);
+    this.knowledgeDb.db
+      .prepare("DELETE FROM documents_vec WHERE id = ?")
+      .run(id);
+    this.knowledgeDb.db
+      .prepare("INSERT INTO documents_vec (id, embedding) VALUES (?, ?)")
+      .run(id, buf);
+  }
+
+  search(queryEmbedding: Float32Array, limit: number = 10): VectorResult[] {
+    this.ensureVecLoaded();
+    const buf = float32ToBuffer(queryEmbedding);
+    return this.knowledgeDb.db
+      .prepare(
+        `
+      SELECT id, distance
+      FROM documents_vec
+      WHERE embedding MATCH ? AND k = ?
+      ORDER BY distance
+    `
+      )
+      .all(buf, limit) as VectorResult[];
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "sourceMap": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}