@lssm/lib.knowledge 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,65 @@
+# @lssm/lib.knowledge
+
+Knowledge retrieval and management library for ContractSpec. Provides the runtime implementation for knowledge spaces, including:
+
+- **Retriever Interface**: Unified interface for knowledge retrieval (vector, static, hybrid)
+- **Query Service**: RAG-powered question answering over knowledge spaces
+- **Ingestion Pipeline**: Document processing, embedding, and vector indexing
+- **Access Guard**: Policy-based access control for knowledge spaces
+
+## Installation
+
+```bash
+bun add @lssm/lib.knowledge
+```
+
+## Usage
+
+### Basic Retriever
+
+```typescript
+import { createVectorRetriever } from '@lssm/lib.knowledge/retriever';
+
+const retriever = createVectorRetriever({
+  embeddings: embeddingProvider,
+  vectorStore: vectorStoreProvider,
+});
+
+const results = await retriever.retrieve('How do I reset my password?', {
+  spaceKey: 'support-faq',
+  topK: 5,
+});
+```
+
+### Static Knowledge
+
+```typescript
+import { createStaticRetriever } from '@lssm/lib.knowledge/retriever';
+
+const retriever = createStaticRetriever({
+  'product-canon': 'Product specifications and documentation...',
+  'support-faq': 'Frequently asked questions...',
+});
+
+const content = await retriever.getStatic('product-canon');
+```
+
+## Architecture
+
+This package bridges `@lssm/lib.contracts` (specs/types) with `@lssm/lib.ai-agent` (AI SDK integration):
+
+```
+@lssm/lib.contracts (specs/types)
+         ↓
+@lssm/lib.knowledge (runtime)
+         ↓
+@lssm/lib.ai-agent (AI SDK)
+```
+
+## License
+
+MIT
+
+
+
+

package/dist/access/guard.d.ts

@@ -0,0 +1,20 @@
+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/guard.js

@@ -0,0 +1 @@
+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.d.ts

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

package/dist/access/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+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/index.js

@@ -0,0 +1 @@
+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.d.ts

@@ -0,0 +1,24 @@
+//#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/document-processor.js

@@ -0,0 +1 @@
+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.d.ts

@@ -0,0 +1,12 @@
+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/embedding-service.js

@@ -0,0 +1 @@
+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.d.ts

@@ -0,0 +1,18 @@
+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/gmail-adapter.js

@@ -0,0 +1,6 @@
+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(`
+
+---
+
+`)}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.d.ts

@@ -0,0 +1,6 @@
+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/index.js

@@ -0,0 +1 @@
+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.d.ts

@@ -0,0 +1,15 @@
+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/storage-adapter.js

@@ -0,0 +1 @@
+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.d.ts

@@ -0,0 +1,17 @@
+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/ingestion/vector-indexer.js

@@ -0,0 +1 @@
+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.d.ts

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

package/dist/query/index.js

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

package/dist/query/service.d.ts

@@ -0,0 +1,27 @@
+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/query/service.js

@@ -0,0 +1,3 @@
+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(`
+
+`)}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.d.ts

@@ -0,0 +1,4 @@
+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/index.js

@@ -0,0 +1 @@
+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/interface.d.ts

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,34 @@
+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/static-retriever.js

@@ -0,0 +1,2 @@
+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.d.ts

@@ -0,0 +1,42 @@
+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/retriever/vector-retriever.js

@@ -0,0 +1 @@
+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/dist/types.d.ts

@@ -0,0 +1,55 @@
+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 };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lssm/lib.knowledge",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@lssm/lib.contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "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",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}