@contractspec/lib.knowledge 2.3.0 → 2.5.0

package/dist/ingestion/gmail-adapter.js

@@ -1,15 +1,287 @@
 // @bun
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'Knowledge space "{spaceKey}" is not bound in the resolved app config.',
+      description: "Denial reason when a knowledge space is not bound",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "access.readOnly": {
+      value: 'Knowledge space "{spaceKey}" is category "{category}" and is read-only.',
+      description: "Denial reason when write is attempted on a read-only space",
+      placeholders: [
+        { name: "spaceKey", type: "string" },
+        { name: "category", type: "string" }
+      ]
+    },
+    "access.workflowUnauthorized": {
+      value: 'Workflow "{workflowName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access",
+      placeholders: [
+        { name: "workflowName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.agentUnauthorized": {
+      value: 'Agent "{agentName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access",
+      placeholders: [
+        { name: "agentName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.ephemeralWarning": {
+      value: 'Knowledge space "{spaceKey}" is ephemeral; results may be transient.',
+      description: "Warning for ephemeral knowledge spaces",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "query.systemPrompt": {
+      value: "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question:
+{question}
+
+Context:
+{context}`,
+      description: "User message template combining question and context",
+      placeholders: [
+        { name: "question", type: "string" },
+        { name: "context", type: "string" }
+      ]
+    },
+    "query.noResults": {
+      value: "No relevant documents found.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score: {score}):",
+      description: "Label prefix for each source in the context block",
+      placeholders: [
+        { name: "index", type: "number" },
+        { name: "score", type: "string" }
+      ]
+    },
+    "ingestion.gmail.subject": {
+      value: "Subject: {subject}",
+      description: "Gmail thread subject label",
+      placeholders: [{ name: "subject", type: "string" }]
+    },
+    "ingestion.gmail.snippet": {
+      value: "Snippet: {snippet}",
+      description: "Gmail thread snippet label",
+      placeholders: [{ name: "snippet", type: "string" }]
+    },
+    "ingestion.gmail.from": {
+      value: "From: {from}",
+      description: "Gmail message sender label",
+      placeholders: [{ name: "from", type: "string" }]
+    },
+    "ingestion.gmail.to": {
+      value: "To: {to}",
+      description: "Gmail message recipients label",
+      placeholders: [{ name: "to", type: "string" }]
+    },
+    "ingestion.gmail.date": {
+      value: "Date: {date}",
+      description: "Gmail message date label",
+      placeholders: [{ name: "date", type: "string" }]
+    }
+  }
+});
+
+// src/i18n/catalogs/fr.ts
+import { defineTranslation as defineTranslation2 } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation2({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (French)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: `L'espace de connaissances "{spaceKey}" n'est pas li\xE9 dans la configuration de l'application.`,
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: `L'espace de connaissances "{spaceKey}" est de cat\xE9gorie "{category}" et est en lecture seule.`,
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: `Le workflow "{workflowName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: `L'agent "{agentName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: `L'espace de connaissances "{spaceKey}" est \xE9ph\xE9m\xE8re ; les r\xE9sultats peuvent \xEAtre transitoires.`,
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Vous \xEAtes un assistant de connaissances qui r\xE9pond aux questions en utilisant le contexte fourni. Citez les sources pertinentes si possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question :
+{question}
+
+Contexte :
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "Aucun document pertinent trouv\xE9.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score : {score}) :",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Objet : {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extrait : {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De : {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "\xC0 : {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Date : {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/catalogs/es.ts
+import { defineTranslation as defineTranslation3 } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation3({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (Spanish)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'El espacio de conocimiento "{spaceKey}" no est\xE1 vinculado en la configuraci\xF3n de la aplicaci\xF3n.',
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: 'El espacio de conocimiento "{spaceKey}" es de categor\xEDa "{category}" y es de solo lectura.',
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: 'El flujo de trabajo "{workflowName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: 'El agente "{agentName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: 'El espacio de conocimiento "{spaceKey}" es ef\xEDmero; los resultados pueden ser transitorios.',
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Eres un asistente de conocimiento que responde preguntas utilizando el contexto proporcionado. Cita las fuentes relevantes si es posible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Pregunta:
+{question}
+
+Contexto:
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "No se encontraron documentos relevantes.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Fuente {index} (puntuaci\xF3n: {score}):",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Asunto: {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extracto: {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De: {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "Para: {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Fecha: {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/messages.ts
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory = createI18nFactory({
+  specKey: "knowledge.messages",
+  catalogs: [enMessages, frMessages, esMessages]
+});
+var createKnowledgeI18n = factory.create;
+var getDefaultI18n = factory.getDefault;
+var resetI18nRegistry = factory.resetRegistry;
+
 // src/ingestion/gmail-adapter.ts
 class GmailIngestionAdapter {
   gmail;
   processor;
   embeddings;
   indexer;
-  constructor(gmail, processor, embeddings, indexer) {
+  i18n;
+  constructor(gmail, processor, embeddings, indexer, locale) {
     this.gmail = gmail;
     this.processor = processor;
     this.embeddings = embeddings;
     this.indexer = indexer;
+    this.i18n = locale ? createKnowledgeI18n(locale) : getDefaultI18n();
   }
   async syncThreads(query) {
     const threads = await this.gmail.listThreads(query);
@@ -24,7 +296,7 @@ class GmailIngestionAdapter {
     await this.indexer.upsert(fragments, embeddings);
   }
   toRawDocument(thread) {
-    const content = composeThreadText(thread);
+    const content = composeThreadText(thread, this.i18n);
     return {
       id: thread.id,
       mimeType: "text/plain",
@@ -37,18 +309,22 @@ class GmailIngestionAdapter {
     };
   }
 }
-function composeThreadText(thread) {
+function composeThreadText(thread, i18n) {
   const header = [
-    `Subject: ${thread.subject ?? ""}`,
-    `Snippet: ${thread.snippet ?? ""}`
+    i18n.t("ingestion.gmail.subject", { subject: thread.subject ?? "" }),
+    i18n.t("ingestion.gmail.snippet", { snippet: thread.snippet ?? "" })
   ];
   const messageTexts = thread.messages.map((message) => {
     const parts = [
-      `From: ${formatAddress(message.from)}`,
-      `To: ${message.to.map(formatAddress).join(", ")}`
+      i18n.t("ingestion.gmail.from", { from: formatAddress(message.from) }),
+      i18n.t("ingestion.gmail.to", {
+        to: message.to.map(formatAddress).join(", ")
+      })
     ];
     if (message.sentAt) {
-      parts.push(`Date: ${message.sentAt.toISOString()}`);
+      parts.push(i18n.t("ingestion.gmail.date", {
+        date: message.sentAt.toISOString()
+      }));
     }
     const body = message.textBody ?? stripHtml(message.htmlBody ?? "");
     return `${parts.join(`

package/dist/ingestion/index.js

@@ -1,4 +1,274 @@
 // @bun
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'Knowledge space "{spaceKey}" is not bound in the resolved app config.',
+      description: "Denial reason when a knowledge space is not bound",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "access.readOnly": {
+      value: 'Knowledge space "{spaceKey}" is category "{category}" and is read-only.',
+      description: "Denial reason when write is attempted on a read-only space",
+      placeholders: [
+        { name: "spaceKey", type: "string" },
+        { name: "category", type: "string" }
+      ]
+    },
+    "access.workflowUnauthorized": {
+      value: 'Workflow "{workflowName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access",
+      placeholders: [
+        { name: "workflowName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.agentUnauthorized": {
+      value: 'Agent "{agentName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access",
+      placeholders: [
+        { name: "agentName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.ephemeralWarning": {
+      value: 'Knowledge space "{spaceKey}" is ephemeral; results may be transient.',
+      description: "Warning for ephemeral knowledge spaces",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "query.systemPrompt": {
+      value: "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question:
+{question}
+
+Context:
+{context}`,
+      description: "User message template combining question and context",
+      placeholders: [
+        { name: "question", type: "string" },
+        { name: "context", type: "string" }
+      ]
+    },
+    "query.noResults": {
+      value: "No relevant documents found.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score: {score}):",
+      description: "Label prefix for each source in the context block",
+      placeholders: [
+        { name: "index", type: "number" },
+        { name: "score", type: "string" }
+      ]
+    },
+    "ingestion.gmail.subject": {
+      value: "Subject: {subject}",
+      description: "Gmail thread subject label",
+      placeholders: [{ name: "subject", type: "string" }]
+    },
+    "ingestion.gmail.snippet": {
+      value: "Snippet: {snippet}",
+      description: "Gmail thread snippet label",
+      placeholders: [{ name: "snippet", type: "string" }]
+    },
+    "ingestion.gmail.from": {
+      value: "From: {from}",
+      description: "Gmail message sender label",
+      placeholders: [{ name: "from", type: "string" }]
+    },
+    "ingestion.gmail.to": {
+      value: "To: {to}",
+      description: "Gmail message recipients label",
+      placeholders: [{ name: "to", type: "string" }]
+    },
+    "ingestion.gmail.date": {
+      value: "Date: {date}",
+      description: "Gmail message date label",
+      placeholders: [{ name: "date", type: "string" }]
+    }
+  }
+});
+
+// src/i18n/catalogs/fr.ts
+import { defineTranslation as defineTranslation2 } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation2({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (French)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: `L'espace de connaissances "{spaceKey}" n'est pas li\xE9 dans la configuration de l'application.`,
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: `L'espace de connaissances "{spaceKey}" est de cat\xE9gorie "{category}" et est en lecture seule.`,
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: `Le workflow "{workflowName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: `L'agent "{agentName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: `L'espace de connaissances "{spaceKey}" est \xE9ph\xE9m\xE8re ; les r\xE9sultats peuvent \xEAtre transitoires.`,
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Vous \xEAtes un assistant de connaissances qui r\xE9pond aux questions en utilisant le contexte fourni. Citez les sources pertinentes si possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question :
+{question}
+
+Contexte :
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "Aucun document pertinent trouv\xE9.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score : {score}) :",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Objet : {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extrait : {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De : {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "\xC0 : {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Date : {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/catalogs/es.ts
+import { defineTranslation as defineTranslation3 } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation3({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (Spanish)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'El espacio de conocimiento "{spaceKey}" no est\xE1 vinculado en la configuraci\xF3n de la aplicaci\xF3n.',
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: 'El espacio de conocimiento "{spaceKey}" es de categor\xEDa "{category}" y es de solo lectura.',
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: 'El flujo de trabajo "{workflowName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: 'El agente "{agentName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: 'El espacio de conocimiento "{spaceKey}" es ef\xEDmero; los resultados pueden ser transitorios.',
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Eres un asistente de conocimiento que responde preguntas utilizando el contexto proporcionado. Cita las fuentes relevantes si es posible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Pregunta:
+{question}
+
+Contexto:
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "No se encontraron documentos relevantes.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Fuente {index} (puntuaci\xF3n: {score}):",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Asunto: {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extracto: {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De: {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "Para: {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Fecha: {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/messages.ts
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory = createI18nFactory({
+  specKey: "knowledge.messages",
+  catalogs: [enMessages, frMessages, esMessages]
+});
+var createKnowledgeI18n = factory.create;
+var getDefaultI18n = factory.getDefault;
+var resetI18nRegistry = factory.resetRegistry;
+
 // src/ingestion/document-processor.ts
 import { Buffer as Buffer2 } from "buffer";
 
@@ -121,11 +391,13 @@ class GmailIngestionAdapter {
   processor;
   embeddings;
   indexer;
-  constructor(gmail, processor, embeddings, indexer) {
+  i18n;
+  constructor(gmail, processor, embeddings, indexer, locale) {
     this.gmail = gmail;
     this.processor = processor;
     this.embeddings = embeddings;
     this.indexer = indexer;
+    this.i18n = locale ? createKnowledgeI18n(locale) : getDefaultI18n();
   }
   async syncThreads(query) {
     const threads = await this.gmail.listThreads(query);
@@ -140,7 +412,7 @@ class GmailIngestionAdapter {
     await this.indexer.upsert(fragments, embeddings);
   }
   toRawDocument(thread) {
-    const content = composeThreadText(thread);
+    const content = composeThreadText(thread, this.i18n);
     return {
       id: thread.id,
       mimeType: "text/plain",
@@ -153,18 +425,22 @@ class GmailIngestionAdapter {
     };
   }
 }
-function composeThreadText(thread) {
+function composeThreadText(thread, i18n) {
   const header = [
-    `Subject: ${thread.subject ?? ""}`,
-    `Snippet: ${thread.snippet ?? ""}`
+    i18n.t("ingestion.gmail.subject", { subject: thread.subject ?? "" }),
+    i18n.t("ingestion.gmail.snippet", { snippet: thread.snippet ?? "" })
   ];
   const messageTexts = thread.messages.map((message) => {
     const parts = [
-      `From: ${formatAddress(message.from)}`,
-      `To: ${message.to.map(formatAddress).join(", ")}`
+      i18n.t("ingestion.gmail.from", { from: formatAddress(message.from) }),
+      i18n.t("ingestion.gmail.to", {
+        to: message.to.map(formatAddress).join(", ")
+      })
     ];
     if (message.sentAt) {
-      parts.push(`Date: ${message.sentAt.toISOString()}`);
+      parts.push(i18n.t("ingestion.gmail.date", {
+        date: message.sentAt.toISOString()
+      }));
     }
     const body = message.textBody ?? stripHtml(message.htmlBody ?? "");
     return `${parts.join(`