hana-kgvector 0.1.0

package/dist/index.js

@@ -0,0 +1,1036 @@
+import "./chunk-VUNV25KB.js";
+
+// src/env.ts
+import dotenv from "dotenv";
+function loadEnv() {
+  dotenv.config({ path: ".env.local" });
+}
+
+// src/hana/parse-host-port.ts
+function parseHostPort(host, fallbackPort) {
+  const idx = host.lastIndexOf(":");
+  if (idx > -1 && idx < host.length - 1) {
+    const maybePort = Number(host.slice(idx + 1));
+    if (!Number.isNaN(maybePort) && maybePort > 0) {
+      return { host: host.slice(0, idx), port: maybePort };
+    }
+  }
+  return { host, port: fallbackPort };
+}
+
+// src/hana/connection.ts
+async function createHanaConnection(config) {
+  let hana;
+  try {
+    const hanaModule = await import("./lib-J24D2XQX.js");
+    hana = hanaModule.default || hanaModule;
+  } catch {
+    throw new Error(
+      "@sap/hana-client is not available. Ensure it is installed and pnpm build scripts are approved (pnpm approve-builds)."
+    );
+  }
+  const fallbackPort = config.port ?? 443;
+  const { host, port } = parseHostPort(config.host, fallbackPort);
+  const conn = hana.createConnection();
+  await new Promise((resolve, reject) => {
+    conn.connect(
+      {
+        serverNode: `${host}:${port}`,
+        uid: config.user,
+        pwd: config.password,
+        encrypt: config.encrypt ?? true,
+        sslValidateCertificate: config.sslValidateCertificate ?? true
+      },
+      (err) => err ? reject(err) : resolve()
+    );
+  });
+  return conn;
+}
+async function hanaExec(conn, sql) {
+  return await new Promise((resolve, reject) => {
+    conn.exec(sql, (err, result) => {
+      if (err) return reject(err);
+      resolve(result);
+    });
+  });
+}
+
+// src/hana/sparql-store.ts
+var HanaSparqlStore = class {
+  conn;
+  constructor(conn) {
+    this.conn = conn;
+  }
+  async execute(options) {
+    const headerLines = [];
+    if (options.defaultGraphUri) {
+      headerLines.push(`rqx-default-graph-uri: ${options.defaultGraphUri}`);
+    }
+    if (options.headers) {
+      headerLines.push(options.headers.trim());
+    }
+    const hdrs = headerLines.length ? `${headerLines.join("\r\n")}\r
+` : "";
+    const sql = "CALL SPARQL_EXECUTE(?, ?, ?, ?)";
+    return await new Promise((resolve, reject) => {
+      this.conn.exec(sql, [options.sparql, hdrs, "", null], (err, result) => {
+        if (err) return reject(err);
+        resolve(result);
+      });
+    });
+  }
+  async loadTurtle(options) {
+    const requestHdrs = [
+      "rqx-load-protocol: true",
+      options.filename ? `rqx-load-filename: ${options.filename}` : void 0,
+      `rqx-load-graphname: ${options.graphName}`
+    ].filter(Boolean).join("\r\n");
+    return await this.execute({ sparql: options.turtle, headers: requestHdrs });
+  }
+};
+
+// src/graph/types.ts
+import { z } from "zod";
+var TRIPLET_SOURCE_KEY = "triplet_source_id";
+var KG_NODES_KEY = "kg_nodes";
+var KG_RELATIONS_KEY = "kg_relations";
+var VECTOR_SOURCE_KEY = "vector_source_id";
+var KG_SOURCE_REL = "HAS_SOURCE";
+var EntityNodeSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  name: z.string(),
+  properties: z.record(z.unknown()).default({}),
+  embedding: z.array(z.number()).optional()
+});
+var RelationSchema = z.object({
+  id: z.string().optional(),
+  label: z.string(),
+  sourceId: z.string(),
+  targetId: z.string(),
+  properties: z.record(z.unknown()).default({})
+});
+function createEntityNode(opts) {
+  const id = `${opts.label.toUpperCase()}_${opts.name.replace(/\s+/g, "_").toUpperCase()}`;
+  return {
+    id,
+    label: opts.label,
+    name: opts.name,
+    properties: opts.properties ?? {},
+    embedding: opts.embedding
+  };
+}
+function createRelation(opts) {
+  return {
+    id: `${opts.sourceId}_${opts.label}_${opts.targetId}`,
+    label: opts.label,
+    sourceId: opts.sourceId,
+    targetId: opts.targetId,
+    properties: opts.properties ?? {}
+  };
+}
+function tripletToString(triplet, includeProperties = false) {
+  const [subj, rel, obj] = triplet;
+  if (includeProperties) {
+    return `${subj.name} (${subj.label}) -[${rel.label}]-> ${obj.name} (${obj.label})`;
+  }
+  return `${subj.id} -> ${rel.label} -> ${obj.id}`;
+}
+
+// src/graph/hana-property-graph-store.ts
+var HanaPropertyGraphStore = class {
+  conn;
+  graphName;
+  vectorTableName;
+  llamaNodesTableName;
+  resetTables;
+  initialized = false;
+  supportsVectorQueries = true;
+  supportsStructuredQueries = true;
+  constructor(conn, options) {
+    this.conn = conn;
+    this.graphName = options.graphName;
+    this.vectorTableName = options.vectorTableName ?? `${options.graphName.replace(/[^a-zA-Z0-9]/g, "_")}_VECTORS`;
+    this.llamaNodesTableName = options.llamaNodesTableName ?? `${options.graphName.replace(/[^a-zA-Z0-9]/g, "_")}_NODES`;
+    this.resetTables = options.resetTables ?? false;
+  }
+  async ensureInitialized() {
+    if (this.initialized) return;
+    if (this.resetTables) {
+      await this.exec(`DROP TABLE ${this.vectorTableName}`).catch(() => {
+      });
+      await this.exec(`DROP TABLE ${this.llamaNodesTableName}`).catch(() => {
+      });
+      await this.sparqlExecute(`CLEAR GRAPH <${this.graphName}>`).catch(() => {
+      });
+    }
+    const createVectorTable = `
+      CREATE COLUMN TABLE ${this.vectorTableName} (
+        id NVARCHAR(512) PRIMARY KEY,
+        node_type NVARCHAR(64),
+        label NVARCHAR(128),
+        name NVARCHAR(512),
+        properties NCLOB,
+        embedding REAL_VECTOR
+      )
+    `;
+    await this.exec(createVectorTable).catch((err) => {
+      const message = String(err?.message ?? "");
+      if (!/exists|duplicate table name/i.test(message)) {
+        throw err;
+      }
+    });
+    const createLlamaTable = `
+      CREATE COLUMN TABLE ${this.llamaNodesTableName} (
+        id NVARCHAR(512) PRIMARY KEY,
+        text NCLOB,
+        metadata NCLOB,
+        hash NVARCHAR(64),
+        embedding REAL_VECTOR
+      )
+    `;
+    await this.exec(createLlamaTable).catch((err) => {
+      const message = String(err?.message ?? "");
+      if (!/exists|duplicate table name/i.test(message)) {
+        throw err;
+      }
+    });
+    this.initialized = true;
+  }
+  async exec(sql, params) {
+    return new Promise((resolve, reject) => {
+      if (params && params.length > 0) {
+        this.conn.exec(sql, params, (err, result) => {
+          if (err) reject(err);
+          else resolve(result);
+        });
+      } else {
+        this.conn.exec(sql, (err, result) => {
+          if (err) reject(err);
+          else resolve(result);
+        });
+      }
+    });
+  }
+  async sparqlExecute(sparql, headers = "") {
+    try {
+      const streamMod = await import("./Stream-JW2S2DUH.js");
+      const Stream = streamMod.default ?? streamMod;
+      return await new Promise((resolve, reject) => {
+        Stream.createProcStatement(this.conn, "CALL SPARQL_EXECUTE(?, ?, ?, ?)", (err, stmt) => {
+          if (err) return reject(err);
+          stmt.exec([sparql, headers], (err2, scalarParams) => {
+            if (err2) return reject(err2);
+            resolve(scalarParams);
+          });
+        });
+      });
+    } catch {
+      return await new Promise((resolve, reject) => {
+        this.conn.exec(
+          "CALL SPARQL_EXECUTE(?, ?, ?, ?)",
+          // Important: only pass IN params; OUT params are placeholders in SQL.
+          [sparql, headers],
+          (err, result) => {
+            if (err) reject(err);
+            else resolve(result);
+          }
+        );
+      });
+    }
+  }
+  entityToUri(node) {
+    return `<urn:hkv:${this.graphName}:${node.label}:${encodeURIComponent(node.id)}>`;
+  }
+  relationToTriples(rel, subj, obj) {
+    const subjUri = this.entityToUri(subj);
+    const objUri = this.entityToUri(obj);
+    const predUri = `<urn:hkv:rel:${rel.label}>`;
+    return `${subjUri} ${predUri} ${objUri} .`;
+  }
+  entityToTriples(node) {
+    const uri = this.entityToUri(node);
+    const lines = [];
+    lines.push(`${uri} a <urn:hkv:type:${node.label}> .`);
+    lines.push(`${uri} <urn:hkv:prop:name> "${this.escapeLiteral(node.name)}" .`);
+    for (const [key, value] of Object.entries(node.properties)) {
+      if (value !== void 0 && value !== null) {
+        const escaped = typeof value === "string" ? this.escapeLiteral(value) : String(value);
+        lines.push(`${uri} <urn:hkv:prop:${key}> "${escaped}" .`);
+      }
+    }
+    return lines.join("\n");
+  }
+  escapeLiteral(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+  }
+  async upsertNodes(nodes) {
+    await this.ensureInitialized();
+    if (nodes.length === 0) return;
+    const triples = nodes.map((n) => this.entityToTriples(n)).join("\n");
+    const sparql = `INSERT DATA { GRAPH <${this.graphName}> { ${triples} } }`;
+    await this.sparqlExecute(sparql);
+    for (const node of nodes) {
+      if (node.embedding) {
+        const safeProps = { ...node.properties ?? {} };
+        delete safeProps.kg_nodes;
+        delete safeProps.kg_relations;
+        const sql = `
+          UPSERT ${this.vectorTableName} (id, node_type, label, name, properties, embedding)
+          VALUES (?, 'entity', ?, ?, ?, TO_REAL_VECTOR(?))
+          WITH PRIMARY KEY
+        `;
+        await this.exec(sql, [
+          node.id,
+          node.label,
+          node.name,
+          JSON.stringify(safeProps),
+          JSON.stringify(node.embedding)
+        ]);
+      }
+    }
+  }
+  async upsertRelations(relations) {
+    await this.ensureInitialized();
+    if (relations.length === 0) return;
+    const nodeIds = /* @__PURE__ */ new Set();
+    for (const rel of relations) {
+      nodeIds.add(rel.sourceId);
+      nodeIds.add(rel.targetId);
+    }
+    const existingNodes = await this.get({ ids: Array.from(nodeIds) });
+    const nodeMap = new Map(existingNodes.map((n) => [n.id, n]));
+    const lines = [];
+    for (const rel of relations) {
+      const subj = nodeMap.get(rel.sourceId);
+      const obj = nodeMap.get(rel.targetId);
+      if (subj && obj) {
+        lines.push(this.relationToTriples(rel, subj, obj));
+      }
+    }
+    if (lines.length > 0) {
+      const sparql = `INSERT DATA { GRAPH <${this.graphName}> { ${lines.join("\n")} } }`;
+      await this.sparqlExecute(sparql);
+    }
+  }
+  async get(opts) {
+    await this.ensureInitialized();
+    if (opts.ids.length === 0) return [];
+    const rows = await this.exec(
+      `SELECT id, label, name, properties FROM ${this.vectorTableName} WHERE id IN (${opts.ids.map(() => "?").join(",")})`,
+      opts.ids
+    );
+    return (rows ?? []).map((r) => ({
+      id: r.ID ?? r.id,
+      label: r.LABEL ?? r.label,
+      name: r.NAME ?? r.name,
+      properties: JSON.parse(r.PROPERTIES ?? r.properties ?? "{}")
+    }));
+  }
+  async getRelMap(opts) {
+    await this.ensureInitialized();
+    if (opts.nodes.length === 0) return [];
+    const nodeIds = opts.nodes.map((n) => n.id);
+    const depth = opts.depth ?? 1;
+    const limit = opts.limit ?? 100;
+    const ignoreRels = opts.ignoreRels ?? [KG_SOURCE_REL];
+    const filterClause = nodeIds.map((id) => `CONTAINS(STR(?s), "${encodeURIComponent(id)}") || CONTAINS(STR(?o), "${encodeURIComponent(id)}")`).join(" || ");
+    const ignoreFilter = ignoreRels.length > 0 ? `FILTER(${ignoreRels.map((r) => `!CONTAINS(STR(?p), "${r}")`).join(" && ")})` : "";
+    const sparql = `
+      SELECT ?s ?p ?o
+      FROM <${this.graphName}>
+      WHERE {
+        ?s ?p ?o .
+        FILTER(${filterClause})
+        ${ignoreFilter}
+      }
+      LIMIT ${limit}
+    `;
+    const result = await this.exec(
+      `SELECT * FROM SPARQL_TABLE('${sparql.replace(/'/g, "''")}')`
+    );
+    const triplets = [];
+    const nodeMap = new Map(opts.nodes.map((n) => [n.id, n]));
+    for (const row of result ?? []) {
+      const sUri = row.S ?? row.s;
+      const pUri = row.P ?? row.p;
+      const oUri = row.O ?? row.o;
+      const sId = this.extractIdFromUri(sUri);
+      const oId = this.extractIdFromUri(oUri);
+      const relLabel = this.extractRelLabelFromUri(pUri);
+      let subj = nodeMap.get(sId);
+      let obj = nodeMap.get(oId);
+      if (!subj) {
+        subj = { id: sId, label: "UNKNOWN", name: sId, properties: {} };
+      }
+      if (!obj) {
+        obj = { id: oId, label: "UNKNOWN", name: oId, properties: {} };
+      }
+      const rel = {
+        label: relLabel,
+        sourceId: sId,
+        targetId: oId,
+        properties: {}
+      };
+      triplets.push([subj, rel, obj]);
+    }
+    return triplets;
+  }
+  extractIdFromUri(uri) {
+    const cleanUri = uri.replace(/^<|>$/g, "");
+    const parts = cleanUri.split(":");
+    if (parts.length >= 2) {
+      return decodeURIComponent(parts[parts.length - 1]);
+    }
+    return uri;
+  }
+  extractRelLabelFromUri(uri) {
+    const match = uri.match(/urn:hkv:rel:(.+)>?$/);
+    return match ? match[1].replace(/>$/, "") : uri;
+  }
+  async delete(opts) {
+    await this.ensureInitialized();
+    if (opts.ids.length === 0) return;
+    for (const id of opts.ids) {
+      await this.exec(`DELETE FROM ${this.vectorTableName} WHERE id = ?`, [id]);
+    }
+  }
+  async vectorQuery(query) {
+    await this.ensureInitialized();
+    const sql = `
+      SELECT id, label, name, properties,
+        COSINE_SIMILARITY(embedding, TO_REAL_VECTOR(?)) AS score
+      FROM ${this.vectorTableName}
+      WHERE embedding IS NOT NULL
+      ORDER BY score DESC
+      LIMIT ?
+    `;
+    const rows = await this.exec(sql, [
+      JSON.stringify(query.queryEmbedding),
+      query.similarityTopK
+    ]);
+    const nodes = [];
+    const scores = [];
+    for (const row of rows ?? []) {
+      nodes.push({
+        id: row.ID ?? row.id,
+        label: row.LABEL ?? row.label,
+        name: row.NAME ?? row.name,
+        properties: JSON.parse(row.PROPERTIES ?? row.properties ?? "{}")
+      });
+      scores.push(row.SCORE ?? row.score ?? 0);
+    }
+    return [nodes, scores];
+  }
+  async upsertLlamaNodes(nodes) {
+    await this.ensureInitialized();
+    for (const node of nodes) {
+      const { metadata, ...rest } = node;
+      const safeMetadata = { ...metadata };
+      delete safeMetadata.kg_nodes;
+      delete safeMetadata.kg_relations;
+      const sql = `
+        UPSERT ${this.llamaNodesTableName} (id, text, metadata, hash, embedding)
+        VALUES (?, ?, ?, ?, ${node.embedding ? "TO_REAL_VECTOR(?)" : "NULL"})
+        WITH PRIMARY KEY
+      `;
+      const params = [
+        node.id,
+        node.text,
+        JSON.stringify(safeMetadata ?? {}),
+        node.hash ?? null
+      ];
+      if (node.embedding) {
+        params.push(JSON.stringify(node.embedding));
+      }
+      await this.exec(sql, params);
+    }
+  }
+  async getLlamaNodes(ids) {
+    await this.ensureInitialized();
+    if (ids.length === 0) return [];
+    const rows = await this.exec(
+      `SELECT id, text, metadata, hash FROM ${this.llamaNodesTableName} WHERE id IN (${ids.map(() => "?").join(",")})`,
+      ids
+    );
+    return (rows ?? []).map((r) => ({
+      id: r.ID ?? r.id,
+      text: r.TEXT ?? r.text,
+      metadata: JSON.parse(r.METADATA ?? r.metadata ?? "{}"),
+      hash: r.HASH ?? r.hash
+    }));
+  }
+};
+
+// src/graph/pg-retriever.ts
+var PGRetriever = class {
+  subRetrievers;
+  showProgress;
+  constructor(options) {
+    this.subRetrievers = options.subRetrievers;
+    this.showProgress = options.showProgress ?? false;
+  }
+  deduplicate(nodes) {
+    const seen = /* @__PURE__ */ new Set();
+    const deduped = [];
+    for (const node of nodes) {
+      if (!seen.has(node.node.text)) {
+        deduped.push(node);
+        seen.add(node.node.text);
+      }
+    }
+    return deduped;
+  }
+  async retrieve(queryBundle) {
+    const allResults = [];
+    const promises = this.subRetrievers.map((r) => r.retrieve(queryBundle));
+    const results = await Promise.all(promises);
+    for (const result of results) {
+      allResults.push(...result);
+    }
+    return this.deduplicate(allResults);
+  }
+};
+
+// src/graph/retrievers/base.ts
+var DEFAULT_PREAMBLE = "Here are some facts extracted from the provided text:\n\n";
+var BasePGRetriever = class {
+  graphStore;
+  includeText;
+  includeTextPreamble;
+  includeProperties;
+  constructor(options) {
+    this.graphStore = options.graphStore;
+    this.includeText = options.includeText ?? true;
+    this.includeTextPreamble = options.includeTextPreamble ?? DEFAULT_PREAMBLE;
+    this.includeProperties = options.includeProperties ?? false;
+  }
+  getNodesWithScore(triplets, scores) {
+    const results = [];
+    for (let i = 0; i < triplets.length; i++) {
+      const triplet = triplets[i];
+      const sourceId = triplet[0].properties[TRIPLET_SOURCE_KEY];
+      const text = tripletToString(triplet, this.includeProperties);
+      results.push({
+        node: {
+          id: `triplet_${i}`,
+          text,
+          metadata: {},
+          refDocId: sourceId
+        },
+        score: scores?.[i] ?? 1
+      });
+    }
+    return results;
+  }
+  async addSourceText(nodes) {
+    if (!this.graphStore.getLlamaNodes) {
+      return nodes;
+    }
+    const refDocIds = nodes.map((n) => n.node.refDocId).filter((id) => id !== void 0);
+    if (refDocIds.length === 0) return nodes;
+    const ogNodes = await this.graphStore.getLlamaNodes(refDocIds);
+    const nodeMap = new Map(ogNodes.map((n) => [n.id, n]));
+    const graphNodeMap = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      const refDocId = node.node.refDocId ?? "";
+      if (!graphNodeMap.has(refDocId)) {
+        graphNodeMap.set(refDocId, []);
+      }
+      graphNodeMap.get(refDocId).push(node.node.text);
+    }
+    const resultNodes = [];
+    for (const nodeWithScore of nodes) {
+      const mappedNode = nodeMap.get(nodeWithScore.node.refDocId ?? "");
+      if (mappedNode) {
+        const graphContent = graphNodeMap.get(mappedNode.id) ?? [];
+        if (graphContent.length > 0) {
+          const graphContentStr = graphContent.join("\n");
+          const newContent = this.includeTextPreamble + graphContentStr + "\n\n" + mappedNode.text;
+          resultNodes.push({
+            node: {
+              id: mappedNode.id,
+              text: newContent,
+              metadata: mappedNode.metadata,
+              refDocId: nodeWithScore.node.refDocId
+            },
+            score: nodeWithScore.score
+          });
+        } else {
+          resultNodes.push({
+            node: {
+              id: mappedNode.id,
+              text: mappedNode.text,
+              metadata: mappedNode.metadata,
+              refDocId: nodeWithScore.node.refDocId
+            },
+            score: nodeWithScore.score
+          });
+        }
+      } else {
+        resultNodes.push(nodeWithScore);
+      }
+    }
+    return resultNodes;
+  }
+  async retrieve(queryBundle) {
+    let nodes = await this.retrieveFromGraph(queryBundle);
+    if (this.includeText && nodes.length > 0) {
+      nodes = await this.addSourceText(nodes);
+    }
+    return nodes;
+  }
+};
+
+// src/graph/retrievers/vector-context.ts
+var VectorContextRetriever = class extends BasePGRetriever {
+  embedModel;
+  similarityTopK;
+  pathDepth;
+  limit;
+  similarityScore;
+  crossCheckBoost;
+  crossCheckBoostFactor;
+  constructor(options) {
+    super(options);
+    this.embedModel = options.embedModel;
+    this.similarityTopK = options.similarityTopK ?? 4;
+    this.pathDepth = options.pathDepth ?? 1;
+    this.limit = options.limit ?? 30;
+    this.similarityScore = options.similarityScore;
+    this.crossCheckBoost = options.crossCheckBoost ?? true;
+    this.crossCheckBoostFactor = options.crossCheckBoostFactor ?? 1.25;
+  }
+  async retrieveFromGraph(queryBundle) {
+    let embedding = queryBundle.embedding;
+    if (!embedding) {
+      embedding = await this.embedModel.getTextEmbedding(queryBundle.queryStr);
+    }
+    const vectorQuery = {
+      queryEmbedding: embedding,
+      similarityTopK: this.similarityTopK
+    };
+    if (!this.graphStore.supportsVectorQueries || !this.graphStore.vectorQuery) {
+      throw new Error("Graph store does not support vector queries");
+    }
+    const [kgNodes, scores] = await this.graphStore.vectorQuery(vectorQuery);
+    if (kgNodes.length === 0) {
+      return [];
+    }
+    const kgIds = kgNodes.map((n) => n.id);
+    const provenanceSet = /* @__PURE__ */ new Set();
+    if (this.crossCheckBoost) {
+      for (const node of kgNodes) {
+        provenanceSet.add(node.id.toLowerCase());
+        provenanceSet.add(node.name.toLowerCase());
+        const props = node.properties ?? {};
+        if (props.documentId) {
+          provenanceSet.add(String(props.documentId).toLowerCase());
+        }
+        if (props.sourceChunk) {
+          provenanceSet.add(String(props.sourceChunk).toLowerCase());
+        }
+      }
+    }
+    const triplets = await this.graphStore.getRelMap({
+      nodes: kgNodes,
+      depth: this.pathDepth,
+      limit: this.limit,
+      ignoreRels: [KG_SOURCE_REL]
+    });
+    const newScores = [];
+    for (const triplet of triplets) {
+      const idx1 = kgIds.indexOf(triplet[0].id);
+      const idx2 = kgIds.indexOf(triplet[2].id);
+      const score1 = idx1 >= 0 ? scores[idx1] : 0;
+      const score2 = idx2 >= 0 ? scores[idx2] : 0;
+      let baseScore = Math.max(score1, score2);
+      if (this.crossCheckBoost && baseScore > 0) {
+        const shouldBoost = this.checkProvenance(triplet[0], provenanceSet) || this.checkProvenance(triplet[2], provenanceSet);
+        if (shouldBoost) {
+          baseScore = Math.min(1, baseScore * this.crossCheckBoostFactor);
+        }
+      }
+      newScores.push(baseScore);
+    }
+    let results = triplets.map((t, i) => ({ triplet: t, score: newScores[i] }));
+    if (this.similarityScore !== void 0) {
+      results = results.filter((r) => r.score >= this.similarityScore);
+    }
+    results.sort((a, b) => b.score - a.score);
+    return this.getNodesWithScore(
+      results.map((r) => r.triplet),
+      results.map((r) => r.score)
+    );
+  }
+  /**
+   * Check if a node has provenance linking to the vector-matched nodes.
+   * Returns true if the node's properties contain a documentId or sourceChunk
+   * that matches something in the provenance set.
+   */
+  checkProvenance(node, provenanceSet) {
+    if (provenanceSet.size === 0) return false;
+    const props = node.properties ?? {};
+    if (props.documentId && provenanceSet.has(String(props.documentId).toLowerCase())) {
+      return true;
+    }
+    if (props.sourceChunk && provenanceSet.has(String(props.sourceChunk).toLowerCase())) {
+      return true;
+    }
+    if (provenanceSet.has(node.id.toLowerCase()) || provenanceSet.has(node.name.toLowerCase())) {
+      return true;
+    }
+    return false;
+  }
+};
+
+// src/graph/extractors/implicit.ts
+var ImplicitPathExtractor = class {
+  async transform(nodes, options) {
+    const results = [];
+    for (const node of nodes) {
+      const existingNodes = node.metadata[KG_NODES_KEY] ?? [];
+      const existingRelations = node.metadata[KG_RELATIONS_KEY] ?? [];
+      const safeMetadata = { ...node.metadata };
+      delete safeMetadata[KG_NODES_KEY];
+      delete safeMetadata[KG_RELATIONS_KEY];
+      const chunkNode = createEntityNode({
+        label: "CHUNK",
+        name: node.id,
+        properties: {
+          text: node.text.slice(0, 500),
+          ...safeMetadata
+        }
+      });
+      if (node.metadata.documentId) {
+        const docNode = createEntityNode({
+          label: "DOCUMENT",
+          name: String(node.metadata.documentId),
+          properties: {}
+        });
+        const rel = createRelation({
+          label: "FROM_DOCUMENT",
+          sourceId: chunkNode.id,
+          targetId: docNode.id
+        });
+        existingNodes.push(docNode);
+        existingRelations.push(rel);
+      }
+      existingNodes.push(chunkNode);
+      results.push({
+        ...node,
+        metadata: {
+          ...node.metadata,
+          [KG_NODES_KEY]: existingNodes,
+          [KG_RELATIONS_KEY]: existingRelations
+        }
+      });
+    }
+    return results;
+  }
+};
+
+// src/graph/property-graph-index.ts
+import { createHash } from "crypto";
+var PropertyGraphIndex = class _PropertyGraphIndex {
+  propertyGraphStore;
+  kgExtractors;
+  embedModel;
+  embedKgNodes;
+  showProgress;
+  constructor(options) {
+    this.propertyGraphStore = options.propertyGraphStore;
+    this.kgExtractors = options.kgExtractors ?? [new ImplicitPathExtractor()];
+    this.embedModel = options.embedModel;
+    this.embedKgNodes = options.embedKgNodes ?? true;
+    this.showProgress = options.showProgress ?? false;
+  }
+  get graphStore() {
+    return this.propertyGraphStore;
+  }
+  static fromExisting(options) {
+    return new _PropertyGraphIndex(options);
+  }
+  computeHash(text) {
+    return createHash("md5").update(text).digest("hex");
+  }
+  async insert(nodes) {
+    if (nodes.length === 0) return [];
+    let processedNodes = nodes;
+    for (const extractor of this.kgExtractors) {
+      processedNodes = await extractor.transform(processedNodes, {
+        showProgress: this.showProgress
+      });
+    }
+    for (const node of processedNodes) {
+      if (!node.metadata[KG_NODES_KEY] && !node.metadata[KG_RELATIONS_KEY]) {
+        throw new Error(`Node ${node.id} has no KG_NODES_KEY or KG_RELATIONS_KEY after extraction`);
+      }
+    }
+    const kgNodesToInsert = [];
+    const kgRelsToInsert = [];
+    for (const node of processedNodes) {
+      const kgNodes = node.metadata[KG_NODES_KEY] ?? [];
+      const kgRels = node.metadata[KG_RELATIONS_KEY] ?? [];
+      for (const kgNode of kgNodes) {
+        kgNode.properties[TRIPLET_SOURCE_KEY] = node.id;
+      }
+      for (const kgRel of kgRels) {
+        kgRel.properties[TRIPLET_SOURCE_KEY] = node.id;
+      }
+      kgNodesToInsert.push(...kgNodes);
+      kgRelsToInsert.push(...kgRels);
+    }
+    const kgNodeIds = [...new Set(kgNodesToInsert.map((n) => n.id))];
+    const existingKgNodes = await this.propertyGraphStore.get({ ids: kgNodeIds });
+    const existingKgNodeIds = new Set(existingKgNodes.map((n) => n.id));
+    const newKgNodes = kgNodesToInsert.filter((n) => !existingKgNodeIds.has(n.id));
+    if (this.propertyGraphStore.getLlamaNodes) {
+      const existingLlamaNodes = await this.propertyGraphStore.getLlamaNodes(
+        processedNodes.map((n) => n.id)
+      );
+      const existingHashes = new Set(existingLlamaNodes.map((n) => n.hash));
+      processedNodes = processedNodes.filter((n) => {
+        const hash = this.computeHash(n.text);
+        n.hash = hash;
+        return !existingHashes.has(hash);
+      });
+    }
+    if (this.embedKgNodes && this.embedModel && newKgNodes.length > 0) {
+      const nodeTexts = processedNodes.map((n) => n.text);
+      const embeddings = await this.embedModel.getTextEmbeddingBatch(nodeTexts);
+      for (let i = 0; i < processedNodes.length; i++) {
+        processedNodes[i].embedding = embeddings[i];
+      }
+      const kgNodeTexts = newKgNodes.map((n) => `${n.label}: ${n.name}`);
+      const kgEmbeddings = await this.embedModel.getTextEmbeddingBatch(kgNodeTexts);
+      for (let i = 0; i < newKgNodes.length; i++) {
+        newKgNodes[i].embedding = kgEmbeddings[i];
+      }
+    }
+    if (this.propertyGraphStore.upsertLlamaNodes && processedNodes.length > 0) {
+      await this.propertyGraphStore.upsertLlamaNodes(
+        processedNodes.map((n) => ({
+          id: n.id,
+          text: n.text,
+          metadata: n.metadata,
+          embedding: n.embedding,
+          hash: n.hash
+        }))
+      );
+    }
+    if (newKgNodes.length > 0) {
+      await this.propertyGraphStore.upsertNodes(newKgNodes);
+    }
+    if (kgRelsToInsert.length > 0) {
+      await this.propertyGraphStore.upsertRelations(kgRelsToInsert);
+    }
+    return processedNodes;
+  }
+  async delete(nodeIds) {
+    await this.propertyGraphStore.delete({ ids: nodeIds });
+  }
+  asRetriever(options) {
+    let subRetrievers = options?.subRetrievers;
+    if (!subRetrievers && this.embedModel && this.propertyGraphStore.supportsVectorQueries) {
+      subRetrievers = [
+        new VectorContextRetriever({
+          graphStore: this.propertyGraphStore,
+          embedModel: this.embedModel,
+          includeText: options?.includeText ?? true,
+          similarityTopK: options?.similarityTopK,
+          pathDepth: options?.pathDepth,
+          limit: options?.limit,
+          similarityScore: options?.similarityScore,
+          crossCheckBoost: options?.crossCheckBoost,
+          crossCheckBoostFactor: options?.crossCheckBoostFactor
+        })
+      ];
+    }
+    if (!subRetrievers) {
+      subRetrievers = [];
+    }
+    return new PGRetriever({ subRetrievers });
+  }
+  async query(queryStr, options) {
+    const retriever = this.asRetriever(options);
+    return retriever.retrieve({ queryStr });
+  }
+};
+
+// src/graph/extractors/schema-llm.ts
+import { z as z2 } from "zod";
+var DEFAULT_EXTRACT_PROMPT = `Given the following text, extract a knowledge graph according to the provided schema.
+Try to limit to {maxTriplets} extracted paths.
+
+Schema:
+- Entity types: {entityTypes}
+- Relation types: {relationTypes}
+- Valid relationships: {validationSchema}
+
+Text:
+-------
+{text}
+-------
+
+Extract entities and relationships from the text above.
+Return your answer as a JSON object with a "triplets" array. Each triplet should have:
+- "subject": { "name": string, "type": one of [{entityTypes}] }
+- "relation": { "type": one of [{relationTypes}] }
+- "object": { "name": string, "type": one of [{entityTypes}] }
+
+Example output format:
+{
+  "triplets": [
+    {
+      "subject": { "name": "John", "type": "PERSON" },
+      "relation": { "type": "WORKS_AT" },
+      "object": { "name": "Acme Corp", "type": "ORGANIZATION" }
+    }
+  ]
+}`;
+var SchemaLLMPathExtractor = class {
+  llm;
+  schema;
+  maxTripletsPerChunk;
+  strict;
+  extractPromptTemplate;
+  tripletSchema;
+  constructor(options) {
+    this.llm = options.llm;
+    this.schema = options.schema;
+    this.maxTripletsPerChunk = options.maxTripletsPerChunk ?? 10;
+    this.strict = options.strict ?? true;
+    this.extractPromptTemplate = options.extractPromptTemplate ?? DEFAULT_EXTRACT_PROMPT;
+    const entityTypeEnum = z2.enum(this.schema.entityTypes);
+    const relationTypeEnum = z2.enum(this.schema.relationTypes);
+    const entitySchema = z2.object({
+      name: z2.string(),
+      type: entityTypeEnum,
+      properties: z2.record(z2.unknown()).optional()
+    });
+    const relationSchema = z2.object({
+      type: relationTypeEnum,
+      properties: z2.record(z2.unknown()).optional()
+    });
+    const tripletSchema = z2.object({
+      subject: entitySchema,
+      relation: relationSchema,
+      object: entitySchema
+    });
+    this.tripletSchema = z2.object({
+      triplets: z2.array(tripletSchema)
+    });
+  }
+  buildPrompt(text) {
+    const validationSchemaStr = this.schema.validationSchema?.map(([s, r, o]) => `(${s})-[${r}]->(${o})`).join(", ") ?? "Any valid combination";
+    return this.extractPromptTemplate.replace("{maxTriplets}", String(this.maxTripletsPerChunk)).replace("{entityTypes}", this.schema.entityTypes.join(", ")).replace("{relationTypes}", this.schema.relationTypes.join(", ")).replace("{validationSchema}", validationSchemaStr).replace("{text}", text);
+  }
+  isValidTriplet(subjectType, relationType, objectType) {
+    if (!this.strict || !this.schema.validationSchema) {
+      return true;
+    }
+    return this.schema.validationSchema.some(
+      ([s, r, o]) => s.toUpperCase() === subjectType.toUpperCase() && r.toUpperCase() === relationType.toUpperCase() && o.toUpperCase() === objectType.toUpperCase()
+    );
+  }
+  pruneInvalidTriplets(extracted) {
+    const validTriplets = [];
+    for (const triplet of extracted.triplets) {
+      const subjectType = String(triplet.subject.type).toUpperCase().replace(/\s+/g, "_");
+      const relationType = String(triplet.relation.type).toUpperCase().replace(/\s+/g, "_");
+      const objectType = String(triplet.object.type).toUpperCase().replace(/\s+/g, "_");
+      if (!this.isValidTriplet(subjectType, relationType, objectType)) {
+        continue;
+      }
+      const subjectName = String(triplet.subject.name).trim();
+      const objectName = String(triplet.object.name).trim();
+      if (subjectName.toLowerCase() === objectName.toLowerCase()) {
+        continue;
+      }
+      const subj = createEntityNode({
+        label: subjectType,
+        name: subjectName,
+        properties: triplet.subject.properties ?? {}
+      });
+      const obj = createEntityNode({
+        label: objectType,
+        name: objectName,
+        properties: triplet.object.properties ?? {}
+      });
+      const rel = createRelation({
+        label: relationType,
+        sourceId: subj.id,
+        targetId: obj.id,
+        properties: triplet.relation.properties ?? {}
+      });
+      validTriplets.push([subj, rel, obj]);
+    }
+    return validTriplets;
+  }
+  async extractFromNode(node) {
+    const prompt = this.buildPrompt(node.text);
+    let triplets = [];
+    try {
+      const result = await this.llm.structuredPredict(this.tripletSchema, prompt);
+      triplets = this.pruneInvalidTriplets(result);
+    } catch (err) {
+      console.warn(`[SchemaLLMPathExtractor] Failed to extract from node ${node.id}:`, err);
+      triplets = [];
+    }
+    const existingNodes = node.metadata[KG_NODES_KEY] ?? [];
+    const existingRelations = node.metadata[KG_RELATIONS_KEY] ?? [];
+    const safeMetadata = { ...node.metadata };
+    delete safeMetadata[KG_NODES_KEY];
+    delete safeMetadata[KG_RELATIONS_KEY];
+    for (const [subj, rel, obj] of triplets) {
+      subj.properties = { ...subj.properties, ...safeMetadata };
+      obj.properties = { ...obj.properties, ...safeMetadata };
+      rel.properties = { ...rel.properties, ...safeMetadata };
+      existingNodes.push(subj);
+      existingNodes.push(obj);
+      existingRelations.push(rel);
+    }
+    return {
+      ...node,
+      metadata: {
+        ...node.metadata,
+        [KG_NODES_KEY]: existingNodes,
+        [KG_RELATIONS_KEY]: existingRelations
+      }
+    };
+  }
+  async transform(nodes, options) {
+    const results = [];
+    for (const node of nodes) {
+      const processed = await this.extractFromNode(node);
+      results.push(processed);
+    }
+    return results;
+  }
+};
+export {
+  BasePGRetriever,
+  DEFAULT_PREAMBLE,
+  EntityNodeSchema,
+  HanaPropertyGraphStore,
+  HanaSparqlStore,
+  ImplicitPathExtractor,
+  KG_NODES_KEY,
+  KG_RELATIONS_KEY,
+  KG_SOURCE_REL,
+  PGRetriever,
+  PropertyGraphIndex,
+  RelationSchema,
+  SchemaLLMPathExtractor,
+  TRIPLET_SOURCE_KEY,
+  VECTOR_SOURCE_KEY,
+  VectorContextRetriever,
+  createEntityNode,
+  createHanaConnection,
+  createRelation,
+  hanaExec,
+  loadEnv,
+  tripletToString
+};
+//# sourceMappingURL=index.js.map