@stackfactor/agent-utils 1.9.0 → 1.11.0

package/dist/esm/stackfactorKnowledge.js

@@ -18,7 +18,9 @@
 //     generates without it.
 //
 // A reference points at the content and never copies it: the passage is
-// searched again, under the reader's own access, whenever it is used. It is
+// searched again, under the reader's own access, whenever it is used. Its
+// `url` is the document's page at its source (GitHub, Confluence…), when the
+// platform knows it, so a person can open what was cited. It is
 // EDIT-only (`visibility: "EDIT"`): the platform strips it from what is
 // published, so a knowledge base's titles never reach a learner; agents read
 // it from the draft.
@@ -45,6 +47,8 @@ const CONCURRENCY = 4;
 /** Statuses that mean the person may not read the knowledge base, or it is gone. */
 const NO_ACCESS = new Set([401, 403, 404]);
 const text = (value) => (typeof value === "string" ? value.trim() : "");
+/** An http(s) address, or null: a reference's url lands in an `href`. */
+const webUrl = (value) => (/^https?:\/\//i.test(text(value)) ? text(value) : null);
 const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
 /**
  * The knowledge bases, and the documents in them, that a list of references
@@ -195,6 +199,7 @@ export const retrievePassages = async (options) => {
         chunkId,
         documentId: id(chunk.documentId),
         documentName: text(chunk.documentName) || null,
+        documentUrl: webUrl(chunk.documentUrl),
         knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
         pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
         score: typeof chunk.score === "number" ? chunk.score : null,
@@ -222,7 +227,8 @@ export const passagesForPrompt = (passages) => (Array.isArray(passages) ? passag
 /**
  * STACKFACTOR references for passages: one per passage, in their order, with no
  * cap. With `tags`, only the passages the model cited by tag (any tag it made
- * up is passed over); without, every passage.
+ * up is passed over); without, every passage. Each links to its document's
+ * page at the source (`url`) when the passage has one.
  * @param passages From `retrievePassages`
  * @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
  * @returns The references, ready for a skill's, a microskill's or a question's `references`
@@ -234,24 +240,28 @@ export const referencesFor = (passages, tags) => {
         : null;
     return list
         .filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
-        .map((passage) => ({
-        description: passage.sectionTitle,
-        kind: STACKFACTOR_REFERENCE.KIND,
-        knowledgeBase: {
-            chunkId: passage.chunkId,
-            documentId: passage.documentId,
-            knowledgeBaseId: passage.knowledgeBaseId,
-            sectionTitle: passage.sectionTitle,
-        },
-        origin: STACKFACTOR_REFERENCE.ORIGIN,
-        target: {
-            elementId: passage.documentId,
-            elementType: STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
-            parentId: passage.knowledgeBaseId,
-        },
-        title: passage.documentName || passage.sectionTitle || "Knowledge base document",
-        visibility: STACKFACTOR_REFERENCE.VISIBILITY,
-    }));
+        .map((passage) => {
+        const url = webUrl(passage.documentUrl);
+        return {
+            description: passage.sectionTitle,
+            kind: STACKFACTOR_REFERENCE.KIND,
+            knowledgeBase: {
+                chunkId: passage.chunkId,
+                documentId: passage.documentId,
+                knowledgeBaseId: passage.knowledgeBaseId,
+                sectionTitle: passage.sectionTitle,
+            },
+            origin: STACKFACTOR_REFERENCE.ORIGIN,
+            target: {
+                elementId: passage.documentId,
+                elementType: STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
+                parentId: passage.knowledgeBaseId,
+            },
+            title: passage.documentName || passage.sectionTitle || "Knowledge base document",
+            ...(url ? { url } : {}),
+            visibility: STACKFACTOR_REFERENCE.VISIBILITY,
+        };
+    });
 };
 export default {
     DEFAULT_TOP_K,

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",