@100xprompt/chitta 0.1.0

package/src/embedded/kgqa/answer-paths.ts

@@ -0,0 +1,197 @@
+// The per-path answer resolvers. Each takes the providers it needs explicitly so the
+// KgqaService can orchestrate by composing them. Logic, confidences, and outputs are
+// identical to the original monolithic service - this is a pure structural split.
+
+import type { SqliteGraphProvider } from "../sqlite-graph-provider"
+import type { SqliteStore } from "../sqlite-store"
+import type { EmbeddingProvider } from "../../provider"
+import type { KgqaResult } from "../kgqa-service"
+import type { Graph } from "./types"
+import { stem } from "./text"
+import { PREFERENCE_PREDICATES } from "./preference"
+import { predMatch } from "./predicates"
+import { QUERY_STOP, narrow, linesMentioningAny } from "./select"
+
+// Record names (ACL-scoped) that mention any of the given entities.
+export function cite(
+  graph: SqliteGraphProvider,
+  entityIds: string[],
+  _userId: string,
+  _orgId: string,
+  accessibleRecordIds: string[],
+): string[] {
+  if (entityIds.length === 0 || accessibleRecordIds.length === 0) return []
+  return graph.recordsMentioning(entityIds, accessibleRecordIds).slice(0, 3)
+}
+
+export function compose(
+  graph: SqliteGraphProvider,
+  anchor: string,
+  predicate: string,
+  answerIds: string[],
+  labelOf: Map<string, string>,
+  userId: string,
+  orgId: string,
+  recordIds: string[],
+  reverse = false,
+): KgqaResult {
+  const labels = [...new Set(answerIds)].map((id) => labelOf.get(id) ?? id)
+  const anchorLabel = labelOf.get(anchor) ?? anchor
+  const triple = reverse
+    ? { subject: labels.join(", "), predicate, object: anchorLabel }
+    : { subject: anchorLabel, predicate, object: labels.join(", ") }
+  // one fact per object so multi-valued answers list cleanly (e.g. "what do I love"
+  // → "you love coding", "you love Lavanya"), not a comma-run.
+  const pred = predicate.replace(/_/g, " ")
+  const facts = labels.map((l) => (reverse ? `${l} ${pred} ${anchorLabel}` : `${anchorLabel} ${pred} ${l}`))
+  return {
+    answer: labels.join(", "),
+    facts,
+    triple,
+    citations: cite(graph, [anchor, ...answerIds], userId, orgId, recordIds),
+    confidence: 0.9,
+  }
+}
+
+// Binary: does (subject, predicate, object) hold?
+export function binaryAnswer(
+  graph: SqliteGraphProvider,
+  g: Graph,
+  subj: string,
+  obj: string,
+  predStem: string,
+  predicate: string | undefined,
+  labelOf: Map<string, string>,
+  userId: string,
+  orgId: string,
+  recordIds: string[],
+): KgqaResult {
+  const yes = g.relations.some(
+    (r) => r.from === subj && r.to === obj && predMatch(r.type, predStem),
+  )
+  const bAnswer = yes ? "Yes." : "No (not found in your knowledge graph)."
+  return {
+    answer: bAnswer,
+    facts: [bAnswer],
+    triple: { subject: labelOf.get(subj) ?? subj, predicate: predicate ?? "", object: labelOf.get(obj) ?? obj },
+    citations: yes ? cite(graph, [subj, obj], userId, orgId, recordIds) : [],
+    confidence: yes ? 0.9 : 0.5,
+  }
+}
+
+// Self / preference answer: return the user's preference edges (loves/likes/…) from
+// the graph. Resolves abstract self-queries ("what do I like that needs logic?")
+// through the graph regardless of phrasing; the frontier LLM does the final filter.
+export function preferenceAnswer(
+  graph: SqliteGraphProvider,
+  g: Graph,
+  userId: string,
+  orgId: string,
+  recordIds: string[],
+): KgqaResult | null {
+  const labelOf = new Map(g.entities.map((e) => [e.id, e.label]))
+  const isPref = (t: string) => PREFERENCE_PREDICATES.has(t) || PREFERENCE_PREDICATES.has(stem(t))
+  const edges = g.relations.filter((r) => isPref(r.type))
+  if (!edges.length) return null
+  const facts = edges.map((r) => `${labelOf.get(r.from) ?? r.from} ${r.type.replace(/_/g, " ")} ${labelOf.get(r.to) ?? r.to}`)
+  const objs = [...new Set(edges.map((r) => labelOf.get(r.to) ?? r.to))]
+  const ids = [...new Set(edges.flatMap((r) => [r.from, r.to]))]
+  return {
+    answer: facts.join("\n"),
+    facts,
+    triple: { subject: "you", predicate: "prefer", object: objs.join(", ") },
+    citations: cite(graph, ids, userId, orgId, recordIds),
+    confidence: 0.85,
+  }
+}
+
+// Predicate-anchored answer: a query naming a RELATION but no entity ("what
+// partnerships exist") → all edges of the matching predicate(s). Last resort before
+// vector fallback, so named-entity queries (handled by entityLookup) are unaffected.
+export function predicateAnswer(
+  graph: SqliteGraphProvider,
+  question: string,
+  g: Graph,
+  userId: string,
+  orgId: string,
+  recordIds: string[],
+): KgqaResult | null {
+  const preds = [...new Set(g.relations.map((r) => r.type).filter((t) => t !== "relates_to"))]
+  if (!preds.length) return null
+  // Don't apply QUERY_STOP here - relational words (partnership/deal/…) are exactly
+  // the high-level signal we want. The predicate HEAD is its first segment
+  // ("partners_with" → "partners"), matched loosely against the query's stems.
+  const qStems = [...new Set(question.toLowerCase().split(/[^a-z]+/).filter((w) => w.length >= 4).map(stem))]
+  const hit = preds.filter((p) => {
+    const head = stem(p.split("_")[0] ?? p)
+    return head.length >= 4 && qStems.some((qs) => qs === head || qs.includes(head) || head.includes(qs))
+  })
+  if (!hit.length) return null
+  const set = new Set(hit)
+  const edges = g.relations.filter((r) => set.has(r.type))
+  if (!edges.length) return null
+  const labelOf = new Map(g.entities.map((e) => [e.id, e.label]))
+  const facts = edges.map((r) => `${labelOf.get(r.from) ?? r.from} ${r.type.replace(/_/g, " ")} ${labelOf.get(r.to) ?? r.to}`)
+  const ids = [...new Set(edges.flatMap((r) => [r.from, r.to]))]
+  return {
+    answer: facts.join("\n"),
+    facts,
+    triple: { subject: "", predicate: hit.join(" / "), object: "" },
+    citations: cite(graph, ids, userId, orgId, recordIds),
+    confidence: 0.8,
+  }
+}
+
+// Entity-anchored answer (no LLM needed): if the query names a known entity,
+// return the line(s)/facts about it THAT MATCH THE QUERY - a specific question
+// gets the specific fact; a bare entity name gets everything.
+export async function entityLookup(
+  graph: SqliteGraphProvider,
+  store: SqliteStore,
+  embeddings: EmbeddingProvider,
+  question: string,
+  g: Graph,
+  accessibleVids: string[],
+  recordIds: string[],
+  _userId: string,
+  _orgId: string,
+): Promise<KgqaResult | null> {
+  // Anchor on the query's KNOWN terms (words that appear in some entity label),
+  // not one entity node - so "Google" gathers all Google lines, and the full
+  // query then decides which of them to keep.
+  const qwords = question.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 3 && !QUERY_STOP.has(w))
+  const entityWords = new Set<string>()
+  for (const e of g.entities) for (const w of e.label.toLowerCase().split(/[^a-z0-9]+/)) if (w.length >= 3) entityWords.add(w)
+  const anchors = qwords.filter((w) => w.length >= 3 && entityWords.has(w)) // incl. acronyms (SAP, IBM, UCP)
+  if (anchors.length === 0) return null
+  const anchorSet = new Set(anchors)
+
+  const matchedIds = g.entities
+    .filter((e) => e.label.toLowerCase().split(/[^a-z0-9]+/).some((w) => anchorSet.has(w)))
+    .map((e) => e.id)
+  const cites = graph.recordsMentioning(matchedIds, recordIds).slice(0, 3)
+  const subject = anchors.join(", ")
+
+  // 1) Typed facts about the matched entities (when the LLM produced predicates).
+  const labelOf = new Map(g.entities.map((e) => [e.id, e.label]))
+  const mset = new Set(matchedIds)
+  const factLines = g.relations
+    .filter((r) => (mset.has(r.from) || mset.has(r.to)) && r.type !== "relates_to")
+    .map((r) => `${labelOf.get(r.from) ?? r.from} ${r.type.replace(/_/g, " ")} ${labelOf.get(r.to) ?? r.to}`)
+  if (factLines.length) {
+    const chosen = await narrow(embeddings, question, anchors, anchorSet, factLines)
+    return { answer: chosen.join("\n"), facts: chosen, triple: { subject, predicate: "facts", object: `${chosen.length}` }, citations: cites, confidence: 0.85 }
+  }
+
+  // 2) Otherwise the exact line(s) mentioning an anchor - query-filtered.
+  const all = linesMentioningAny(store, anchors, accessibleVids)
+  if (all.length === 0) return null
+  const lines = await narrow(embeddings, question, anchors, anchorSet, all)
+  return {
+    answer: lines.join("\n"),
+    facts: lines,
+    triple: { subject, predicate: "info", object: lines.length > 1 ? `${lines.length} facts` : lines[0] },
+    citations: cites,
+    confidence: 0.78,
+  }
+}

package/src/embedded/kgqa/entity-link.ts

@@ -0,0 +1,13 @@
+// Entity linking - resolve a mention from parsed intent to a graph entity id,
+// by slug first then exact label match.
+
+import { slugify, entityId } from "../extract"
+import type { Graph } from "./types"
+
+export function link(mention: string, g: Graph): string | null {
+  const id = entityId(slugify(mention))
+  if (g.entities.some((e) => e.id === id)) return id
+  const m = mention.toLowerCase()
+  const byLabel = g.entities.find((e) => e.label.toLowerCase() === m)
+  return byLabel?.id ?? null
+}

package/src/embedded/kgqa/intent.ts

@@ -0,0 +1,14 @@
+// Intent parsing - the no-LLM heuristic for simple "who/what do I <verb>" questions.
+// (The LLM path is preferred; this covers the offline case.)
+
+import type { QuestionIntent } from "../extract"
+
+export function heuristicIntent(q: string): QuestionIntent | null {
+  // "who/what do/does/did I/you/<x> <verb>" → forward relation query
+  const m = q.toLowerCase().match(/\b(who|what)\b\s+(?:do|does|did)\s+([a-z]+)\s+([a-z]+)/)
+  if (m) {
+    const subj = ["i", "me", "my", "we", "you"].includes(m[2]) ? "user" : m[2]
+    return { type: "relation_query", subject: subj, predicate: m[3] }
+  }
+  return null
+}

package/src/embedded/kgqa/predicates.ts

@@ -0,0 +1,9 @@
+// Predicate stem-matching: loosely match an edge type against a stemmed predicate
+// from the parsed intent ("partnered_with" vs "partner").
+
+import { stem } from "./text"
+
+export function predMatch(edgeType: string, predStem: string): boolean {
+  const e = stem(edgeType)
+  return e === predStem || e.includes(predStem) || predStem.includes(e)
+}

package/src/embedded/kgqa/preference.ts

@@ -0,0 +1,20 @@
+// HIGH-LEVEL (thematic) routing - LightRAG-style dual-level retrieval.
+// A query about the USER'S OWN preferences should be answered from the graph's
+// preference edges (loves/likes/…), NEVER the vector index - so abstract self-queries
+// ("do I like anything logical?") route through the graph, and the frontier LLM then
+// filters. A preference NOUN (preferences/interests/hobbies) is self-evidently about
+// the user; a preference VERB (like/love) needs a self pronoun so we don't hijack a
+// relational query like "does Google love AI".
+
+const PREF_NOUN = /\b(prefer(?:ence)?s?|interests?|hobb(?:y|ies)|favou?rites?|passions?|tastes?)\b/i
+const PREF_VERB = /\b(likes?|loves?|loving|enjoys?|enjoying|prefers?|fond|keen|into)\b/i
+const SELF_REF = /\b(i|me|my|mine|myself|im|i'm)\b/i
+
+export const PREFERENCE_PREDICATES = new Set([
+  "loves", "love", "likes", "like", "enjoys", "enjoy", "prefers", "prefer", "favors", "favours",
+  "interested_in", "fond_of", "passionate_about", "fan_of", "keen_on", "into",
+])
+
+export function isSelfPreference(q: string): boolean {
+  return PREF_NOUN.test(q) || (PREF_VERB.test(q) && SELF_REF.test(q))
+}

package/src/embedded/kgqa/select.ts

@@ -0,0 +1,99 @@
+// Relevance filtering + line gathering. Decides whether a query is BROAD (return
+// everything about an entity) or SPECIFIC (semantically filter the candidate lines),
+// and pulls exact lines from accessible chunks.
+
+import { embedQueryWith, type EmbeddingProvider } from "../../provider"
+import type { SqliteStore } from "../sqlite-store"
+import { cleanLine, isBoilerplate } from "../extract"
+import { cosine } from "./text"
+
+// Generic question words to strip when deciding if a query is SPECIFIC (asks about
+// a particular aspect) vs BROAD (just names the entity → return everything).
+export const QUERY_STOP = new Set([
+  "about", "info", "information", "news", "tell", "me", "what", "whats", "is", "are", "do", "does", "did",
+  "the", "a", "an", "of", "on", "for", "and", "company", "companies", "details", "detail", "give", "show", "all", "any",
+  "please", "know", "regarding", "related", "to", "with", "recent", "latest", "update", "updates", "who", "which",
+  // generic RELATIONAL words - non-discriminating, so "X partnerships" returns ALL of X's
+  // relationships (let the LLM deduce), rather than only lines that literally say "partnership".
+  "partner", "partners", "partnered", "partnering", "partnership", "partnerships",
+  "relationship", "relationships", "deal", "deals", "collaboration", "collaborations", "collaborate",
+  "connection", "connections", "work", "works", "working", "involved", "between",
+  // comparison / full-coverage signals - these mean "give me everything", not a filter.
+  "compare", "comparison", "versus", "vs", "both", "each", "every", "everything", "anything", "list", "summary",
+])
+
+// Query words that signal the user wants COMPREHENSIVE coverage (union of all the
+// named entities' facts), not the single connecting line.
+export const WANTS_ALL = /\b(compare|comparison|versus|vs|both|each|every|everything|all|list|summary)\b/
+
+// Narrow candidate lines to the query. First prefer lines that mention ALL named
+// anchors ("SAP" + "Google" → only the SAP+Google line, not every Google line);
+// then apply the broad/specific semantic filter on what remains.
+export async function narrow(
+  embeddings: EmbeddingProvider,
+  question: string,
+  anchors: string[],
+  anchorSet: Set<string>,
+  lines: string[],
+): Promise<string[]> {
+  if (lines.length <= 1) return lines
+  let candidate = lines
+  // Intersection narrows "SAP + Google" to their shared line - UNLESS the query is
+  // a comparison/coverage request ("compare X and Y"), where we want all of both.
+  if (anchors.length > 1 && !WANTS_ALL.test(question.toLowerCase())) {
+    const inter = lines.filter((l) => {
+      const ll = l.toLowerCase()
+      return anchors.every((a) => ll.includes(a))
+    })
+    if (inter.length > 0) candidate = inter
+  }
+  return selectByQuery(embeddings, question, anchorSet, candidate)
+}
+
+// Broad query (only anchor terms) → return all; specific (extra content words) →
+// embed the full query and keep only lines that semantically match it.
+export async function selectByQuery(
+  embeddings: EmbeddingProvider,
+  question: string,
+  anchorSet: Set<string>,
+  lines: string[],
+): Promise<string[]> {
+  if (lines.length <= 1) return lines
+  const residual = question
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 1 && !QUERY_STOP.has(w) && !anchorSet.has(w))
+  if (residual.length === 0) return lines // broad → everything
+
+  const q = await embedQueryWith(embeddings, question)
+  const scored: Array<{ line: string; s: number }> = []
+  for (const line of lines) scored.push({ line, s: cosine(q, await embeddings.embedDense(line)) })
+  scored.sort((a, b) => b.s - a.s)
+  const top = scored[0].s
+  const margin = Number(process.env.CONTEXT_LINE_MARGIN ?? 0.08)
+  return scored.filter((x) => x.s >= top - margin).map((x) => x.line)
+}
+
+export function linesMentioningAny(store: SqliteStore, terms: string[], accessibleVids: string[]): string[] {
+  const out = new Set<string>()
+  for (const term of terms) for (const l of linesMentioning(store, term, accessibleVids)) out.add(l)
+  return [...out]
+}
+
+// Exact lines/sentences from accessible chunks that mention the entity label.
+export function linesMentioning(store: SqliteStore, label: string, accessibleVids: string[]): string[] {
+  if (accessibleVids.length === 0) return []
+  const vp = accessibleVids.map(() => "?").join(",")
+  const rows = store.db
+    .query(`SELECT content FROM chunks WHERE virtual_record_id IN (${vp}) AND content LIKE ?`)
+    .all(...accessibleVids, `%${label}%`) as Array<{ content: string }>
+  const want = label.toLowerCase()
+  const out = new Set<string>()
+  for (const r of rows) {
+    for (const raw of r.content.split(/\n|(?<=[.!?])\s+/)) {
+      const line = cleanLine(raw) // strip markdown ** / # / bullets
+      if (line && !isBoilerplate(line) && line.toLowerCase().includes(want)) out.add(line)
+    }
+  }
+  return [...out]
+}

package/src/embedded/kgqa/text.ts

@@ -0,0 +1,16 @@
+// Low-level text/vector helpers shared across the KGQA paths.
+
+export function cosine(a: number[], b: number[]): number {
+  let d = 0
+  let na = 0
+  let nb = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    d += a[i] * b[i]
+    na += a[i] * a[i]
+    nb += b[i] * b[i]
+  }
+  return na && nb ? d / (Math.sqrt(na) * Math.sqrt(nb)) : 0
+}
+
+export const stem = (s: string) => s.toLowerCase().replace(/(ing|ed|es|s)$/, "")

package/src/embedded/kgqa/types.ts

@@ -0,0 +1,6 @@
+// Shared structural types for the KGQA subsystem.
+
+export type Graph = {
+  entities: Array<{ id: string; label: string; type: string }>
+  relations: Array<{ from: string; to: string; type: string }>
+}

package/src/embedded/kgqa-service.ts

@@ -0,0 +1,122 @@
+// KGQA - answer a question with the EXACT fact from the typed graph, not a ranked
+// list. "who do I love" → resolve (user, loves, ?) → "Lavanya", cited. Falls back
+// to null (→ vector retrieval) when it can't answer confidently.
+//
+// Works best when the graph has TYPED predicate edges (from the LLM triple
+// extractor). Intent parsing prefers the LLM; a small heuristic covers the
+// no-LLM case for simple "who/what do I <verb>" questions.
+//
+// This module is the ORCHESTRATOR: the actual resolvers live under ./kgqa/* and are
+// composed here. Public API (KgqaResult, KgqaService) is unchanged.
+
+import type { SqliteGraphProvider } from "./sqlite-graph-provider"
+import type { SqliteStore } from "./sqlite-store"
+import type { LlmExtractor } from "./llm-extractor"
+import type { EmbeddingProvider } from "../provider"
+import type { QuestionIntent } from "./extract"
+import { stem } from "./kgqa/text"
+import type { Graph } from "./kgqa/types"
+import { heuristicIntent } from "./kgqa/intent"
+import { isSelfPreference } from "./kgqa/preference"
+import { predMatch } from "./kgqa/predicates"
+import { link } from "./kgqa/entity-link"
+import {
+  compose,
+  binaryAnswer,
+  preferenceAnswer,
+  predicateAnswer,
+  entityLookup,
+} from "./kgqa/answer-paths"
+
+export interface KgqaResult {
+  answer: string
+  /** The individual facts that make up the answer - a query can match SEVERAL typed
+   *  facts (e.g. "Google limits Meta" AND "Meta uses Gemini"); each is its own item so
+   *  callers/UI can list them instead of running them together. */
+  facts: string[]
+  triple: { subject: string; predicate: string; object: string }
+  citations: string[] // record names supporting the answer
+  confidence: number
+}
+
+export class KgqaService {
+  constructor(
+    private readonly graph: SqliteGraphProvider,
+    private readonly store: SqliteStore,
+    private readonly embeddings: EmbeddingProvider,
+    private readonly llm?: LlmExtractor,
+  ) {}
+
+  async answer(question: string, userId: string, orgId: string): Promise<KgqaResult | null> {
+    // ACL-scoped graph: only entities/relations from records this user may see.
+    const accessible = await this.graph.getAccessibleVirtualRecordIds({ userId, orgId })
+    const recordIds = [...new Set(Object.values(accessible))]
+    const g = this.graph.getKnowledgeGraph(recordIds) as Graph
+    if (g.entities.length === 0) return null
+    const labelOf = new Map(g.entities.map((e) => [e.id, e.label]))
+
+    const intent = (await this.llm?.parseQuestionIntent(question)) ?? heuristicIntent(question)
+    // No relational intent? Route through the intelligent graph fallback (self/
+    // preference → entity anchor → predicate anchor) before any vector search.
+    if (!intent) return this.graphFallback(question, g, Object.keys(accessible), recordIds, userId, orgId)
+
+    const subj = intent.subject ? link(intent.subject, g) : null
+    const obj = intent.object ? link(intent.object, g) : null
+    const predStem = intent.predicate ? stem(intent.predicate.replace(/\s+/g, "_")) : null
+
+    // Forward relation: (subject, predicate, ?)
+    if (intent.type === "relation_query" && subj && predStem && !obj) {
+      const objs = g.relations.filter((r) => r.from === subj && predMatch(r.type, predStem)).map((r) => r.to)
+      if (objs.length) return compose(this.graph, subj, intent.predicate!, objs, labelOf, userId, orgId, recordIds)
+    }
+    // Reverse relation: (?, predicate, object)
+    if (intent.type === "relation_query" && obj && predStem && !subj) {
+      const subs = g.relations.filter((r) => r.to === obj && predMatch(r.type, predStem)).map((r) => r.from)
+      if (subs.length) return compose(this.graph, obj, intent.predicate!, subs, labelOf, userId, orgId, recordIds, true)
+    }
+    // Binary: does (subject, predicate, object) hold?
+    if (intent.type === "binary_relation" && subj && obj && predStem) {
+      return binaryAnswer(this.graph, g, subj, obj, predStem, intent.predicate, labelOf, userId, orgId, recordIds)
+    }
+    // Relational paths didn't resolve → intelligent graph fallback, else vector.
+    return this.graphFallback(question, g, Object.keys(accessible), recordIds, userId, orgId)
+  }
+
+  // Intelligent graph routing (LightRAG dual-level): self/preference theme → entity
+  // anchor → predicate anchor → null (after which the MCP falls back to vector search).
+  private async graphFallback(
+    question: string,
+    g: Graph,
+    accessibleVids: string[],
+    recordIds: string[],
+    userId: string,
+    orgId: string,
+  ): Promise<KgqaResult | null> {
+    if (isSelfPreference(question)) {
+      const p = preferenceAnswer(this.graph, g, userId, orgId, recordIds)
+      if (p) return p
+    }
+    const e = await this.entityLookup(question, g, accessibleVids, recordIds, userId, orgId)
+    if (e) return e
+    return predicateAnswer(this.graph, question, g, userId, orgId, recordIds)
+  }
+
+  // Entity-anchored answer (no LLM needed): if the query names a known entity,
+  // return the line(s)/facts about it THAT MATCH THE QUERY - a specific question
+  // gets the specific fact; a bare entity name gets everything.
+  entityLookup(
+    question: string,
+    g: Graph,
+    accessibleVids: string[],
+    recordIds: string[],
+    userId: string,
+    orgId: string,
+  ): Promise<KgqaResult | null> {
+    return entityLookup(this.graph, this.store, this.embeddings, question, g, accessibleVids, recordIds, userId, orgId)
+  }
+
+  // Parse a question into a typed intent - LLM-preferred with a heuristic fallback.
+  async parseQuestionIntent(question: string): Promise<QuestionIntent | null> {
+    return (await this.llm?.parseQuestionIntent(question)) ?? heuristicIntent(question)
+  }
+}

package/src/embedded/llm-extractor.ts

@@ -0,0 +1,10 @@
+// LLM-backed knowledge extraction. Calls an OpenAI-compatible chat endpoint -
+// point it at a LOCAL/sovereign model (vLLM/SGLang/Ollama) so nothing leaves the
+// building. Unlike the deterministic extractor, it handles casual lowercase text
+// ("i love lavanya" → Lavanya[PERSON], user -loves→ Lavanya).
+//
+// Thin facade: the implementation lives in ./extractors/llm and is re-exported here
+// so existing imports keep resolving unchanged. Public API is preserved exactly.
+
+export type { LlmExtractorConfig } from "./extractors/llm"
+export { LlmExtractor, HybridExtractor } from "./extractors/llm"

package/src/embedded/local-embeddings.ts

@@ -0,0 +1,36 @@
+// In-process embeddings. This deterministic hashing embedder is dependency-free
+// so the embedded stack runs and tests with zero downloads. For real semantic
+// quality in the single binary, swap in transformers.js / fastembed (ONNX bge-*)
+// - it implements the same EmbeddingProvider interface, so nothing above changes.
+
+import type { EmbeddingProvider } from "../provider"
+
+const DIM = 64
+
+function tokens(text: string): string[] {
+  return text.toLowerCase().match(/[a-z0-9]+/g) ?? []
+}
+
+function bucket(token: string): number {
+  let h = 2166136261
+  for (let i = 0; i < token.length; i++) {
+    h ^= token.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return Math.abs(h) % DIM
+}
+
+export class LocalHashEmbeddings implements EmbeddingProvider {
+  async embedDense(query: string): Promise<number[]> {
+    const v = new Array(DIM).fill(0)
+    for (const t of tokens(query)) v[bucket(t)] += 1
+    const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1
+    return v.map((x) => x / norm)
+  }
+
+  async embedSparse(query: string): Promise<{ indices: number[]; values: number[] }> {
+    const counts = new Map<number, number>()
+    for (const t of tokens(query)) counts.set(bucket(t), (counts.get(bucket(t)) ?? 0) + 1)
+    return { indices: [...counts.keys()], values: [...counts.values()] }
+  }
+}

package/src/embedded/personal.ts

@@ -0,0 +1,100 @@
+// Shared, persistent embedded context for the CLI agent - a single local
+// knowledge graph + vector store the `context_ingest` and `get_context` tools both
+// use. Single local user (no ACL friction for personal use); zero servers, zero
+// config. The DB persists at CONTEXT_DB or the app data dir.
+
+import path from "node:path"
+import os from "node:os"
+import fs from "node:fs"
+import { buildEmbeddedContext, type EmbeddedContext } from "./index"
+import { LocalHashEmbeddings } from "./local-embeddings"
+import { TransformersEmbeddings, AutoEmbeddings } from "./transformers-embeddings"
+import { DeterministicExtractor, HybridExtractor, type KnowledgeExtractor } from "./index"
+import { LlmExtractor } from "./llm-extractor"
+import { CrossEncoderReranker } from "./reranker"
+import type { Reranker } from "./reranker"
+import type { Role } from "./authorizer"
+import type { EmbeddingProvider } from "../provider"
+
+/** Cross-encoder reranker is ON by default (measured +40% MRR / +27% nDCG, recall
+ *  unchanged). It downloads a small (~22M) model on first use and degrades gracefully
+ *  to RRF order if unavailable. Disable with CONTEXT_RERANK=0. */
+function pickReranker(): Reranker | undefined {
+  return /^(0|false|off)$/i.test(process.env.CONTEXT_RERANK ?? "") ? undefined : new CrossEncoderReranker()
+}
+
+// Distinct ids - the nodes table is keyed by id, so user and org must not collide.
+export const LOCAL_USER = "local-user"
+export const LOCAL_ORG = "local-org"
+
+/** WHO is asking. One shared graph (the DB at CONTEXT_DB), but EACH process carries
+ *  its own identity from env, so N users hit the same graph and each sees only their
+ *  ACL slice. Single-user default (no env) → local-user/local-org/admin, unchanged. */
+export interface Identity {
+  userId: string
+  orgId: string
+  role: Role
+  groups: string[]
+}
+export function identity(): Identity {
+  const userId = process.env.CONTEXT_USER_ID
+  return {
+    userId: userId || LOCAL_USER,
+    orgId: process.env.CONTEXT_ORG_ID || LOCAL_ORG,
+    // explicit identity ⇒ default to least-privilege 'editor'; personal default ⇒ 'admin'.
+    role: ((process.env.CONTEXT_USER_ROLE as Role) || (userId ? "editor" : "admin")) as Role,
+    groups: (process.env.CONTEXT_USER_GROUPS || "").split(",").map((g) => g.trim()).filter(Boolean),
+  }
+}
+
+let cached: (EmbeddedContext & { userId: string; orgId: string }) | null = null
+
+export function personalContextPath(): string {
+  if (process.env.CONTEXT_DB) return process.env.CONTEXT_DB
+  const dir = path.join(os.homedir(), ".local", "share", "100xprompt")
+  return path.join(dir, "context.db")
+}
+
+/** Pick the embedder from env: real semantic (transformers) or the offline
+ *  keyword-hash default. CONTEXT_EMBEDDINGS=transformers enables the real model. */
+export function pickEmbeddings(): EmbeddingProvider {
+  const mode = (process.env.CONTEXT_EMBEDDINGS ?? "auto").toLowerCase()
+  if (mode === "hash") return new LocalHashEmbeddings()
+  if (mode === "transformers") return new TransformersEmbeddings(process.env.CONTEXT_EMBED_MODEL || undefined)
+  return new AutoEmbeddings(process.env.CONTEXT_EMBED_MODEL || undefined) // default: real, hash fallback
+}
+
+/** Build the sovereign/local LLM client if CONTEXT_LLM_URL is set (used for both
+ *  typed-triple extraction and KGQA question parsing). */
+export function pickLlm(): LlmExtractor | undefined {
+  const url = process.env.CONTEXT_LLM_URL
+  if (!url) return undefined
+  return new LlmExtractor({
+    endpoint: url,
+    model: process.env.CONTEXT_LLM_MODEL || "default",
+    apiKey: process.env.CONTEXT_LLM_KEY,
+  })
+}
+
+/** Deterministic by default; Hybrid (deterministic + LLM) when a local model is set. */
+export function pickExtractor(llm?: LlmExtractor): KnowledgeExtractor {
+  return llm ? new HybridExtractor(new DeterministicExtractor(), llm) : new DeterministicExtractor()
+}
+
+export function personalContext() {
+  if (cached) return cached
+  const dbPath = personalContextPath()
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true })
+  const llm = pickLlm()
+  const ctx = buildEmbeddedContext({ path: dbPath, embeddings: pickEmbeddings(), extractor: pickExtractor(llm), llm, reranker: pickReranker() })
+  const { userId, orgId, role, groups } = identity()
+  // Provision the asking user into the SHARED graph: their role + group memberships
+  // drive what they can create and access. Idempotent (INSERT OR REPLACE).
+  ctx.ingestor.registerUser(userId, orgId, undefined, role)
+  for (const g of groups) {
+    ctx.ingestor.registerGroup(g)
+    ctx.ingestor.addMembership(userId, g)
+  }
+  cached = Object.assign(ctx, { userId, orgId })
+  return cached
+}