@kilnai/core 0.1.16 → 0.9.1

package/dist/knowledge/contact-memory.js

@@ -0,0 +1,235 @@
+// Contact memory: per-user fact storage across conversations
+// Extracts structured facts via LLM (Mem0 ADD/UPDATE/DELETE/NOOP pattern)
+// Stores facts as vector entries with metadata for recall via similarity search
+import { textParts, extractText } from "../engine/domain/content.js";
+import { withRetry } from "../agents/infrastructure/retry.js";
+import { KilnError } from "../engine/errors.js";
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const EXTRACTION_MAX_TOKENS = 2048;
+const DEFAULT_RECALL_LIMIT = 20;
+const CONTACT_FACT_TYPE = "contact_fact";
+const EXTRACTION_SYSTEM_PROMPT = `You extract facts about the customer from conversations.
+
+For each fact, output a JSON array of objects:
+[{"action": "ADD", "content": "...", "category": "preference"|"entity"|"issue"|"general", "confidence": 0.0-1.0}]
+
+Rules:
+- Only extract facts about the CUSTOMER, not the agent
+- ADD: new fact not previously known
+- UPDATE: correction or update to a previously known fact (include "existingFactId" if provided in existing facts)
+- DELETE: fact no longer true (include "existingFactId" if provided in existing facts)
+- NOOP: fact already known and unchanged
+- High confidence (0.7-1.0) for explicit statements, lower (0.3-0.6) for inferences
+- No trivial or obvious facts
+- Output ONLY the JSON array, nothing else`;
+const VALID_ACTIONS = new Set(["ADD", "UPDATE", "DELETE", "NOOP"]);
+const VALID_CATEGORIES = new Set(["preference", "entity", "issue", "general"]);
+function isValidExtractedFact(f) {
+    if (typeof f !== "object" || f === null)
+        return false;
+    const obj = f;
+    return (typeof obj.action === "string" &&
+        VALID_ACTIONS.has(obj.action) &&
+        typeof obj.content === "string" &&
+        obj.content.length > 0 &&
+        typeof obj.category === "string" &&
+        VALID_CATEGORIES.has(obj.category) &&
+        typeof obj.confidence === "number" &&
+        obj.confidence >= 0 &&
+        obj.confidence <= 1);
+}
+function vectorResultToContactFact(result) {
+    const m = result.metadata;
+    if (m.type !== CONTACT_FACT_TYPE)
+        return null;
+    return {
+        id: result.id,
+        externalUserId: String(m.externalUserId ?? ""),
+        tenantId: String(m.tenantId ?? ""),
+        content: result.content,
+        category: m.category ?? "general",
+        confidence: typeof m.confidence === "number" ? m.confidence : 0,
+        validAt: String(m.validAt ?? ""),
+        expiredAt: m.expiredAt ? String(m.expiredAt) : undefined,
+        createdAt: String(m.createdAt ?? ""),
+    };
+}
+export class ContactMemoryServiceImpl {
+    vectorStore;
+    embedder;
+    provider;
+    constructor(config) {
+        this.vectorStore = config.vectorStore;
+        this.embedder = config.embedder;
+        this.provider = config.provider;
+    }
+    async extractAndStore(conversationHistory, externalUserId, tenantId) {
+        if (!conversationHistory.trim())
+            return [];
+        // Recall existing facts to provide context for UPDATE/DELETE
+        const existingFacts = await this.recall(externalUserId, tenantId);
+        let userMessage = `Conversation:\n${conversationHistory}`;
+        if (existingFacts.length > 0) {
+            const existingContext = existingFacts
+                .map((f) => `[id:${f.id}] ${f.content} (${f.category})`)
+                .join("\n");
+            userMessage = `Existing facts about this customer:\n${existingContext}\n\n${userMessage}`;
+        }
+        // LLM extraction -- fail-open
+        let extractedFacts;
+        try {
+            const response = await withRetry(() => this.provider.createMessage({
+                system: EXTRACTION_SYSTEM_PROMPT,
+                messages: [{ role: "user", parts: textParts(userMessage) }],
+                maxTokens: EXTRACTION_MAX_TOKENS,
+            }), {
+                maxRetries: MAX_RETRIES,
+                baseDelayMs: BASE_DELAY_MS,
+                isRetryable: (error) => {
+                    if (error instanceof KilnError)
+                        return error.retryable;
+                    if (error instanceof Error && "status" in error) {
+                        const status = error.status;
+                        return status === 429 || status >= 500;
+                    }
+                    return false;
+                },
+            });
+            const responseText = extractText(response.parts).trim();
+            const parsed = JSON.parse(responseText);
+            if (!Array.isArray(parsed))
+                return [];
+            extractedFacts = parsed.filter(isValidExtractedFact);
+        }
+        catch {
+            // Fail-open: extraction errors are non-fatal
+            return [];
+        }
+        if (extractedFacts.length === 0)
+            return [];
+        const now = new Date().toISOString();
+        const storedFacts = [];
+        for (const fact of extractedFacts) {
+            switch (fact.action) {
+                case "ADD": {
+                    const contactFact = await this.addFact(fact, externalUserId, tenantId, now);
+                    storedFacts.push(contactFact);
+                    break;
+                }
+                case "UPDATE": {
+                    // Expire old fact, then add new version
+                    if (fact.existingFactId) {
+                        await this.expireFact(fact.existingFactId);
+                    }
+                    else {
+                        await this.expireByContent(fact.content, externalUserId, tenantId);
+                    }
+                    const updated = await this.addFact(fact, externalUserId, tenantId, now);
+                    storedFacts.push(updated);
+                    break;
+                }
+                case "DELETE": {
+                    if (fact.existingFactId) {
+                        await this.expireFact(fact.existingFactId);
+                    }
+                    else {
+                        await this.expireByContent(fact.content, externalUserId, tenantId);
+                    }
+                    break;
+                }
+                // NOOP: skip
+            }
+        }
+        return storedFacts;
+    }
+    async recall(externalUserId, tenantId, options) {
+        const limit = options?.limit ?? DEFAULT_RECALL_LIMIT;
+        // If query is provided, use vector similarity to rank results
+        const queryText = options?.query ?? `facts about user ${externalUserId}`;
+        const [embedding] = await this.embedder.embed([queryText]);
+        if (!embedding)
+            return [];
+        const results = await this.vectorStore.query(embedding, {
+            topK: limit * 2, // Fetch extra to filter expired
+            filter: { externalUserId, tenantId, type: CONTACT_FACT_TYPE },
+        });
+        // Filter out expired facts and convert to ContactFact
+        const facts = [];
+        for (const result of results) {
+            if (result.metadata.expiredAt)
+                continue;
+            const fact = vectorResultToContactFact(result);
+            if (fact)
+                facts.push(fact);
+            if (facts.length >= limit)
+                break;
+        }
+        return facts;
+    }
+    // tenantId reserved for future per-tenant isolation at the store level
+    async forget(factId, _tenantId) {
+        await this.vectorStore.delete([factId]);
+    }
+    async forgetAll(externalUserId, tenantId) {
+        await this.vectorStore.deleteByMetadata({
+            externalUserId,
+            tenantId,
+            type: CONTACT_FACT_TYPE,
+        });
+    }
+    async addFact(fact, externalUserId, tenantId, now) {
+        const id = crypto.randomUUID();
+        const [embedding] = await this.embedder.embed([fact.content]);
+        if (!embedding) {
+            throw new KilnError("CONTACT_MEMORY_EXTRACTION_FAILED", "Failed to embed fact content", {
+                context: { content: fact.content },
+            });
+        }
+        await this.vectorStore.upsert([
+            {
+                id,
+                content: fact.content,
+                embedding,
+                metadata: {
+                    externalUserId,
+                    tenantId,
+                    category: fact.category,
+                    confidence: fact.confidence,
+                    validAt: now,
+                    createdAt: now,
+                    type: CONTACT_FACT_TYPE,
+                },
+            },
+        ]);
+        return {
+            id,
+            externalUserId,
+            tenantId,
+            content: fact.content,
+            category: fact.category,
+            confidence: fact.confidence,
+            validAt: now,
+            createdAt: now,
+        };
+    }
+    async expireFact(factId) {
+        // VectorStore doesn't have a get-by-id + update metadata flow,
+        // so we delete the entry. The fact is logically expired (removed from active queries).
+        await this.vectorStore.delete([factId]);
+    }
+    async expireByContent(content, externalUserId, tenantId) {
+        const [embedding] = await this.embedder.embed([content]);
+        if (!embedding)
+            return;
+        const results = await this.vectorStore.query(embedding, {
+            topK: 1,
+            minScore: 0.8,
+            filter: { externalUserId, tenantId, type: CONTACT_FACT_TYPE },
+        });
+        if (results.length > 0 && !results[0].metadata.expiredAt) {
+            await this.vectorStore.delete([results[0].id]);
+        }
+    }
+}
+//# sourceMappingURL=contact-memory.js.map

package/dist/knowledge/contact-memory.js.map

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

package/dist/knowledge/contextual-enricher.d.ts

@@ -0,0 +1,16 @@
+import type { Document, Chunk, ChunkEnricher } from "../engine/domain/chunker.js";
+import type { ProviderAdapter } from "../agents/index.js";
+export interface ContextualEnricherConfig {
+    readonly provider: ProviderAdapter;
+    readonly concurrency?: number;
+    readonly maxDocumentChars?: number;
+}
+export declare class ContextualEnricher implements ChunkEnricher {
+    private readonly provider;
+    private readonly concurrency;
+    private readonly maxDocumentChars;
+    constructor(config: ContextualEnricherConfig);
+    enrich(document: Document, chunks: Chunk[]): Promise<Chunk[]>;
+    private generateContext;
+}
+//# sourceMappingURL=contextual-enricher.d.ts.map

package/dist/knowledge/contextual-enricher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextual-enricher.d.ts","sourceRoot":"","sources":["../../src/knowledge/contextual-enricher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAkB1D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,MAAM,EAAE,wBAAwB;IAMtC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;YAsCrD,eAAe;CA0B9B"}

package/dist/knowledge/contextual-enricher.js

@@ -0,0 +1,82 @@
+// Contextual retrieval enrichment -- Anthropic pattern
+// Prepends document-level context to each chunk before embedding via LLM
+import { textParts, extractText } from "../engine/domain/content.js";
+import { withRetry } from "../agents/infrastructure/retry.js";
+import { KilnError } from "../engine/errors.js";
+const DEFAULT_CONCURRENCY = 5;
+const DEFAULT_MAX_DOCUMENT_CHARS = 100_000;
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const ENRICHMENT_MAX_TOKENS = 200;
+const ENRICHMENT_PROMPT_TEMPLATE = `Here is a chunk from the document:
+<chunk>
+{chunk}
+</chunk>
+
+Give a short succinct context to situate this chunk within the overall document for the purposes of improving search retrieval of the chunk. Answer only with the succinct context and nothing else.`;
+export class ContextualEnricher {
+    provider;
+    concurrency;
+    maxDocumentChars;
+    constructor(config) {
+        this.provider = config.provider;
+        this.concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+        this.maxDocumentChars = config.maxDocumentChars ?? DEFAULT_MAX_DOCUMENT_CHARS;
+    }
+    async enrich(document, chunks) {
+        if (chunks.length === 0)
+            return [];
+        const docContent = document.content.length > this.maxDocumentChars
+            ? document.content.slice(0, this.maxDocumentChars)
+            : document.content;
+        const results = new Array(chunks.length);
+        let cursor = 0;
+        const processChunk = async (index) => {
+            const chunk = chunks[index];
+            try {
+                const context = await this.generateContext(docContent, chunk.content);
+                results[index] = {
+                    ...chunk,
+                    content: `<context>\n${context}\n</context>\n${chunk.content}`,
+                };
+            }
+            catch {
+                // Fail-open: return original chunk unchanged
+                results[index] = chunk;
+            }
+        };
+        // Simple semaphore-based concurrency control
+        while (cursor < chunks.length) {
+            const batch = Math.min(this.concurrency, chunks.length - cursor);
+            const batchTasks = [];
+            for (let i = 0; i < batch; i++) {
+                batchTasks.push(processChunk(cursor + i));
+            }
+            await Promise.all(batchTasks);
+            cursor += batch;
+        }
+        return results;
+    }
+    async generateContext(documentContent, chunkContent) {
+        const userPrompt = ENRICHMENT_PROMPT_TEMPLATE.replace("{chunk}", chunkContent);
+        const response = await withRetry(() => this.provider.createMessage({
+            system: documentContent,
+            messages: [{ role: "user", parts: textParts(userPrompt) }],
+            maxTokens: ENRICHMENT_MAX_TOKENS,
+        }), {
+            maxRetries: MAX_RETRIES,
+            baseDelayMs: BASE_DELAY_MS,
+            isRetryable: (error) => {
+                if (error instanceof KilnError)
+                    return error.retryable;
+                if (error instanceof Error && "status" in error) {
+                    const status = error.status;
+                    return status === 429 || status >= 500;
+                }
+                return false;
+            },
+        });
+        return extractText(response.parts).trim();
+    }
+}
+//# sourceMappingURL=contextual-enricher.js.map

package/dist/knowledge/contextual-enricher.js.map

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

package/dist/knowledge/index.d.ts

@@ -3,8 +3,24 @@ export { MarkdownChunker } from "./markdown-chunker.js";
 export { OpenAIEmbeddingAdapter } from "./infrastructure/openai-embedding.js";
 export { OllamaEmbeddingAdapter } from "./infrastructure/ollama-embedding.js";
 export { InMemoryVectorStore, cosineSimilarity } from "./infrastructure/memory-vector-store.js";
+export { PgVectorStore, createPgVectorStore } from "./infrastructure/pgvector-store.js";
+export type { PgVectorStoreConfig } from "./infrastructure/pgvector-store.js";
 export { RetrievalPipeline } from "./retrieval-pipeline.js";
 export type { RetrievalPipelineConfig } from "./retrieval-pipeline.js";
 export { type Reranker } from "./reranker.js";
+export { CohereReranker } from "./infrastructure/cohere-reranker.js";
+export type { CohereRerankerConfig } from "./infrastructure/cohere-reranker.js";
 export { createKnowledgeCapability, executeKnowledgeSearch } from "./knowledge-capability.js";
+export { ContextualEnricher } from "./contextual-enricher.js";
+export type { ContextualEnricherConfig } from "./contextual-enricher.js";
+export { ContactMemoryServiceImpl } from "./contact-memory.js";
+export type { ContactMemoryServiceConfig } from "./contact-memory.js";
+export { FileExtractor } from "./infrastructure/file-extractor.js";
+export { UrlExtractor } from "./infrastructure/url-extractor.js";
+export { PdfExtractor } from "./infrastructure/pdf-extractor.js";
+export { CompositeExtractor } from "./infrastructure/composite-extractor.js";
+export { InMemorySourceStore } from "./infrastructure/memory-source-store.js";
+export { JsonSourceStore } from "./infrastructure/json-source-store.js";
+export { SourceManager } from "./source-manager.js";
+export type { SourceManagerConfig } from "./source-manager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/index.js

@@ -4,6 +4,19 @@ export { MarkdownChunker } from "./markdown-chunker.js";
 export { OpenAIEmbeddingAdapter } from "./infrastructure/openai-embedding.js";
 export { OllamaEmbeddingAdapter } from "./infrastructure/ollama-embedding.js";
 export { InMemoryVectorStore, cosineSimilarity } from "./infrastructure/memory-vector-store.js";
+export { PgVectorStore, createPgVectorStore } from "./infrastructure/pgvector-store.js";
 export { RetrievalPipeline } from "./retrieval-pipeline.js";
+export { CohereReranker } from "./infrastructure/cohere-reranker.js";
 export { createKnowledgeCapability, executeKnowledgeSearch } from "./knowledge-capability.js";
+export { ContextualEnricher } from "./contextual-enricher.js";
+// Contact memory (Phase 4d)
+export { ContactMemoryServiceImpl } from "./contact-memory.js";
+// Source management (Phase 4c)
+export { FileExtractor } from "./infrastructure/file-extractor.js";
+export { UrlExtractor } from "./infrastructure/url-extractor.js";
+export { PdfExtractor } from "./infrastructure/pdf-extractor.js";
+export { CompositeExtractor } from "./infrastructure/composite-extractor.js";
+export { InMemorySourceStore } from "./infrastructure/memory-source-store.js";
+export { JsonSourceStore } from "./infrastructure/json-source-store.js";
+export { SourceManager } from "./source-manager.js";
 //# sourceMappingURL=index.js.map

package/dist/knowledge/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAExF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAErE,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,4BAA4B;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,+BAA+B;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/infrastructure/cohere-reranker.d.ts

@@ -0,0 +1,13 @@
+import type { VectorResult } from "../../engine/domain/vector-store.js";
+import type { Reranker } from "../reranker.js";
+export interface CohereRerankerConfig {
+    readonly apiKey: string;
+    readonly model?: string;
+}
+export declare class CohereReranker implements Reranker {
+    private readonly apiKey;
+    private readonly model;
+    constructor(config: CohereRerankerConfig);
+    rerank(query: string, results: VectorResult[]): Promise<VectorResult[]>;
+}
+//# sourceMappingURL=cohere-reranker.d.ts.map

package/dist/knowledge/infrastructure/cohere-reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere-reranker.d.ts","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/cohere-reranker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI/C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AASD,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,EAAE,oBAAoB;IAKlC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAyD9E"}

package/dist/knowledge/infrastructure/cohere-reranker.js

@@ -0,0 +1,61 @@
+// Cohere reranker adapter -- fetch-based, no external SDK dependency
+import { KilnError } from "../../engine/errors.js";
+import { withRetry } from "../../agents/infrastructure/retry.js";
+export class CohereReranker {
+    apiKey;
+    model;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.model = config.model ?? "rerank-v3.5";
+    }
+    async rerank(query, results) {
+        if (results.length === 0) {
+            return [];
+        }
+        const data = await withRetry(async () => {
+            const response = await fetch("https://api.cohere.com/v2/rerank", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    query,
+                    documents: results.map((r) => r.content),
+                    top_n: results.length,
+                }),
+            });
+            if (!response.ok) {
+                const status = response.status;
+                if (status === 429 || status >= 500) {
+                    const err = new Error(`Cohere rerank returned ${status}`);
+                    err.status = status;
+                    throw err;
+                }
+                const body = await response.text();
+                throw new KilnError("PROVIDER_UNAVAILABLE", `Cohere rerank error ${status}: ${body}`, {
+                    context: { provider: "cohere", status },
+                    retryable: false,
+                });
+            }
+            return response.json();
+        }, {
+            maxRetries: 3,
+            baseDelayMs: 1000,
+            isRetryable: (error) => !(error instanceof KilnError) &&
+                error instanceof Error &&
+                "status" in error,
+        });
+        return data.results.map((r) => {
+            const original = results[r.index];
+            return {
+                id: original.id,
+                content: original.content,
+                score: r.relevance_score,
+                metadata: original.metadata,
+            };
+        });
+    }
+}
+//# sourceMappingURL=cohere-reranker.js.map

package/dist/knowledge/infrastructure/cohere-reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere-reranker.js","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/cohere-reranker.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAIrE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAcjE,MAAM,OAAO,cAAc;IACR,MAAM,CAAS;IACf,KAAK,CAAS;IAE/B,YAAY,MAA4B;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,SAAS,CAC1B,KAAK,IAAI,EAAE;YACT,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,kCAAkC,EAAE;gBAC/D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;iBACvC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,KAAK;oBACL,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;oBACxC,KAAK,EAAE,OAAO,CAAC,MAAM;iBACtB,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;gBAC/B,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;oBACpC,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;oBACzD,GAAyC,CAAC,MAAM,GAAG,MAAM,CAAC;oBAC3D,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnC,MAAM,IAAI,SAAS,CAAC,sBAAsB,EAAE,uBAAuB,MAAM,KAAK,IAAI,EAAE,EAAE;oBACpF,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE;oBACvC,SAAS,EAAE,KAAK;iBACjB,CAAC,CAAC;YACL,CAAC;YAED,OAAO,QAAQ,CAAC,IAAI,EAAmC,CAAC;QAC1D,CAAC,EACD;YACE,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,IAAI;YACjB,WAAW,EAAE,CAAC,KAAc,EAAE,EAAE,CAC9B,CAAC,CAAC,KAAK,YAAY,SAAS,CAAC;gBAC7B,KAAK,YAAY,KAAK;gBACtB,QAAQ,IAAI,KAAK;SACpB,CACF,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAE,CAAC;YACnC,OAAO;gBACL,EAAE,EAAE,QAAQ,CAAC,EAAE;gBACf,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,KAAK,EAAE,CAAC,CAAC,eAAe;gBACxB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;aAC5B,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/knowledge/infrastructure/composite-extractor.d.ts

@@ -0,0 +1,8 @@
+import type { ContentExtractor, ExtractedContent, KnowledgeSourceType } from "../../engine/domain/knowledge-source.js";
+export declare class CompositeExtractor implements ContentExtractor {
+    readonly supportedTypes: readonly KnowledgeSourceType[];
+    private readonly extractors;
+    constructor(extractors: readonly ContentExtractor[]);
+    extract(uri: string, type: KnowledgeSourceType): Promise<ExtractedContent>;
+}
+//# sourceMappingURL=composite-extractor.d.ts.map

package/dist/knowledge/infrastructure/composite-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-extractor.d.ts","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/composite-extractor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAEvH,qBAAa,kBAAmB,YAAW,gBAAgB;IACzD,QAAQ,CAAC,cAAc,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqD;gBAEpE,UAAU,EAAE,SAAS,gBAAgB,EAAE;IAW7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CASjF"}

package/dist/knowledge/infrastructure/composite-extractor.js

@@ -0,0 +1,26 @@
+// CompositeExtractor -- routes extraction to the correct extractor by source type
+import { KilnError } from "../../engine/errors.js";
+export class CompositeExtractor {
+    supportedTypes;
+    extractors;
+    constructor(extractors) {
+        const map = new Map();
+        for (const extractor of extractors) {
+            for (const type of extractor.supportedTypes) {
+                map.set(type, extractor);
+            }
+        }
+        this.extractors = map;
+        this.supportedTypes = [...map.keys()];
+    }
+    async extract(uri, type) {
+        const extractor = this.extractors.get(type);
+        if (!extractor) {
+            throw new KilnError("SOURCE_EXTRACTION_FAILED", `No extractor available for source type: ${type}`, {
+                context: { uri, type },
+            });
+        }
+        return extractor.extract(uri, type);
+    }
+}
+//# sourceMappingURL=composite-extractor.js.map

package/dist/knowledge/infrastructure/composite-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-extractor.js","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/composite-extractor.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,MAAM,OAAO,kBAAkB;IACpB,cAAc,CAAiC;IACvC,UAAU,CAAqD;IAEhF,YAAY,UAAuC;QACjD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyC,CAAC;QAC7D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,cAAc,EAAE,CAAC;gBAC5C,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,cAAc,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,IAAyB;QAClD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,SAAS,CAAC,0BAA0B,EAAE,2CAA2C,IAAI,EAAE,EAAE;gBACjG,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;aACvB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/knowledge/infrastructure/file-extractor.d.ts

@@ -0,0 +1,6 @@
+import type { ContentExtractor, ExtractedContent, KnowledgeSourceType } from "../../engine/domain/knowledge-source.js";
+export declare class FileExtractor implements ContentExtractor {
+    readonly supportedTypes: readonly KnowledgeSourceType[];
+    extract(uri: string): Promise<ExtractedContent>;
+}
+//# sourceMappingURL=file-extractor.d.ts.map

package/dist/knowledge/infrastructure/file-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-extractor.d.ts","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/file-extractor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAEvH,qBAAa,aAAc,YAAW,gBAAgB;IACpD,QAAQ,CAAC,cAAc,EAAE,SAAS,mBAAmB,EAAE,CAAY;IAE7D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAWtD"}

package/dist/knowledge/infrastructure/file-extractor.js

@@ -0,0 +1,19 @@
+// FileExtractor -- reads local files for knowledge ingestion
+import { readFile } from "node:fs/promises";
+import { KilnError } from "../../engine/errors.js";
+export class FileExtractor {
+    supportedTypes = ["file"];
+    async extract(uri) {
+        try {
+            const content = await readFile(uri, "utf-8");
+            return { content, metadata: { source: uri } };
+        }
+        catch (err) {
+            throw new KilnError("SOURCE_EXTRACTION_FAILED", `Failed to read file: ${uri}`, {
+                context: { uri },
+                cause: err,
+            });
+        }
+    }
+}
+//# sourceMappingURL=file-extractor.js.map

package/dist/knowledge/infrastructure/file-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-extractor.js","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/file-extractor.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,MAAM,OAAO,aAAa;IACf,cAAc,GAAmC,CAAC,MAAM,CAAC,CAAC;IAEnE,KAAK,CAAC,OAAO,CAAC,GAAW;QACvB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,SAAS,CAAC,0BAA0B,EAAE,wBAAwB,GAAG,EAAE,EAAE;gBAC7E,OAAO,EAAE,EAAE,GAAG,EAAE;gBAChB,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}

package/dist/knowledge/infrastructure/json-source-store.d.ts

@@ -0,0 +1,14 @@
+import type { KnowledgeSource, SourceStore } from "../../engine/domain/knowledge-source.js";
+export declare class JsonSourceStore implements SourceStore {
+    private readonly storageDir;
+    private readonly sources;
+    constructor(storageDir: string);
+    private key;
+    private load;
+    get(appName: string, sourceId: string): KnowledgeSource | undefined;
+    list(appName: string): readonly KnowledgeSource[];
+    save(source: KnowledgeSource): void;
+    remove(appName: string, sourceId: string): boolean;
+    private persist;
+}
+//# sourceMappingURL=json-source-store.d.ts.map

package/dist/knowledge/infrastructure/json-source-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-source-store.d.ts","sourceRoot":"","sources":["../../../src/knowledge/infrastructure/json-source-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAE5F,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;gBAElD,UAAU,EAAE,MAAM;IAK9B,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI;IAUZ,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAInE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAUjD,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAKnC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASlD,OAAO,CAAC,OAAO;CAKhB"}