@astratra/ai 1.3.0 → 1.4.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/README.md +133 -0
- package/package.json +2 -1
- package/src/agentLoop.js +88 -11
- package/src/answerText.js +117 -0
- package/src/askLimit.js +69 -0
- package/src/breakers.js +97 -0
- package/src/index.d.ts +252 -0
- package/src/index.js +9 -1
- package/src/language.js +85 -0
- package/src/masking.js +279 -0
- package/src/openaiCompatible.js +170 -0
- package/src/passages.js +101 -0
- package/src/providerRouter.js +77 -11
- package/src/sources.js +243 -0
package/src/sources.js
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sources: what was read, what the answer relies on, and whether the answer
|
|
3
|
+
* contradicts them.
|
|
4
|
+
*
|
|
5
|
+
* Tools and search bring several passages; the model uses a few. Showing all
|
|
6
|
+
* of them under the answer claims support it does not have. Three pieces:
|
|
7
|
+
*
|
|
8
|
+
* createSourceLedger — collects sources as tools return them, and the text
|
|
9
|
+
* behind each one; a tool that returned SEVERAL sources does not tie its
|
|
10
|
+
* whole output to each of them;
|
|
11
|
+
* usedSources — keeps only the sources the answer relies on, told from the
|
|
12
|
+
* answer itself (its link, a reference both name, enough shared distinctive
|
|
13
|
+
* words). Nothing is ever added: a source is kept or left out;
|
|
14
|
+
* findContradiction — asks a local inference model whether a sentence of the
|
|
15
|
+
* answer contradicts the closest source. Only a clear contradiction counts;
|
|
16
|
+
* a doubt, a failure or a timeout says nothing.
|
|
17
|
+
*
|
|
18
|
+
* And rerankResults, for search results a local reranker orders better than
|
|
19
|
+
* the engine that ranks for the whole web.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const fold = (text) => String(text === null || text === undefined ? '' : text).normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
|
|
23
|
+
|
|
24
|
+
function wordsOf(text, { minLength, common }) {
|
|
25
|
+
return new Set(fold(text).split(/[^\p{L}\d]+/u).filter((word) => word.length >= minLength && !common.has(word)));
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* @param {object} [options]
|
|
30
|
+
* @param {Function} [options.keyOf] (source) => string. Default kind + JSON of ref, else url, else title.
|
|
31
|
+
*/
|
|
32
|
+
function createSourceLedger(options = {}) {
|
|
33
|
+
const keyOf = options.keyOf || ((source) => (
|
|
34
|
+
source.ref !== undefined ? `${source.kind || ''}:${JSON.stringify(source.ref)}` : `${source.kind || ''}:${source.url || source.title || ''}`
|
|
35
|
+
));
|
|
36
|
+
const sources = new Map();
|
|
37
|
+
const evidence = new Map();
|
|
38
|
+
|
|
39
|
+
/** Record what a tool found, and — when it found exactly one source — what it gave. */
|
|
40
|
+
function keep(found = [], data = null) {
|
|
41
|
+
const list = Array.isArray(found) ? found.filter(Boolean) : [];
|
|
42
|
+
const read = list.length === 1 && data !== null && data !== undefined
|
|
43
|
+
? (typeof data === 'string' ? data : JSON.stringify(data))
|
|
44
|
+
: '';
|
|
45
|
+
for (const source of list) {
|
|
46
|
+
const key = keyOf(source);
|
|
47
|
+
if (!sources.has(key)) sources.set(key, source);
|
|
48
|
+
evidence.set(key, [evidence.get(key), source.title, source.excerpt, read].filter(Boolean).join('\n'));
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
return {
|
|
53
|
+
keep,
|
|
54
|
+
sources: () => [...sources.values()],
|
|
55
|
+
evidence: () => [...sources.keys()].map((key) => evidence.get(key) || ''),
|
|
56
|
+
size: () => sources.size
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* @param {string} answer the answer as the person reads it.
|
|
62
|
+
* @param {object[]} sources what was read, in order.
|
|
63
|
+
* @param {string[]} evidence the text behind each source.
|
|
64
|
+
* @param {object} [options]
|
|
65
|
+
* @param {Function} [options.references] (text) => places named in it. With
|
|
66
|
+
* `sameReference`, a source whose evidence names a place the answer names is kept.
|
|
67
|
+
* @param {Function} [options.sameReference] (a, b) => boolean.
|
|
68
|
+
* @param {Function} [options.ownReference] (source) => place | null — a source
|
|
69
|
+
* that IS a reference (a verse, an article number) is kept only when the
|
|
70
|
+
* answer names it.
|
|
71
|
+
* @param {Iterable<string>} [options.commonWords] folded words never compared
|
|
72
|
+
* (the everyday words of your languages, and the names every answer says).
|
|
73
|
+
* @param {number} [options.minWordLength] Default 5.
|
|
74
|
+
* @param {number} [options.sharedMin] distinct shared words that tie a passage. Default 3.
|
|
75
|
+
* @param {number} [options.shortEvidence] evidence with this many words or fewer needs only 2. Default 5.
|
|
76
|
+
* @returns {object[]} the sources relied on, unchanged, in their order.
|
|
77
|
+
*/
|
|
78
|
+
function usedSources(answer, sources, evidence = [], options = {}) {
|
|
79
|
+
const minLength = options.minWordLength || 5;
|
|
80
|
+
const sharedMin = options.sharedMin || 3;
|
|
81
|
+
const shortEvidence = options.shortEvidence || 5;
|
|
82
|
+
const common = new Set([...(options.commonWords || [])].map(fold));
|
|
83
|
+
const text = String(answer || '');
|
|
84
|
+
const said = wordsOf(text, { minLength, common });
|
|
85
|
+
const references = typeof options.references === 'function' ? options.references : null;
|
|
86
|
+
const same = typeof options.sameReference === 'function' ? options.sameReference : null;
|
|
87
|
+
const named = references ? references(text) || [] : [];
|
|
88
|
+
|
|
89
|
+
return (Array.isArray(sources) ? sources : []).filter((source, index) => {
|
|
90
|
+
if (typeof options.ownReference === 'function') {
|
|
91
|
+
const own = options.ownReference(source);
|
|
92
|
+
/* Without a way to read references, the source's own title named in
|
|
93
|
+
the answer is the only honest test. */
|
|
94
|
+
if (own) {
|
|
95
|
+
if (!references || !same) return Boolean(source.title) && fold(text).includes(fold(source.title));
|
|
96
|
+
return named.some((place) => same(place, own));
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
if (source && source.url && text.includes(source.url)) return true;
|
|
100
|
+
const behind = evidence[index] || '';
|
|
101
|
+
if (references && same && named.length) {
|
|
102
|
+
const inEvidence = references(behind) || [];
|
|
103
|
+
if (inEvidence.some((place) => named.some((other) => same(place, other)))) return true;
|
|
104
|
+
}
|
|
105
|
+
const own = wordsOf(behind, { minLength, common });
|
|
106
|
+
const shared = [...own].filter((word) => said.has(word)).length;
|
|
107
|
+
const needed = own.size <= shortEvidence ? Math.min(2, own.size) : sharedMin;
|
|
108
|
+
return own.size > 0 && shared >= needed;
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/* ───────────────────────── contradiction ───────────────────────── */
|
|
113
|
+
|
|
114
|
+
const cleanSentence = (sentence) => sentence
|
|
115
|
+
.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, '')
|
|
116
|
+
.replace(/[*_`#]+/g, '')
|
|
117
|
+
.replace(/\s+/g, ' ')
|
|
118
|
+
.trim();
|
|
119
|
+
|
|
120
|
+
function factualSentences(answer, minWords) {
|
|
121
|
+
return String(answer)
|
|
122
|
+
.split(/(?<=[.!?…])\s+|\n+/)
|
|
123
|
+
.map(cleanSentence)
|
|
124
|
+
.filter((sentence) => !/[?¿]$/.test(sentence) && sentence.split(' ').length >= minWords);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Does a sentence of the answer contradict the source closest to it?
|
|
129
|
+
*
|
|
130
|
+
* @param {string} answer
|
|
131
|
+
* @param {Array<string|{content?: string, snippet?: string, url?: string, source?: string}>} sources
|
|
132
|
+
* @param {object} options
|
|
133
|
+
* @param {Function} options.compare async (pairs: {premise, hypothesis}[]) =>
|
|
134
|
+
* [{ entailment, neutral, contradiction }] | null — a local NLI model.
|
|
135
|
+
* @param {number} [options.timeoutMs] give up after this. Default 1500: the
|
|
136
|
+
* answer is already on its way, it is not held for a check.
|
|
137
|
+
* @returns {Promise<{contradicts: boolean, sentence: string|null, source: string|null} | null>}
|
|
138
|
+
* null when nothing could be checked — the caller then says nothing.
|
|
139
|
+
*/
|
|
140
|
+
async function findContradiction(answer, sources, options = {}) {
|
|
141
|
+
const compare = options.compare;
|
|
142
|
+
if (typeof compare !== 'function') throw new Error('findContradiction requires options.compare.');
|
|
143
|
+
const none = { contradicts: false, sentence: null, source: null };
|
|
144
|
+
if (typeof answer !== 'string' || !Array.isArray(sources)) return none;
|
|
145
|
+
|
|
146
|
+
const minWords = options.minWords || 5;
|
|
147
|
+
const sharedMin = options.sharedMin || 2;
|
|
148
|
+
const maxPairs = options.maxPairs || 20;
|
|
149
|
+
const contradictionMin = options.contradictionMin === undefined ? 0.8 : options.contradictionMin;
|
|
150
|
+
const entailmentMax = options.entailmentMax === undefined ? 0.2 : options.entailmentMax;
|
|
151
|
+
const common = new Set([...(options.commonWords || [])].map(fold));
|
|
152
|
+
const words = (text) => new Set((fold(text).match(/[\p{L}\p{N}]+/gu) || []).filter((word) => (word.length >= 3 || /^\d+$/.test(word)) && !common.has(word)));
|
|
153
|
+
|
|
154
|
+
const excerpts = sources.map((source) => {
|
|
155
|
+
if (typeof source === 'string') return { text: source.trim(), name: source.trim() };
|
|
156
|
+
const text = String((source && (source.content || source.snippet)) || '').trim();
|
|
157
|
+
return { text, name: (source && (source.source || source.url)) || text };
|
|
158
|
+
}).filter((excerpt) => excerpt.text).map((excerpt) => ({ ...excerpt, words: words(excerpt.text) }));
|
|
159
|
+
const sentences = factualSentences(answer, minWords).map((text) => ({ text, words: words(text) }));
|
|
160
|
+
|
|
161
|
+
const candidates = [];
|
|
162
|
+
sentences.forEach((sentence, iSentence) => excerpts.forEach((excerpt, iExcerpt) => {
|
|
163
|
+
let shared = 0;
|
|
164
|
+
for (const word of sentence.words) if (excerpt.words.has(word)) shared += 1;
|
|
165
|
+
if (shared >= sharedMin) candidates.push({ iSentence, iExcerpt, shared });
|
|
166
|
+
}));
|
|
167
|
+
if (!candidates.length) return none;
|
|
168
|
+
|
|
169
|
+
const pairs = candidates.sort((a, b) => b.shared - a.shared).slice(0, maxPairs);
|
|
170
|
+
let timer;
|
|
171
|
+
const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(null), options.timeoutMs || 1500); });
|
|
172
|
+
let results;
|
|
173
|
+
try {
|
|
174
|
+
results = await Promise.race([
|
|
175
|
+
Promise.resolve().then(() => compare(pairs.map((pair) => ({ premise: excerpts[pair.iExcerpt].text, hypothesis: sentences[pair.iSentence].text })))),
|
|
176
|
+
timeout
|
|
177
|
+
]);
|
|
178
|
+
} catch (_error) {
|
|
179
|
+
results = null;
|
|
180
|
+
} finally {
|
|
181
|
+
clearTimeout(timer);
|
|
182
|
+
}
|
|
183
|
+
if (!Array.isArray(results) || results.length !== pairs.length) return null;
|
|
184
|
+
|
|
185
|
+
/* Sorted by overlap: the first pair seen for a sentence is its closest source. */
|
|
186
|
+
const seen = new Set();
|
|
187
|
+
let worst = null;
|
|
188
|
+
pairs.forEach((pair, index) => {
|
|
189
|
+
if (seen.has(pair.iSentence)) return;
|
|
190
|
+
seen.add(pair.iSentence);
|
|
191
|
+
const verdict = results[index] || {};
|
|
192
|
+
if (verdict.contradiction >= contradictionMin && verdict.entailment < entailmentMax && (!worst || verdict.contradiction > worst.score)) {
|
|
193
|
+
worst = { score: verdict.contradiction, pair };
|
|
194
|
+
}
|
|
195
|
+
});
|
|
196
|
+
if (!worst) return none;
|
|
197
|
+
return { contradicts: true, sentence: sentences[worst.pair.iSentence].text, source: excerpts[worst.pair.iExcerpt].name };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/* ───────────────────────── rerank ───────────────────────── */
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Put the most relevant results first, and the sources in the same order.
|
|
204
|
+
*
|
|
205
|
+
* @param {string} query
|
|
206
|
+
* @param {{ results: object[], sources?: object[] }} found
|
|
207
|
+
* @param {object} options
|
|
208
|
+
* @param {Function} options.score async (query, passages: string[]) => number[] | null.
|
|
209
|
+
* @param {Function} [options.passageOf] (result) => string. Default title — content.
|
|
210
|
+
* @param {Function} [options.sourceMatches] (source, result) => boolean. Default url === result.source || result.url.
|
|
211
|
+
* @returns the same shape, reordered — or unchanged when the scorer has nothing to say.
|
|
212
|
+
*/
|
|
213
|
+
async function rerankResults(query, found, options = {}) {
|
|
214
|
+
if (typeof options.score !== 'function') throw new Error('rerankResults requires options.score.');
|
|
215
|
+
if (!found || !Array.isArray(found.results) || found.results.length < 2) return found;
|
|
216
|
+
const passageOf = options.passageOf || ((result) => [result.title, result.content].filter(Boolean).join(' — '));
|
|
217
|
+
let scores;
|
|
218
|
+
try {
|
|
219
|
+
scores = await options.score(query, found.results.map(passageOf));
|
|
220
|
+
} catch (_error) {
|
|
221
|
+
return found;
|
|
222
|
+
}
|
|
223
|
+
if (!Array.isArray(scores) || scores.length !== found.results.length || !scores.every((value) => typeof value === 'number' && Number.isFinite(value))) {
|
|
224
|
+
return found;
|
|
225
|
+
}
|
|
226
|
+
const results = found.results
|
|
227
|
+
.map((result, index) => ({ result, score: scores[index], index }))
|
|
228
|
+
.sort((a, b) => (b.score - a.score) || (a.index - b.index))
|
|
229
|
+
.map(({ result }) => result);
|
|
230
|
+
if (!Array.isArray(found.sources)) return { ...found, results };
|
|
231
|
+
const matches = options.sourceMatches || ((source, result) => Boolean(source && result && source.url && (source.url === result.source || source.url === result.url)));
|
|
232
|
+
const rank = (source) => {
|
|
233
|
+
const index = results.findIndex((result) => matches(source, result));
|
|
234
|
+
return index === -1 ? results.length : index;
|
|
235
|
+
};
|
|
236
|
+
const sources = found.sources
|
|
237
|
+
.map((source, index) => ({ source, index, rank: rank(source) }))
|
|
238
|
+
.sort((a, b) => (a.rank - b.rank) || (a.index - b.index))
|
|
239
|
+
.map(({ source }) => source);
|
|
240
|
+
return { ...found, results, sources };
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
module.exports = { createSourceLedger, usedSources, findContradiction, rerankResults, factualSentences };
|