@contractspec/lib.contracts 0.0.0-canary-20260113162409

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

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

@@ -0,0 +1,54 @@
+import { Buffer } from "node:buffer";
+
+//#region src/knowledge/ingestion/document-processor.ts
+var DocumentProcessor = class {
+	extractors = /* @__PURE__ */ new Map();
+	constructor() {
+		this.registerExtractor("text/plain", this.extractText);
+		this.registerExtractor("application/json", this.extractJson);
+	}
+	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 };

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

@@ -0,0 +1,12 @@
+import { EmbeddingProvider, EmbeddingResult } from "../../integrations/providers/embedding.js";
+import { DocumentFragment } from "./document-processor.js";
+
+//#region src/knowledge/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/knowledge/ingestion/embedding-service.js

@@ -0,0 +1,25 @@
+//#region src/knowledge/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 };

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

@@ -0,0 +1,18 @@
+import { EmailInboundProvider, EmailThread } from "../../integrations/providers/email.js";
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { VectorIndexer } from "./vector-indexer.js";
+
+//#region src/knowledge/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/knowledge/ingestion/gmail-adapter.js

@@ -0,0 +1,51 @@
+//#region src/knowledge/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 };

package/dist/knowledge/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/knowledge/ingestion/index.js

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

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

@@ -0,0 +1,15 @@
+import { GetObjectResult } from "../../integrations/providers/storage.js";
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { VectorIndexer } from "./vector-indexer.js";
+
+//#region src/knowledge/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/knowledge/ingestion/storage-adapter.js

@@ -0,0 +1,26 @@
+//#region src/knowledge/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 };

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

@@ -0,0 +1,18 @@
+import { EmbeddingResult } from "../../integrations/providers/embedding.js";
+import { VectorStoreProvider } from "../../integrations/providers/vector-store.js";
+import { DocumentFragment } from "./document-processor.js";
+
+//#region src/knowledge/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/knowledge/ingestion/vector-indexer.js

@@ -0,0 +1,32 @@
+//#region src/knowledge/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 };

package/dist/knowledge/knowledge.capability.d.ts

@@ -0,0 +1,7 @@
+import { CapabilitySpec } from "../capabilities/capabilities.js";
+import "../index.js";
+
+//#region src/knowledge/knowledge.capability.d.ts
+declare const KnowledgeCapability: CapabilitySpec;
+//#endregion
+export { KnowledgeCapability };

package/dist/knowledge/knowledge.capability.js

@@ -0,0 +1,21 @@
+import { defineCapability } from "../capabilities/capabilities.js";
+import { StabilityEnum } from "../ownership.js";
+import "../capabilities/index.js";
+
+//#region src/knowledge/knowledge.capability.ts
+const KnowledgeCapability = defineCapability({ meta: {
+	key: "knowledge",
+	version: "1.0.0",
+	kind: "data",
+	stability: StabilityEnum.Experimental,
+	description: "Knowledge base and content management capability",
+	owners: ["@platform.content"],
+	tags: [
+		"knowledge",
+		"content",
+		"data"
+	]
+} });
+
+//#endregion
+export { KnowledgeCapability };

package/dist/knowledge/knowledge.feature.d.ts

@@ -0,0 +1,11 @@
+import { FeatureModuleSpec } from "../features/types.js";
+import "../index.js";
+
+//#region src/knowledge/knowledge.feature.d.ts
+/**
+ * Knowledge Sources feature module that bundles
+ * knowledge source management capabilities.
+ */
+declare const KnowledgeFeature: FeatureModuleSpec;
+//#endregion
+export { KnowledgeFeature };

package/dist/knowledge/knowledge.feature.js

@@ -0,0 +1,68 @@
+import { defineFeature } from "../features/index.js";
+
+//#region src/knowledge/knowledge.feature.ts
+/**
+* Knowledge Sources Feature Module Specification
+*
+* Defines the feature module for managing knowledge sources.
+*/
+/**
+* Knowledge Sources feature module that bundles
+* knowledge source management capabilities.
+*/
+const KnowledgeFeature = defineFeature({
+	meta: {
+		key: "platform.knowledge",
+		version: "1.0.0",
+		title: "Knowledge Sources",
+		description: "Manage knowledge source bindings for ingestion (e.g., Notion, uploads)",
+		domain: "platform",
+		owners: ["@platform.knowledge"],
+		tags: [
+			"knowledge",
+			"sources",
+			"platform",
+			"ingestion"
+		],
+		stability: "experimental"
+	},
+	operations: [
+		{
+			key: "knowledge.source.create",
+			version: "1.0.0"
+		},
+		{
+			key: "knowledge.source.update",
+			version: "1.0.0"
+		},
+		{
+			key: "knowledge.source.delete",
+			version: "1.0.0"
+		},
+		{
+			key: "knowledge.source.list",
+			version: "1.0.0"
+		},
+		{
+			key: "knowledge.source.triggerSync",
+			version: "1.0.0"
+		}
+	],
+	events: [],
+	presentations: [],
+	opToPresentation: [],
+	presentationsTargets: [],
+	capabilities: {
+		provides: [{
+			key: "knowledge",
+			version: "1.0.0"
+		}],
+		requires: [{
+			key: "identity",
+			version: "1.0.0"
+		}]
+	}
+});
+
+//#endregion
+export { KnowledgeFeature };