@contractspec/lib.knowledge 0.0.0-canary-20260113162409

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @contractspec/lib.knowledge
+
+Website: https://contractspec.io/
+
+
+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 @contractspec/lib.knowledge
+```
+
+## Usage
+
+### Basic Retriever
+
+```typescript
+import { createVectorRetriever } from '@contractspec/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 '@contractspec/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 `@contractspec/lib.contracts` (specs/types) with `@contractspec/lib.ai-agent` (AI SDK integration):
+
+```
+@contractspec/lib.contracts (specs/types)
+         ↓
+@contractspec/lib.knowledge (runtime)
+         ↓
+@contractspec/lib.ai-agent (AI SDK)
+```
+
+## License
+
+MIT
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/access/guard.d.ts

@@ -0,0 +1,20 @@
+import { KnowledgeAccessContext, KnowledgeAccessResult } from "../types.js";
+import { KnowledgeCategory, ResolvedAppConfig, ResolvedKnowledge } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=guard.d.ts.map

package/dist/access/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","names":[],"sources":["../../src/access/guard.ts"],"sourcesContent":[],"mappings":";;;;UAOiB,2BAAA;4BACW;EADX,sBAAA,CAAA,EAAA,OAA2B;EAQ/B,mBAAA,CAAA,EAAA,OAAoB;;AAcf,cAdL,oBAAA,CAcK;EACL,iBAAA,eAAA;EACE,iBAAA,sBAAA;EACV,iBAAA,mBAAA;EAAqB,WAAA,CAAA,OAAA,CAAA,EAZH,2BAYG;4BAHR,4BACL,mCACE,oBACV"}

package/dist/access/guard.js

@@ -0,0 +1,50 @@
+//#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 };
+//# sourceMappingURL=guard.js.map

package/dist/access/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","names":[],"sources":["../../src/access/guard.ts"],"sourcesContent":["import type {\n  ResolvedAppConfig,\n  ResolvedKnowledge,\n  KnowledgeCategory,\n} from '@contractspec/lib.contracts';\nimport type { KnowledgeAccessContext, KnowledgeAccessResult } from '../types';\n\nexport interface KnowledgeAccessGuardOptions {\n  disallowWriteCategories?: KnowledgeCategory[];\n  requireWorkflowBinding?: boolean;\n  requireAgentBinding?: boolean;\n}\n\nconst DEFAULT_DISALLOWED_WRITE: KnowledgeCategory[] = ['external', 'ephemeral'];\n\nexport class KnowledgeAccessGuard {\n  private readonly disallowedWrite: Set<KnowledgeCategory>;\n  private readonly requireWorkflowBinding: boolean;\n  private readonly requireAgentBinding: boolean;\n\n  constructor(options: KnowledgeAccessGuardOptions = {}) {\n    this.disallowedWrite = new Set(\n      options.disallowWriteCategories ?? DEFAULT_DISALLOWED_WRITE\n    );\n    this.requireWorkflowBinding = options.requireWorkflowBinding ?? true;\n    this.requireAgentBinding = options.requireAgentBinding ?? false;\n  }\n\n  checkAccess(\n    spaceBinding: ResolvedKnowledge,\n    context: KnowledgeAccessContext,\n    appConfig: ResolvedAppConfig\n  ): KnowledgeAccessResult {\n    const { binding, space } = spaceBinding;\n\n    if (\n      binding.required !== false &&\n      !this.isSpaceBound(spaceBinding, appConfig)\n    ) {\n      return {\n        allowed: false,\n        reason: `Knowledge space \"${space.meta.key}\" is not bound in the resolved app config.`,\n      };\n    }\n\n    if (\n      context.operation === 'write' &&\n      this.disallowedWrite.has(space.meta.category)\n    ) {\n      return {\n        allowed: false,\n        reason: `Knowledge space \"${space.meta.key}\" is category \"${space.meta.category}\" and is read-only.`,\n      };\n    }\n\n    if (this.requireWorkflowBinding && context.workflowName) {\n      const allowedWorkflows = binding.scope?.workflows;\n      if (\n        allowedWorkflows &&\n        !allowedWorkflows.includes(context.workflowName)\n      ) {\n        return {\n          allowed: false,\n          reason: `Workflow \"${context.workflowName}\" is not authorized to access knowledge space \"${space.meta.key}\".`,\n        };\n      }\n    }\n\n    if (this.requireAgentBinding && context.agentName) {\n      const allowedAgents = binding.scope?.agents;\n      if (allowedAgents && !allowedAgents.includes(context.agentName)) {\n        return {\n          allowed: false,\n          reason: `Agent \"${context.agentName}\" is not authorized to access knowledge space \"${space.meta.key}\".`,\n        };\n      }\n    }\n\n    if (space.meta.category === 'ephemeral') {\n      return {\n        allowed: true,\n        severity: 'warning',\n        reason: `Knowledge space \"${space.meta.key}\" is ephemeral; results may be transient.`,\n      };\n    }\n\n    return { allowed: true };\n  }\n\n  private isSpaceBound(\n    resolved: ResolvedKnowledge,\n    appConfig: ResolvedAppConfig\n  ): boolean {\n    return appConfig.knowledge.some(\n      (entry) =>\n        entry.space.meta.key === resolved.space.meta.key &&\n        (resolved.space.meta.version == null ||\n          entry.space.meta.version === resolved.space.meta.version)\n    );\n  }\n}\n"],"mappings":";AAaA,MAAM,2BAAgD,CAAC,YAAY,YAAY;AAE/E,IAAa,uBAAb,MAAkC;CAChC,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,YAAY,UAAuC,EAAE,EAAE;AACrD,OAAK,kBAAkB,IAAI,IACzB,QAAQ,2BAA2B,yBACpC;AACD,OAAK,yBAAyB,QAAQ,0BAA0B;AAChE,OAAK,sBAAsB,QAAQ,uBAAuB;;CAG5D,YACE,cACA,SACA,WACuB;EACvB,MAAM,EAAE,SAAS,UAAU;AAE3B,MACE,QAAQ,aAAa,SACrB,CAAC,KAAK,aAAa,cAAc,UAAU,CAE3C,QAAO;GACL,SAAS;GACT,QAAQ,oBAAoB,MAAM,KAAK,IAAI;GAC5C;AAGH,MACE,QAAQ,cAAc,WACtB,KAAK,gBAAgB,IAAI,MAAM,KAAK,SAAS,CAE7C,QAAO;GACL,SAAS;GACT,QAAQ,oBAAoB,MAAM,KAAK,IAAI,iBAAiB,MAAM,KAAK,SAAS;GACjF;AAGH,MAAI,KAAK,0BAA0B,QAAQ,cAAc;GACvD,MAAM,mBAAmB,QAAQ,OAAO;AACxC,OACE,oBACA,CAAC,iBAAiB,SAAS,QAAQ,aAAa,CAEhD,QAAO;IACL,SAAS;IACT,QAAQ,aAAa,QAAQ,aAAa,iDAAiD,MAAM,KAAK,IAAI;IAC3G;;AAIL,MAAI,KAAK,uBAAuB,QAAQ,WAAW;GACjD,MAAM,gBAAgB,QAAQ,OAAO;AACrC,OAAI,iBAAiB,CAAC,cAAc,SAAS,QAAQ,UAAU,CAC7D,QAAO;IACL,SAAS;IACT,QAAQ,UAAU,QAAQ,UAAU,iDAAiD,MAAM,KAAK,IAAI;IACrG;;AAIL,MAAI,MAAM,KAAK,aAAa,YAC1B,QAAO;GACL,SAAS;GACT,UAAU;GACV,QAAQ,oBAAoB,MAAM,KAAK,IAAI;GAC5C;AAGH,SAAO,EAAE,SAAS,MAAM;;CAG1B,AAAQ,aACN,UACA,WACS;AACT,SAAO,UAAU,UAAU,MACxB,UACC,MAAM,MAAM,KAAK,QAAQ,SAAS,MAAM,KAAK,QAC5C,SAAS,MAAM,KAAK,WAAW,QAC9B,MAAM,MAAM,KAAK,YAAY,SAAS,MAAM,KAAK,SACtD"}

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,3 @@
+import { KnowledgeAccessGuard } from "./guard.js";
+
+export { 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,12 @@
+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 };

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

@@ -0,0 +1,25 @@
+//#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 };
+//# sourceMappingURL=document-processor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-processor.d.ts","names":[],"sources":["../../src/ingestion/document-processor.ts"],"sourcesContent":[],"mappings":";UAEiB,WAAA;EAAA,EAAA,EAAA,MAAA;EAOA,QAAA,EAAA,MAAA;EAOZ,IAAA,EAXG,UAWM;EAAW,QAAA,CAAA,EAVZ,MAUY,CAAA,MAAA,EAAA,MAAA,CAAA;;AAAgB,UAPxB,gBAAA,CAOwB;EAAO,EAAA,EAAA,MAAA;EAEnC,UAAA,EAAA,MAAA;EAQoC,IAAA,EAAA,MAAA;EAIvB,QAAA,CAAA,EAjBb,MAiBa,CAAA,MAAA,EAAA,MAAA,CAAA;;KAdrB,SAAA,GAcmC,CAAA,KAAA,EAdf,WAce,EAAA,GAdC,OAcD,CAdS,gBAcT,EAAA,CAAA;AAAO,cAZlC,iBAAA,CAYkC;;;iDAJE;oBAIvB,cAAc,QAAQ"}

package/dist/ingestion/document-processor.js

@@ -0,0 +1,55 @@
+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 };
+//# sourceMappingURL=document-processor.js.map

package/dist/ingestion/document-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-processor.js","names":[],"sources":["../../src/ingestion/document-processor.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\n\nexport interface RawDocument {\n  id: string;\n  mimeType: string;\n  data: Uint8Array;\n  metadata?: Record<string, string>;\n}\n\nexport interface DocumentFragment {\n  id: string;\n  documentId: string;\n  text: string;\n  metadata?: Record<string, string>;\n}\n\ntype Extractor = (input: RawDocument) => Promise<DocumentFragment[]>;\n\nexport class DocumentProcessor {\n  private readonly extractors = new Map<string, Extractor>();\n\n  constructor() {\n    this.registerExtractor('text/plain', this.extractText.bind(this));\n    this.registerExtractor('application/json', this.extractJson.bind(this));\n  }\n\n  registerExtractor(mimeType: string, extractor: Extractor): void {\n    this.extractors.set(mimeType.toLowerCase(), extractor);\n  }\n\n  async process(document: RawDocument): Promise<DocumentFragment[]> {\n    const extractor =\n      this.extractors.get(document.mimeType.toLowerCase()) ??\n      this.extractors.get('*/*');\n    if (!extractor) {\n      throw new Error(\n        `No extractor registered for mime type ${document.mimeType}`\n      );\n    }\n    const fragments = await extractor(document);\n    if (fragments.length === 0) {\n      return [\n        {\n          id: `${document.id}:0`,\n          documentId: document.id,\n          text: '',\n          metadata: document.metadata,\n        },\n      ];\n    }\n    return fragments;\n  }\n\n  private async extractText(\n    document: RawDocument\n  ): Promise<DocumentFragment[]> {\n    const text = Buffer.from(document.data).toString('utf-8');\n    return [\n      {\n        id: `${document.id}:0`,\n        documentId: document.id,\n        text,\n        metadata: document.metadata,\n      },\n    ];\n  }\n\n  private async extractJson(\n    document: RawDocument\n  ): Promise<DocumentFragment[]> {\n    const text = Buffer.from(document.data).toString('utf-8');\n    try {\n      const json = JSON.parse(text) as unknown;\n      return [\n        {\n          id: `${document.id}:0`,\n          documentId: document.id,\n          text: JSON.stringify(json, null, 2),\n          metadata: {\n            ...document.metadata,\n            contentType: 'application/json',\n          },\n        },\n      ];\n    } catch {\n      return this.extractText(document);\n    }\n  }\n}\n"],"mappings":";;;AAkBA,IAAa,oBAAb,MAA+B;CAC7B,AAAiB,6BAAa,IAAI,KAAwB;CAE1D,cAAc;AACZ,OAAK,kBAAkB,cAAc,KAAK,YAAY,KAAK,KAAK,CAAC;AACjE,OAAK,kBAAkB,oBAAoB,KAAK,YAAY,KAAK,KAAK,CAAC;;CAGzE,kBAAkB,UAAkB,WAA4B;AAC9D,OAAK,WAAW,IAAI,SAAS,aAAa,EAAE,UAAU;;CAGxD,MAAM,QAAQ,UAAoD;EAChE,MAAM,YACJ,KAAK,WAAW,IAAI,SAAS,SAAS,aAAa,CAAC,IACpD,KAAK,WAAW,IAAI,MAAM;AAC5B,MAAI,CAAC,UACH,OAAM,IAAI,MACR,yCAAyC,SAAS,WACnD;EAEH,MAAM,YAAY,MAAM,UAAU,SAAS;AAC3C,MAAI,UAAU,WAAW,EACvB,QAAO,CACL;GACE,IAAI,GAAG,SAAS,GAAG;GACnB,YAAY,SAAS;GACrB,MAAM;GACN,UAAU,SAAS;GACpB,CACF;AAEH,SAAO;;CAGT,MAAc,YACZ,UAC6B;EAC7B,MAAM,OAAO,OAAO,KAAK,SAAS,KAAK,CAAC,SAAS,QAAQ;AACzD,SAAO,CACL;GACE,IAAI,GAAG,SAAS,GAAG;GACnB,YAAY,SAAS;GACrB;GACA,UAAU,SAAS;GACpB,CACF;;CAGH,MAAc,YACZ,UAC6B;EAC7B,MAAM,OAAO,OAAO,KAAK,SAAS,KAAK,CAAC,SAAS,QAAQ;AACzD,MAAI;GACF,MAAM,OAAO,KAAK,MAAM,KAAK;AAC7B,UAAO,CACL;IACE,IAAI,GAAG,SAAS,GAAG;IACnB,YAAY,SAAS;IACrB,MAAM,KAAK,UAAU,MAAM,MAAM,EAAE;IACnC,UAAU;KACR,GAAG,SAAS;KACZ,aAAa;KACd;IACF,CACF;UACK;AACN,UAAO,KAAK,YAAY,SAAS"}

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

@@ -0,0 +1,13 @@
+import { DocumentFragment } from "./document-processor.js";
+import { EmbeddingProvider, EmbeddingResult } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=embedding-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-service.d.ts","names":[],"sources":["../../src/ingestion/embedding-service.ts"],"sourcesContent":[],"mappings":";;;;cAOa,gBAAA;;EAAA,iBAAA,SAAgB;EAIL,WAAA,CAAA,QAAA,EAAA,iBAAA,EAAA,SAAA,CAAA,EAAA,MAAA;EAMT,cAAA,CAAA,SAAA,EAAA,gBAAA,EAAA,CAAA,EACV,OADU,CACF,eADE,EAAA,CAAA"}

package/dist/ingestion/embedding-service.js

@@ -0,0 +1,26 @@
+//#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 };
+//# sourceMappingURL=embedding-service.js.map

package/dist/ingestion/embedding-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-service.js","names":[],"sources":["../../src/ingestion/embedding-service.ts"],"sourcesContent":["import type {\n  EmbeddingDocument,\n  EmbeddingProvider,\n  EmbeddingResult,\n} from '@contractspec/lib.contracts';\nimport type { DocumentFragment } from './document-processor';\n\nexport class EmbeddingService {\n  private readonly provider: EmbeddingProvider;\n  private readonly batchSize: number;\n\n  constructor(provider: EmbeddingProvider, batchSize = 16) {\n    this.provider = provider;\n    this.batchSize = batchSize;\n  }\n\n  async embedFragments(\n    fragments: DocumentFragment[]\n  ): Promise<EmbeddingResult[]> {\n    const results: EmbeddingResult[] = [];\n    for (let i = 0; i < fragments.length; i += this.batchSize) {\n      const slice = fragments.slice(i, i + this.batchSize);\n      const documents: EmbeddingDocument[] = slice.map((fragment) => ({\n        id: fragment.id,\n        text: fragment.text,\n        metadata: fragment.metadata,\n      }));\n      const embeddings = await this.provider.embedDocuments(documents);\n      results.push(...embeddings);\n    }\n    return results;\n  }\n}\n"],"mappings":";AAOA,IAAa,mBAAb,MAA8B;CAC5B,AAAiB;CACjB,AAAiB;CAEjB,YAAY,UAA6B,YAAY,IAAI;AACvD,OAAK,WAAW;AAChB,OAAK,YAAY;;CAGnB,MAAM,eACJ,WAC4B;EAC5B,MAAM,UAA6B,EAAE;AACrC,OAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK,KAAK,WAAW;GAEzD,MAAM,YADQ,UAAU,MAAM,GAAG,IAAI,KAAK,UAAU,CACP,KAAK,cAAc;IAC9D,IAAI,SAAS;IACb,MAAM,SAAS;IACf,UAAU,SAAS;IACpB,EAAE;GACH,MAAM,aAAa,MAAM,KAAK,SAAS,eAAe,UAAU;AAChE,WAAQ,KAAK,GAAG,WAAW;;AAE7B,SAAO"}

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

@@ -0,0 +1,19 @@
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { VectorIndexer } from "./vector-indexer.js";
+import { EmailInboundProvider, EmailThread } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=gmail-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gmail-adapter.d.ts","names":[],"sources":["../../src/ingestion/gmail-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;cAQa,qBAAA;;EAAA,iBAAA,SAAqB;EAEN,iBAAA,UAAA;EACI,iBAAA,OAAA;EACC,WAAA,CAAA,KAAA,EAFL,oBAEK,EAAA,SAAA,EADD,iBACC,EAAA,UAAA,EAAA,gBAAA,EAAA,OAAA,EACH,aADG;EACH,WAAA,CAAA,KAAA,CAAA,EAIlB,UAJkB,CAIP,oBAJO,CAAA,aAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAIgC,OAJhC,CAAA,IAAA,CAAA;EAIP,YAAA,CAAA,MAAA,EAQM,WARN,CAAA,EAQiB,OARjB,CAAA,IAAA,CAAA;EAAX,QAAA,aAAA"}

package/dist/ingestion/gmail-adapter.js

@@ -0,0 +1,52 @@
+//#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, " ");
+}
+
+//#endregion
+export { GmailIngestionAdapter };
+//# sourceMappingURL=gmail-adapter.js.map

package/dist/ingestion/gmail-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmail-adapter.js","names":[],"sources":["../../src/ingestion/gmail-adapter.ts"],"sourcesContent":["import type {\n  EmailInboundProvider,\n  EmailThread,\n} from '@contractspec/lib.contracts';\nimport type { DocumentProcessor, RawDocument } from './document-processor';\nimport type { EmbeddingService } from './embedding-service';\nimport type { VectorIndexer } from './vector-indexer';\n\nexport class GmailIngestionAdapter {\n  constructor(\n    private readonly gmail: EmailInboundProvider,\n    private readonly processor: DocumentProcessor,\n    private readonly embeddings: EmbeddingService,\n    private readonly indexer: VectorIndexer\n  ) {}\n\n  async syncThreads(\n    query?: Parameters<EmailInboundProvider['listThreads']>[0]\n  ) {\n    const threads = await this.gmail.listThreads(query);\n    for (const thread of threads) {\n      await this.ingestThread(thread);\n    }\n  }\n\n  async ingestThread(thread: EmailThread) {\n    const document = this.toRawDocument(thread);\n    const fragments = await this.processor.process(document);\n    const embeddings = await this.embeddings.embedFragments(fragments);\n    await this.indexer.upsert(fragments, embeddings);\n  }\n\n  private toRawDocument(thread: EmailThread): RawDocument {\n    const content = composeThreadText(thread);\n    return {\n      id: thread.id,\n      mimeType: 'text/plain',\n      data: Buffer.from(content, 'utf-8'),\n      metadata: {\n        subject: thread.subject ?? '',\n        participants: thread.participants.map((p) => p.email).join(', '),\n        updatedAt: thread.updatedAt.toISOString(),\n      },\n    };\n  }\n}\n\nfunction composeThreadText(thread: EmailThread): string {\n  const header = [\n    `Subject: ${thread.subject ?? ''}`,\n    `Snippet: ${thread.snippet ?? ''}`,\n  ];\n  const messageTexts = thread.messages.map((message) => {\n    const parts = [\n      `From: ${formatAddress(message.from)}`,\n      `To: ${message.to.map(formatAddress).join(', ')}`,\n    ];\n    if (message.sentAt) {\n      parts.push(`Date: ${message.sentAt.toISOString()}`);\n    }\n    const body = message.textBody ?? stripHtml(message.htmlBody ?? '');\n    return `${parts.join('\\n')}\\n\\n${body ?? ''}`;\n  });\n  return [...header, ...messageTexts].join('\\n\\n---\\n\\n');\n}\n\nfunction formatAddress(address: { email: string; name?: string }): string {\n  return address.name ? `${address.name} <${address.email}>` : address.email;\n}\n\nfunction stripHtml(html: string): string {\n  return html.replace(/<[^>]+>/g, ' ');\n}\n"],"mappings":";AAQA,IAAa,wBAAb,MAAmC;CACjC,YACE,AAAiB,OACjB,AAAiB,WACjB,AAAiB,YACjB,AAAiB,SACjB;EAJiB;EACA;EACA;EACA;;CAGnB,MAAM,YACJ,OACA;EACA,MAAM,UAAU,MAAM,KAAK,MAAM,YAAY,MAAM;AACnD,OAAK,MAAM,UAAU,QACnB,OAAM,KAAK,aAAa,OAAO;;CAInC,MAAM,aAAa,QAAqB;EACtC,MAAM,WAAW,KAAK,cAAc,OAAO;EAC3C,MAAM,YAAY,MAAM,KAAK,UAAU,QAAQ,SAAS;EACxD,MAAM,aAAa,MAAM,KAAK,WAAW,eAAe,UAAU;AAClE,QAAM,KAAK,QAAQ,OAAO,WAAW,WAAW;;CAGlD,AAAQ,cAAc,QAAkC;EACtD,MAAM,UAAU,kBAAkB,OAAO;AACzC,SAAO;GACL,IAAI,OAAO;GACX,UAAU;GACV,MAAM,OAAO,KAAK,SAAS,QAAQ;GACnC,UAAU;IACR,SAAS,OAAO,WAAW;IAC3B,cAAc,OAAO,aAAa,KAAK,MAAM,EAAE,MAAM,CAAC,KAAK,KAAK;IAChE,WAAW,OAAO,UAAU,aAAa;IAC1C;GACF;;;AAIL,SAAS,kBAAkB,QAA6B;CACtD,MAAM,SAAS,CACb,YAAY,OAAO,WAAW,MAC9B,YAAY,OAAO,WAAW,KAC/B;CACD,MAAM,eAAe,OAAO,SAAS,KAAK,YAAY;EACpD,MAAM,QAAQ,CACZ,SAAS,cAAc,QAAQ,KAAK,IACpC,OAAO,QAAQ,GAAG,IAAI,cAAc,CAAC,KAAK,KAAK,GAChD;AACD,MAAI,QAAQ,OACV,OAAM,KAAK,SAAS,QAAQ,OAAO,aAAa,GAAG;EAErD,MAAM,OAAO,QAAQ,YAAY,UAAU,QAAQ,YAAY,GAAG;AAClE,SAAO,GAAG,MAAM,KAAK,KAAK,CAAC,MAAM,QAAQ;GACzC;AACF,QAAO,CAAC,GAAG,QAAQ,GAAG,aAAa,CAAC,KAAK,cAAc;;AAGzD,SAAS,cAAc,SAAmD;AACxE,QAAO,QAAQ,OAAO,GAAG,QAAQ,KAAK,IAAI,QAAQ,MAAM,KAAK,QAAQ;;AAGvE,SAAS,UAAU,MAAsB;AACvC,QAAO,KAAK,QAAQ,YAAY,IAAI"}

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

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

@@ -0,0 +1,16 @@
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { VectorIndexer } from "./vector-indexer.js";
+import { GetObjectResult } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=storage-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage-adapter.d.ts","names":[],"sources":["../../src/ingestion/storage-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;cAKa,uBAAA;;EAAA,iBAAA,UAAuB;EAEJ,iBAAA,OAAA;EACC,WAAA,CAAA,SAAA,EADD,iBACC,EAAA,UAAA,EAAA,gBAAA,EAAA,OAAA,EACH,aADG;EACH,YAAA,CAAA,MAAA,EAGD,eAHC,CAAA,EAGiB,OAHjB,CAAA,IAAA,CAAA"}

package/dist/ingestion/storage-adapter.js

@@ -0,0 +1,27 @@
+//#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 };
+//# sourceMappingURL=storage-adapter.js.map

package/dist/ingestion/storage-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-adapter.js","names":[],"sources":["../../src/ingestion/storage-adapter.ts"],"sourcesContent":["import type { GetObjectResult } from '@contractspec/lib.contracts';\nimport type { DocumentProcessor } from './document-processor';\nimport type { EmbeddingService } from './embedding-service';\nimport type { VectorIndexer } from './vector-indexer';\n\nexport class StorageIngestionAdapter {\n  constructor(\n    private readonly processor: DocumentProcessor,\n    private readonly embeddings: EmbeddingService,\n    private readonly indexer: VectorIndexer\n  ) {}\n\n  async ingestObject(object: GetObjectResult): Promise<void> {\n    if (!('data' in object) || !object.data) {\n      throw new Error('Storage ingestion requires object data');\n    }\n\n    const raw = {\n      id: object.key,\n      mimeType: object.contentType ?? 'application/octet-stream',\n      data: object.data,\n      metadata: {\n        bucket: object.bucket,\n        checksum: object.checksum ?? '',\n      },\n    };\n\n    const fragments = await this.processor.process(raw);\n    const embeddings = await this.embeddings.embedFragments(fragments);\n    await this.indexer.upsert(fragments, embeddings);\n  }\n}\n"],"mappings":";AAKA,IAAa,0BAAb,MAAqC;CACnC,YACE,AAAiB,WACjB,AAAiB,YACjB,AAAiB,SACjB;EAHiB;EACA;EACA;;CAGnB,MAAM,aAAa,QAAwC;AACzD,MAAI,EAAE,UAAU,WAAW,CAAC,OAAO,KACjC,OAAM,IAAI,MAAM,yCAAyC;EAG3D,MAAM,MAAM;GACV,IAAI,OAAO;GACX,UAAU,OAAO,eAAe;GAChC,MAAM,OAAO;GACb,UAAU;IACR,QAAQ,OAAO;IACf,UAAU,OAAO,YAAY;IAC9B;GACF;EAED,MAAM,YAAY,MAAM,KAAK,UAAU,QAAQ,IAAI;EACnD,MAAM,aAAa,MAAM,KAAK,WAAW,eAAe,UAAU;AAClE,QAAM,KAAK,QAAQ,OAAO,WAAW,WAAW"}

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

@@ -0,0 +1,18 @@
+import { DocumentFragment } from "./document-processor.js";
+import { EmbeddingResult, VectorStoreProvider } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=vector-indexer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vector-indexer.d.ts","names":[],"sources":["../../src/ingestion/vector-indexer.ts"],"sourcesContent":[],"mappings":";;;;UAOiB,iBAAA;;EAAA,SAAA,CAAA,EAAA,MAAA;EAMJ,QAAA,CAAA,EAHA,MAGa,CAAA,MAAA,EAAA,MAAA,CAAA;;AAI2B,cAJxC,aAAA,CAIwC;EAMtC,iBAAA,QAAA;EACC,iBAAA,MAAA;EACX,WAAA,CAAA,QAAA,EARmB,mBAQnB,EAAA,MAAA,EARgD,iBAQhD;EAAO,MAAA,CAAA,SAAA,EAFG,gBAEH,EAAA,EAAA,UAAA,EADI,eACJ,EAAA,CAAA,EAAP,OAAO,CAAA,IAAA,CAAA"}

package/dist/ingestion/vector-indexer.js

@@ -0,0 +1,33 @@
+//#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 };
+//# sourceMappingURL=vector-indexer.js.map

package/dist/ingestion/vector-indexer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-indexer.js","names":[],"sources":["../../src/ingestion/vector-indexer.ts"],"sourcesContent":["import type {\n  VectorStoreProvider,\n  VectorUpsertRequest,\n  EmbeddingResult,\n} from '@contractspec/lib.contracts';\nimport type { DocumentFragment } from './document-processor';\n\nexport interface VectorIndexConfig {\n  collection: string;\n  namespace?: string;\n  metadata?: Record<string, string>;\n}\n\nexport class VectorIndexer {\n  private readonly provider: VectorStoreProvider;\n  private readonly config: VectorIndexConfig;\n\n  constructor(provider: VectorStoreProvider, config: VectorIndexConfig) {\n    this.provider = provider;\n    this.config = config;\n  }\n\n  async upsert(\n    fragments: DocumentFragment[],\n    embeddings: EmbeddingResult[]\n  ): Promise<void> {\n    const documents = embeddings.map((embedding) => {\n      const fragment = fragments.find((f) => f.id === embedding.id);\n      return {\n        id: embedding.id,\n        vector: embedding.vector,\n        payload: {\n          ...this.config.metadata,\n          ...(fragment?.metadata ?? {}),\n          documentId: fragment?.documentId,\n        },\n        namespace: this.config.namespace,\n      };\n    });\n\n    const request: VectorUpsertRequest = {\n      collection: this.config.collection,\n      documents,\n    };\n\n    await this.provider.upsert(request);\n  }\n}\n"],"mappings":";AAaA,IAAa,gBAAb,MAA2B;CACzB,AAAiB;CACjB,AAAiB;CAEjB,YAAY,UAA+B,QAA2B;AACpE,OAAK,WAAW;AAChB,OAAK,SAAS;;CAGhB,MAAM,OACJ,WACA,YACe;EACf,MAAM,YAAY,WAAW,KAAK,cAAc;GAC9C,MAAM,WAAW,UAAU,MAAM,MAAM,EAAE,OAAO,UAAU,GAAG;AAC7D,UAAO;IACL,IAAI,UAAU;IACd,QAAQ,UAAU;IAClB,SAAS;KACP,GAAG,KAAK,OAAO;KACf,GAAI,UAAU,YAAY,EAAE;KAC5B,YAAY,UAAU;KACvB;IACD,WAAW,KAAK,OAAO;IACxB;IACD;EAEF,MAAM,UAA+B;GACnC,YAAY,KAAK,OAAO;GACxB;GACD;AAED,QAAM,KAAK,SAAS,OAAO,QAAQ"}

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,3 @@
+import { KnowledgeQueryService } from "./service.js";
+
+export { KnowledgeQueryService };

package/dist/query/service.d.ts

@@ -0,0 +1,28 @@
+import { EmbeddingProvider, LLMProvider, LLMResponse, VectorSearchResult, VectorStoreProvider } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=service.d.ts.map

package/dist/query/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","names":[],"sources":["../../src/query/service.ts"],"sourcesContent":[],"mappings":";;;UASiB,oBAAA;;EAAA,SAAA,CAAA,EAAA,MAAA;EAOA,IAAA,CAAA,EAAA,MAAA;EAQJ,YAAA,CAAA,EAAA,MAAA;;AAQI,UAhBA,eAAA,CAgBA;EACR,MAAA,EAAA,MAAA;EACG,UAAA,EAAA,CAhBG,kBAgBH,GAAA;IAQ6B,IAAA,CAAA,EAAA,MAAA;EAAR,CAAA,CAAA,EAAA;EAAO,KAAA,CAAA,EArB9B,WAqB8B,CAAA,OAAA,CAAA;;cAlB3B,qBAAA;;;;;0BAOG,gCACC,0BACR,qBACG;2BAQqB,QAAQ"}

package/dist/query/service.js

@@ -0,0 +1,66 @@
+//#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);
+}
+
+//#endregion
+export { KnowledgeQueryService };
+//# sourceMappingURL=service.js.map

package/dist/query/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","names":[],"sources":["../../src/query/service.ts"],"sourcesContent":["import type {\n  EmbeddingProvider,\n  VectorStoreProvider,\n  VectorSearchResult,\n  LLMProvider,\n  LLMMessage,\n  LLMResponse,\n} from '@contractspec/lib.contracts';\n\nexport interface KnowledgeQueryConfig {\n  collection: string;\n  namespace?: string;\n  topK?: number;\n  systemPrompt?: string;\n}\n\nexport interface KnowledgeAnswer {\n  answer: string;\n  references: (VectorSearchResult & {\n    text?: string;\n  })[];\n  usage?: LLMResponse['usage'];\n}\n\nexport class KnowledgeQueryService {\n  private readonly embeddings: EmbeddingProvider;\n  private readonly vectorStore: VectorStoreProvider;\n  private readonly llm: LLMProvider;\n  private readonly config: KnowledgeQueryConfig;\n\n  constructor(\n    embeddings: EmbeddingProvider,\n    vectorStore: VectorStoreProvider,\n    llm: LLMProvider,\n    config: KnowledgeQueryConfig\n  ) {\n    this.embeddings = embeddings;\n    this.vectorStore = vectorStore;\n    this.llm = llm;\n    this.config = config;\n  }\n\n  async query(question: string): Promise<KnowledgeAnswer> {\n    const embedding = await this.embeddings.embedQuery(question);\n    const results = await this.vectorStore.search({\n      collection: this.config.collection,\n      vector: embedding.vector,\n      topK: this.config.topK ?? 5,\n      namespace: this.config.namespace,\n      filter: undefined,\n    });\n    const context = buildContext(results);\n    const messages = this.buildMessages(question, context);\n    const response = await this.llm.chat(messages);\n    return {\n      answer: response.message.content\n        .map((part) => ('text' in part ? part.text : ''))\n        .join(''),\n      references: results.map((result) => ({\n        ...result,\n        text: extractText(result),\n      })),\n      usage: response.usage,\n    };\n  }\n\n  private buildMessages(question: string, context: string): LLMMessage[] {\n    const systemPrompt =\n      this.config.systemPrompt ??\n      'You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.';\n    return [\n      {\n        role: 'system',\n        content: [{ type: 'text', text: systemPrompt }],\n      },\n      {\n        role: 'user',\n        content: [\n          {\n            type: 'text',\n            text: `Question:\\n${question}\\n\\nContext:\\n${context}`,\n          },\n        ],\n      },\n    ];\n  }\n}\n\nfunction buildContext(results: VectorSearchResult[]): string {\n  if (results.length === 0) {\n    return 'No relevant documents found.';\n  }\n  return results\n    .map((result, index) => {\n      const text = extractText(result);\n      return `Source ${index + 1} (score: ${result.score.toFixed(3)}):\\n${text}`;\n    })\n    .join('\\n\\n');\n}\n\nfunction extractText(result: VectorSearchResult): string {\n  const payload = result.payload ?? {};\n  if (typeof payload.text === 'string') return payload.text;\n  if (typeof payload.content === 'string') return payload.content;\n  return JSON.stringify(payload);\n}\n"],"mappings":";AAwBA,IAAa,wBAAb,MAAmC;CACjC,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,YACE,YACA,aACA,KACA,QACA;AACA,OAAK,aAAa;AAClB,OAAK,cAAc;AACnB,OAAK,MAAM;AACX,OAAK,SAAS;;CAGhB,MAAM,MAAM,UAA4C;EACtD,MAAM,YAAY,MAAM,KAAK,WAAW,WAAW,SAAS;EAC5D,MAAM,UAAU,MAAM,KAAK,YAAY,OAAO;GAC5C,YAAY,KAAK,OAAO;GACxB,QAAQ,UAAU;GAClB,MAAM,KAAK,OAAO,QAAQ;GAC1B,WAAW,KAAK,OAAO;GACvB,QAAQ;GACT,CAAC;EACF,MAAM,UAAU,aAAa,QAAQ;EACrC,MAAM,WAAW,KAAK,cAAc,UAAU,QAAQ;EACtD,MAAM,WAAW,MAAM,KAAK,IAAI,KAAK,SAAS;AAC9C,SAAO;GACL,QAAQ,SAAS,QAAQ,QACtB,KAAK,SAAU,UAAU,OAAO,KAAK,OAAO,GAAI,CAChD,KAAK,GAAG;GACX,YAAY,QAAQ,KAAK,YAAY;IACnC,GAAG;IACH,MAAM,YAAY,OAAO;IAC1B,EAAE;GACH,OAAO,SAAS;GACjB;;CAGH,AAAQ,cAAc,UAAkB,SAA+B;AAIrE,SAAO,CACL;GACE,MAAM;GACN,SAAS,CAAC;IAAE,MAAM;IAAQ,MAL5B,KAAK,OAAO,gBACZ;IAIgD,CAAC;GAChD,EACD;GACE,MAAM;GACN,SAAS,CACP;IACE,MAAM;IACN,MAAM,cAAc,SAAS,gBAAgB;IAC9C,CACF;GACF,CACF;;;AAIL,SAAS,aAAa,SAAuC;AAC3D,KAAI,QAAQ,WAAW,EACrB,QAAO;AAET,QAAO,QACJ,KAAK,QAAQ,UAAU;EACtB,MAAM,OAAO,YAAY,OAAO;AAChC,SAAO,UAAU,QAAQ,EAAE,WAAW,OAAO,MAAM,QAAQ,EAAE,CAAC,MAAM;GACpE,CACD,KAAK,OAAO;;AAGjB,SAAS,YAAY,QAAoC;CACvD,MAAM,UAAU,OAAO,WAAW,EAAE;AACpC,KAAI,OAAO,QAAQ,SAAS,SAAU,QAAO,QAAQ;AACrD,KAAI,OAAO,QAAQ,YAAY,SAAU,QAAO,QAAQ;AACxD,QAAO,KAAK,UAAU,QAAQ"}

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,4 @@
+import { StaticRetriever, createStaticRetriever } from "./static-retriever.js";
+import { VectorRetriever, createVectorRetriever } from "./vector-retriever.js";
+
+export { StaticRetriever, VectorRetriever, createStaticRetriever, createVectorRetriever };

package/dist/retriever/interface.d.ts

@@ -0,0 +1,56 @@
+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 @contractspec/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 };
+//# sourceMappingURL=interface.d.ts.map

package/dist/retriever/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","names":[],"sources":["../../src/retriever/interface.ts"],"sourcesContent":[],"mappings":";;;;;;AASA;;;;;AAsBsC,UAtBrB,kBAAA,CAsBqB;EAqBrB;;;;;;;mCAjCJ,mBACR,QAAQ;;;;;;;;;;+BAWkB;;;;;;;;;;;;;;;;;;UAqBd,eAAA"}

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

@@ -0,0 +1,35 @@
+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 };
+//# sourceMappingURL=static-retriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static-retriever.d.ts","names":[],"sources":["../../src/retriever/static-retriever.ts"],"sourcesContent":[],"mappings":";;;;;;;AAMA;AAEW,UAFM,qBAAA,SAA8B,eAEpC,CAAA;EAAsB;EAFc,OAAA,EAEpC,GAFoC,CAAA,MAAA,EAAA,MAAA,CAAA,GAEd,MAFc,CAAA,MAAA,EAAA,MAAA,CAAA;;AAa/C;;;;;;;;AAoDgB,cApDH,eAAA,YAA2B,kBAoDH,CAAA;EAC1B,iBAAA,OAAA;EAAyB,WAAA,CAAA,MAAA,EAlDd,qBAkDc;EACjC,QAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,EA1CU,gBA0CV,CAAA,EAzCE,OAyCF,CAzCU,eAyCV,EAAA,CAAA;EAAe,SAAA,CAAA,QAAA,EAAA,MAAA,CAAA,EAlBmB,OAkBnB,CAAA,MAAA,GAAA,IAAA,CAAA;;;;;;;iBAFF,qBAAA,UACL,yBAAyB,sBACjC"}

package/dist/retriever/static-retriever.js

@@ -0,0 +1,48 @@
+//#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 };
+//# sourceMappingURL=static-retriever.js.map

package/dist/retriever/static-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-retriever.js","names":[],"sources":["../../src/retriever/static-retriever.ts"],"sourcesContent":["import type { RetrievalResult, RetrievalOptions } from '../types';\nimport type { KnowledgeRetriever, RetrieverConfig } from './interface';\n\n/**\n * Configuration for the static retriever.\n */\nexport interface StaticRetrieverConfig extends RetrieverConfig {\n  /** Map of space key to static content */\n  content: Map<string, string> | Record<string, string>;\n}\n\n/**\n * A simple in-memory retriever for static knowledge content.\n *\n * Useful for:\n * - Required knowledge that doesn't need semantic search\n * - Testing and development\n * - Small knowledge bases that fit in memory\n */\nexport class StaticRetriever implements KnowledgeRetriever {\n  private readonly content: Map<string, string>;\n\n  constructor(config: StaticRetrieverConfig) {\n    this.content =\n      config.content instanceof Map\n        ? config.content\n        : new Map(Object.entries(config.content));\n  }\n\n  async retrieve(\n    query: string,\n    options: RetrievalOptions\n  ): Promise<RetrievalResult[]> {\n    const content = this.content.get(options.spaceKey);\n    if (!content) return [];\n\n    // Simple keyword matching for static retriever\n    const queryLower = query.toLowerCase();\n    const lines = content.split('\\n').filter((line) => line.trim());\n\n    const results: RetrievalResult[] = [];\n    for (const line of lines) {\n      if (line.toLowerCase().includes(queryLower)) {\n        results.push({\n          content: line,\n          source: options.spaceKey,\n          score: 1.0,\n          metadata: { type: 'static' },\n        });\n      }\n    }\n\n    return results.slice(0, options.topK ?? 5);\n  }\n\n  async getStatic(spaceKey: string): Promise<string | null> {\n    return this.content.get(spaceKey) ?? null;\n  }\n\n  supportsSpace(spaceKey: string): boolean {\n    return this.content.has(spaceKey);\n  }\n\n  listSpaces(): string[] {\n    return [...this.content.keys()];\n  }\n}\n\n/**\n * Create a static retriever from a content map.\n */\nexport function createStaticRetriever(\n  content: Record<string, string> | Map<string, string>\n): StaticRetriever {\n  return new StaticRetriever({ content });\n}\n"],"mappings":";;;;;;;;;AAmBA,IAAa,kBAAb,MAA2D;CACzD,AAAiB;CAEjB,YAAY,QAA+B;AACzC,OAAK,UACH,OAAO,mBAAmB,MACtB,OAAO,UACP,IAAI,IAAI,OAAO,QAAQ,OAAO,QAAQ,CAAC;;CAG/C,MAAM,SACJ,OACA,SAC4B;EAC5B,MAAM,UAAU,KAAK,QAAQ,IAAI,QAAQ,SAAS;AAClD,MAAI,CAAC,QAAS,QAAO,EAAE;EAGvB,MAAM,aAAa,MAAM,aAAa;EACtC,MAAM,QAAQ,QAAQ,MAAM,KAAK,CAAC,QAAQ,SAAS,KAAK,MAAM,CAAC;EAE/D,MAAM,UAA6B,EAAE;AACrC,OAAK,MAAM,QAAQ,MACjB,KAAI,KAAK,aAAa,CAAC,SAAS,WAAW,CACzC,SAAQ,KAAK;GACX,SAAS;GACT,QAAQ,QAAQ;GAChB,OAAO;GACP,UAAU,EAAE,MAAM,UAAU;GAC7B,CAAC;AAIN,SAAO,QAAQ,MAAM,GAAG,QAAQ,QAAQ,EAAE;;CAG5C,MAAM,UAAU,UAA0C;AACxD,SAAO,KAAK,QAAQ,IAAI,SAAS,IAAI;;CAGvC,cAAc,UAA2B;AACvC,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAGnC,aAAuB;AACrB,SAAO,CAAC,GAAG,KAAK,QAAQ,MAAM,CAAC;;;;;;AAOnC,SAAgB,sBACd,SACiB;AACjB,QAAO,IAAI,gBAAgB,EAAE,SAAS,CAAC"}

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

@@ -0,0 +1,43 @@
+import { RetrievalOptions, RetrievalResult } from "../types.js";
+import { KnowledgeRetriever, RetrieverConfig } from "./interface.js";
+import { EmbeddingProvider, VectorStoreProvider } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=vector-retriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vector-retriever.d.ts","names":[],"sources":["../../src/retriever/vector-retriever.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAUA;AAEc,UAFG,qBAAA,SAA8B,eAEjC,CAAA;EAEC;EAEK,UAAA,EAJN,iBAIM;EAAsB;EAExB,WAAA,EAJH,mBAIG;EAAsB;EARO,gBAAA,EAM3B,GAN2B,CAAA,MAAA,EAAA,MAAA,CAAA,GAML,MANK,CAAA,MAAA,EAAA,MAAA,CAAA;EAAe;EAiBjD,aAAA,CAAA,EATK,GASW,CAAA,MAAA,EAAA,MAAA,CAAA,GATW,MASX,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;;;AA2Eb,cA3EH,eAAA,YAA2B,kBA6ErC,CAAA;;;;sBAxEmB;mCAeT,mBACR,QAAQ;+BA+BwB;;;;;;;;iBAuBrB,qBAAA,SACN,wBACP"}

package/dist/retriever/vector-retriever.js

@@ -0,0 +1,61 @@
+//#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 };
+//# sourceMappingURL=vector-retriever.js.map

package/dist/retriever/vector-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-retriever.js","names":[],"sources":["../../src/retriever/vector-retriever.ts"],"sourcesContent":["import type {\n  EmbeddingProvider,\n  VectorStoreProvider,\n} from '@contractspec/lib.contracts';\nimport type { RetrievalResult, RetrievalOptions } from '../types';\nimport type { KnowledgeRetriever, RetrieverConfig } from './interface';\n\n/**\n * Configuration for the vector retriever.\n */\nexport interface VectorRetrieverConfig extends RetrieverConfig {\n  /** Embedding provider for query vectorization */\n  embeddings: EmbeddingProvider;\n  /** Vector store provider for similarity search */\n  vectorStore: VectorStoreProvider;\n  /** Map of space key to collection name */\n  spaceCollections: Map<string, string> | Record<string, string>;\n  /** Optional static content for getStatic() calls */\n  staticContent?: Map<string, string> | Record<string, string>;\n}\n\n/**\n * A retriever that uses vector similarity search.\n *\n * Uses embedding provider to vectorize queries and vector store\n * provider to perform similarity search.\n */\nexport class VectorRetriever implements KnowledgeRetriever {\n  private readonly config: VectorRetrieverConfig;\n  private readonly spaceCollections: Map<string, string>;\n  private readonly staticContent: Map<string, string>;\n\n  constructor(config: VectorRetrieverConfig) {\n    this.config = config;\n    this.spaceCollections =\n      config.spaceCollections instanceof Map\n        ? config.spaceCollections\n        : new Map(Object.entries(config.spaceCollections));\n    this.staticContent = config.staticContent\n      ? config.staticContent instanceof Map\n        ? config.staticContent\n        : new Map(Object.entries(config.staticContent))\n      : new Map();\n  }\n\n  async retrieve(\n    query: string,\n    options: RetrievalOptions\n  ): Promise<RetrievalResult[]> {\n    const collection = this.spaceCollections.get(options.spaceKey);\n    if (!collection) {\n      return [];\n    }\n\n    // Embed the query\n    const embedding = await this.config.embeddings.embedQuery(query);\n\n    // Search the vector store\n    const results = await this.config.vectorStore.search({\n      collection,\n      vector: embedding.vector,\n      topK: options.topK ?? this.config.defaultTopK ?? 5,\n      namespace: options.tenantId,\n      filter: options.filter,\n    });\n\n    // Filter by minimum score\n    const minScore = options.minScore ?? this.config.defaultMinScore ?? 0;\n    const filtered = results.filter((r) => r.score >= minScore);\n\n    // Map to RetrievalResult\n    return filtered.map((result) => ({\n      content: this.extractContent(result.payload),\n      source: result.id,\n      score: result.score,\n      metadata: result.payload as Record<string, unknown> | undefined,\n    }));\n  }\n\n  async getStatic(spaceKey: string): Promise<string | null> {\n    return this.staticContent.get(spaceKey) ?? null;\n  }\n\n  supportsSpace(spaceKey: string): boolean {\n    return this.spaceCollections.has(spaceKey);\n  }\n\n  listSpaces(): string[] {\n    return [...this.spaceCollections.keys()];\n  }\n\n  private extractContent(payload: Record<string, unknown> | undefined): string {\n    if (!payload) return '';\n    if (typeof payload.text === 'string') return payload.text;\n    if (typeof payload.content === 'string') return payload.content;\n    return JSON.stringify(payload);\n  }\n}\n\n/**\n * Create a vector retriever from configuration.\n */\nexport function createVectorRetriever(\n  config: VectorRetrieverConfig\n): VectorRetriever {\n  return new VectorRetriever(config);\n}\n"],"mappings":";;;;;;;AA2BA,IAAa,kBAAb,MAA2D;CACzD,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,YAAY,QAA+B;AACzC,OAAK,SAAS;AACd,OAAK,mBACH,OAAO,4BAA4B,MAC/B,OAAO,mBACP,IAAI,IAAI,OAAO,QAAQ,OAAO,iBAAiB,CAAC;AACtD,OAAK,gBAAgB,OAAO,gBACxB,OAAO,yBAAyB,MAC9B,OAAO,gBACP,IAAI,IAAI,OAAO,QAAQ,OAAO,cAAc,CAAC,mBAC/C,IAAI,KAAK;;CAGf,MAAM,SACJ,OACA,SAC4B;EAC5B,MAAM,aAAa,KAAK,iBAAiB,IAAI,QAAQ,SAAS;AAC9D,MAAI,CAAC,WACH,QAAO,EAAE;EAIX,MAAM,YAAY,MAAM,KAAK,OAAO,WAAW,WAAW,MAAM;EAGhE,MAAM,UAAU,MAAM,KAAK,OAAO,YAAY,OAAO;GACnD;GACA,QAAQ,UAAU;GAClB,MAAM,QAAQ,QAAQ,KAAK,OAAO,eAAe;GACjD,WAAW,QAAQ;GACnB,QAAQ,QAAQ;GACjB,CAAC;EAGF,MAAM,WAAW,QAAQ,YAAY,KAAK,OAAO,mBAAmB;AAIpE,SAHiB,QAAQ,QAAQ,MAAM,EAAE,SAAS,SAAS,CAG3C,KAAK,YAAY;GAC/B,SAAS,KAAK,eAAe,OAAO,QAAQ;GAC5C,QAAQ,OAAO;GACf,OAAO,OAAO;GACd,UAAU,OAAO;GAClB,EAAE;;CAGL,MAAM,UAAU,UAA0C;AACxD,SAAO,KAAK,cAAc,IAAI,SAAS,IAAI;;CAG7C,cAAc,UAA2B;AACvC,SAAO,KAAK,iBAAiB,IAAI,SAAS;;CAG5C,aAAuB;AACrB,SAAO,CAAC,GAAG,KAAK,iBAAiB,MAAM,CAAC;;CAG1C,AAAQ,eAAe,SAAsD;AAC3E,MAAI,CAAC,QAAS,QAAO;AACrB,MAAI,OAAO,QAAQ,SAAS,SAAU,QAAO,QAAQ;AACrD,MAAI,OAAO,QAAQ,YAAY,SAAU,QAAO,QAAQ;AACxD,SAAO,KAAK,UAAU,QAAQ;;;;;;AAOlC,SAAgB,sBACd,QACiB;AACjB,QAAO,IAAI,gBAAgB,OAAO"}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import { KnowledgeCategory } from "@contractspec/lib.contracts";
+
+//#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 };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAciB,UAdA,eAAA,CAcgB;EAkBhB;EAYA,OAAA,EAAA,MAAA;;;;;;aApCJ;;;;;UAMI,gBAAA;;;;;;;;aAQJ;;;;WAIF;;;;;UAMM,sBAAA;;;;;;;;;;;UAYA,qBAAA"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@contractspec/lib.knowledge",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "RAG and knowledge base primitives",
+  "keywords": [
+    "contractspec",
+    "rag",
+    "knowledge-base",
+    "embeddings",
+    "typescript"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "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": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.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",
+    "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",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/libs/knowledge"
+  },
+  "homepage": "https://contractspec.io"
+}