@stackfactor/agent-utils 1.9.0 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/stackfactorKnowledge.d.ts +8 -1
- package/dist/cjs/stackfactorKnowledge.d.ts.map +1 -1
- package/dist/cjs/stackfactorKnowledge.js +30 -20
- package/dist/esm/stackfactorKnowledge.d.ts +8 -1
- package/dist/esm/stackfactorKnowledge.d.ts.map +1 -1
- package/dist/esm/stackfactorKnowledge.js +30 -20
- package/package.json +1 -1
|
@@ -17,6 +17,8 @@ export interface KnowledgeChunk {
|
|
|
17
17
|
knowledgeBaseId?: string;
|
|
18
18
|
documentId: string;
|
|
19
19
|
documentName?: string | null;
|
|
20
|
+
/** The document's page at its source (sent by the platform's search since backend-core #630). */
|
|
21
|
+
documentUrl?: string | null;
|
|
20
22
|
sectionTitle?: string | null;
|
|
21
23
|
pageNumber?: number | null;
|
|
22
24
|
text?: string;
|
|
@@ -48,6 +50,8 @@ export interface GroundingPassage {
|
|
|
48
50
|
knowledgeBaseId: string;
|
|
49
51
|
documentId: string;
|
|
50
52
|
documentName: string | null;
|
|
53
|
+
/** The document's page at its source, an http(s) address; null when the platform has none. */
|
|
54
|
+
documentUrl?: string | null;
|
|
51
55
|
sectionTitle: string | null;
|
|
52
56
|
pageNumber: number | null;
|
|
53
57
|
text: string;
|
|
@@ -72,6 +76,8 @@ export interface StackFactorReference {
|
|
|
72
76
|
kind: "STACKFACTOR";
|
|
73
77
|
title: string;
|
|
74
78
|
description: string | null;
|
|
79
|
+
/** The document's page at its source; absent when the platform has none. */
|
|
80
|
+
url?: string;
|
|
75
81
|
target: {
|
|
76
82
|
elementType: "KNOWLEDGE_BASE_DOCUMENT";
|
|
77
83
|
elementId: string;
|
|
@@ -142,7 +148,8 @@ export declare const passagesForPrompt: (passages: GroundingPassage[]) => {
|
|
|
142
148
|
/**
|
|
143
149
|
* STACKFACTOR references for passages: one per passage, in their order, with no
|
|
144
150
|
* cap. With `tags`, only the passages the model cited by tag (any tag it made
|
|
145
|
-
* up is passed over); without, every passage.
|
|
151
|
+
* up is passed over); without, every passage. Each links to its document's
|
|
152
|
+
* page at the source (`url`) when the passage has one.
|
|
146
153
|
* @param passages From `retrievePassages`
|
|
147
154
|
* @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
|
|
148
155
|
* @returns The references, ready for a skill's, a microskill's or a question's `references`
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"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"}
|
|
@@ -19,7 +19,9 @@
|
|
|
19
19
|
// generates without it.
|
|
20
20
|
//
|
|
21
21
|
// A reference points at the content and never copies it: the passage is
|
|
22
|
-
// searched again, under the reader's own access, whenever it is used.
|
|
22
|
+
// searched again, under the reader's own access, whenever it is used. Its
|
|
23
|
+
// `url` is the document's page at its source (GitHub, Confluence…), when the
|
|
24
|
+
// platform knows it, so a person can open what was cited. It is
|
|
23
25
|
// EDIT-only (`visibility: "EDIT"`): the platform strips it from what is
|
|
24
26
|
// published, so a knowledge base's titles never reach a learner; agents read
|
|
25
27
|
// it from the draft.
|
|
@@ -48,6 +50,8 @@ const CONCURRENCY = 4;
|
|
|
48
50
|
/** Statuses that mean the person may not read the knowledge base, or it is gone. */
|
|
49
51
|
const NO_ACCESS = new Set([401, 403, 404]);
|
|
50
52
|
const text = (value) => (typeof value === "string" ? value.trim() : "");
|
|
53
|
+
/** An http(s) address, or null: a reference's url lands in an `href`. */
|
|
54
|
+
const webUrl = (value) => (/^https?:\/\//i.test(text(value)) ? text(value) : null);
|
|
51
55
|
const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
|
|
52
56
|
/**
|
|
53
57
|
* The knowledge bases, and the documents in them, that a list of references
|
|
@@ -200,6 +204,7 @@ const retrievePassages = async (options) => {
|
|
|
200
204
|
chunkId,
|
|
201
205
|
documentId: id(chunk.documentId),
|
|
202
206
|
documentName: text(chunk.documentName) || null,
|
|
207
|
+
documentUrl: webUrl(chunk.documentUrl),
|
|
203
208
|
knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
|
|
204
209
|
pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
|
|
205
210
|
score: typeof chunk.score === "number" ? chunk.score : null,
|
|
@@ -229,7 +234,8 @@ exports.passagesForPrompt = passagesForPrompt;
|
|
|
229
234
|
/**
|
|
230
235
|
* STACKFACTOR references for passages: one per passage, in their order, with no
|
|
231
236
|
* cap. With `tags`, only the passages the model cited by tag (any tag it made
|
|
232
|
-
* up is passed over); without, every passage.
|
|
237
|
+
* up is passed over); without, every passage. Each links to its document's
|
|
238
|
+
* page at the source (`url`) when the passage has one.
|
|
233
239
|
* @param passages From `retrievePassages`
|
|
234
240
|
* @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
|
|
235
241
|
* @returns The references, ready for a skill's, a microskill's or a question's `references`
|
|
@@ -241,24 +247,28 @@ const referencesFor = (passages, tags) => {
|
|
|
241
247
|
: null;
|
|
242
248
|
return list
|
|
243
249
|
.filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
|
|
244
|
-
.map((passage) =>
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
250
|
+
.map((passage) => {
|
|
251
|
+
const url = webUrl(passage.documentUrl);
|
|
252
|
+
return {
|
|
253
|
+
description: passage.sectionTitle,
|
|
254
|
+
kind: exports.STACKFACTOR_REFERENCE.KIND,
|
|
255
|
+
knowledgeBase: {
|
|
256
|
+
chunkId: passage.chunkId,
|
|
257
|
+
documentId: passage.documentId,
|
|
258
|
+
knowledgeBaseId: passage.knowledgeBaseId,
|
|
259
|
+
sectionTitle: passage.sectionTitle,
|
|
260
|
+
},
|
|
261
|
+
origin: exports.STACKFACTOR_REFERENCE.ORIGIN,
|
|
262
|
+
target: {
|
|
263
|
+
elementId: passage.documentId,
|
|
264
|
+
elementType: exports.STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
|
|
265
|
+
parentId: passage.knowledgeBaseId,
|
|
266
|
+
},
|
|
267
|
+
title: passage.documentName || passage.sectionTitle || "Knowledge base document",
|
|
268
|
+
...(url ? { url } : {}),
|
|
269
|
+
visibility: exports.STACKFACTOR_REFERENCE.VISIBILITY,
|
|
270
|
+
};
|
|
271
|
+
});
|
|
262
272
|
};
|
|
263
273
|
exports.referencesFor = referencesFor;
|
|
264
274
|
exports.default = {
|
|
@@ -17,6 +17,8 @@ export interface KnowledgeChunk {
|
|
|
17
17
|
knowledgeBaseId?: string;
|
|
18
18
|
documentId: string;
|
|
19
19
|
documentName?: string | null;
|
|
20
|
+
/** The document's page at its source (sent by the platform's search since backend-core #630). */
|
|
21
|
+
documentUrl?: string | null;
|
|
20
22
|
sectionTitle?: string | null;
|
|
21
23
|
pageNumber?: number | null;
|
|
22
24
|
text?: string;
|
|
@@ -48,6 +50,8 @@ export interface GroundingPassage {
|
|
|
48
50
|
knowledgeBaseId: string;
|
|
49
51
|
documentId: string;
|
|
50
52
|
documentName: string | null;
|
|
53
|
+
/** The document's page at its source, an http(s) address; null when the platform has none. */
|
|
54
|
+
documentUrl?: string | null;
|
|
51
55
|
sectionTitle: string | null;
|
|
52
56
|
pageNumber: number | null;
|
|
53
57
|
text: string;
|
|
@@ -72,6 +76,8 @@ export interface StackFactorReference {
|
|
|
72
76
|
kind: "STACKFACTOR";
|
|
73
77
|
title: string;
|
|
74
78
|
description: string | null;
|
|
79
|
+
/** The document's page at its source; absent when the platform has none. */
|
|
80
|
+
url?: string;
|
|
75
81
|
target: {
|
|
76
82
|
elementType: "KNOWLEDGE_BASE_DOCUMENT";
|
|
77
83
|
elementId: string;
|
|
@@ -142,7 +148,8 @@ export declare const passagesForPrompt: (passages: GroundingPassage[]) => {
|
|
|
142
148
|
/**
|
|
143
149
|
* STACKFACTOR references for passages: one per passage, in their order, with no
|
|
144
150
|
* cap. With `tags`, only the passages the model cited by tag (any tag it made
|
|
145
|
-
* up is passed over); without, every passage.
|
|
151
|
+
* up is passed over); without, every passage. Each links to its document's
|
|
152
|
+
* page at the source (`url`) when the passage has one.
|
|
146
153
|
* @param passages From `retrievePassages`
|
|
147
154
|
* @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
|
|
148
155
|
* @returns The references, ready for a skill's, a microskill's or a question's `references`
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"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"}
|
|
@@ -18,7 +18,9 @@
|
|
|
18
18
|
// generates without it.
|
|
19
19
|
//
|
|
20
20
|
// A reference points at the content and never copies it: the passage is
|
|
21
|
-
// searched again, under the reader's own access, whenever it is used.
|
|
21
|
+
// searched again, under the reader's own access, whenever it is used. Its
|
|
22
|
+
// `url` is the document's page at its source (GitHub, Confluence…), when the
|
|
23
|
+
// platform knows it, so a person can open what was cited. It is
|
|
22
24
|
// EDIT-only (`visibility: "EDIT"`): the platform strips it from what is
|
|
23
25
|
// published, so a knowledge base's titles never reach a learner; agents read
|
|
24
26
|
// it from the draft.
|
|
@@ -45,6 +47,8 @@ const CONCURRENCY = 4;
|
|
|
45
47
|
/** Statuses that mean the person may not read the knowledge base, or it is gone. */
|
|
46
48
|
const NO_ACCESS = new Set([401, 403, 404]);
|
|
47
49
|
const text = (value) => (typeof value === "string" ? value.trim() : "");
|
|
50
|
+
/** An http(s) address, or null: a reference's url lands in an `href`. */
|
|
51
|
+
const webUrl = (value) => (/^https?:\/\//i.test(text(value)) ? text(value) : null);
|
|
48
52
|
const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
|
|
49
53
|
/**
|
|
50
54
|
* The knowledge bases, and the documents in them, that a list of references
|
|
@@ -195,6 +199,7 @@ export const retrievePassages = async (options) => {
|
|
|
195
199
|
chunkId,
|
|
196
200
|
documentId: id(chunk.documentId),
|
|
197
201
|
documentName: text(chunk.documentName) || null,
|
|
202
|
+
documentUrl: webUrl(chunk.documentUrl),
|
|
198
203
|
knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
|
|
199
204
|
pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
|
|
200
205
|
score: typeof chunk.score === "number" ? chunk.score : null,
|
|
@@ -222,7 +227,8 @@ export const passagesForPrompt = (passages) => (Array.isArray(passages) ? passag
|
|
|
222
227
|
/**
|
|
223
228
|
* STACKFACTOR references for passages: one per passage, in their order, with no
|
|
224
229
|
* cap. With `tags`, only the passages the model cited by tag (any tag it made
|
|
225
|
-
* up is passed over); without, every passage.
|
|
230
|
+
* up is passed over); without, every passage. Each links to its document's
|
|
231
|
+
* page at the source (`url`) when the passage has one.
|
|
226
232
|
* @param passages From `retrievePassages`
|
|
227
233
|
* @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
|
|
228
234
|
* @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) => {
|
|
|
234
240
|
: null;
|
|
235
241
|
return list
|
|
236
242
|
.filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
|
|
237
|
-
.map((passage) =>
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
243
|
+
.map((passage) => {
|
|
244
|
+
const url = webUrl(passage.documentUrl);
|
|
245
|
+
return {
|
|
246
|
+
description: passage.sectionTitle,
|
|
247
|
+
kind: STACKFACTOR_REFERENCE.KIND,
|
|
248
|
+
knowledgeBase: {
|
|
249
|
+
chunkId: passage.chunkId,
|
|
250
|
+
documentId: passage.documentId,
|
|
251
|
+
knowledgeBaseId: passage.knowledgeBaseId,
|
|
252
|
+
sectionTitle: passage.sectionTitle,
|
|
253
|
+
},
|
|
254
|
+
origin: STACKFACTOR_REFERENCE.ORIGIN,
|
|
255
|
+
target: {
|
|
256
|
+
elementId: passage.documentId,
|
|
257
|
+
elementType: STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
|
|
258
|
+
parentId: passage.knowledgeBaseId,
|
|
259
|
+
},
|
|
260
|
+
title: passage.documentName || passage.sectionTitle || "Knowledge base document",
|
|
261
|
+
...(url ? { url } : {}),
|
|
262
|
+
visibility: STACKFACTOR_REFERENCE.VISIBILITY,
|
|
263
|
+
};
|
|
264
|
+
});
|
|
255
265
|
};
|
|
256
266
|
export default {
|
|
257
267
|
DEFAULT_TOP_K,
|