@lssm/lib.knowledge 0.0.0-canary-20251217083314 → 1.41.1

package/dist/access/guard.js

@@ -1,49 +1 @@
-//#region src/access/guard.ts
-const DEFAULT_DISALLOWED_WRITE = ["external", "ephemeral"];
-var KnowledgeAccessGuard = class {
-	disallowedWrite;
-	requireWorkflowBinding;
-	requireAgentBinding;
-	constructor(options = {}) {
-		this.disallowedWrite = new Set(options.disallowWriteCategories ?? DEFAULT_DISALLOWED_WRITE);
-		this.requireWorkflowBinding = options.requireWorkflowBinding ?? true;
-		this.requireAgentBinding = options.requireAgentBinding ?? false;
-	}
-	checkAccess(spaceBinding, context, appConfig) {
-		const { binding, space } = spaceBinding;
-		if (binding.required !== false && !this.isSpaceBound(spaceBinding, appConfig)) return {
-			allowed: false,
-			reason: `Knowledge space "${space.meta.key}" is not bound in the resolved app config.`
-		};
-		if (context.operation === "write" && this.disallowedWrite.has(space.meta.category)) return {
-			allowed: false,
-			reason: `Knowledge space "${space.meta.key}" is category "${space.meta.category}" and is read-only.`
-		};
-		if (this.requireWorkflowBinding && context.workflowName) {
-			const allowedWorkflows = binding.scope?.workflows;
-			if (allowedWorkflows && !allowedWorkflows.includes(context.workflowName)) return {
-				allowed: false,
-				reason: `Workflow "${context.workflowName}" is not authorized to access knowledge space "${space.meta.key}".`
-			};
-		}
-		if (this.requireAgentBinding && context.agentName) {
-			const allowedAgents = binding.scope?.agents;
-			if (allowedAgents && !allowedAgents.includes(context.agentName)) return {
-				allowed: false,
-				reason: `Agent "${context.agentName}" is not authorized to access knowledge space "${space.meta.key}".`
-			};
-		}
-		if (space.meta.category === "ephemeral") return {
-			allowed: true,
-			severity: "warning",
-			reason: `Knowledge space "${space.meta.key}" is ephemeral; results may be transient.`
-		};
-		return { allowed: true };
-	}
-	isSpaceBound(resolved, appConfig) {
-		return appConfig.knowledge.some((entry) => entry.space.meta.key === resolved.space.meta.key && (resolved.space.meta.version == null || entry.space.meta.version === resolved.space.meta.version));
-	}
-};
-
-//#endregion
-export { KnowledgeAccessGuard };
+const e=[`external`,`ephemeral`];var t=class{disallowedWrite;requireWorkflowBinding;requireAgentBinding;constructor(t={}){this.disallowedWrite=new Set(t.disallowWriteCategories??e),this.requireWorkflowBinding=t.requireWorkflowBinding??!0,this.requireAgentBinding=t.requireAgentBinding??!1}checkAccess(e,t,n){let{binding:r,space:i}=e;if(r.required!==!1&&!this.isSpaceBound(e,n))return{allowed:!1,reason:`Knowledge space "${i.meta.key}" is not bound in the resolved app config.`};if(t.operation===`write`&&this.disallowedWrite.has(i.meta.category))return{allowed:!1,reason:`Knowledge space "${i.meta.key}" is category "${i.meta.category}" and is read-only.`};if(this.requireWorkflowBinding&&t.workflowName){let e=r.scope?.workflows;if(e&&!e.includes(t.workflowName))return{allowed:!1,reason:`Workflow "${t.workflowName}" is not authorized to access knowledge space "${i.meta.key}".`}}if(this.requireAgentBinding&&t.agentName){let e=r.scope?.agents;if(e&&!e.includes(t.agentName))return{allowed:!1,reason:`Agent "${t.agentName}" is not authorized to access knowledge space "${i.meta.key}".`}}return i.meta.category===`ephemeral`?{allowed:!0,severity:`warning`,reason:`Knowledge space "${i.meta.key}" is ephemeral; results may be transient.`}:{allowed:!0}}isSpaceBound(e,t){return t.knowledge.some(t=>t.space.meta.key===e.space.meta.key&&(e.space.meta.version==null||t.space.meta.version===e.space.meta.version))}};export{t as KnowledgeAccessGuard};

package/dist/access/index.js

@@ -1,3 +1 @@
-import { KnowledgeAccessGuard } from "./guard.js";
-
-export { KnowledgeAccessGuard };
+import{KnowledgeAccessGuard as e}from"./guard.js";export{e as KnowledgeAccessGuard};

package/dist/index.js

@@ -1,12 +1 @@
-import { StaticRetriever, createStaticRetriever } from "./retriever/static-retriever.js";
-import { VectorRetriever, createVectorRetriever } from "./retriever/vector-retriever.js";
-import { KnowledgeQueryService } from "./query/service.js";
-import { DocumentProcessor } from "./ingestion/document-processor.js";
-import { EmbeddingService } from "./ingestion/embedding-service.js";
-import { VectorIndexer } from "./ingestion/vector-indexer.js";
-import { GmailIngestionAdapter } from "./ingestion/gmail-adapter.js";
-import { StorageIngestionAdapter } from "./ingestion/storage-adapter.js";
-import "./ingestion/index.js";
-import { KnowledgeAccessGuard } from "./access/guard.js";
-
-export { DocumentProcessor, EmbeddingService, GmailIngestionAdapter, KnowledgeAccessGuard, KnowledgeQueryService, StaticRetriever, StorageIngestionAdapter, VectorIndexer, VectorRetriever, createStaticRetriever, createVectorRetriever };
+import{StaticRetriever as e,createStaticRetriever as t}from"./retriever/static-retriever.js";import{VectorRetriever as n,createVectorRetriever as r}from"./retriever/vector-retriever.js";import{KnowledgeQueryService as i}from"./query/service.js";import{DocumentProcessor as a}from"./ingestion/document-processor.js";import{EmbeddingService as o}from"./ingestion/embedding-service.js";import{VectorIndexer as s}from"./ingestion/vector-indexer.js";import{GmailIngestionAdapter as c}from"./ingestion/gmail-adapter.js";import{StorageIngestionAdapter as l}from"./ingestion/storage-adapter.js";import"./ingestion/index.js";import{KnowledgeAccessGuard as u}from"./access/guard.js";export{a as DocumentProcessor,o as EmbeddingService,c as GmailIngestionAdapter,u as KnowledgeAccessGuard,i as KnowledgeQueryService,e as StaticRetriever,l as StorageIngestionAdapter,s as VectorIndexer,n as VectorRetriever,t as createStaticRetriever,r as createVectorRetriever};

package/dist/ingestion/document-processor.js

@@ -1,54 +1 @@
-import { Buffer } from "node:buffer";
-
-//#region src/ingestion/document-processor.ts
-var DocumentProcessor = class {
-	extractors = /* @__PURE__ */ new Map();
-	constructor() {
-		this.registerExtractor("text/plain", this.extractText.bind(this));
-		this.registerExtractor("application/json", this.extractJson.bind(this));
-	}
-	registerExtractor(mimeType, extractor) {
-		this.extractors.set(mimeType.toLowerCase(), extractor);
-	}
-	async process(document) {
-		const extractor = this.extractors.get(document.mimeType.toLowerCase()) ?? this.extractors.get("*/*");
-		if (!extractor) throw new Error(`No extractor registered for mime type ${document.mimeType}`);
-		const fragments = await extractor(document);
-		if (fragments.length === 0) return [{
-			id: `${document.id}:0`,
-			documentId: document.id,
-			text: "",
-			metadata: document.metadata
-		}];
-		return fragments;
-	}
-	async extractText(document) {
-		const text = Buffer.from(document.data).toString("utf-8");
-		return [{
-			id: `${document.id}:0`,
-			documentId: document.id,
-			text,
-			metadata: document.metadata
-		}];
-	}
-	async extractJson(document) {
-		const text = Buffer.from(document.data).toString("utf-8");
-		try {
-			const json = JSON.parse(text);
-			return [{
-				id: `${document.id}:0`,
-				documentId: document.id,
-				text: JSON.stringify(json, null, 2),
-				metadata: {
-					...document.metadata,
-					contentType: "application/json"
-				}
-			}];
-		} catch {
-			return this.extractText(document);
-		}
-	}
-};
-
-//#endregion
-export { DocumentProcessor };
+import{Buffer as e}from"node:buffer";var t=class{extractors=new Map;constructor(){this.registerExtractor(`text/plain`,this.extractText.bind(this)),this.registerExtractor(`application/json`,this.extractJson.bind(this))}registerExtractor(e,t){this.extractors.set(e.toLowerCase(),t)}async process(e){let t=this.extractors.get(e.mimeType.toLowerCase())??this.extractors.get(`*/*`);if(!t)throw Error(`No extractor registered for mime type ${e.mimeType}`);let n=await t(e);return n.length===0?[{id:`${e.id}:0`,documentId:e.id,text:``,metadata:e.metadata}]:n}async extractText(t){let n=e.from(t.data).toString(`utf-8`);return[{id:`${t.id}:0`,documentId:t.id,text:n,metadata:t.metadata}]}async extractJson(t){let n=e.from(t.data).toString(`utf-8`);try{let e=JSON.parse(n);return[{id:`${t.id}:0`,documentId:t.id,text:JSON.stringify(e,null,2),metadata:{...t.metadata,contentType:`application/json`}}]}catch{return this.extractText(t)}}};export{t as DocumentProcessor};

package/dist/ingestion/embedding-service.js

@@ -1,25 +1 @@
-//#region src/ingestion/embedding-service.ts
-var EmbeddingService = class {
-	provider;
-	batchSize;
-	constructor(provider, batchSize = 16) {
-		this.provider = provider;
-		this.batchSize = batchSize;
-	}
-	async embedFragments(fragments) {
-		const results = [];
-		for (let i = 0; i < fragments.length; i += this.batchSize) {
-			const documents = fragments.slice(i, i + this.batchSize).map((fragment) => ({
-				id: fragment.id,
-				text: fragment.text,
-				metadata: fragment.metadata
-			}));
-			const embeddings = await this.provider.embedDocuments(documents);
-			results.push(...embeddings);
-		}
-		return results;
-	}
-};
-
-//#endregion
-export { EmbeddingService };
+var e=class{provider;batchSize;constructor(e,t=16){this.provider=e,this.batchSize=t}async embedFragments(e){let t=[];for(let n=0;n<e.length;n+=this.batchSize){let r=e.slice(n,n+this.batchSize).map(e=>({id:e.id,text:e.text,metadata:e.metadata})),i=await this.provider.embedDocuments(r);t.push(...i)}return t}};export{e as EmbeddingService};

package/dist/ingestion/gmail-adapter.js

@@ -1,51 +1,6 @@
-//#region src/ingestion/gmail-adapter.ts
-var GmailIngestionAdapter = class {
-	constructor(gmail, processor, embeddings, indexer) {
-		this.gmail = gmail;
-		this.processor = processor;
-		this.embeddings = embeddings;
-		this.indexer = indexer;
-	}
-	async syncThreads(query) {
-		const threads = await this.gmail.listThreads(query);
-		for (const thread of threads) await this.ingestThread(thread);
-	}
-	async ingestThread(thread) {
-		const document = this.toRawDocument(thread);
-		const fragments = await this.processor.process(document);
-		const embeddings = await this.embeddings.embedFragments(fragments);
-		await this.indexer.upsert(fragments, embeddings);
-	}
-	toRawDocument(thread) {
-		const content = composeThreadText(thread);
-		return {
-			id: thread.id,
-			mimeType: "text/plain",
-			data: Buffer.from(content, "utf-8"),
-			metadata: {
-				subject: thread.subject ?? "",
-				participants: thread.participants.map((p) => p.email).join(", "),
-				updatedAt: thread.updatedAt.toISOString()
-			}
-		};
-	}
-};
-function composeThreadText(thread) {
-	const header = [`Subject: ${thread.subject ?? ""}`, `Snippet: ${thread.snippet ?? ""}`];
-	const messageTexts = thread.messages.map((message) => {
-		const parts = [`From: ${formatAddress(message.from)}`, `To: ${message.to.map(formatAddress).join(", ")}`];
-		if (message.sentAt) parts.push(`Date: ${message.sentAt.toISOString()}`);
-		const body = message.textBody ?? stripHtml(message.htmlBody ?? "");
-		return `${parts.join("\n")}\n\n${body ?? ""}`;
-	});
-	return [...header, ...messageTexts].join("\n\n---\n\n");
-}
-function formatAddress(address) {
-	return address.name ? `${address.name} <${address.email}>` : address.email;
-}
-function stripHtml(html) {
-	return html.replace(/<[^>]+>/g, " ");
-}
+var e=class{constructor(e,t,n,r){this.gmail=e,this.processor=t,this.embeddings=n,this.indexer=r}async syncThreads(e){let t=await this.gmail.listThreads(e);for(let e of t)await this.ingestThread(e)}async ingestThread(e){let t=this.toRawDocument(e),n=await this.processor.process(t),r=await this.embeddings.embedFragments(n);await this.indexer.upsert(n,r)}toRawDocument(e){let n=t(e);return{id:e.id,mimeType:`text/plain`,data:Buffer.from(n,`utf-8`),metadata:{subject:e.subject??``,participants:e.participants.map(e=>e.email).join(`, `),updatedAt:e.updatedAt.toISOString()}}}};function t(e){let t=[`Subject: ${e.subject??``}`,`Snippet: ${e.snippet??``}`],i=e.messages.map(e=>{let t=[`From: ${n(e.from)}`,`To: ${e.to.map(n).join(`, `)}`];e.sentAt&&t.push(`Date: ${e.sentAt.toISOString()}`);let i=e.textBody??r(e.htmlBody??``);return`${t.join(`
+`)}\n\n${i??``}`});return[...t,...i].join(`
 
-//#endregion
-export { GmailIngestionAdapter };
+---
+
+`)}function n(e){return e.name?`${e.name} <${e.email}>`:e.email}function r(e){return e.replace(/<[^>]+>/g,` `)}export{e as GmailIngestionAdapter};

package/dist/ingestion/index.js

@@ -1,7 +1 @@
-import { DocumentProcessor } from "./document-processor.js";
-import { EmbeddingService } from "./embedding-service.js";
-import { VectorIndexer } from "./vector-indexer.js";
-import { GmailIngestionAdapter } from "./gmail-adapter.js";
-import { StorageIngestionAdapter } from "./storage-adapter.js";
-
-export { DocumentProcessor, EmbeddingService, GmailIngestionAdapter, StorageIngestionAdapter, VectorIndexer };
+import{DocumentProcessor as e}from"./document-processor.js";import{EmbeddingService as t}from"./embedding-service.js";import{VectorIndexer as n}from"./vector-indexer.js";import{GmailIngestionAdapter as r}from"./gmail-adapter.js";import{StorageIngestionAdapter as i}from"./storage-adapter.js";export{e as DocumentProcessor,t as EmbeddingService,r as GmailIngestionAdapter,i as StorageIngestionAdapter,n as VectorIndexer};

package/dist/ingestion/storage-adapter.js

@@ -1,26 +1 @@
-//#region src/ingestion/storage-adapter.ts
-var StorageIngestionAdapter = class {
-	constructor(processor, embeddings, indexer) {
-		this.processor = processor;
-		this.embeddings = embeddings;
-		this.indexer = indexer;
-	}
-	async ingestObject(object) {
-		if (!("data" in object) || !object.data) throw new Error("Storage ingestion requires object data");
-		const raw = {
-			id: object.key,
-			mimeType: object.contentType ?? "application/octet-stream",
-			data: object.data,
-			metadata: {
-				bucket: object.bucket,
-				checksum: object.checksum ?? ""
-			}
-		};
-		const fragments = await this.processor.process(raw);
-		const embeddings = await this.embeddings.embedFragments(fragments);
-		await this.indexer.upsert(fragments, embeddings);
-	}
-};
-
-//#endregion
-export { StorageIngestionAdapter };
+var e=class{constructor(e,t,n){this.processor=e,this.embeddings=t,this.indexer=n}async ingestObject(e){if(!(`data`in e)||!e.data)throw Error(`Storage ingestion requires object data`);let t={id:e.key,mimeType:e.contentType??`application/octet-stream`,data:e.data,metadata:{bucket:e.bucket,checksum:e.checksum??``}},n=await this.processor.process(t),r=await this.embeddings.embedFragments(n);await this.indexer.upsert(n,r)}};export{e as StorageIngestionAdapter};

package/dist/ingestion/vector-indexer.js

@@ -1,32 +1 @@
-//#region src/ingestion/vector-indexer.ts
-var VectorIndexer = class {
-	provider;
-	config;
-	constructor(provider, config) {
-		this.provider = provider;
-		this.config = config;
-	}
-	async upsert(fragments, embeddings) {
-		const documents = embeddings.map((embedding) => {
-			const fragment = fragments.find((f) => f.id === embedding.id);
-			return {
-				id: embedding.id,
-				vector: embedding.vector,
-				payload: {
-					...this.config.metadata,
-					...fragment?.metadata ?? {},
-					documentId: fragment?.documentId
-				},
-				namespace: this.config.namespace
-			};
-		});
-		const request = {
-			collection: this.config.collection,
-			documents
-		};
-		await this.provider.upsert(request);
-	}
-};
-
-//#endregion
-export { VectorIndexer };
+var e=class{provider;config;constructor(e,t){this.provider=e,this.config=t}async upsert(e,t){let n=t.map(t=>{let n=e.find(e=>e.id===t.id);return{id:t.id,vector:t.vector,payload:{...this.config.metadata,...n?.metadata??{},documentId:n?.documentId},namespace:this.config.namespace}}),r={collection:this.config.collection,documents:n};await this.provider.upsert(r)}};export{e as VectorIndexer};

package/dist/query/index.js

@@ -1,3 +1 @@
-import { KnowledgeQueryService } from "./service.js";
-
-export { KnowledgeQueryService };
+import{KnowledgeQueryService as e}from"./service.js";export{e as KnowledgeQueryService};

package/dist/query/service.js

@@ -1,65 +1,3 @@
-//#region src/query/service.ts
-var KnowledgeQueryService = class {
-	embeddings;
-	vectorStore;
-	llm;
-	config;
-	constructor(embeddings, vectorStore, llm, config) {
-		this.embeddings = embeddings;
-		this.vectorStore = vectorStore;
-		this.llm = llm;
-		this.config = config;
-	}
-	async query(question) {
-		const embedding = await this.embeddings.embedQuery(question);
-		const results = await this.vectorStore.search({
-			collection: this.config.collection,
-			vector: embedding.vector,
-			topK: this.config.topK ?? 5,
-			namespace: this.config.namespace,
-			filter: void 0
-		});
-		const context = buildContext(results);
-		const messages = this.buildMessages(question, context);
-		const response = await this.llm.chat(messages);
-		return {
-			answer: response.message.content.map((part) => "text" in part ? part.text : "").join(""),
-			references: results.map((result) => ({
-				...result,
-				text: extractText(result)
-			})),
-			usage: response.usage
-		};
-	}
-	buildMessages(question, context) {
-		return [{
-			role: "system",
-			content: [{
-				type: "text",
-				text: this.config.systemPrompt ?? "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible."
-			}]
-		}, {
-			role: "user",
-			content: [{
-				type: "text",
-				text: `Question:\n${question}\n\nContext:\n${context}`
-			}]
-		}];
-	}
-};
-function buildContext(results) {
-	if (results.length === 0) return "No relevant documents found.";
-	return results.map((result, index) => {
-		const text = extractText(result);
-		return `Source ${index + 1} (score: ${result.score.toFixed(3)}):\n${text}`;
-	}).join("\n\n");
-}
-function extractText(result) {
-	const payload = result.payload ?? {};
-	if (typeof payload.text === "string") return payload.text;
-	if (typeof payload.content === "string") return payload.content;
-	return JSON.stringify(payload);
-}
+var e=class{embeddings;vectorStore;llm;config;constructor(e,t,n,r){this.embeddings=e,this.vectorStore=t,this.llm=n,this.config=r}async query(e){let r=await this.embeddings.embedQuery(e),i=await this.vectorStore.search({collection:this.config.collection,vector:r.vector,topK:this.config.topK??5,namespace:this.config.namespace,filter:void 0}),a=t(i),o=this.buildMessages(e,a),s=await this.llm.chat(o);return{answer:s.message.content.map(e=>`text`in e?e.text:``).join(``),references:i.map(e=>({...e,text:n(e)})),usage:s.usage}}buildMessages(e,t){return[{role:`system`,content:[{type:`text`,text:this.config.systemPrompt??`You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.`}]},{role:`user`,content:[{type:`text`,text:`Question:\n${e}\n\nContext:\n${t}`}]}]}};function t(e){return e.length===0?`No relevant documents found.`:e.map((e,t)=>{let r=n(e);return`Source ${t+1} (score: ${e.score.toFixed(3)}):\n${r}`}).join(`
 
-//#endregion
-export { KnowledgeQueryService };
+`)}function n(e){let t=e.payload??{};return typeof t.text==`string`?t.text:typeof t.content==`string`?t.content:JSON.stringify(t)}export{e as KnowledgeQueryService};

package/dist/retriever/index.js

@@ -1,4 +1 @@
-import { StaticRetriever, createStaticRetriever } from "./static-retriever.js";
-import { VectorRetriever, createVectorRetriever } from "./vector-retriever.js";
-
-export { StaticRetriever, VectorRetriever, createStaticRetriever, createVectorRetriever };
+import{StaticRetriever as e,createStaticRetriever as t}from"./static-retriever.js";import{VectorRetriever as n,createVectorRetriever as r}from"./vector-retriever.js";export{e as StaticRetriever,n as VectorRetriever,t as createStaticRetriever,r as createVectorRetriever};

package/dist/retriever/static-retriever.js

@@ -1,47 +1,2 @@
-//#region src/retriever/static-retriever.ts
-/**
-* A simple in-memory retriever for static knowledge content.
-*
-* Useful for:
-* - Required knowledge that doesn't need semantic search
-* - Testing and development
-* - Small knowledge bases that fit in memory
-*/
-var StaticRetriever = class {
-	content;
-	constructor(config) {
-		this.content = config.content instanceof Map ? config.content : new Map(Object.entries(config.content));
-	}
-	async retrieve(query, options) {
-		const content = this.content.get(options.spaceKey);
-		if (!content) return [];
-		const queryLower = query.toLowerCase();
-		const lines = content.split("\n").filter((line) => line.trim());
-		const results = [];
-		for (const line of lines) if (line.toLowerCase().includes(queryLower)) results.push({
-			content: line,
-			source: options.spaceKey,
-			score: 1,
-			metadata: { type: "static" }
-		});
-		return results.slice(0, options.topK ?? 5);
-	}
-	async getStatic(spaceKey) {
-		return this.content.get(spaceKey) ?? null;
-	}
-	supportsSpace(spaceKey) {
-		return this.content.has(spaceKey);
-	}
-	listSpaces() {
-		return [...this.content.keys()];
-	}
-};
-/**
-* Create a static retriever from a content map.
-*/
-function createStaticRetriever(content) {
-	return new StaticRetriever({ content });
-}
-
-//#endregion
-export { StaticRetriever, createStaticRetriever };
+var e=class{content;constructor(e){this.content=e.content instanceof Map?e.content:new Map(Object.entries(e.content))}async retrieve(e,t){let n=this.content.get(t.spaceKey);if(!n)return[];let r=e.toLowerCase(),i=n.split(`
+`).filter(e=>e.trim()),a=[];for(let e of i)e.toLowerCase().includes(r)&&a.push({content:e,source:t.spaceKey,score:1,metadata:{type:`static`}});return a.slice(0,t.topK??5)}async getStatic(e){return this.content.get(e)??null}supportsSpace(e){return this.content.has(e)}listSpaces(){return[...this.content.keys()]}};function t(t){return new e({content:t})}export{e as StaticRetriever,t as createStaticRetriever};

package/dist/retriever/vector-retriever.js

@@ -1,60 +1 @@
-//#region src/retriever/vector-retriever.ts
-/**
-* A retriever that uses vector similarity search.
-*
-* Uses embedding provider to vectorize queries and vector store
-* provider to perform similarity search.
-*/
-var VectorRetriever = class {
-	config;
-	spaceCollections;
-	staticContent;
-	constructor(config) {
-		this.config = config;
-		this.spaceCollections = config.spaceCollections instanceof Map ? config.spaceCollections : new Map(Object.entries(config.spaceCollections));
-		this.staticContent = config.staticContent ? config.staticContent instanceof Map ? config.staticContent : new Map(Object.entries(config.staticContent)) : /* @__PURE__ */ new Map();
-	}
-	async retrieve(query, options) {
-		const collection = this.spaceCollections.get(options.spaceKey);
-		if (!collection) return [];
-		const embedding = await this.config.embeddings.embedQuery(query);
-		const results = await this.config.vectorStore.search({
-			collection,
-			vector: embedding.vector,
-			topK: options.topK ?? this.config.defaultTopK ?? 5,
-			namespace: options.tenantId,
-			filter: options.filter
-		});
-		const minScore = options.minScore ?? this.config.defaultMinScore ?? 0;
-		return results.filter((r) => r.score >= minScore).map((result) => ({
-			content: this.extractContent(result.payload),
-			source: result.id,
-			score: result.score,
-			metadata: result.payload
-		}));
-	}
-	async getStatic(spaceKey) {
-		return this.staticContent.get(spaceKey) ?? null;
-	}
-	supportsSpace(spaceKey) {
-		return this.spaceCollections.has(spaceKey);
-	}
-	listSpaces() {
-		return [...this.spaceCollections.keys()];
-	}
-	extractContent(payload) {
-		if (!payload) return "";
-		if (typeof payload.text === "string") return payload.text;
-		if (typeof payload.content === "string") return payload.content;
-		return JSON.stringify(payload);
-	}
-};
-/**
-* Create a vector retriever from configuration.
-*/
-function createVectorRetriever(config) {
-	return new VectorRetriever(config);
-}
-
-//#endregion
-export { VectorRetriever, createVectorRetriever };
+var e=class{config;spaceCollections;staticContent;constructor(e){this.config=e,this.spaceCollections=e.spaceCollections instanceof Map?e.spaceCollections:new Map(Object.entries(e.spaceCollections)),this.staticContent=e.staticContent?e.staticContent instanceof Map?e.staticContent:new Map(Object.entries(e.staticContent)):new Map}async retrieve(e,t){let n=this.spaceCollections.get(t.spaceKey);if(!n)return[];let r=await this.config.embeddings.embedQuery(e),i=await this.config.vectorStore.search({collection:n,vector:r.vector,topK:t.topK??this.config.defaultTopK??5,namespace:t.tenantId,filter:t.filter}),a=t.minScore??this.config.defaultMinScore??0;return i.filter(e=>e.score>=a).map(e=>({content:this.extractContent(e.payload),source:e.id,score:e.score,metadata:e.payload}))}async getStatic(e){return this.staticContent.get(e)??null}supportsSpace(e){return this.spaceCollections.has(e)}listSpaces(){return[...this.spaceCollections.keys()]}extractContent(e){return e?typeof e.text==`string`?e.text:typeof e.content==`string`?e.content:JSON.stringify(e):``}};function t(t){return new e(t)}export{e as VectorRetriever,t as createVectorRetriever};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.knowledge",
-  "version": "0.0.0-canary-20251217083314",
+  "version": "1.41.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,31 +23,31 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "0.0.0-canary-20251217083314"
+    "@lssm/lib.contracts": "1.41.1"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217083314",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217083314",
+    "@lssm/tool.tsdown": "1.41.1",
+    "@lssm/tool.typescript": "1.41.1",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "exports": {
-    ".": "./dist/index.js",
-    "./access": "./dist/access/index.js",
-    "./access/guard": "./dist/access/guard.js",
-    "./ingestion": "./dist/ingestion/index.js",
-    "./ingestion/document-processor": "./dist/ingestion/document-processor.js",
-    "./ingestion/embedding-service": "./dist/ingestion/embedding-service.js",
-    "./ingestion/gmail-adapter": "./dist/ingestion/gmail-adapter.js",
-    "./ingestion/storage-adapter": "./dist/ingestion/storage-adapter.js",
-    "./ingestion/vector-indexer": "./dist/ingestion/vector-indexer.js",
-    "./query": "./dist/query/index.js",
-    "./query/service": "./dist/query/service.js",
-    "./retriever": "./dist/retriever/index.js",
-    "./retriever/interface": "./dist/retriever/interface.js",
-    "./retriever/static-retriever": "./dist/retriever/static-retriever.js",
-    "./retriever/vector-retriever": "./dist/retriever/vector-retriever.js",
-    "./types": "./dist/types.js",
+    ".": "./src/index.ts",
+    "./access": "./src/access/index.ts",
+    "./access/guard": "./src/access/guard.ts",
+    "./ingestion": "./src/ingestion/index.ts",
+    "./ingestion/document-processor": "./src/ingestion/document-processor.ts",
+    "./ingestion/embedding-service": "./src/ingestion/embedding-service.ts",
+    "./ingestion/gmail-adapter": "./src/ingestion/gmail-adapter.ts",
+    "./ingestion/storage-adapter": "./src/ingestion/storage-adapter.ts",
+    "./ingestion/vector-indexer": "./src/ingestion/vector-indexer.ts",
+    "./query": "./src/query/index.ts",
+    "./query/service": "./src/query/service.ts",
+    "./retriever": "./src/retriever/index.ts",
+    "./retriever/interface": "./src/retriever/interface.ts",
+    "./retriever/static-retriever": "./src/retriever/static-retriever.ts",
+    "./retriever/vector-retriever": "./src/retriever/vector-retriever.ts",
+    "./types": "./src/types.ts",
     "./*": "./*"
   },
   "publishConfig": {

package/dist/access/guard.d.ts

@@ -1,20 +0,0 @@
-import { KnowledgeAccessContext, KnowledgeAccessResult } from "../types.js";
-import { ResolvedAppConfig, ResolvedKnowledge } from "@lssm/lib.contracts/app-config";
-import { KnowledgeCategory } from "@lssm/lib.contracts/knowledge";
-
-//#region src/access/guard.d.ts
-interface KnowledgeAccessGuardOptions {
-  disallowWriteCategories?: KnowledgeCategory[];
-  requireWorkflowBinding?: boolean;
-  requireAgentBinding?: boolean;
-}
-declare class KnowledgeAccessGuard {
-  private readonly disallowedWrite;
-  private readonly requireWorkflowBinding;
-  private readonly requireAgentBinding;
-  constructor(options?: KnowledgeAccessGuardOptions);
-  checkAccess(spaceBinding: ResolvedKnowledge, context: KnowledgeAccessContext, appConfig: ResolvedAppConfig): KnowledgeAccessResult;
-  private isSpaceBound;
-}
-//#endregion
-export { KnowledgeAccessGuard, KnowledgeAccessGuardOptions };

package/dist/access/index.d.ts

@@ -1,2 +0,0 @@
-import { KnowledgeAccessGuard, KnowledgeAccessGuardOptions } from "./guard.js";
-export { KnowledgeAccessGuard, KnowledgeAccessGuardOptions };

package/dist/index.d.ts

@@ -1,12 +0,0 @@
-import { KnowledgeAccessContext, KnowledgeAccessResult, RetrievalOptions, RetrievalResult } from "./types.js";
-import { KnowledgeAccessGuard, KnowledgeAccessGuardOptions } from "./access/guard.js";
-import { KnowledgeRetriever, RetrieverConfig } from "./retriever/interface.js";
-import { StaticRetriever, StaticRetrieverConfig, createStaticRetriever } from "./retriever/static-retriever.js";
-import { VectorRetriever, VectorRetrieverConfig, createVectorRetriever } from "./retriever/vector-retriever.js";
-import { KnowledgeAnswer, KnowledgeQueryConfig, KnowledgeQueryService } from "./query/service.js";
-import { DocumentFragment, DocumentProcessor, RawDocument } from "./ingestion/document-processor.js";
-import { EmbeddingService } from "./ingestion/embedding-service.js";
-import { VectorIndexConfig, VectorIndexer } from "./ingestion/vector-indexer.js";
-import { GmailIngestionAdapter } from "./ingestion/gmail-adapter.js";
-import { StorageIngestionAdapter } from "./ingestion/storage-adapter.js";
-export { DocumentFragment, DocumentProcessor, EmbeddingService, GmailIngestionAdapter, KnowledgeAccessContext, KnowledgeAccessGuard, KnowledgeAccessGuardOptions, KnowledgeAccessResult, KnowledgeAnswer, KnowledgeQueryConfig, KnowledgeQueryService, KnowledgeRetriever, RawDocument, RetrievalOptions, RetrievalResult, RetrieverConfig, StaticRetriever, StaticRetrieverConfig, StorageIngestionAdapter, VectorIndexConfig, VectorIndexer, VectorRetriever, VectorRetrieverConfig, createStaticRetriever, createVectorRetriever };

package/dist/ingestion/document-processor.d.ts

@@ -1,24 +0,0 @@
-//#region src/ingestion/document-processor.d.ts
-interface RawDocument {
-  id: string;
-  mimeType: string;
-  data: Uint8Array;
-  metadata?: Record<string, string>;
-}
-interface DocumentFragment {
-  id: string;
-  documentId: string;
-  text: string;
-  metadata?: Record<string, string>;
-}
-type Extractor = (input: RawDocument) => Promise<DocumentFragment[]>;
-declare class DocumentProcessor {
-  private readonly extractors;
-  constructor();
-  registerExtractor(mimeType: string, extractor: Extractor): void;
-  process(document: RawDocument): Promise<DocumentFragment[]>;
-  private extractText;
-  private extractJson;
-}
-//#endregion
-export { DocumentFragment, DocumentProcessor, RawDocument };

package/dist/ingestion/embedding-service.d.ts

@@ -1,12 +0,0 @@
-import { DocumentFragment } from "./document-processor.js";
-import { EmbeddingProvider, EmbeddingResult } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/ingestion/embedding-service.d.ts
-declare class EmbeddingService {
-  private readonly provider;
-  private readonly batchSize;
-  constructor(provider: EmbeddingProvider, batchSize?: number);
-  embedFragments(fragments: DocumentFragment[]): Promise<EmbeddingResult[]>;
-}
-//#endregion
-export { EmbeddingService };

package/dist/ingestion/gmail-adapter.d.ts

@@ -1,18 +0,0 @@
-import { DocumentProcessor } from "./document-processor.js";
-import { EmbeddingService } from "./embedding-service.js";
-import { VectorIndexer } from "./vector-indexer.js";
-import { EmailInboundProvider, EmailThread } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/ingestion/gmail-adapter.d.ts
-declare class GmailIngestionAdapter {
-  private readonly gmail;
-  private readonly processor;
-  private readonly embeddings;
-  private readonly indexer;
-  constructor(gmail: EmailInboundProvider, processor: DocumentProcessor, embeddings: EmbeddingService, indexer: VectorIndexer);
-  syncThreads(query?: Parameters<EmailInboundProvider['listThreads']>[0]): Promise<void>;
-  ingestThread(thread: EmailThread): Promise<void>;
-  private toRawDocument;
-}
-//#endregion
-export { GmailIngestionAdapter };

package/dist/ingestion/index.d.ts

@@ -1,6 +0,0 @@
-import { DocumentFragment, DocumentProcessor, RawDocument } from "./document-processor.js";
-import { EmbeddingService } from "./embedding-service.js";
-import { VectorIndexConfig, VectorIndexer } from "./vector-indexer.js";
-import { GmailIngestionAdapter } from "./gmail-adapter.js";
-import { StorageIngestionAdapter } from "./storage-adapter.js";
-export { DocumentFragment, DocumentProcessor, EmbeddingService, GmailIngestionAdapter, RawDocument, StorageIngestionAdapter, VectorIndexConfig, VectorIndexer };

package/dist/ingestion/storage-adapter.d.ts

@@ -1,15 +0,0 @@
-import { DocumentProcessor } from "./document-processor.js";
-import { EmbeddingService } from "./embedding-service.js";
-import { VectorIndexer } from "./vector-indexer.js";
-import { GetObjectResult } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/ingestion/storage-adapter.d.ts
-declare class StorageIngestionAdapter {
-  private readonly processor;
-  private readonly embeddings;
-  private readonly indexer;
-  constructor(processor: DocumentProcessor, embeddings: EmbeddingService, indexer: VectorIndexer);
-  ingestObject(object: GetObjectResult): Promise<void>;
-}
-//#endregion
-export { StorageIngestionAdapter };

package/dist/ingestion/vector-indexer.d.ts

@@ -1,17 +0,0 @@
-import { DocumentFragment } from "./document-processor.js";
-import { EmbeddingResult, VectorStoreProvider } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/ingestion/vector-indexer.d.ts
-interface VectorIndexConfig {
-  collection: string;
-  namespace?: string;
-  metadata?: Record<string, string>;
-}
-declare class VectorIndexer {
-  private readonly provider;
-  private readonly config;
-  constructor(provider: VectorStoreProvider, config: VectorIndexConfig);
-  upsert(fragments: DocumentFragment[], embeddings: EmbeddingResult[]): Promise<void>;
-}
-//#endregion
-export { VectorIndexConfig, VectorIndexer };

package/dist/query/index.d.ts

@@ -1,2 +0,0 @@
-import { KnowledgeAnswer, KnowledgeQueryConfig, KnowledgeQueryService } from "./service.js";
-export { KnowledgeAnswer, KnowledgeQueryConfig, KnowledgeQueryService };

package/dist/query/service.d.ts

@@ -1,27 +0,0 @@
-import { EmbeddingProvider, LLMProvider, LLMResponse, VectorSearchResult, VectorStoreProvider } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/query/service.d.ts
-interface KnowledgeQueryConfig {
-  collection: string;
-  namespace?: string;
-  topK?: number;
-  systemPrompt?: string;
-}
-interface KnowledgeAnswer {
-  answer: string;
-  references: (VectorSearchResult & {
-    text?: string;
-  })[];
-  usage?: LLMResponse['usage'];
-}
-declare class KnowledgeQueryService {
-  private readonly embeddings;
-  private readonly vectorStore;
-  private readonly llm;
-  private readonly config;
-  constructor(embeddings: EmbeddingProvider, vectorStore: VectorStoreProvider, llm: LLMProvider, config: KnowledgeQueryConfig);
-  query(question: string): Promise<KnowledgeAnswer>;
-  private buildMessages;
-}
-//#endregion
-export { KnowledgeAnswer, KnowledgeQueryConfig, KnowledgeQueryService };

package/dist/retriever/index.d.ts

@@ -1,4 +0,0 @@
-import { KnowledgeRetriever, RetrieverConfig } from "./interface.js";
-import { StaticRetriever, StaticRetrieverConfig, createStaticRetriever } from "./static-retriever.js";
-import { VectorRetriever, VectorRetrieverConfig, createVectorRetriever } from "./vector-retriever.js";
-export { KnowledgeRetriever, RetrieverConfig, StaticRetriever, StaticRetrieverConfig, VectorRetriever, VectorRetrieverConfig, createStaticRetriever, createVectorRetriever };

package/dist/retriever/interface.d.ts

@@ -1,55 +0,0 @@
-import { RetrievalOptions, RetrievalResult } from "../types.js";
-
-//#region src/retriever/interface.d.ts
-
-/**
- * Unified interface for knowledge retrieval.
- *
- * Implementations can use vector stores, static content, or hybrid approaches.
- * This interface is consumed by @lssm/lib.ai-agent for both static injection
- * and dynamic RAG tool queries.
- */
-interface KnowledgeRetriever {
-  /**
-   * Retrieve relevant content for a query using semantic search.
-   *
-   * @param query - The search query or question
-   * @param options - Retrieval options including space key and filters
-   * @returns Array of retrieval results sorted by relevance
-   */
-  retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-  /**
-   * Get static content by space key (for required knowledge injection).
-   *
-   * Used for injecting required knowledge into agent system prompts
-   * without performing semantic search.
-   *
-   * @param spaceKey - The knowledge space key
-   * @returns The static content or null if not available
-   */
-  getStatic(spaceKey: string): Promise<string | null>;
-  /**
-   * Check if this retriever supports a given knowledge space.
-   *
-   * @param spaceKey - The knowledge space key to check
-   * @returns True if the space is supported
-   */
-  supportsSpace(spaceKey: string): boolean;
-  /**
-   * List all supported knowledge space keys.
-   *
-   * @returns Array of supported space keys
-   */
-  listSpaces(): string[];
-}
-/**
- * Configuration for creating a retriever.
- */
-interface RetrieverConfig {
-  /** Default number of results to return */
-  defaultTopK?: number;
-  /** Default minimum score threshold */
-  defaultMinScore?: number;
-}
-//#endregion
-export { KnowledgeRetriever, RetrieverConfig };

package/dist/retriever/static-retriever.d.ts

@@ -1,34 +0,0 @@
-import { RetrievalOptions, RetrievalResult } from "../types.js";
-import { KnowledgeRetriever, RetrieverConfig } from "./interface.js";
-
-//#region src/retriever/static-retriever.d.ts
-
-/**
- * Configuration for the static retriever.
- */
-interface StaticRetrieverConfig extends RetrieverConfig {
-  /** Map of space key to static content */
-  content: Map<string, string> | Record<string, string>;
-}
-/**
- * A simple in-memory retriever for static knowledge content.
- *
- * Useful for:
- * - Required knowledge that doesn't need semantic search
- * - Testing and development
- * - Small knowledge bases that fit in memory
- */
-declare class StaticRetriever implements KnowledgeRetriever {
-  private readonly content;
-  constructor(config: StaticRetrieverConfig);
-  retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-  getStatic(spaceKey: string): Promise<string | null>;
-  supportsSpace(spaceKey: string): boolean;
-  listSpaces(): string[];
-}
-/**
- * Create a static retriever from a content map.
- */
-declare function createStaticRetriever(content: Record<string, string> | Map<string, string>): StaticRetriever;
-//#endregion
-export { StaticRetriever, StaticRetrieverConfig, createStaticRetriever };

package/dist/retriever/vector-retriever.d.ts

@@ -1,42 +0,0 @@
-import { RetrievalOptions, RetrievalResult } from "../types.js";
-import { KnowledgeRetriever, RetrieverConfig } from "./interface.js";
-import { EmbeddingProvider, VectorStoreProvider } from "@lssm/lib.contracts/integrations/providers";
-
-//#region src/retriever/vector-retriever.d.ts
-
-/**
- * Configuration for the vector retriever.
- */
-interface VectorRetrieverConfig extends RetrieverConfig {
-  /** Embedding provider for query vectorization */
-  embeddings: EmbeddingProvider;
-  /** Vector store provider for similarity search */
-  vectorStore: VectorStoreProvider;
-  /** Map of space key to collection name */
-  spaceCollections: Map<string, string> | Record<string, string>;
-  /** Optional static content for getStatic() calls */
-  staticContent?: Map<string, string> | Record<string, string>;
-}
-/**
- * A retriever that uses vector similarity search.
- *
- * Uses embedding provider to vectorize queries and vector store
- * provider to perform similarity search.
- */
-declare class VectorRetriever implements KnowledgeRetriever {
-  private readonly config;
-  private readonly spaceCollections;
-  private readonly staticContent;
-  constructor(config: VectorRetrieverConfig);
-  retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-  getStatic(spaceKey: string): Promise<string | null>;
-  supportsSpace(spaceKey: string): boolean;
-  listSpaces(): string[];
-  private extractContent;
-}
-/**
- * Create a vector retriever from configuration.
- */
-declare function createVectorRetriever(config: VectorRetrieverConfig): VectorRetriever;
-//#endregion
-export { VectorRetriever, VectorRetrieverConfig, createVectorRetriever };

package/dist/types.d.ts

@@ -1,55 +0,0 @@
-import { KnowledgeCategory } from "@lssm/lib.contracts/knowledge";
-
-//#region src/types.d.ts
-
-/**
- * Result from a knowledge retrieval operation.
- */
-interface RetrievalResult {
-  /** The retrieved content/text */
-  content: string;
-  /** Source identifier (document ID, URL, etc.) */
-  source: string;
-  /** Relevance score (0-1, higher is more relevant) */
-  score: number;
-  /** Additional metadata about the result */
-  metadata?: Record<string, unknown>;
-}
-/**
- * Options for knowledge retrieval.
- */
-interface RetrievalOptions {
-  /** Knowledge space key to query */
-  spaceKey: string;
-  /** Maximum number of results to return */
-  topK?: number;
-  /** Minimum relevance score threshold */
-  minScore?: number;
-  /** Filter by knowledge category */
-  category?: KnowledgeCategory;
-  /** Tenant-scoped retrieval */
-  tenantId?: string;
-  /** Additional filter criteria */
-  filter?: Record<string, unknown>;
-}
-/**
- * Context for knowledge access operations.
- */
-interface KnowledgeAccessContext {
-  tenantId: string;
-  appId: string;
-  environment?: string;
-  workflowName?: string;
-  agentName?: string;
-  operation: 'read' | 'write' | 'search';
-}
-/**
- * Result of an access check.
- */
-interface KnowledgeAccessResult {
-  allowed: boolean;
-  reason?: string;
-  severity?: 'error' | 'warning';
-}
-//#endregion
-export { KnowledgeAccessContext, KnowledgeAccessResult, RetrievalOptions, RetrievalResult };