@restormel/graphrag-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — @restormel/graphrag-core
+
+## 0.1.0 — 2026-06-01
+
+- Initial extraction from SOPHIA retrieval pipeline (Phase 4 suite migration).
+- `retrieveContext`, `buildContextBlock`, hybrid/seed/balance helpers, Surreal enhancement fetchers (store-injected).
+- `emptyGraphData` helper retained for consumer smoke tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Boon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @restormel/graphrag-core
+
+Graph-aware **Retrieve** pipeline for Knowledge RAG — hybrid dense/lexical seeding, beam graph traversal, argument closure, and LLM context formatting. Host apps inject **`GraphStore`** and **`EmbeddingPort`** (no Surreal driver in this package).
+
+## Install
+
+```bash
+npm install @restormel/graphrag-core @restormel/contracts
+```
+
+## Usage
+
+```ts
+import {
+  retrieveContext,
+  buildContextBlock,
+  type GraphRagDeps,
+} from "@restormel/graphrag-core";
+
+const deps: GraphRagDeps = {
+  store: sophiaGraphStore,
+  embedder: { embedQuery: (text) => hostEmbedQuery(text) },
+  resolveOriginBucket: (url, sourceType) => hostOriginBucket(url, sourceType),
+};
+
+const result = await retrieveContext("What is epistemic injustice?", deps, {
+  topK: 6,
+  maxClaims: 24,
+});
+
+const promptBlock = buildContextBlock(result);
+```
+
+Compose with **`@restormel/context-packs`** for pass-specific analysis/critique/synthesis blocks (host adapter maps `RetrievalResult` → `ContextPackRetrievalInput`).
+
+## Publish
+
+Tag **`platform-v*`** in the restormel-keys monorepo — see [docs/restormel/SUITE-ARCHITECTURE-MIGRATION.md](../../docs/restormel/SUITE-ARCHITECTURE-MIGRATION.md) Phase 4.

package/dist/empty-graph.d.ts

@@ -0,0 +1,4 @@
+import type { GraphData } from "@restormel/graph-core/viewModel";
+export declare function emptyGraphData(): GraphData;
+export type { GraphData } from "@restormel/graph-core/viewModel";
+//# sourceMappingURL=empty-graph.d.ts.map

package/dist/empty-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-graph.d.ts","sourceRoot":"","sources":["../src/empty-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAEjE,wBAAgB,cAAc,IAAI,SAAS,CAE1C;AAED,YAAY,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/empty-graph.js

@@ -0,0 +1,3 @@
+export function emptyGraphData() {
+    return { nodes: [], edges: [], ghostNodes: [], ghostEdges: [] };
+}

package/dist/hybrid-candidate-generation.d.ts

@@ -0,0 +1,23 @@
+export interface HybridCandidate {
+    id: string;
+    text: string;
+    confidence: number;
+    source_title: string;
+    section_context?: string | null;
+}
+export interface HybridFusionResult<T extends HybridCandidate> {
+    ranked: T[];
+    denseCount: number;
+    lexicalCount: number;
+    fusedCount: number;
+}
+export declare function detectCorpusLevelQuery(query: string): boolean;
+export declare function extractLexicalTerms(query: string): string[];
+export declare function fuseHybridCandidates<T extends HybridCandidate>(params: {
+    dense: T[];
+    lexical: T[];
+    lexicalTerms: string[];
+    poolSize: number;
+    corpusLevelQuery: boolean;
+}): HybridFusionResult<T>;
+//# sourceMappingURL=hybrid-candidate-generation.d.ts.map

package/dist/hybrid-candidate-generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-candidate-generation.d.ts","sourceRoot":"","sources":["../src/hybrid-candidate-generation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,eAAe;IAC3D,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAoDD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG7D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAmC3D;AAoCD,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE;IACtE,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAoCxB"}

package/dist/hybrid-candidate-generation.js

@@ -0,0 +1,147 @@
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'be',
+    'by',
+    'for',
+    'from',
+    'how',
+    'in',
+    'is',
+    'it',
+    'of',
+    'on',
+    'or',
+    'that',
+    'the',
+    'this',
+    'to',
+    'what',
+    'when',
+    'where',
+    'which',
+    'why',
+    'with'
+]);
+const CORPUS_LEVEL_SIGNALS = [
+    'across philosophy',
+    'across traditions',
+    'across thinkers',
+    'historical development',
+    'main positions',
+    'overview',
+    'survey',
+    'big picture',
+    'in general'
+];
+function normalize(text) {
+    return text.toLowerCase().replace(/[^\w\s-]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function uniq(input) {
+    return [...new Set(input)];
+}
+export function detectCorpusLevelQuery(query) {
+    const q = normalize(query);
+    return CORPUS_LEVEL_SIGNALS.some((signal) => q.includes(signal));
+}
+export function extractLexicalTerms(query) {
+    const normalized = normalize(query);
+    if (!normalized)
+        return [];
+    const terms = [];
+    const quoted = [...query.matchAll(/"([^"]+)"/g)].map((m) => normalize(m[1])).filter(Boolean);
+    terms.push(...quoted);
+    const hyphenated = normalized.match(/\b[a-z0-9]+(?:-[a-z0-9]+)+\b/g) ?? [];
+    terms.push(...hyphenated);
+    const tokens = normalized.split(' ').filter(Boolean);
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const bigram = `${tokens[i]} ${tokens[i + 1]}`;
+        if (!STOPWORDS.has(tokens[i]) &&
+            !STOPWORDS.has(tokens[i + 1]) &&
+            bigram.length >= 10) {
+            terms.push(bigram);
+        }
+    }
+    for (const token of tokens) {
+        if (token.length >= 8 && !STOPWORDS.has(token)) {
+            terms.push(token);
+        }
+    }
+    const knownPhrases = ['public reason', 'epistemic injustice', 'non-identity problem'];
+    for (const phrase of knownPhrases) {
+        if (normalized.includes(phrase))
+            terms.push(phrase);
+    }
+    return uniq(terms).slice(0, 8);
+}
+function rrf(rank, k = 60) {
+    return 1 / (k + rank);
+}
+function termCoverage(text, terms) {
+    if (terms.length === 0)
+        return 0;
+    const normalized = normalize(text);
+    let hits = 0;
+    for (const term of terms) {
+        if (normalized.includes(term))
+            hits += 1;
+    }
+    return hits / terms.length;
+}
+function diversifyBySource(ranked, size) {
+    const selected = [];
+    const seenSources = new Set();
+    for (const row of ranked) {
+        if (selected.length >= size)
+            break;
+        if (!seenSources.has(row.source_title)) {
+            selected.push(row);
+            seenSources.add(row.source_title);
+        }
+    }
+    for (const row of ranked) {
+        if (selected.length >= size)
+            break;
+        if (!selected.includes(row))
+            selected.push(row);
+    }
+    return selected;
+}
+export function fuseHybridCandidates(params) {
+    const { dense, lexical, lexicalTerms, poolSize, corpusLevelQuery } = params;
+    const denseRanks = new Map();
+    const lexicalRanks = new Map();
+    const byId = new Map();
+    dense.forEach((row, idx) => {
+        denseRanks.set(row.id, idx + 1);
+        byId.set(row.id, row);
+    });
+    lexical.forEach((row, idx) => {
+        lexicalRanks.set(row.id, idx + 1);
+        if (!byId.has(row.id))
+            byId.set(row.id, row);
+    });
+    const scored = Array.from(byId.values()).map((row) => {
+        const denseRank = denseRanks.get(row.id);
+        const lexicalRank = lexicalRanks.get(row.id);
+        const fusionScore = (denseRank ? rrf(denseRank) : 0) + (lexicalRank ? rrf(lexicalRank) : 0);
+        const coverage = termCoverage(`${row.text} ${row.section_context ?? ''}`, lexicalTerms);
+        const rerankScore = fusionScore + coverage * 0.025 + Math.max(0, row.confidence) * 0.01;
+        return { row, rerankScore };
+    });
+    scored.sort((a, b) => b.rerankScore - a.rerankScore);
+    const ordered = scored.map((s) => s.row);
+    const ranked = corpusLevelQuery
+        ? diversifyBySource(ordered, poolSize)
+        : ordered.slice(0, poolSize);
+    return {
+        ranked,
+        denseCount: dense.length,
+        lexicalCount: lexical.length,
+        fusedCount: ranked.length
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { GraphStore, EmbeddingPort, GraphRagDeps, OriginBucketResolver, RetrievalOriginBalanceKey, } from "./ports.js";
+export { detectCorpusLevelQuery, extractLexicalTerms, fuseHybridCandidates, type HybridCandidate, type HybridFusionResult, } from "./hybrid-candidate-generation.js";
+export { constructSeedSet, type SeedCandidate, type SeedBalanceStats, type SeedRole, type SeedSetConstructionResult, } from "./seed-set-constructor.js";
+export { IDEAL_RETRIEVAL_ORIGIN_FRACTIONS, RETRIEVAL_ORIGIN_BALANCE_STRENGTH, RETRIEVAL_DOMAIN_BALANCE_STRENGTH, isRetrievalKgBalanceEnabled, computeKgBalanceMultiplier, } from "./kg-balance.js";
+export { isRetrievalBm25Enabled, isRetrievalNativeGraphEnabled, isRetrievalPassageGroundedEnabled, isRetrievalTaxonomyRoutingEnabled, isKgEnforcePassageOnAcceptEnabled, fetchBm25ClaimCandidates, fetchNativeGraphNeighbors, fetchPassageGroundedClaimIds, fetchTaxonomySeedClaimIds, ensureClaimSearchIndex, ensurePassageEmbeddingIndex, ensureClaimAcceptPassageEvent, } from "./surreal-retrieval-enhancements.js";
+export { retrieveContext, buildContextBlock, formatThinkerContextBlock, type RetrievedClaim, type RetrievedRelation, type RetrievedArgument, type ThinkerSummary, type ThinkerContext, type RejectedClaimReasonCode, type RejectedRelationReasonCode, type RejectedClaimCandidate, type RejectedRelationCandidate, type ClosureUnitTrace, type RetrievalClosureStats, type RetrievalSeedTrace, type RetrievalQueryDecompositionTrace, type RetrievalPruningSummaryTrace, type RetrievalResult, type RetrievalOptions, } from "./retrieve-context.js";
+export { emptyGraphData, type GraphData } from "./empty-graph.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,gCAAgC,EAChC,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,iCAAiC,EACjC,iCAAiC,EACjC,iCAAiC,EACjC,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,GAC9B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,gCAAgC,EACrC,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { detectCorpusLevelQuery, extractLexicalTerms, fuseHybridCandidates, } from "./hybrid-candidate-generation.js";
+export { constructSeedSet, } from "./seed-set-constructor.js";
+export { IDEAL_RETRIEVAL_ORIGIN_FRACTIONS, RETRIEVAL_ORIGIN_BALANCE_STRENGTH, RETRIEVAL_DOMAIN_BALANCE_STRENGTH, isRetrievalKgBalanceEnabled, computeKgBalanceMultiplier, } from "./kg-balance.js";
+export { isRetrievalBm25Enabled, isRetrievalNativeGraphEnabled, isRetrievalPassageGroundedEnabled, isRetrievalTaxonomyRoutingEnabled, isKgEnforcePassageOnAcceptEnabled, fetchBm25ClaimCandidates, fetchNativeGraphNeighbors, fetchPassageGroundedClaimIds, fetchTaxonomySeedClaimIds, ensureClaimSearchIndex, ensurePassageEmbeddingIndex, ensureClaimAcceptPassageEvent, } from "./surreal-retrieval-enhancements.js";
+export { retrieveContext, buildContextBlock, formatThinkerContextBlock, } from "./retrieve-context.js";
+export { emptyGraphData } from "./empty-graph.js";

package/dist/kg-balance.d.ts

@@ -0,0 +1,21 @@
+import type { PhilosophicalDomain } from "@restormel/contracts/domains";
+/** Target mix for inquiry-time retrieval seed selection (not operator dataset metrics). */
+export type RetrievalOriginBalanceKey = "sep" | "gutenberg" | "other";
+/** Default SEP / Gutenberg / other mix for seed claims (sums to 1). */
+export declare const IDEAL_RETRIEVAL_ORIGIN_FRACTIONS: Record<RetrievalOriginBalanceKey, number>;
+export declare const RETRIEVAL_ORIGIN_BALANCE_STRENGTH = 0.95;
+export declare const RETRIEVAL_DOMAIN_BALANCE_STRENGTH = 0.85;
+export declare function isRetrievalKgBalanceEnabled(): boolean;
+/** Multiplicative boost for MMR relevance (1 = neutral). Uses deficit vs ideal fractions. */
+export declare function computeKgBalanceMultiplier(params: {
+    origin: RetrievalOriginBalanceKey;
+    domain: PhilosophicalDomain | string | null | undefined;
+    selectedOriginCounts: Record<RetrievalOriginBalanceKey, number>;
+    selectedDomainCounts: Map<string, number>;
+    totalSelected: number;
+    idealOrigin: Record<RetrievalOriginBalanceKey, number>;
+    domainsInPool: Set<string>;
+    originStrength?: number;
+    domainStrength?: number;
+}): number;
+//# sourceMappingURL=kg-balance.d.ts.map

package/dist/kg-balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kg-balance.d.ts","sourceRoot":"","sources":["../src/kg-balance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,2FAA2F;AAC3F,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,WAAW,GAAG,OAAO,CAAC;AAEtE,uEAAuE;AACvE,eAAO,MAAM,gCAAgC,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAItF,CAAC;AAEF,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAEtD,wBAAgB,2BAA2B,IAAI,OAAO,CAGrD;AAeD,6FAA6F;AAC7F,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,yBAAyB,CAAC;IAClC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxD,oBAAoB,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;IAChE,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;IACvD,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAiCT"}

package/dist/kg-balance.js

@@ -0,0 +1,43 @@
+/** Default SEP / Gutenberg / other mix for seed claims (sums to 1). */
+export const IDEAL_RETRIEVAL_ORIGIN_FRACTIONS = {
+    sep: 0.42,
+    gutenberg: 0.33,
+    other: 0.25,
+};
+export const RETRIEVAL_ORIGIN_BALANCE_STRENGTH = 0.95;
+export const RETRIEVAL_DOMAIN_BALANCE_STRENGTH = 0.85;
+export function isRetrievalKgBalanceEnabled() {
+    const v = (process.env.RETRIEVAL_KG_BALANCE ?? "1").trim().toLowerCase();
+    return v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+function normalizeFractions(w) {
+    const sum = Object.values(w).reduce((a, b) => a + (Number.isFinite(b) ? b : 0), 0);
+    if (sum <= 0)
+        return { ...w };
+    const out = {};
+    for (const k of Object.keys(w)) {
+        out[k] = w[k] / sum;
+    }
+    return out;
+}
+/** Multiplicative boost for MMR relevance (1 = neutral). Uses deficit vs ideal fractions. */
+export function computeKgBalanceMultiplier(params) {
+    const { origin, domain, selectedOriginCounts, selectedDomainCounts, totalSelected, idealOrigin, domainsInPool, originStrength = RETRIEVAL_ORIGIN_BALANCE_STRENGTH, domainStrength = RETRIEVAL_DOMAIN_BALANCE_STRENGTH, } = params;
+    if (totalSelected === 0)
+        return 1;
+    const idealO = normalizeFractions(idealOrigin);
+    const curO = selectedOriginCounts[origin] / totalSelected;
+    const tgtO = idealO[origin] ?? 0;
+    const originMult = tgtO > 0 ? 1 + originStrength * Math.max(0, (tgtO - curO) / Math.max(0.08, tgtO)) : 1;
+    let domainMult = 1;
+    const nDom = domainsInPool.size;
+    if (nDom > 1 && domain) {
+        const dKey = String(domain);
+        if (domainsInPool.has(dKey)) {
+            const idealD = 1 / nDom;
+            const curD = (selectedDomainCounts.get(dKey) ?? 0) / totalSelected;
+            domainMult = 1 + domainStrength * Math.max(0, (idealD - curD) / Math.max(0.06, idealD));
+        }
+    }
+    return Math.min(2.4, originMult * domainMult);
+}

package/dist/ports.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Injected graph read port — Surreal (or other) implementations live in the host app.
+ */
+export interface GraphStore {
+    query<T>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+    isDatabaseUnavailable(error: unknown): boolean;
+}
+export interface EmbeddingPort {
+    embedQuery(text: string): Promise<number[]>;
+}
+export type RetrievalOriginBalanceKey = "sep" | "gutenberg" | "other";
+/** Host resolves corpus origin bucket (SOPHIA uses ingestRuns URL heuristics). */
+export type OriginBucketResolver = (url: string | null | undefined, storedSourceType?: string | null) => RetrievalOriginBalanceKey;
+export interface GraphRagDeps {
+    store: GraphStore;
+    embedder: EmbeddingPort;
+    resolveOriginBucket: OriginBucketResolver;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClE,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,WAAW,GAAG,OAAO,CAAC;AAEtE,kFAAkF;AAClF,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,KAC7B,yBAAyB,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,mBAAmB,EAAE,oBAAoB,CAAC;CAC3C"}

package/dist/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/retrieve-context.d.ts

@@ -0,0 +1,196 @@
+/**
+ * SOPHIA — Argument-Aware Retrieval
+ *
+ * Core differentiator: not just semantic similarity, but graph traversal
+ * that assembles complete argumentative chains from the knowledge graph.
+ *
+ * Retrieval pipeline:
+ *   1. Embed query via Voyage AI
+ *   2. Vector search for top-K semantically similar claims
+ *   3. Graph traversal for each seed claim (depends_on, supports, contradicts, responds_to, defines, qualifies, part_of)
+ *   4. Deduplicate claims
+ *   5. Resolve inter-claim relations
+ *   6. Fetch argument structure (conclusion + key premises)
+ *   7. Return assembled RetrievalResult
+ *
+ * Graceful degradation: never throws — returns empty result on any failure
+ * so the three-pass engine can still work without the graph.
+ */
+import type { PhilosophicalDomain } from '@restormel/contracts/domains';
+import type { GraphRagDeps } from './ports.js';
+import { type SeedBalanceStats } from './seed-set-constructor.js';
+export interface RetrievedClaim {
+    id: string;
+    text: string;
+    claim_type: string;
+    domain: PhilosophicalDomain;
+    source_title: string;
+    source_author: string[];
+    confidence: number;
+    position_in_source: number;
+}
+export interface RetrievedRelation {
+    from_index: number;
+    to_index: number;
+    relation_type: string;
+    strength?: string;
+    note?: string;
+}
+export interface RetrievedArgument {
+    id: string;
+    name: string;
+    tradition: string | null;
+    domain: PhilosophicalDomain;
+    summary: string;
+    conclusion_text: string | null;
+    key_premises: string[];
+}
+export interface ThinkerSummary {
+    wikidata_id: string;
+    name: string;
+    birth_year: number | null;
+    death_year: number | null;
+    traditions: string[];
+}
+export interface ThinkerContext {
+    direct_authors: ThinkerSummary[];
+    influences: ThinkerSummary[];
+    teachers: ThinkerSummary[];
+}
+export type RejectedClaimReasonCode = 'seed_pool_pruned' | 'duplicate_traversal' | 'confidence_gate' | 'source_integrity_gate';
+export type RejectedRelationReasonCode = 'duplicate_relation' | 'missing_endpoint';
+export interface RejectedClaimCandidate {
+    id: string;
+    text: string;
+    source_title: string;
+    confidence?: number;
+    reason_code: RejectedClaimReasonCode;
+    considered_in: 'seed_pool' | 'traversal';
+    anchor_claim_id?: string;
+}
+export interface RejectedRelationCandidate {
+    from_claim_id: string;
+    to_claim_id: string;
+    relation_type: string;
+    reason_code: RejectedRelationReasonCode;
+    strength?: string;
+    note?: string;
+}
+export interface ClosureUnitTrace {
+    thesis_claim_id: string;
+    objection_claim_id?: string;
+    reply_claim_id?: string;
+    objection_found: boolean;
+    reply_found: boolean;
+    unit_complete: boolean;
+}
+export interface RetrievalClosureStats {
+    major_thesis_count: number;
+    units_attempted: number;
+    units_completed: number;
+    claims_added_for_closure: number;
+    objections_added: number;
+    replies_added: number;
+    cap_limited_units: number;
+    units: ClosureUnitTrace[];
+}
+export interface RetrievalSeedTrace {
+    id: string;
+    claim_type: string;
+    domain: PhilosophicalDomain;
+    source_title: string;
+    confidence: number;
+}
+export interface RetrievalQueryDecompositionTrace {
+    focus_mode: 'corpus_overview' | 'focused';
+    domain_filter?: PhilosophicalDomain;
+    hybrid_mode: 'auto' | 'dense_only';
+    corpus_level_query: boolean;
+    lexical_terms: string[];
+    lexical_term_count: number;
+}
+export interface RetrievalPruningSummaryTrace {
+    claims_by_reason: Record<RejectedClaimReasonCode, number>;
+    relations_by_reason: Record<RejectedRelationReasonCode, number>;
+}
+export interface RetrievalResult {
+    claims: RetrievedClaim[];
+    relations: RetrievedRelation[];
+    arguments: RetrievedArgument[];
+    seed_claim_ids: string[];
+    evidence_passages?: Array<{
+        passage_id: string;
+        excerpt: string;
+        claim_ids: string[];
+    }>;
+    thinker_context?: ThinkerContext | null;
+    trace?: {
+        seed_pool_count: number;
+        selected_seed_count: number;
+        hybrid_mode?: 'auto' | 'dense_only';
+        dense_seed_count?: number;
+        lexical_seed_count?: number;
+        lexical_terms?: string[];
+        corpus_level_query?: boolean;
+        seed_balance_stats?: SeedBalanceStats;
+        traversal_mode?: 'beam_trusted_v1';
+        traversal_max_hops?: number;
+        traversal_hop_decay?: number;
+        traversal_base_confidence_threshold?: number;
+        traversal_confidence_thresholds?: number[];
+        traversal_domain_aware?: boolean;
+        traversal_trusted_edges_only?: boolean;
+        traversal_edge_priors?: Partial<Record<string, number>>;
+        query_decomposition?: RetrievalQueryDecompositionTrace;
+        seed_claims?: RetrievalSeedTrace[];
+        pruning_summary?: RetrievalPruningSummaryTrace;
+        traversed_claim_count: number;
+        relation_candidate_count: number;
+        relation_kept_count: number;
+        argument_candidate_count: number;
+        argument_kept_count: number;
+        closure_stats?: RetrievalClosureStats;
+        rejected_claims?: RejectedClaimCandidate[];
+        rejected_relations?: RejectedRelationCandidate[];
+    };
+    degraded: boolean;
+    degraded_reason?: string;
+}
+export interface RetrievalOptions {
+    /** Number of seed claims from vector search (default: 5) */
+    topK?: number;
+    /** Filter by philosophical domain */
+    domain?: PhilosophicalDomain;
+    /** Minimum confidence threshold for claims (default: 0) */
+    minConfidence?: number;
+    /** Optional override for graph traversal depth (hops from seed claims) */
+    maxHops?: number;
+    /** Optional cap on total claims returned after traversal */
+    maxClaims?: number;
+    /** Optional retrieval mode override for baseline comparisons */
+    hybridMode?: 'auto' | 'dense_only';
+    /** Optional viewer context for trace/audit routing */
+    viewerUid?: string | null;
+    /** Opt-in thinker graph enrichment for retrieved claim context */
+    enrichWithThinkerContext?: boolean;
+}
+export declare function formatThinkerContextBlock(context: ThinkerContext | null): string;
+/**
+ * Retrieve structured philosophical context from the argument graph.
+ *
+ * Assembles complete argumentative chains by:
+ * 1. Finding semantically similar claims via vector search
+ * 2. Traversing the graph for supporting/contradicting/dependent claims
+ * 3. Resolving arguments those claims participate in
+ *
+ * Never throws — returns empty result on any failure.
+ */
+export declare function retrieveContext(userQuery: string, deps: GraphRagDeps, options?: RetrievalOptions): Promise<RetrievalResult>;
+/**
+ * Format a RetrievalResult into a structured text block for the LLM prompt.
+ *
+ * Returns a human-readable representation of the retrieved argument graph
+ * that the model can use as grounding context for its three-pass analysis.
+ */
+export declare function buildContextBlock(result: RetrievalResult): string;
+//# sourceMappingURL=retrieve-context.d.ts.map

package/dist/retrieve-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve-context.d.ts","sourceRoot":"","sources":["../src/retrieve-context.ts"],"names":[],"mappings":"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"}