@contractspec/lib.knowledge 2.3.0 → 2.5.0

package/dist/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/access/guard.ts
 var DEFAULT_DISALLOWED_WRITE = ["external", "ephemeral"];
 
@@ -6,23 +276,30 @@ class KnowledgeAccessGuard {
   disallowedWrite;
   requireWorkflowBinding;
   requireAgentBinding;
+  i18n;
   constructor(options = {}) {
     this.disallowedWrite = new Set(options.disallowWriteCategories ?? DEFAULT_DISALLOWED_WRITE);
     this.requireWorkflowBinding = options.requireWorkflowBinding ?? true;
     this.requireAgentBinding = options.requireAgentBinding ?? false;
+    this.i18n = options.locale ? createKnowledgeI18n(options.locale) : getDefaultI18n();
   }
   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.`
+        reason: this.i18n.t("access.notBound", {
+          spaceKey: space.meta.key
+        })
       };
     }
     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.`
+        reason: this.i18n.t("access.readOnly", {
+          spaceKey: space.meta.key,
+          category: space.meta.category
+        })
       };
     }
     if (this.requireWorkflowBinding && context.workflowName) {
@@ -30,7 +307,10 @@ class KnowledgeAccessGuard {
       if (allowedWorkflows && !allowedWorkflows.includes(context.workflowName)) {
         return {
           allowed: false,
-          reason: `Workflow "${context.workflowName}" is not authorized to access knowledge space "${space.meta.key}".`
+          reason: this.i18n.t("access.workflowUnauthorized", {
+            workflowName: context.workflowName,
+            spaceKey: space.meta.key
+          })
         };
       }
     }
@@ -39,7 +319,10 @@ class KnowledgeAccessGuard {
       if (allowedAgents && !allowedAgents.includes(context.agentName)) {
         return {
           allowed: false,
-          reason: `Agent "${context.agentName}" is not authorized to access knowledge space "${space.meta.key}".`
+          reason: this.i18n.t("access.agentUnauthorized", {
+            agentName: context.agentName,
+            spaceKey: space.meta.key
+          })
         };
       }
     }
@@ -47,7 +330,9 @@ class KnowledgeAccessGuard {
       return {
         allowed: true,
         severity: "warning",
-        reason: `Knowledge space "${space.meta.key}" is ephemeral; results may be transient.`
+        reason: this.i18n.t("access.ephemeralWarning", {
+          spaceKey: space.meta.key
+        })
       };
     }
     return { allowed: true };
@@ -156,11 +441,13 @@ class KnowledgeQueryService {
   vectorStore;
   llm;
   config;
+  i18n;
   constructor(embeddings, vectorStore, llm, config) {
     this.embeddings = embeddings;
     this.vectorStore = vectorStore;
     this.llm = llm;
     this.config = config;
+    this.i18n = config.locale ? createKnowledgeI18n(config.locale) : getDefaultI18n();
   }
   async query(question) {
     const embedding = await this.embeddings.embedQuery(question);
@@ -171,7 +458,7 @@ class KnowledgeQueryService {
       namespace: this.config.namespace,
       filter: undefined
     });
-    const context = buildContext(results);
+    const context = buildContext(results, this.i18n);
     const messages = this.buildMessages(question, context);
     const response = await this.llm.chat(messages);
     return {
@@ -184,7 +471,7 @@ class KnowledgeQueryService {
     };
   }
   buildMessages(question, context) {
-    const systemPrompt = this.config.systemPrompt ?? "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.";
+    const systemPrompt = this.config.systemPrompt ?? this.i18n.t("query.systemPrompt");
     return [
       {
         role: "system",
@@ -195,24 +482,24 @@ class KnowledgeQueryService {
         content: [
           {
             type: "text",
-            text: `Question:
-${question}
-
-Context:
-${context}`
+            text: this.i18n.t("query.userMessage", { question, context })
           }
         ]
       }
     ];
   }
 }
-function buildContext(results) {
+function buildContext(results, i18n) {
   if (results.length === 0) {
-    return "No relevant documents found.";
+    return i18n.t("query.noResults");
   }
   return results.map((result, index) => {
     const text = extractText(result);
-    return `Source ${index + 1} (score: ${result.score.toFixed(3)}):
+    const label = i18n.t("query.sourceLabel", {
+      index: index + 1,
+      score: result.score.toFixed(3)
+    });
+    return `${label}
 ${text}`;
   }).join(`
 
@@ -348,11 +635,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);
@@ -367,7 +656,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",
@@ -380,18 +669,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/gmail-adapter.d.ts

@@ -7,7 +7,8 @@ export declare class GmailIngestionAdapter {
     private readonly processor;
     private readonly embeddings;
     private readonly indexer;
-    constructor(gmail: EmailInboundProvider, processor: DocumentProcessor, embeddings: EmbeddingService, indexer: VectorIndexer);
+    private readonly i18n;
+    constructor(gmail: EmailInboundProvider, processor: DocumentProcessor, embeddings: EmbeddingService, indexer: VectorIndexer, locale?: string);
     syncThreads(query?: Parameters<EmailInboundProvider['listThreads']>[0]): Promise<void>;
     ingestThread(thread: EmailThread): Promise<void>;
     private toRawDocument;