kodingo-core 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from "./src/domain/decision/decision";
 export * from "./src/domain/decision/decision-outcome";
 export * from "./src/domain/decision/decision-event";
 export * from "./src/domain/decision/decision-errors";
+export * from "./src/query/query-engine";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AAErD,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAElD,cAAc,wCAAwC,CAAC;AACvD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AAErD,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAElD,cAAc,wCAAwC,CAAC;AACvD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -27,4 +27,5 @@ __exportStar(require("./src/domain/decision/decision"), exports);
 __exportStar(require("./src/domain/decision/decision-outcome"), exports);
 __exportStar(require("./src/domain/decision/decision-event"), exports);
 __exportStar(require("./src/domain/decision/decision-errors"), exports);
+__exportStar(require("./src/query/query-engine"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qEAAmD;AACnD,uEAAqD;AAErD,0DAAwC;AACxC,6DAA2C;AAC3C,yDAAuC;AACvC,yDAAuC;AAEvC,qEAAmD;AACnD,oEAAkD;AAElD,yEAAuD;AACvD,iEAA+C;AAC/C,yEAAuD;AACvD,uEAAqD;AACrD,wEAAsD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qEAAmD;AACnD,uEAAqD;AAErD,0DAAwC;AACxC,6DAA2C;AAC3C,yDAAuC;AACvC,yDAAuC;AAEvC,qEAAmD;AACnD,oEAAkD;AAElD,yEAAuD;AACvD,iEAA+C;AAC/C,yEAAuD;AACvD,uEAAqD;AACrD,wEAAsD;AACtD,2DAAyC"}

package/dist/src/query/query-engine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * query-engine.ts
+ *
+ * Core domain logic for the Kortex query engine.
+ * Defines types, ranking, and synthesis interface.
+ * No LLM calls, no DB access — pure deterministic domain logic.
+ */
+import type { MemoryRecord } from "../domain/memory/project-memory";
+export type QueryIntentType = "concept" | "symbol" | "decision_history" | "comparison" | "general";
+export interface QueryIntent {
+    raw: string;
+    type: QueryIntentType;
+    entities: string[];
+    symbolHint?: string;
+    confidence: number;
+}
+export interface QuerySource {
+    memory: MemoryRecord;
+    relevanceScore: number;
+    vectorScore: number;
+    domainScore: number;
+}
+export interface QueryResult {
+    answer: string;
+    sources: QuerySource[];
+    intent: QueryIntent;
+    synthesisedAt: Date;
+    totalCandidates: number;
+}
+export interface SynthesisPort {
+    /**
+     * Generate a natural language answer grounded in the provided memories.
+     * Implementations use an LLM with the memories as context.
+     */
+    synthesise(params: {
+        intent: QueryIntent;
+        memories: MemoryRecord[];
+        projectName?: string;
+    }): Promise<{
+        answer: string;
+    }>;
+}
+/**
+ * Re-ranks vector search candidates using domain scoring.
+ * Called after pgvector retrieval to apply Kortex-specific ranking rules.
+ *
+ * Combined score = (vectorScore * 0.6) + (domainScore * 0.4)
+ * Vector similarity is weighted higher but domain scoring prevents
+ * low-confidence or denied memories from surfacing.
+ */
+export declare function rankMemoriesForQuery(candidates: Array<{
+    memory: MemoryRecord;
+    vectorScore: number;
+}>, intent: QueryIntent): QuerySource[];
+/**
+ * Builds the context string passed to the LLM for synthesis.
+ * Formats ranked memories into a structured prompt context.
+ */
+export declare function buildQueryContext(sources: QuerySource[], maxSources?: number): string;
+//# sourceMappingURL=query-engine.d.ts.map

package/dist/src/query/query-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-engine.d.ts","sourceRoot":"","sources":["../../../src/query/query-engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIpE,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,QAAQ,GACR,kBAAkB,GAClB,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,WAAW,CAAC;QACpB,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjC;AAuCD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,EAChE,MAAM,EAAE,WAAW,GAClB,WAAW,EAAE,CAoDf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,UAAU,SAAI,GACb,MAAM,CAgBR"}

package/dist/src/query/query-engine.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * query-engine.ts
+ *
+ * Core domain logic for the Kortex query engine.
+ * Defines types, ranking, and synthesis interface.
+ * No LLM calls, no DB access — pure deterministic domain logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankMemoriesForQuery = rankMemoriesForQuery;
+exports.buildQueryContext = buildQueryContext;
+// ── Ranking ───────────────────────────────────────────────────────────────────
+const STATUS_WEIGHT = {
+    affirmed: 1.0,
+    proposed: 0.6,
+    ignored: 0.3,
+    denied: 0.0,
+};
+const INTENT_TYPE_WEIGHT = {
+    concept: {
+        decision: 1.0,
+        context: 0.8,
+        note: 0.6,
+    },
+    symbol: {
+        context: 1.0,
+        decision: 0.8,
+        note: 0.6,
+    },
+    decision_history: {
+        decision: 1.0,
+        note: 0.7,
+        context: 0.5,
+    },
+    comparison: {
+        decision: 1.0,
+        context: 0.8,
+        note: 0.6,
+    },
+    general: {
+        decision: 0.9,
+        context: 0.9,
+        note: 0.7,
+    },
+};
+/**
+ * Re-ranks vector search candidates using domain scoring.
+ * Called after pgvector retrieval to apply Kortex-specific ranking rules.
+ *
+ * Combined score = (vectorScore * 0.6) + (domainScore * 0.4)
+ * Vector similarity is weighted higher but domain scoring prevents
+ * low-confidence or denied memories from surfacing.
+ */
+function rankMemoriesForQuery(candidates, intent) {
+    const intentWeights = INTENT_TYPE_WEIGHT[intent.type] ?? INTENT_TYPE_WEIGHT.general;
+    return candidates
+        .map(({ memory, vectorScore }) => {
+        const statusScore = STATUS_WEIGHT[memory.status] ?? 0;
+        const typeScore = intentWeights[memory.type] ?? 0.5;
+        const confidenceScore = memory.confidence;
+        // Boost if symbol matches the hint exactly
+        const symbolBoost = intent.symbolHint &&
+            memory.symbol?.toLowerCase().includes(intent.symbolHint.toLowerCase())
+            ? 0.2
+            : 0;
+        // Boost if any entity matches tags or symbol
+        const entityBoost = intent.entities.some(e => memory.tags?.some(t => t.toLowerCase().includes(e.toLowerCase())) ||
+            memory.symbol?.toLowerCase().includes(e.toLowerCase()) ||
+            memory.title?.toLowerCase().includes(e.toLowerCase()))
+            ? 0.15
+            : 0;
+        // Recency boost — memories updated in last 30 days get a small boost
+        const daysSinceUpdate = (Date.now() - new Date(memory.updatedAt).getTime()) / (1000 * 60 * 60 * 24);
+        const recencyBoost = daysSinceUpdate < 30 ? 0.05 : 0;
+        const domainScore = Math.min(1, statusScore * 0.4 +
+            typeScore * 0.25 +
+            confidenceScore * 0.2 +
+            symbolBoost +
+            entityBoost +
+            recencyBoost);
+        // Denied memories never surface regardless of vector score
+        if (memory.status === "denied") {
+            return { memory, vectorScore, domainScore: 0, relevanceScore: 0 };
+        }
+        const relevanceScore = vectorScore * 0.6 + domainScore * 0.4;
+        return { memory, vectorScore, domainScore, relevanceScore };
+    })
+        .filter(s => s.relevanceScore > 0)
+        .sort((a, b) => b.relevanceScore - a.relevanceScore);
+}
+/**
+ * Builds the context string passed to the LLM for synthesis.
+ * Formats ranked memories into a structured prompt context.
+ */
+function buildQueryContext(sources, maxSources = 8) {
+    return sources
+        .slice(0, maxSources)
+        .map((s, i) => {
+        const m = s.memory;
+        const lines = [];
+        lines.push(`[Source ${i + 1}]`);
+        if (m.title)
+            lines.push(`Title: ${m.title}`);
+        if (m.symbol)
+            lines.push(`Symbol: ${m.symbol}`);
+        if (m.repo)
+            lines.push(`Repo: ${m.repo}`);
+        lines.push(`Type: ${m.type} | Status: ${m.status} | Confidence: ${Math.round(m.confidence * 100)}%`);
+        if (m.tags?.length)
+            lines.push(`Tags: ${m.tags.join(", ")}`);
+        lines.push(`Content: ${m.content}`);
+        return lines.join("\n");
+    })
+        .join("\n\n---\n\n");
+}
+//# sourceMappingURL=query-engine.js.map

package/dist/src/query/query-engine.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodingo-core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Core domain logic and ports for Kodingo.",
   "license": "ISC",
   "type": "commonjs",