@promptev/context-engine 0.0.0

package/dist/graph/index.cjs

@@ -0,0 +1,1428 @@
+'use strict';
+
+var OpenAI = require('openai');
+var crypto = require('crypto');
+var jsonrepair = require('jsonrepair');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var OpenAI__default = /*#__PURE__*/_interopDefault(OpenAI);
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var ExtraMissingError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    ExtraMissingError = class extends Error {
+      constructor(extra, pkg, what) {
+        super(`${what} requires the '${pkg}' package (optional extra: ${extra}): npm install ${pkg}`);
+        this.name = "ExtraMissingError";
+      }
+    };
+  }
+});
+
+// src/extras.ts
+async function requireExtra(specifier, extra, what) {
+  try {
+    return await import(specifier);
+  } catch (_err) {
+    throw new ExtraMissingError(extra, specifier, what);
+  }
+}
+var init_extras = __esm({
+  "src/extras.ts"() {
+    init_errors();
+  }
+});
+
+// src/hooks.ts
+function emitError(hooks, exc, ctx) {
+  log.error("context_engine error:", exc, "| ctx=", ctx);
+  if (!hooks?.onError) return;
+  try {
+    hooks.onError(exc, ctx);
+  } catch {
+    log.warn("onError callback raised; swallowing");
+  }
+}
+var log;
+var init_hooks = __esm({
+  "src/hooks.ts"() {
+    log = {
+      warn: (...args) => console.warn("[context-engine]", ...args),
+      error: (...args) => console.error("[context-engine]", ...args)
+    };
+  }
+});
+
+// src/providers/llm.ts
+var llm_exports = {};
+__export(llm_exports, {
+  LLMClient: () => LLMClient,
+  TIMEOUT_MS: () => TIMEOUT_MS,
+  buildLlmClient: () => buildLlmClient,
+  buildOpenAIChatClient: () => buildOpenAIChatClient,
+  callLlm: () => callLlm
+});
+function toBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+async function postJson(fetchImpl, url, body, headers) {
+  const resp = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`HTTP ${resp.status} ${resp.statusText}${text ? `: ${text}` : ""}`);
+  }
+  return resp.json();
+}
+function buildOpenAIChatClient(cfg) {
+  return new OpenAI__default.default({
+    apiKey: cfg.apiKey ?? void 0,
+    baseURL: cfg.baseUrl ?? void 0,
+    timeout: TIMEOUT_MS,
+    maxRetries: 0
+  });
+}
+async function loadGeminiChatClient(apiKey) {
+  const specifier = "@google/genai";
+  let mod;
+  try {
+    mod = await import(specifier);
+  } catch {
+    throw new ExtraMissingError("gemini", specifier, "gemini llm");
+  }
+  const Ctor = mod.GoogleGenAI ?? mod.Client;
+  if (!Ctor) {
+    throw new ExtraMissingError("gemini", specifier, "gemini llm");
+  }
+  return new Ctor({ apiKey: apiKey ?? null });
+}
+async function loadBedrockSdk() {
+  const specifier = "@aws-sdk/client-bedrock-runtime";
+  try {
+    return await import(specifier);
+  } catch {
+    throw new ExtraMissingError("bedrock", specifier, "bedrock llm");
+  }
+}
+function buildLlmClient(cfg, opts) {
+  if (opts?.client || opts?.fetch || opts?.fetchImpl) {
+    return new LLMClient(cfg, opts);
+  }
+  if (cfg.provider === "anthropic") {
+    return new LLMClient(cfg, { fetch: globalThis.fetch });
+  }
+  if (OPENAI_FAMILY.has(cfg.provider)) {
+    return new LLMClient(cfg, { client: buildOpenAIChatClient(cfg) });
+  }
+  if (cfg.provider === "gemini" || cfg.provider === "bedrock") {
+    return new LLMClient(cfg);
+  }
+  throw new Error(`unknown llm provider: ${JSON.stringify(cfg.provider)}`);
+}
+async function callLlm(cfg, opts) {
+  const { client, ...callOpts } = opts;
+  if (client) {
+    return client.call(callOpts);
+  }
+  const owned = buildLlmClient(cfg);
+  try {
+    return await owned.call(callOpts);
+  } finally {
+    await owned.aclose();
+  }
+}
+var TIMEOUT_MS, ANTHROPIC_VERSION, ANTHROPIC_MAX_TOKENS, OPENAI_FAMILY, LLMClient;
+var init_llm = __esm({
+  "src/providers/llm.ts"() {
+    init_errors();
+    TIMEOUT_MS = 3e4;
+    ANTHROPIC_VERSION = "2023-06-01";
+    ANTHROPIC_MAX_TOKENS = 4096;
+    OPENAI_FAMILY = /* @__PURE__ */ new Set(["openai", "azure_openai", "custom"]);
+    LLMClient = class {
+      cfg;
+      provider;
+      model;
+      client;
+      fetchImpl;
+      genaiClient = null;
+      constructor(cfg, opts = {}) {
+        this.cfg = cfg;
+        this.provider = cfg.provider;
+        this.model = cfg.model;
+        this.client = opts.client ?? null;
+        this.fetchImpl = opts.fetch ?? opts.fetchImpl ?? null;
+      }
+      async aclose() {
+        const closer = this.client?.close;
+        if (typeof closer === "function") {
+          await closer.call(this.client);
+        }
+      }
+      async [Symbol.asyncDispose]() {
+        await this.aclose();
+      }
+      async call(opts) {
+        const { system, user, jsonMode = false, images = null } = opts;
+        if (this.provider === "anthropic") {
+          return this.callAnthropic(system, user, jsonMode, images);
+        }
+        if (OPENAI_FAMILY.has(this.provider)) {
+          return this.callOpenAI(system, user, jsonMode, images);
+        }
+        if (this.provider === "gemini") {
+          return this.callGemini(system, user, jsonMode, images);
+        }
+        if (this.provider === "bedrock") {
+          return this.callBedrock(system, user, jsonMode, images);
+        }
+        throw new Error(`unknown llm provider: ${JSON.stringify(this.provider)}`);
+      }
+      async callAnthropic(system, user, jsonMode, images) {
+        if (!this.fetchImpl) {
+          throw new Error("anthropic llm client has no fetch implementation");
+        }
+        if (jsonMode) {
+          system = `${system}
+
+Respond with valid JSON only.`;
+        }
+        const content = [];
+        for (const image of images ?? []) {
+          content.push({
+            type: "image",
+            source: {
+              type: "base64",
+              media_type: "image/png",
+              data: toBase64(image)
+            }
+          });
+        }
+        content.push({ type: "text", text: user });
+        const data = await postJson(
+          this.fetchImpl,
+          "https://api.anthropic.com/v1/messages",
+          {
+            model: this.model,
+            max_tokens: ANTHROPIC_MAX_TOKENS,
+            system,
+            messages: [{ role: "user", content }]
+          },
+          {
+            "x-api-key": this.cfg.apiKey ?? "",
+            "anthropic-version": ANTHROPIC_VERSION,
+            "content-type": "application/json"
+          }
+        );
+        const text = data.content[0].text;
+        const usage = data.usage ?? {};
+        return [text, { input: usage.input_tokens ?? 0, output: usage.output_tokens ?? 0 }];
+      }
+      async callOpenAI(system, user, jsonMode, images) {
+        if (!this.client) {
+          throw new Error("openai-family llm client has no client");
+        }
+        const content = [{ type: "text", text: user }];
+        for (const image of images ?? []) {
+          content.push({
+            type: "image_url",
+            image_url: { url: `data:image/png;base64,${toBase64(image)}` }
+          });
+        }
+        const body = {
+          model: this.model,
+          messages: [
+            { role: "system", content: system },
+            { role: "user", content }
+          ]
+        };
+        if (jsonMode) {
+          body.response_format = { type: "json_object" };
+        }
+        const resp = await this.client.chat.completions.create(body);
+        const text = resp.choices[0]?.message?.content ?? "";
+        const usage = resp.usage;
+        return [text, { input: usage?.prompt_tokens ?? 0, output: usage?.completion_tokens ?? 0 }];
+      }
+      async callGemini(system, user, jsonMode, images) {
+        if (!this.genaiClient) {
+          this.genaiClient = await loadGeminiChatClient(this.cfg.apiKey);
+        }
+        const parts = [];
+        for (const img of images ?? []) {
+          parts.push({ inlineData: { mimeType: "image/png", data: toBase64(img) } });
+        }
+        parts.push({ text: user });
+        const config = { systemInstruction: system };
+        if (jsonMode) {
+          config.responseMimeType = "application/json";
+        }
+        const resp = await this.genaiClient.models.generateContent({
+          model: this.model,
+          contents: parts,
+          config
+        });
+        const text = resp.text ?? "";
+        const usageMeta = resp.usageMetadata;
+        const inputTokens = usageMeta?.promptTokenCount ?? usageMeta?.prompt_token_count ?? 0;
+        const outputTokens = usageMeta?.candidatesTokenCount ?? usageMeta?.candidates_token_count ?? 0;
+        return [text, { input: inputTokens || 0, output: outputTokens || 0 }];
+      }
+      async callBedrock(system, user, jsonMode, images) {
+        const { BedrockRuntimeClient, ConverseCommand } = await loadBedrockSdk();
+        if (jsonMode) {
+          system = `${system}
+
+Respond with valid JSON only.`;
+        }
+        const content = [];
+        for (const image of images ?? []) {
+          content.push({ image: { format: "png", source: { bytes: image } } });
+        }
+        content.push({ text: user });
+        const runtime = new BedrockRuntimeClient({
+          maxAttempts: 1,
+          requestHandler: {
+            requestTimeout: TIMEOUT_MS,
+            connectionTimeout: TIMEOUT_MS
+          }
+        });
+        try {
+          const result = await runtime.send(
+            new ConverseCommand({
+              modelId: this.model,
+              system: [{ text: system }],
+              messages: [{ role: "user", content }]
+            })
+          );
+          const text = result.output?.message?.content?.[0]?.text ?? "";
+          const usage = result.usage ?? {};
+          return [text, { input: usage.inputTokens ?? 0, output: usage.outputTokens ?? 0 }];
+        } finally {
+          runtime.destroy?.();
+        }
+      }
+    };
+  }
+});
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function partitionGraph(G, louvain, opts = {}) {
+  const maxLevels = opts.maxLevels ?? exports.MAX_HIERARCHY_LEVELS;
+  const minSize = opts.minSize ?? MIN_COMMUNITY_SIZE;
+  const seed = opts.seed ?? LOUVAIN_SEED;
+  const communities = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let level = 0; level < maxLevels; level++) {
+    const resolution = 1 / (level + 1);
+    const assignment = louvain(G, { resolution, rng: mulberry32(seed + level) });
+    const buckets = /* @__PURE__ */ new Map();
+    for (const [node, cid] of Object.entries(assignment)) {
+      const list = buckets.get(cid) ?? [];
+      list.push(node);
+      buckets.set(cid, list);
+    }
+    const kept = [...buckets.values()].filter((m) => m.length >= minSize).map((m) => [...m].sort());
+    const key = JSON.stringify([...kept].map((m) => [...m].sort()).sort());
+    if (seen.has(key)) continue;
+    seen.add(key);
+    for (const members of kept) communities.push({ level, members });
+  }
+  return communities;
+}
+async function loadLouvain() {
+  const mod = await requireExtra(
+    "graphology-communities-louvain",
+    "graph",
+    "community detection"
+  );
+  const fn = mod.default ?? mod;
+  return fn;
+}
+async function detectWithPython(pool) {
+  const entities = (await pool.query(`SELECT id FROM context_engine_entities`)).rows;
+  if (entities.length < MIN_COMMUNITY_SIZE) return [];
+  const entityMap = /* @__PURE__ */ new Map();
+  const entityIds = [];
+  entities.forEach((e, i) => {
+    entityMap.set(String(e.id), i);
+    entityIds.push(String(e.id));
+  });
+  const relationships = (await pool.query(`SELECT source_entity_id, target_entity_id FROM context_engine_entity_relationships`)).rows;
+  const graphology = await requireExtra(
+    "graphology",
+    "graph",
+    "community detection"
+  );
+  const Graph = graphology.default;
+  if (!Graph) throw new Error("graphology export shape is unexpected");
+  const louvain = await loadLouvain();
+  const G = new Graph({ type: "undirected" });
+  for (let i = 0; i < entities.length; i++) G.addNode(String(i));
+  let hasEdge = false;
+  for (const rel of relationships) {
+    const src = entityMap.get(String(rel.source_entity_id));
+    const tgt = entityMap.get(String(rel.target_entity_id));
+    if (src != null && tgt != null && src !== tgt) {
+      hasEdge = true;
+      const a = String(src);
+      const b = String(tgt);
+      if (G.hasEdge(a, b)) {
+        const w = Number(G.getEdgeAttribute(a, b, "weight") ?? 1);
+        G.setEdgeAttribute(a, b, "weight", w + 1);
+      } else {
+        G.addEdge(a, b, { weight: 1 });
+      }
+    }
+  }
+  if (!hasEdge) return [];
+  const partitions = partitionGraph(G, louvain);
+  return partitions.map((p) => ({
+    level: p.level,
+    entity_ids: p.members.map((idx) => entityIds[Number(idx)])
+  }));
+}
+async function summarizeCommunities(pending, config) {
+  if (!pending.length || !config.graph.extractionLlm) return pending.map(() => null);
+  const blocks = pending.map((pc, idx) => {
+    const entityList = (pc.entities ?? []).slice(0, MAX_SUMMARY_ENTITIES);
+    const entityLines = entityList.map((e) => `  - ${e.name} (${e.type}, mentioned ${e.frequency}x)`);
+    const idToName = Object.fromEntries(entityList.map((e) => [String(e.id), e.name]));
+    const relLines = (pc.relationships ?? []).map(
+      (r) => `  - ${idToName[String(r.source_entity_id)] ?? "?"} -> ${r.label} -> ${idToName[String(r.target_entity_id)] ?? "?"}`
+    );
+    return `COMMUNITY ${idx}:
+Entities (${entityList.length}):
+` + entityLines.join("\n") + `
+Relationships (${relLines.length}):
+` + (relLines.length ? relLines.join("\n") : "  None");
+  });
+  const prompt = "Summarize each community below in 2-4 sentences.\n\n" + blocks.join("\n\n") + '\n\nReturn a JSON array with one summary string per community, in order: ["summary 0", "summary 1", ...]. Return ONLY the JSON array.';
+  try {
+    const { callLlm: callLlm2 } = await Promise.resolve().then(() => (init_llm(), llm_exports));
+    const out = await callLlm2(config.graph.extractionLlm, {
+      system: SUMMARY_SYSTEM,
+      user: prompt,
+      jsonMode: true
+    });
+    const raw = Array.isArray(out) ? out[0] : out.text ?? String(out);
+    let summaries = [];
+    try {
+      summaries = JSON.parse(jsonrepair.jsonrepair(String(raw)));
+    } catch {
+      summaries = [];
+    }
+    if (!Array.isArray(summaries)) summaries = [];
+    while (summaries.length < pending.length) summaries.push(null);
+    return summaries.slice(0, pending.length).map((s) => typeof s === "string" && s.trim() ? s : null);
+  } catch (exc) {
+    console.warn("community summarization failed:", exc);
+    return pending.map(() => null);
+  }
+}
+async function detectCommunities(opts) {
+  const stats = { communities_detected: 0, communities_summarized: 0, primary_communities: 0 };
+  const communities = await detectWithPython(opts.pool);
+  stats.communities_detected = communities.length;
+  const pending = [];
+  for (const comm of communities) {
+    const entityIds = comm.entity_ids;
+    if (entityIds.length < MIN_COMMUNITY_SIZE) continue;
+    const entities = (await opts.pool.query(`SELECT * FROM context_engine_entities WHERE id = ANY($1::uuid[])`, [entityIds])).rows;
+    if (entities.length < MIN_COMMUNITY_SIZE) continue;
+    const rels = (await opts.pool.query(
+      `SELECT * FROM context_engine_entity_relationships
+         WHERE source_entity_id = ANY($1::uuid[]) AND target_entity_id = ANY($1::uuid[])
+         LIMIT 50`,
+      [entityIds]
+    )).rows;
+    pending.push({
+      entities,
+      entity_ids: entityIds,
+      entity_count: entityIds.length,
+      rel_count: rels.length,
+      relationships: rels,
+      level: comm.level ?? 0
+    });
+  }
+  if (!pending.length) return stats;
+  const summaries = await summarizeCommunities(pending, opts.config);
+  const embeddings = summaries.map(() => null);
+  const toEmbed = summaries.map((s, i) => [i, s]).filter((x) => Boolean(x[1]));
+  if (toEmbed.length) {
+    try {
+      const result = await opts.embedder.embed(
+        toEmbed.map(([, s]) => s),
+        { kind: "document" }
+      );
+      const vectors = Array.isArray(result) ? result[0] : result.vectors ?? [];
+      toEmbed.forEach(([i], idx) => {
+        embeddings[i] = vectors[idx] ? [...vectors[idx]] : null;
+      });
+    } catch (exc) {
+      if (opts.hooks) emitError(opts.hooks, exc, { stage: "community_embedding" });
+      else console.warn("community embedding failed:", exc);
+    }
+  }
+  await opts.pool.query(`DELETE FROM context_engine_communities`);
+  let primary = 0;
+  for (let i = 0; i < pending.length; i++) {
+    const pc = pending[i];
+    const embedding = embeddings[i];
+    await opts.pool.query(
+      `INSERT INTO context_engine_communities
+         (id, level, entity_ids, entity_count, relationship_count, summary, embedding)
+       VALUES ($1, $2, $3::jsonb, $4, $5, $6, $7::vector)`,
+      [
+        crypto.randomUUID(),
+        pc.level,
+        JSON.stringify(pc.entity_ids.map(String)),
+        pc.entity_count,
+        pc.rel_count,
+        summaries[i],
+        embedding ? `[${embedding.join(",")}]` : null
+      ]
+    );
+    if (pc.level === 0) primary += 1;
+  }
+  stats.communities_summarized = pending.length;
+  stats.primary_communities = primary;
+  return stats;
+}
+exports.MAX_HIERARCHY_LEVELS = void 0; var MIN_COMMUNITY_SIZE, MAX_SUMMARY_ENTITIES, LOUVAIN_SEED, SUMMARY_SYSTEM;
+var init_communities = __esm({
+  "src/graph/communities.ts"() {
+    init_extras();
+    init_hooks();
+    exports.MAX_HIERARCHY_LEVELS = 3;
+    MIN_COMMUNITY_SIZE = 3;
+    MAX_SUMMARY_ENTITIES = 30;
+    LOUVAIN_SEED = 42;
+    SUMMARY_SYSTEM = "You are a knowledge graph analyst. Be factual.";
+  }
+});
+function normalizeEntityName(name) {
+  return (name || "").toLowerCase().trim().replace(/ {2}/g, " ");
+}
+function sharedSignificantTokens(a, b, minLen = 4) {
+  const tokensA = new Set(a.split(/\s+/).filter((t) => t.length >= minLen));
+  const tokensB = b.split(/\s+/).filter((t) => t.length >= minLen);
+  return tokensB.some((t) => tokensA.has(t));
+}
+function buildPrompt(fullText) {
+  return `Extract ALL entities and relationships from the following document text.
+
+DOCUMENT TEXT:
+${fullText}
+
+ENTITY TYPES: PERSON, ORG, PRODUCT, LOCATION, REFERENCE, TEMPORAL, CONCEPT
+
+RELATIONSHIP CATEGORIES: HIERARCHICAL, MEMBERSHIP, CREATION, TEMPORAL, SPATIAL, REFERENCE, FUNCTIONAL, QUANTITATIVE
+
+OUTPUT FORMAT (STRICT JSON):
+{
+  "entities": [
+    {"name": "exact text", "type": "PERSON|ORG|PRODUCT|LOCATION|REFERENCE|TEMPORAL|CONCEPT"}
+  ],
+  "relationships": [
+    {"source": "entity name", "target": "entity name", "category": "CATEGORY", "label": "verb", "evidence": "brief quote"}
+  ]
+}
+
+RULES:
+- Extract EVERY meaningful entity (people, organizations, products, locations, codes, dates, concepts)
+- Choose the MOST SPECIFIC type; only use CONCEPT when no other type fits
+- Be exhaustive but do NOT invent entities not present in the text
+- Deduplicate: each entity appears once
+- Relationships: source/target MUST be entities you extracted; category MUST be one of the 8
+- Return ONLY the JSON object
+`;
+}
+function safeJsonParse(text, expected) {
+  const stripped = text.trim();
+  try {
+    const result = JSON.parse(stripped);
+    if (expected === "object" && result && typeof result === "object" && !Array.isArray(result))
+      return result;
+    if (expected === "array" && Array.isArray(result)) ;
+  } catch {
+  }
+  const repaired = JSON.parse(jsonrepair.jsonrepair(stripped));
+  return repaired;
+}
+async function resolveEntity(db, _name, normalizedName, entityType) {
+  const exact = await db.query(`SELECT * FROM context_engine_entities WHERE normalized_name = $1 LIMIT 1`, [
+    normalizedName
+  ]);
+  if (exact.rows[0]) return exact.rows[0];
+  const trigram = await db.query(
+    `SELECT id FROM context_engine_entities
+     WHERE similarity(normalized_name, $1) > 0.75
+     ORDER BY similarity(normalized_name, $1) DESC LIMIT 1`,
+    [normalizedName]
+  );
+  if (trigram.rows[0]) {
+    const row = await db.query(`SELECT * FROM context_engine_entities WHERE id = $1`, [trigram.rows[0].id]);
+    return row.rows[0] ?? null;
+  }
+  const typed = await db.query(
+    `SELECT id, normalized_name FROM context_engine_entities
+     WHERE type = $2 AND similarity(normalized_name, $1) > 0.45
+     ORDER BY similarity(normalized_name, $1) DESC LIMIT 5`,
+    [normalizedName, entityType]
+  );
+  for (const row of typed.rows) {
+    if (sharedSignificantTokens(normalizedName, String(row.normalized_name))) {
+      const full = await db.query(`SELECT * FROM context_engine_entities WHERE id = $1`, [row.id]);
+      return full.rows[0] ?? null;
+    }
+  }
+  return null;
+}
+async function extractFromText(fullText, config) {
+  try {
+    const llm = config.graph.extractionLlm;
+    if (!llm) return { entities: [], relationships: [], tokens: {} };
+    const { callLlm: callLlm2 } = await Promise.resolve().then(() => (init_llm(), llm_exports));
+    const out = await callLlm2(llm, {
+      system: EXTRACTION_SYSTEM,
+      user: buildPrompt(fullText),
+      jsonMode: true
+    });
+    const raw = Array.isArray(out) ? out[0] : out.text ?? String(out);
+    const tokens = (Array.isArray(out) ? out[1] : out.tokens) ?? {};
+    let result = {};
+    try {
+      result = safeJsonParse(String(raw), "object") ?? {};
+    } catch {
+      result = {};
+    }
+    const entities = (result.entities ?? []).filter(
+      (e) => Boolean(e && typeof e === "object" && e.name && e.type)
+    );
+    const relationships = (result.relationships ?? []).filter(
+      (r) => Boolean(
+        r && typeof r === "object" && r.source && r.target
+      )
+    );
+    return { entities, relationships, tokens };
+  } catch (exc) {
+    console.error("entity extraction LLM call failed:", exc);
+    return { entities: [], relationships: [], tokens: {} };
+  }
+}
+async function loadDocumentChunks(pool, documentId) {
+  const result = await pool.query(
+    `SELECT id, text, idx, source_id, meta_data FROM context_engine_chunks WHERE document_id = $1 ORDER BY idx`,
+    [documentId]
+  );
+  return result.rows.map((c) => ({
+    id: c.id,
+    text: c.text || "",
+    text_lower: String(c.text || "").toLowerCase(),
+    idx: c.idx || 0,
+    source_id: c.source_id,
+    token_count: c.meta_data?.token_count ?? Math.floor(String(c.text || "").length / 4)
+  }));
+}
+async function persistExtraction(pool, chunkSnaps, extracted) {
+  const stats = { entities_created: 0, entities_found: 0, relationships_created: 0 };
+  const byNorm = /* @__PURE__ */ new Map();
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    for (const entityData of extracted.entities) {
+      const normalized = normalizeEntityName(String(entityData.name));
+      if (!normalized) continue;
+      const entityType = String(entityData.type);
+      let entity = await resolveEntity(client, String(entityData.name), normalized, entityType);
+      if (entity) {
+        await client.query(
+          `UPDATE context_engine_entities SET frequency = COALESCE(frequency, 1) + 1,
+             name = CASE WHEN length($2) > length(name) THEN $2 ELSE name END, updated_at = now()
+           WHERE id = $1`,
+          [entity.id, entityData.name]
+        );
+        entity = (await client.query(`SELECT * FROM context_engine_entities WHERE id = $1`, [entity.id])).rows[0];
+      } else {
+        const id = crypto.randomUUID();
+        await client.query(
+          `INSERT INTO context_engine_entities (id, name, normalized_name, type, frequency)
+           VALUES ($1, $2, $3, $4, 1)`,
+          [id, entityData.name, normalized, entityType]
+        );
+        entity = (await client.query(`SELECT * FROM context_engine_entities WHERE id = $1`, [id])).rows[0];
+        stats.entities_created += 1;
+      }
+      byNorm.set(normalized, entity);
+      byNorm.set(String(entity.normalized_name), entity);
+      const nameLower = String(entityData.name).toLowerCase();
+      for (const snap of chunkSnaps) {
+        if (nameLower && String(snap.text_lower).includes(nameLower)) {
+          const exists = await client.query(
+            `SELECT 1 FROM context_engine_chunk_entities WHERE chunk_id = $1 AND entity_id = $2`,
+            [snap.id, entity.id]
+          );
+          if (!exists.rows.length) {
+            await client.query(
+              `INSERT INTO context_engine_chunk_entities (chunk_id, entity_id) VALUES ($1, $2)`,
+              [snap.id, entity.id]
+            );
+            stats.entities_found += 1;
+          }
+        }
+      }
+    }
+    for (const rel of extracted.relationships) {
+      const sourceNorm = normalizeEntityName(String(rel.source ?? ""));
+      const targetNorm = normalizeEntityName(String(rel.target ?? ""));
+      const category = String(rel.category ?? "").toUpperCase();
+      const label = String(rel.label ?? "");
+      const evidence = String(rel.evidence ?? "");
+      if (!RELATIONSHIP_CATEGORIES.has(category)) continue;
+      let src = byNorm.get(sourceNorm);
+      let tgt = byNorm.get(targetNorm);
+      if (!src) {
+        src = (await client.query(`SELECT * FROM context_engine_entities WHERE normalized_name = $1`, [sourceNorm])).rows[0];
+      }
+      if (!tgt) {
+        tgt = (await client.query(`SELECT * FROM context_engine_entities WHERE normalized_name = $1`, [targetNorm])).rows[0];
+      }
+      if (!src || !tgt) continue;
+      const exists = await client.query(
+        `SELECT 1 FROM context_engine_entity_relationships
+         WHERE source_entity_id = $1 AND target_entity_id = $2 AND category = $3 AND label = $4`,
+        [src.id, tgt.id, category, label]
+      );
+      if (!exists.rows.length) {
+        await client.query(
+          `INSERT INTO context_engine_entity_relationships
+             (id, source_entity_id, target_entity_id, category, label, evidence)
+           VALUES ($1, $2, $3, $4, $5, $6)`,
+          [crypto.randomUUID(), src.id, tgt.id, category, label, evidence.slice(0, 200)]
+        );
+        stats.relationships_created += 1;
+      }
+    }
+    await client.query("COMMIT");
+  } catch (e) {
+    await client.query("ROLLBACK");
+    throw e;
+  } finally {
+    client.release();
+  }
+  return stats;
+}
+async function syncToNeo4j(pool, documentId, chunkSnaps, graphStore) {
+  const chunkRows = chunkSnaps.map((s) => ({
+    id: String(s.id),
+    document_id: String(documentId),
+    source_id: s.source_id,
+    text_preview: String(s.text).slice(0, 200),
+    position: s.idx,
+    token_count: s.token_count
+  }));
+  try {
+    await graphStore.connect();
+    const entities = (await pool.query(`SELECT * FROM context_engine_entities`)).rows;
+    const entityById = new Map(entities.map((e) => [String(e.id), e]));
+    const entityRows = entities.map((e) => ({
+      name: e.name,
+      normalized_name: e.normalized_name,
+      entity_type: e.type
+    }));
+    const ids = chunkSnaps.map((s) => s.id);
+    const links = ids.length ? (await pool.query(`SELECT * FROM context_engine_chunk_entities WHERE chunk_id = ANY($1::uuid[])`, [
+      ids
+    ])).rows : [];
+    const mentionRows = links.filter((l) => entityById.has(String(l.entity_id))).map((l) => ({
+      chunk_id: String(l.chunk_id),
+      entity_name: entityById.get(String(l.entity_id)).normalized_name
+    }));
+    const rels = (await pool.query(`SELECT * FROM context_engine_entity_relationships`)).rows;
+    const relRows = [];
+    for (const r of rels) {
+      const src = entityById.get(String(r.source_entity_id));
+      const tgt = entityById.get(String(r.target_entity_id));
+      if (src && tgt) {
+        relRows.push({
+          source_name: src.normalized_name,
+          target_name: tgt.normalized_name,
+          category: r.category,
+          label: r.label,
+          evidence: r.evidence,
+          chunk_id: r.chunk_id ? String(r.chunk_id) : null
+        });
+      }
+    }
+    await graphStore.upsertChunksBatch(chunkRows);
+    await graphStore.linkSequentialChunks(String(documentId));
+    await graphStore.upsertEntitiesBatch(entityRows);
+    await graphStore.linkChunksToEntitiesBatch(mentionRows);
+    await graphStore.upsertEntityRelationshipsBatch(relRows);
+  } catch (exc) {
+    console.warn("Neo4j sync failed (continuing on PG mirror):", exc);
+  }
+}
+async function extractEntitiesForDocument(documentId, opts) {
+  const chunkSnaps = await loadDocumentChunks(opts.pool, documentId);
+  const stats = {
+    chunk_count: chunkSnaps.length,
+    entities_created: 0,
+    entities_found: 0,
+    relationships_created: 0,
+    provider_tokens: {}
+  };
+  if (!chunkSnaps.length) return stats;
+  const batches = [];
+  for (let i = 0; i < chunkSnaps.length; i += exports.CHUNKS_PER_BATCH) {
+    batches.push(chunkSnaps.slice(i, i + exports.CHUNKS_PER_BATCH));
+  }
+  let llmInput = 0;
+  let llmOutput = 0;
+  for (const batch of batches) {
+    const fullText = batch.map((s) => String(s.text)).join("\n\n");
+    const extracted = await extractFromText(fullText, opts.config);
+    llmInput += Number(extracted.tokens.input ?? 0);
+    llmOutput += Number(extracted.tokens.output ?? 0);
+    const persisted = await persistExtraction(opts.pool, batch, extracted);
+    stats.entities_created = Number(stats.entities_created) + persisted.entities_created;
+    stats.entities_found = Number(stats.entities_found) + persisted.entities_found;
+    stats.relationships_created = Number(stats.relationships_created) + persisted.relationships_created;
+  }
+  const tokens = stats.provider_tokens;
+  if (llmInput) tokens.graph_llm_input = llmInput;
+  if (llmOutput) tokens.graph_llm_output = llmOutput;
+  if (opts.graphStore) await syncToNeo4j(opts.pool, documentId, chunkSnaps, opts.graphStore);
+  return stats;
+}
+exports.ENTITY_TYPES = void 0; var RELATIONSHIP_CATEGORIES; exports.CHUNKS_PER_BATCH = void 0; var EXTRACTION_SYSTEM;
+var init_entities = __esm({
+  "src/graph/entities.ts"() {
+    exports.ENTITY_TYPES = [
+      "PERSON",
+      "ORG",
+      "PRODUCT",
+      "LOCATION",
+      "REFERENCE",
+      "TEMPORAL",
+      "CONCEPT"
+    ];
+    RELATIONSHIP_CATEGORIES = /* @__PURE__ */ new Set([
+      "HIERARCHICAL",
+      "MEMBERSHIP",
+      "CREATION",
+      "TEMPORAL",
+      "SPATIAL",
+      "REFERENCE",
+      "FUNCTIONAL",
+      "QUANTITATIVE"
+    ]);
+    exports.CHUNKS_PER_BATCH = 11;
+    EXTRACTION_SYSTEM = "You are a STRICT JSON entity and relationship extraction engine.";
+  }
+});
+
+// src/graph/schema.ts
+async function ensureSchema(driver, database) {
+  const session = driver.session({
+    database
+  });
+  try {
+    for (const stmt of [...CONSTRAINTS, ...INDEXES]) {
+      try {
+        await session.run(stmt);
+      } catch (exc) {
+        console.error("Neo4j schema statement FAILED:", stmt.split(" ")[2], exc);
+      }
+    }
+  } finally {
+    await session.close();
+  }
+}
+var CONSTRAINTS, INDEXES;
+var init_schema = __esm({
+  "src/graph/schema.ts"() {
+    CONSTRAINTS = [
+      "CREATE CONSTRAINT ce_chunk_unique IF NOT EXISTS FOR (c:Chunk) REQUIRE c.id IS UNIQUE",
+      "CREATE CONSTRAINT ce_entity_unique IF NOT EXISTS FOR (e:Entity) REQUIRE e.normalized_name IS UNIQUE"
+    ];
+    INDEXES = [
+      "CREATE INDEX ce_entity_type_idx IF NOT EXISTS FOR (e:Entity) ON (e.type)",
+      "CREATE INDEX ce_chunk_source_idx IF NOT EXISTS FOR (c:Chunk) ON (c.source_id)",
+      "CREATE INDEX ce_chunk_docid_idx IF NOT EXISTS FOR (c:Chunk) ON (c.document_id)"
+    ];
+  }
+});
+
+// src/graph/neo4j-client.ts
+var neo4j_client_exports = {};
+__export(neo4j_client_exports, {
+  GraphStore: () => exports.GraphStore
+});
+var SYNC_BATCH_ROWS, MAX_EXPANSION; exports.GraphStore = void 0;
+var init_neo4j_client = __esm({
+  "src/graph/neo4j-client.ts"() {
+    init_extras();
+    init_hooks();
+    init_schema();
+    SYNC_BATCH_ROWS = 1e3;
+    MAX_EXPANSION = 500;
+    exports.GraphStore = class {
+      cfg;
+      hooks;
+      database;
+      driver = null;
+      schemaReady = false;
+      cache = /* @__PURE__ */ new Map();
+      generation = 0;
+      constructor(cfg, opts = {}) {
+        this.cfg = cfg;
+        this.hooks = opts.hooks;
+        this.database = cfg.neo4jDatabase;
+      }
+      async connect() {
+        if (this.driver) return;
+        const neo4j = await requireExtra("neo4j-driver", "graph", "graph features");
+        const ns = neo4j.default ?? neo4j;
+        const driverFn = ns.driver;
+        const auth = ns.auth;
+        if (!driverFn || !auth) throw new Error("neo4j-driver export shape is unexpected");
+        const driver = driverFn(this.cfg.neo4jUri, auth.basic(this.cfg.neo4jUser, this.cfg.neo4jPassword));
+        this.driver = driver;
+        if (!this.schemaReady) {
+          await ensureSchema(driver, this.database);
+          this.schemaReady = true;
+        }
+      }
+      async close() {
+        if (this.driver) {
+          await this.driver.close();
+          this.driver = null;
+          this.schemaReady = false;
+        }
+      }
+      async ping(timeout = 2e3) {
+        try {
+          await this.connect();
+          await Promise.race([
+            this.pingInternal(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeout))
+          ]);
+          return true;
+        } catch (exc) {
+          this.report(exc, { service: "neo4j", operation: "ping" });
+          return false;
+        }
+      }
+      async pingInternal() {
+        const session = this.driver.session({ database: this.database });
+        try {
+          await session.run("RETURN 1 AS ping");
+        } finally {
+          await session.close();
+        }
+      }
+      report(exc, ctx) {
+        if (this.hooks) emitError(this.hooks, exc, ctx);
+        else console.error("neo4j error:", exc, "| ctx=", ctx);
+      }
+      cacheGet(key) {
+        const entry = this.cache.get(key);
+        if (!entry) return null;
+        if (entry.expiresAt > Date.now() / 1e3) return entry.value;
+        this.cache.delete(key);
+        return null;
+      }
+      cacheSet(key, value, ttl = 86400) {
+        this.cache.set(key, { expiresAt: Date.now() / 1e3 + ttl, value });
+      }
+      async upsertChunksBatch(rows) {
+        const query = `
+        UNWIND $rows AS row
+        MERGE (c:Chunk {id: row.id})
+        SET c.document_id = row.document_id,
+            c.source_id = row.source_id,
+            c.text_preview = row.text_preview,
+            c.position = row.position,
+            c.token_count = row.token_count,
+            c.updated_at = datetime()
+        `;
+        return this.runBatched(query, rows);
+      }
+      async upsertEntitiesBatch(rows) {
+        const query = `
+        UNWIND $rows AS row
+        MERGE (e:Entity {normalized_name: row.normalized_name})
+        SET e.name = row.name,
+            e.type = row.entity_type,
+            e.created_at = coalesce(e.created_at, datetime()),
+            e.updated_at = datetime()
+        `;
+        return this.runBatched(query, rows);
+      }
+      async linkChunksToEntitiesBatch(rows) {
+        const query = `
+        UNWIND $rows AS row
+        MATCH (c:Chunk {id: row.chunk_id})
+        MATCH (e:Entity {normalized_name: row.entity_name})
+        MERGE (c)-[:MENTIONS]->(e)
+        `;
+        return this.runBatched(query, rows);
+      }
+      async upsertEntityRelationshipsBatch(rows) {
+        const query = `
+        UNWIND $rows AS row
+        MATCH (src:Entity {normalized_name: row.source_name})
+        MATCH (tgt:Entity {normalized_name: row.target_name})
+        MERGE (src)-[r:RELATES_TO {category: row.category, label: row.label}]->(tgt)
+        SET r.evidence = row.evidence,
+            r.chunk_id = row.chunk_id,
+            r.updated_at = datetime()
+        `;
+        return this.runBatched(query, rows);
+      }
+      async linkSequentialChunks(documentId) {
+        const query = `
+        MATCH (c:Chunk {document_id: $document_id})
+        WITH c ORDER BY c.position
+        WITH COLLECT(c) AS chunks
+        UNWIND RANGE(0, SIZE(chunks)-2) AS i
+        WITH chunks[i] AS curr, chunks[i+1] AS next
+        MERGE (curr)-[:NEXT]->(next)
+        `;
+        await this.connect();
+        const session = this.driver.session({ database: this.database });
+        try {
+          await session.run(query, { document_id: String(documentId) });
+        } finally {
+          await session.close();
+        }
+        this.generation += 1;
+      }
+      async runBatched(query, rows) {
+        if (!rows.length) return 0;
+        await this.connect();
+        let done = 0;
+        const session = this.driver.session({ database: this.database });
+        try {
+          for (let i = 0; i < rows.length; i += SYNC_BATCH_ROWS) {
+            const batch = rows.slice(i, i + SYNC_BATCH_ROWS);
+            await session.run(query, { rows: batch });
+            done += batch.length;
+          }
+        } finally {
+          await session.close();
+        }
+        this.generation += 1;
+        return done;
+      }
+      async deleteSourceData(sourceId) {
+        await this.connect();
+        const session = this.driver.session({ database: this.database });
+        try {
+          const result = await session.run(
+            "MATCH (c:Chunk {source_id: $source_id}) DETACH DELETE c RETURN count(c) AS n",
+            { source_id: String(sourceId) }
+          );
+          const deleted = Number(result.records[0]?.get("n") ?? 0);
+          this.generation += 1;
+          return { chunks_deleted: deleted };
+        } finally {
+          await session.close();
+        }
+      }
+      expansionCacheKey(queryEntities, maxDepth, chunkIds) {
+        const chunkDigest = crypto.createHash("md5").update([...chunkIds].sort().join(",")).digest("hex");
+        const keyContent = `g${this.generation}:${JSON.stringify([...queryEntities].sort())}:${maxDepth}:${chunkDigest}`;
+        return `expansion:${crypto.createHash("md5").update(keyContent).digest("hex")}`;
+      }
+      async expandChunkSet(chunkIds, queryEntities, maxDepth = 2) {
+        if (!chunkIds.length) return [];
+        const depth = Math.max(1, Math.min(Math.trunc(maxDepth), 5));
+        const cacheKey = this.expansionCacheKey(queryEntities, depth, chunkIds);
+        const cached = this.cacheGet(cacheKey);
+        if (Array.isArray(cached)) return cached;
+        const query = `
+        MATCH (c:Chunk)
+        WHERE c.id IN $chunk_ids
+        WITH COLLECT(DISTINCT c) AS seeds
+
+        CALL {
+            WITH seeds
+            UNWIND seeds AS c
+            OPTIONAL MATCH (c)-[:MENTIONS]->(e:Entity)<-[:MENTIONS]-(related:Chunk)
+            WHERE e.normalized_name IN $query_entities
+            RETURN COLLECT(DISTINCT related.id) AS related_ids
+        }
+        CALL {
+            WITH seeds
+            UNWIND seeds AS c
+            OPTIONAL MATCH (c)-[:NEXT*1..${depth}]-(sequential:Chunk)
+            RETURN COLLECT(DISTINCT sequential.id) AS sequential_ids
+        }
+
+        WITH [s IN seeds | s.id] + related_ids + sequential_ids AS all_ids
+        UNWIND all_ids AS chunk_id
+        WITH chunk_id WHERE chunk_id IS NOT NULL
+        RETURN DISTINCT chunk_id
+        LIMIT $max_results
+        `;
+        await this.connect();
+        const session = this.driver.session({ database: this.database });
+        try {
+          const result = await session.run(query, {
+            chunk_ids: chunkIds,
+            query_entities: queryEntities,
+            max_results: MAX_EXPANSION
+          });
+          const expanded = result.records.map((r) => r.get("chunk_id")).filter((v) => v != null).map(String);
+          if (expanded.length) this.cacheSet(cacheKey, expanded);
+          return expanded;
+        } finally {
+          await session.close();
+        }
+      }
+      async getChunkConnectivityScores(chunkIds) {
+        if (!chunkIds.length) return {};
+        const query = `
+        UNWIND $chunk_ids AS chunk_id
+        MATCH (c:Chunk {id: chunk_id})
+        OPTIONAL MATCH (c)-[out_next:NEXT]->()
+        OPTIONAL MATCH (c)-[out_mentions:MENTIONS]->()
+        OPTIONAL MATCH (c)<-[in_next:NEXT]-()
+        OPTIONAL MATCH (c)<-[in_mentions:MENTIONS]-()
+        WITH c.id AS id,
+             count(DISTINCT out_next) + count(DISTINCT out_mentions) AS outgoing,
+             count(DISTINCT in_next) + count(DISTINCT in_mentions) AS incoming
+        RETURN id, (outgoing + incoming) AS total_connections
+        `;
+        await this.connect();
+        const session = this.driver.session({ database: this.database });
+        try {
+          const result = await session.run(query, { chunk_ids: chunkIds });
+          const records = result.records.map((r) => ({
+            id: String(r.get("id")),
+            total_connections: Number(r.get("total_connections"))
+          }));
+          if (!records.length) return {};
+          const maxConnections = Math.max(...records.map((r) => r.total_connections));
+          if (maxConnections === 0) {
+            return Object.fromEntries(records.map((r) => [r.id, 0.5]));
+          }
+          return Object.fromEntries(
+            records.map((r) => [r.id, Math.min(1, r.total_connections / maxConnections)])
+          );
+        } finally {
+          await session.close();
+        }
+      }
+    };
+  }
+});
+
+// src/graph/retrieval.ts
+var retrieval_exports = {};
+__export(retrieval_exports, {
+  buildGraphRanked: () => buildGraphRanked,
+  corpusIsAclUniform: () => corpusIsAclUniform,
+  shouldUseCommunitySummaries: () => shouldUseCommunitySummaries
+});
+function vecLiteral(vector) {
+  return `[${vector.map((x) => Number(x)).join(",")}]`;
+}
+async function corpusIsAclUniform(pool, sourceIds) {
+  const result = await pool.query(
+    `SELECT EXISTS(SELECT 1 FROM context_engine_chunks c
+     WHERE c.acl IS NOT NULL AND ($1::text[] IS NULL OR c.source_id = ANY($1::text[]))) AS has_acl`,
+    [sourceIds]
+  );
+  return !result.rows[0]?.has_acl;
+}
+async function shouldUseCommunitySummaries(pool, opts) {
+  if (opts.principals == null) return true;
+  return corpusIsAclUniform(pool, opts.sourceIds);
+}
+async function deriveQueryEntities(pool, chunkIds, opts) {
+  if (!chunkIds.length) return [];
+  const result = await pool.query(
+    `SELECT e.normalized_name, e.name, e.type, COUNT(*) AS freq
+     FROM context_engine_chunk_entities ce
+     JOIN context_engine_entities e ON e.id = ce.entity_id
+     JOIN context_engine_chunks c ON c.id = ce.chunk_id
+     WHERE ce.chunk_id = ANY($1::uuid[]) ${SCOPE}
+     GROUP BY e.normalized_name, e.name, e.type
+     ORDER BY freq DESC LIMIT $4`,
+    [chunkIds, opts.sourceIds, opts.principals, ENTITY_LIMIT]
+  );
+  return result.rows.map((r) => ({
+    normalized_name: r.normalized_name,
+    name: r.name,
+    type: r.type
+  }));
+}
+async function computeVectorScores(pool, chunkIds, vector) {
+  if (!chunkIds.length || !vector) return {};
+  const result = await pool.query(
+    `SELECT c.id::text, 1 - (c.embedding <=> CAST($2 AS vector))::float AS sim
+     FROM context_engine_chunks c
+     WHERE c.id = ANY($1::uuid[]) AND c.embedding IS NOT NULL`,
+    [chunkIds, vecLiteral(vector)]
+  );
+  let scores = Object.fromEntries(result.rows.map((r) => [String(r.id), Number(r.sim)]));
+  const vs = Object.values(scores);
+  if (vs.length) {
+    const lo = Math.min(...vs);
+    const hi = Math.max(...vs);
+    if (hi > lo)
+      scores = Object.fromEntries(Object.entries(scores).map(([k, v]) => [k, (v - lo) / (hi - lo)]));
+  }
+  return scores;
+}
+async function computeRelationshipScores(pool, chunkIds, queryEntityNames) {
+  if (!chunkIds.length || !queryEntityNames.length) return {};
+  const result = await pool.query(
+    `SELECT r.chunk_id::text, COUNT(*) AS n
+     FROM context_engine_entity_relationships r
+     JOIN context_engine_entities se ON se.id = r.source_entity_id
+     JOIN context_engine_entities te ON te.id = r.target_entity_id
+     WHERE r.chunk_id = ANY($1::uuid[])
+     AND (se.normalized_name = ANY($2::text[]) OR te.normalized_name = ANY($2::text[]))
+     GROUP BY r.chunk_id`,
+    [chunkIds, queryEntityNames]
+  );
+  const counts = Object.fromEntries(result.rows.map((r) => [String(r.chunk_id), Number(r.n)]));
+  if (!Object.keys(counts).length) return {};
+  const mx = Math.max(...Object.values(counts));
+  return mx ? Object.fromEntries(Object.entries(counts).map(([cid, n]) => [cid, n / mx])) : {};
+}
+async function computeCommunityScores(pool, chunkIds, vector, opts) {
+  if (!opts.useSummaries || !chunkIds.length || !vector) return {};
+  const commRows = await pool.query(
+    `SELECT entity_ids, 1 - (embedding <=> CAST($1 AS vector))::float AS sim
+     FROM context_engine_communities WHERE embedding IS NOT NULL
+     ORDER BY embedding <=> CAST($1 AS vector) LIMIT 5`,
+    [vecLiteral(vector)]
+  );
+  if (!commRows.rows.length) return {};
+  const entityScore = {};
+  for (const row of commRows.rows) {
+    const sim = Number(row.sim);
+    if (sim < 0.15) continue;
+    for (const eid of row.entity_ids ?? []) {
+      entityScore[String(eid)] = Math.max(entityScore[String(eid)] ?? 0, sim);
+    }
+  }
+  if (!Object.keys(entityScore).length) return {};
+  const result = await pool.query(
+    `SELECT ce.chunk_id::text, ce.entity_id::text
+     FROM context_engine_chunk_entities ce
+     JOIN context_engine_chunks c ON c.id = ce.chunk_id
+     WHERE ce.chunk_id = ANY($1::uuid[]) AND ce.entity_id = ANY($4::uuid[]) ${SCOPE}`,
+    [chunkIds, opts.sourceIds, opts.principals, Object.keys(entityScore)]
+  );
+  const chunkScores = {};
+  for (const row of result.rows) {
+    chunkScores[row.chunk_id] = Math.max(chunkScores[row.chunk_id] ?? 0, entityScore[row.entity_id] ?? 0);
+  }
+  return chunkScores;
+}
+async function vectorSeedIds(pool, vector, opts) {
+  const result = await pool.query(
+    `SELECT c.id::text FROM context_engine_chunks c
+     WHERE c.embedding IS NOT NULL ${SCOPE}
+     ORDER BY c.embedding <=> CAST($1 AS vector) LIMIT $4`,
+    [vecLiteral(vector), opts.sourceIds, opts.principals, SEED_LIMIT]
+  );
+  return result.rows.map((r) => String(r.id));
+}
+async function buildGraphRanked(query, opts) {
+  try {
+    const result = await opts.embedder.embed([query], { kind: "query" });
+    const vectors = Array.isArray(result) ? result[0] : result.vectors ?? [];
+    const vector = vectors[0] ? [...vectors[0]] : null;
+    if (!vector) return [];
+    const sourceIds = opts.sourceIds ?? null;
+    const principals = opts.principals ?? null;
+    const seeds = await vectorSeedIds(opts.pool, vector, { sourceIds, principals });
+    if (!seeds.length) return [];
+    const queryEntities = await deriveQueryEntities(opts.pool, seeds.slice(0, TOP_SEEDS_FOR_ENTITIES), {
+      sourceIds,
+      principals
+    });
+    const entityNorms = queryEntities.map((e) => String(e.normalized_name));
+    let expanded = seeds;
+    let connectivity = {};
+    try {
+      await opts.graphStore.connect();
+      expanded = await opts.graphStore.expandChunkSet(seeds, entityNorms, opts.maxDepth ?? 2);
+      connectivity = await opts.graphStore.getChunkConnectivityScores(expanded.length ? expanded : seeds);
+    } catch (exc) {
+      if (opts.hooks) emitError(opts.hooks, exc, { stage: "graph_expand" });
+      else console.warn("graph leg: expansion failed:", exc);
+      expanded = seeds;
+      connectivity = {};
+    }
+    const allIds = expanded.length ? expanded : seeds;
+    const useSummaries = await shouldUseCommunitySummaries(opts.pool, { sourceIds, principals });
+    const vecScores = await computeVectorScores(opts.pool, allIds, vector);
+    const relScores = await computeRelationshipScores(opts.pool, allIds, entityNorms);
+    const commScores = await computeCommunityScores(opts.pool, allIds, vector, {
+      sourceIds,
+      principals,
+      useSummaries
+    });
+    const textRows = await opts.pool.query(
+      `SELECT id::text, lower(coalesce(text,'')) AS t FROM context_engine_chunks WHERE id = ANY($1::uuid[])`,
+      [allIds]
+    );
+    const texts = Object.fromEntries(textRows.rows.map((r) => [String(r.id), String(r.t)]));
+    const weights = {
+      ...DEFAULT_WEIGHTS,
+      ...opts.config.graph.rerankWeights ?? opts.config.graph.rerank_weights ?? {}
+    };
+    const entityNameSet = new Set(entityNorms);
+    const scored = [];
+    for (const cidRaw of allIds) {
+      const cid = String(cidRaw);
+      if (!(cid in texts)) continue;
+      const v = vecScores[cid] ?? 0.5;
+      const chunkText = texts[cid] ?? "";
+      const matches = [...entityNameSet].filter((n) => n && chunkText.includes(n)).length;
+      const e = entityNameSet.size ? Math.min(1, matches / Math.max(1, entityNameSet.size)) : 0;
+      const r = relScores[cid] ?? 0;
+      const cm = commScores[cid] ?? 0;
+      const gc = connectivity[cid] ?? 0.5;
+      const final = v * weights.vector_score + e * weights.entity_match + r * weights.relationship_relevance + cm * weights.community_match + gc * weights.graph_connectivity;
+      scored.push([cid, final]);
+    }
+    scored.sort((a, b) => b[1] - a[1]);
+    return scored.map(([cid]) => cid);
+  } catch (exc) {
+    if (opts.hooks) emitError(opts.hooks, exc, { stage: "graph_embed_query" });
+    else console.warn("graph leg: query embed failed:", exc);
+    return [];
+  }
+}
+var DEFAULT_WEIGHTS, SEED_LIMIT, ENTITY_LIMIT, TOP_SEEDS_FOR_ENTITIES, SCOPE;
+var init_retrieval = __esm({
+  "src/graph/retrieval.ts"() {
+    init_hooks();
+    DEFAULT_WEIGHTS = {
+      vector_score: 0.3,
+      entity_match: 0.3,
+      relationship_relevance: 0.2,
+      community_match: 0.1,
+      graph_connectivity: 0.1
+    };
+    SEED_LIMIT = 200;
+    ENTITY_LIMIT = 30;
+    TOP_SEEDS_FOR_ENTITIES = 20;
+    SCOPE = `
+  AND ($2::text[] IS NULL OR c.source_id = ANY($2::text[]))
+  AND ($3::text[] IS NULL OR c.acl IS NULL OR c.acl && $3::text[])
+`;
+  }
+});
+
+// src/usage.ts
+function graphUnits(chunkCount, primaryCommunityCount) {
+  return Math.ceil(chunkCount / 8) + primaryCommunityCount;
+}
+var init_usage = __esm({
+  "src/usage.ts"() {
+  }
+});
+
+// src/graph/stage.ts
+var stage_exports = {};
+__export(stage_exports, {
+  runGraphStage: () => runGraphStage
+});
+async function runGraphStage(opts) {
+  const entStats = await extractEntitiesForDocument(opts.documentId, {
+    config: opts.config,
+    pool: opts.pool,
+    graphStore: opts.graphStore,
+    hooks: opts.hooks
+  });
+  const commStats = await detectCommunities({
+    config: opts.config,
+    pool: opts.pool,
+    embedder: opts.embedder,
+    hooks: opts.hooks
+  });
+  const chunkCount = Number(entStats.chunk_count ?? 0);
+  const primary = Number(commStats.primary_communities ?? 0);
+  return graphUnits(chunkCount, primary);
+}
+var init_stage = __esm({
+  "src/graph/stage.ts"() {
+    init_usage();
+    init_communities();
+    init_entities();
+  }
+});
+
+// src/graph/index.ts
+init_extras();
+init_communities();
+init_entities();
+init_neo4j_client();
+init_retrieval();
+async function requireGraph() {
+  await requireExtra("neo4j-driver", "graph", "graph features");
+}
+var _requireGraph = requireGraph;
+async function buildGraphStore(cfg, opts = {}) {
+  await requireGraph();
+  const { GraphStore: GraphStore2 } = await Promise.resolve().then(() => (init_neo4j_client(), neo4j_client_exports));
+  return new GraphStore2(cfg, opts);
+}
+async function runGraphStage2(...args) {
+  await requireGraph();
+  const { runGraphStage: impl } = await Promise.resolve().then(() => (init_stage(), stage_exports));
+  return impl(...args);
+}
+async function buildGraphRanked2(...args) {
+  await requireGraph();
+  const { buildGraphRanked: impl } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
+  return impl(...args);
+}
+
+exports._requireGraph = _requireGraph;
+exports.buildGraphRanked = buildGraphRanked2;
+exports.buildGraphStore = buildGraphStore;
+exports.corpusIsAclUniform = corpusIsAclUniform;
+exports.detectCommunities = detectCommunities;
+exports.normalizeEntityName = normalizeEntityName;
+exports.requireGraph = requireGraph;
+exports.resolveEntity = resolveEntity;
+exports.runGraphStage = runGraphStage2;
+exports.shouldUseCommunitySummaries = shouldUseCommunitySummaries;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map