@lssm/lib.knowledge 0.0.0-canary-20251207013726 → 0.0.0-canary-20251207043720

package/README.md

@@ -63,3 +63,4 @@ MIT
 
 
 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.knowledge",
-  "version": "0.0.0-canary-20251207013726",
+  "version": "0.0.0-canary-20251207043720",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -31,25 +31,44 @@
     "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": {
-    "access": "public"
+    "access": "public",
+    "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",
+      "./*": "./*"
+    }
   }
 }

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 };