@astratra/ai 1.2.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/src/masking.js ADDED
@@ -0,0 +1,279 @@
1
+ /**
2
+ * Masking what identifies people before a text leaves for an outside provider,
3
+ * and putting it back in the answer.
4
+ *
5
+ * The prompt was masked; the web search was not. The model wrote the search
6
+ * query from the masked question, the loop unmasked the tool parameters for
7
+ * the tools that need real names — and the child's name went to the search
8
+ * engine in clear. So the rule here is about DIRECTION, not about which tool:
9
+ * whatever leaves the machine is masked at the moment it leaves, and only what
10
+ * comes back is unmasked.
11
+ *
12
+ * One masker per conversation. It LEARNS: a name found once (in the school's
13
+ * register, by a pattern, by an entity detector) is masked everywhere after,
14
+ * with the same token, so the model can still tell two people apart.
15
+ *
16
+ * Choices kept from real use:
17
+ *
18
+ * - register names match CASE-SENSITIVELY and on whole words. "Grace",
19
+ * "Chance" and "Merveille" are real first names; "grâce à" and "la chance"
20
+ * must survive. A common word damaged costs less than a child's name in
21
+ * clear, but the case keeps most sentences intact;
22
+ * - a name shorter than three letters identifies no one and breaks sentences;
23
+ * - a register name absent from the text creates NO token — a register of a
24
+ * thousand names must not pollute the unmasking table;
25
+ * - models drop the leading "#" of a token; unmasking tolerates it;
26
+ * - tokens are replaced longest first, on token boundaries, so #PERSON_0001
27
+ * never eats the start of #PERSON_00012.
28
+ */
29
+
30
+ const DEFAULT_MIN_LENGTH = 3;
31
+ const DEFAULT_MIN_SCORE = 0.6;
32
+ const DEFAULT_DETECT_MAX_CHARS = 1500;
33
+
34
+ const ESCAPE = /[.*+?^${}()|[\]\\]/g;
35
+ const escape = (text) => String(text).replace(ESCAPE, '\\$&');
36
+ const LEXICAL = '\\p{L}\\p{N}\\p{M}_';
37
+
38
+ const defaultToken = (type, sequence) => `#${String(type || 'ENTITY').toUpperCase()}_${String(sequence).padStart(4, '0')}`;
39
+
40
+ /** At most `max` characters, cut on a blank: a name is never sliced in two. */
41
+ function headWithoutCuttingWords(text, max) {
42
+ if (text.length <= max) return text;
43
+ const cut = text.slice(0, max);
44
+ const blank = cut.search(/\s\S*$/);
45
+ return blank > 0 ? cut.slice(0, blank) : cut;
46
+ }
47
+
48
+ /**
49
+ * @param {object} [options]
50
+ * @param {string[]} [options.names] register names, masked case-sensitively.
51
+ * @param {Array<{type: string, pattern: RegExp}>} [options.patterns] global
52
+ * regexes for structured data (e-mail, phone…), masked as found.
53
+ * @param {Function} [options.detect] async (text) => [{ text, type, score }] — an
54
+ * entity detector (a local NER model). Its absence, or a null answer, leaves
55
+ * the register and the patterns alone.
56
+ * @param {string[]} [options.detectTypes] which detected types to mask. Default ['person'].
57
+ * @param {number} [options.minScore] detections under this are ignored. Default 0.6 —
58
+ * a false name masked damages the sentence sent to the model.
59
+ * @param {number} [options.detectMaxChars] text handed to the detector, cut on a blank. Default 1500.
60
+ * @param {number} [options.minLength] shortest value masked. Default 3.
61
+ * @param {Function} [options.token] (type, sequence) => string. Default "#TYPE_0001".
62
+ * @param {Function} [options.typeOf] (value) => type for register names. Default 'PERSON'.
63
+ * @param {Function} [options.keep] (value) => true to never mask it (a product name…).
64
+ */
65
+ function createReversibleMasker(options = {}) {
66
+ const minLength = options.minLength || DEFAULT_MIN_LENGTH;
67
+ const minScore = options.minScore === undefined ? DEFAULT_MIN_SCORE : options.minScore;
68
+ const detectMaxChars = options.detectMaxChars || DEFAULT_DETECT_MAX_CHARS;
69
+ const detect = typeof options.detect === 'function' ? options.detect : null;
70
+ const detectTypes = new Set(options.detectTypes || ['person']);
71
+ const tokenFor = options.token || defaultToken;
72
+ const typeOf = options.typeOf || (() => 'PERSON');
73
+ const keep = options.keep || (() => false);
74
+ const patterns = (options.patterns || []).map(({ type, pattern }) => {
75
+ if (!(pattern instanceof RegExp) || !pattern.global) {
76
+ throw new Error('createReversibleMasker: every pattern must be a global RegExp.');
77
+ }
78
+ return { type, pattern };
79
+ });
80
+
81
+ /* token -> real value ; real value -> token */
82
+ const byToken = new Map();
83
+ const byValue = new Map();
84
+ /* values matched case-insensitively (patterns: an e-mail is an e-mail in any case) */
85
+ const loose = new Set();
86
+ const register = new Set();
87
+ let sequence = 0;
88
+
89
+ const looksLikeToken = (value) => byToken.has(value) || byToken.has(`#${value}`);
90
+ const alreadyMasked = /#[A-Z]+_\d+/;
91
+
92
+ function tokenOf(value, type) {
93
+ if (byValue.has(value)) return byValue.get(value);
94
+ let token;
95
+ do {
96
+ sequence += 1;
97
+ token = tokenFor(type, sequence);
98
+ } while (byToken.has(token));
99
+ byToken.set(token, value);
100
+ byValue.set(value, token);
101
+ return token;
102
+ }
103
+
104
+ function acceptable(value) {
105
+ const text = String(value === null || value === undefined ? '' : value).trim();
106
+ if (text.length < minLength) return null;
107
+ if (alreadyMasked.test(text) || looksLikeToken(text)) return null;
108
+ if (keep(text)) return null;
109
+ return text;
110
+ }
111
+
112
+ function replaceWhole(text, value, token, caseSensitive) {
113
+ const regex = new RegExp(`(^|[^${LEXICAL}])(${escape(value)})(?=$|[^${LEXICAL}])`, caseSensitive ? 'gu' : 'giu');
114
+ return text.replace(regex, (_whole, prefix) => `${prefix}${token}`);
115
+ }
116
+
117
+ function learn(names, type) {
118
+ for (const raw of names || []) {
119
+ const value = acceptable(raw);
120
+ if (value) register.add(value);
121
+ if (value && type) typeOverride.set(value, type);
122
+ }
123
+ }
124
+ const typeOverride = new Map();
125
+ learn(options.names);
126
+
127
+ /** Mask a string with everything known so far, plus `names` for this call. */
128
+ function mask(text, { names } = {}) {
129
+ if (typeof text !== 'string' || !text) return text;
130
+ if (names) learn(names);
131
+ let out = text;
132
+
133
+ /* Structured data first, on the intact text. */
134
+ for (const { type, pattern } of patterns) {
135
+ pattern.lastIndex = 0;
136
+ for (const match of out.matchAll(pattern)) {
137
+ const value = acceptable(match[0]);
138
+ if (!value) continue;
139
+ tokenOf(value, type);
140
+ loose.add(value);
141
+ }
142
+ }
143
+
144
+ /* Longest first: "Marie Kabongo" before "Marie". Case-sensitive for the
145
+ register; a value absent from the text creates no token. */
146
+ const candidates = [...new Set([...register, ...byValue.keys()])].sort((a, b) => b.length - a.length);
147
+ for (const value of candidates) {
148
+ const caseSensitive = !loose.has(value);
149
+ const present = caseSensitive ? out.includes(value) : out.toLowerCase().includes(value.toLowerCase());
150
+ if (!present) continue;
151
+ const token = tokenOf(value, typeOverride.get(value) || typeOf(value));
152
+ out = replaceWhole(out, value, token, caseSensitive);
153
+ }
154
+ return out;
155
+ }
156
+
157
+ /**
158
+ * Names the detector finds, for the register — deduplicated, filtered by
159
+ * type, score and length; tokens already placed are not names.
160
+ */
161
+ async function detectNames(text) {
162
+ if (!detect || typeof text !== 'string' || !text.trim()) return [];
163
+ let found;
164
+ try {
165
+ found = await detect(headWithoutCuttingWords(text, detectMaxChars));
166
+ } catch (_error) {
167
+ return [];
168
+ }
169
+ if (!Array.isArray(found)) return [];
170
+ const names = found
171
+ .filter((entity) => entity && detectTypes.has(entity.type) && typeof entity.score === 'number' && entity.score >= minScore)
172
+ .map((entity) => acceptable(entity.text))
173
+ .filter(Boolean);
174
+ return [...new Set(names)];
175
+ }
176
+
177
+ /** Detect, learn, then mask. The detector sees the text in clear — keep it local. */
178
+ async function maskAsync(text, opts = {}) {
179
+ if (typeof text !== 'string' || !text) return text;
180
+ const detected = await detectNames(text);
181
+ return mask(text, { names: [...(opts.names || []), ...detected] });
182
+ }
183
+
184
+ /** Every string of a structure, masked. Keys are left alone. */
185
+ function maskDeep(value) {
186
+ if (typeof value === 'string') return mask(value);
187
+ if (Array.isArray(value)) return value.map(maskDeep);
188
+ if (value instanceof Date) return new Date(value.getTime());
189
+ if (value && typeof value === 'object') {
190
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, maskDeep(child)]));
191
+ }
192
+ return value;
193
+ }
194
+
195
+ function unmask(text) {
196
+ if (typeof text !== 'string' || !text || !byToken.size) return text;
197
+ let out = text;
198
+ const tokens = [...byToken.keys()].sort((a, b) => b.length - a.length);
199
+ for (const token of tokens) {
200
+ const value = byToken.get(token);
201
+ const variants = token.startsWith('#') ? [token, token.slice(1)] : [token];
202
+ for (const variant of variants) {
203
+ if (!out.includes(variant)) continue;
204
+ const regex = new RegExp(`(^|[^${LEXICAL}#])(${escape(variant)})(?![${LEXICAL}])`, 'gu');
205
+ out = out.replace(regex, (_whole, prefix) => `${prefix}${value}`);
206
+ }
207
+ }
208
+ return out;
209
+ }
210
+
211
+ function unmaskDeep(value) {
212
+ if (typeof value === 'string') return unmask(value);
213
+ if (Array.isArray(value)) return value.map(unmaskDeep);
214
+ if (value instanceof Date) return new Date(value.getTime());
215
+ if (value && typeof value === 'object') {
216
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, unmaskDeep(child)]));
217
+ }
218
+ return value;
219
+ }
220
+
221
+ /**
222
+ * Unmask a stream of chunks. A token can straddle two chunks ("#PERS" then
223
+ * "ON_0001"); the tail that could still be the start of a token is held
224
+ * back until the next chunk decides.
225
+ */
226
+ async function* unmaskStream(chunks) {
227
+ let carry = '';
228
+ const longest = () => Math.max(0, ...[...byToken.keys()].map((token) => token.length));
229
+ for await (const chunk of chunks) {
230
+ const text = carry + String(chunk);
231
+ const hold = holdBack(text, longest());
232
+ carry = text.slice(text.length - hold);
233
+ const ready = text.slice(0, text.length - hold);
234
+ if (ready) yield unmask(ready);
235
+ }
236
+ if (carry) yield unmask(carry);
237
+ }
238
+
239
+ function holdBack(text, maxLength) {
240
+ if (!maxLength) return 0;
241
+ const tokens = [...byToken.keys()].flatMap((token) => (token.startsWith('#') ? [token, token.slice(1)] : [token]));
242
+ for (let size = Math.min(maxLength, text.length); size > 0; size -= 1) {
243
+ const tail = text.slice(text.length - size);
244
+ /* A whole token at the very end may still be followed by a digit that
245
+ makes it another token: hold it too. */
246
+ if (tokens.some((token) => token.startsWith(tail))) return size;
247
+ }
248
+ return 0;
249
+ }
250
+
251
+ return {
252
+ mask,
253
+ maskAsync,
254
+ maskDeep,
255
+ unmask,
256
+ unmaskDeep,
257
+ unmaskStream,
258
+ detectNames,
259
+ /** How many values are masked so far — never the values. */
260
+ size: () => byToken.size
261
+ };
262
+ }
263
+
264
+ /**
265
+ * Wrap an outside call so its input is masked on the way out and its answer
266
+ * unmasked on the way back.
267
+ */
268
+ function withOutboundMasking(masker, call) {
269
+ if (!masker || typeof masker.maskAsync !== 'function' || typeof masker.unmaskDeep !== 'function') {
270
+ throw new Error('withOutboundMasking requires a masker from createReversibleMasker().');
271
+ }
272
+ if (typeof call !== 'function') throw new Error('withOutboundMasking requires a function to wrap.');
273
+ return async (input, ...rest) => {
274
+ const outbound = typeof input === 'string' ? await masker.maskAsync(input) : masker.maskDeep(input);
275
+ return masker.unmaskDeep(await call(outbound, ...rest));
276
+ };
277
+ }
278
+
279
+ module.exports = { createReversibleMasker, withOutboundMasking, headWithoutCuttingWords };
@@ -0,0 +1,170 @@
1
+ /**
2
+ * Providers that speak the OpenAI chat format (Groq, Mistral, Cloudflare
3
+ * Workers AI, gateways…): one request shape, one way to read the answer.
4
+ *
5
+ * Three things real traffic taught:
6
+ *
7
+ * - a model sometimes returns tool arguments that are not JSON. Parsing them
8
+ * blindly threw inside the turn and lost the whole answer; a malformed call
9
+ * is now reported as such and the loop decides;
10
+ * - reasoning models write their thinking between think tags inside the
11
+ * answer — never shown, even when the closing tag is missing;
12
+ * - an error carries the HTTP status (a 429 must reach the router's cooldown)
13
+ * and never the key.
14
+ */
15
+
16
+ const THINK = /<think>[\s\S]*?(?:<\/think>|$)/gi;
17
+
18
+ function toTranscript(messages) {
19
+ return (Array.isArray(messages) ? messages : []).map((message) => {
20
+ if (message.role === 'assistant') {
21
+ return {
22
+ role: 'assistant',
23
+ content: message.text === undefined ? message.content || '' : message.text,
24
+ ...(message.toolCalls && message.toolCalls.length ? {
25
+ tool_calls: message.toolCalls.map((call) => ({
26
+ id: call.id,
27
+ type: 'function',
28
+ function: { name: call.name, arguments: JSON.stringify(call.args === undefined ? {} : call.args) }
29
+ }))
30
+ } : {})
31
+ };
32
+ }
33
+ if (message.role === 'tool') {
34
+ return { role: 'tool', tool_call_id: message.toolCallId, content: typeof message.result === 'string' ? message.result : JSON.stringify(message.result) };
35
+ }
36
+ const text = message.text === undefined ? message.content || '' : message.text;
37
+ /* A photo joined by the person: an image part with a data address. Only
38
+ send it to models that see. */
39
+ if (message.images && message.images.length) {
40
+ return {
41
+ role: 'user',
42
+ content: [
43
+ { type: 'text', text },
44
+ ...message.images.map(({ mimeType, data }) => ({ type: 'image_url', image_url: { url: `data:${mimeType};base64,${data}` } }))
45
+ ]
46
+ };
47
+ }
48
+ return { role: message.role === 'system' ? 'system' : 'user', content: text };
49
+ });
50
+ }
51
+
52
+ /** Tool arguments as an object, or null with `invalid: true` for anything else. */
53
+ function readToolArguments(raw) {
54
+ if (raw === undefined || raw === null || raw === '') return { args: {}, invalid: false };
55
+ if (typeof raw === 'object') return { args: raw, invalid: false };
56
+ try {
57
+ const parsed = JSON.parse(String(raw));
58
+ return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? { args: parsed, invalid: false } : { args: null, invalid: true };
59
+ } catch (_error) {
60
+ return { args: null, invalid: true };
61
+ }
62
+ }
63
+
64
+ /**
65
+ * Ask one model.
66
+ * @param {{ url: string, key: string, model: string, extra?: object }} target
67
+ * @param {{ system?: string, messages: object[], tools?: object[], maxTokens?: number, temperature?: number }} request
68
+ * @param {{ fetch: Function, signal?: AbortSignal, timeoutMs?: number }} io
69
+ * @returns {Promise<{ status: number, text?: string|null, toolCalls?: object[], cut?: boolean }>}
70
+ * A non-2xx answer resolves `{ status }` — nothing is thrown for it.
71
+ */
72
+ async function askChatModel(target, request, io = {}) {
73
+ if (typeof io.fetch !== 'function') throw new Error('askChatModel requires io.fetch.');
74
+ const { url, key, model, extra = {} } = target || {};
75
+ const timeoutMs = io.timeoutMs || 45_000;
76
+ const Signal = globalThis.AbortSignal;
77
+ const timeout = Signal.timeout(timeoutMs);
78
+ const signal = io.signal && typeof Signal.any === 'function' ? Signal.any([io.signal, timeout]) : (io.signal || timeout);
79
+ const messages = [
80
+ ...(request.system ? [{ role: 'system', content: request.system }] : []),
81
+ ...toTranscript(request.messages)
82
+ ];
83
+ const response = await io.fetch(url, {
84
+ method: 'POST',
85
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
86
+ body: JSON.stringify({
87
+ model,
88
+ messages,
89
+ temperature: request.temperature === undefined ? 0.4 : request.temperature,
90
+ max_tokens: request.maxTokens || 1200,
91
+ ...(request.tools && request.tools.length ? { tools: request.tools.map((tool) => ({ type: 'function', function: tool })) } : {}),
92
+ ...extra
93
+ }),
94
+ signal
95
+ });
96
+ if (!response.ok) return { status: response.status };
97
+ const answer = await response.json();
98
+ const choice = (answer && answer.choices && answer.choices[0]) || {};
99
+ const message = choice.message || {};
100
+ if (Array.isArray(message.tool_calls) && message.tool_calls.length) {
101
+ return {
102
+ status: response.status,
103
+ text: null,
104
+ toolCalls: message.tool_calls.map((call) => {
105
+ const { args, invalid } = readToolArguments(call.function && call.function.arguments);
106
+ return { id: call.id, name: call.function && call.function.name, args, ...(invalid ? { invalid: true } : {}) };
107
+ })
108
+ };
109
+ }
110
+ const text = String(message.content === null || message.content === undefined ? '' : message.content).replace(THINK, '').trim();
111
+ return { status: response.status, text, cut: choice.finish_reason === 'length' };
112
+ }
113
+
114
+ /**
115
+ * A provider for createProviderRouter, over an OpenAI-compatible endpoint.
116
+ *
117
+ * @param {object} options
118
+ * @param {string} options.id
119
+ * @param {string} options.url
120
+ * @param {Function} options.getKey () => key, read at every call: a key changed
121
+ * from the settings screen takes effect without a restart.
122
+ * @param {object[]} options.models router model entries ({ id, rpm, rpd, tpd, complexity }).
123
+ * @param {Function} options.fetch
124
+ * @param {boolean} [options.external] false for a model on this machine: the router then does not mask.
125
+ * @param {number} [options.timeoutMs]
126
+ * @param {object} [options.extra] joined to each request.
127
+ * @param {Function} [options.toRequest] (prompt, ctx) => { system?, messages }. Default: the prompt as one user message.
128
+ */
129
+ function createOpenAICompatibleProvider(options = {}) {
130
+ for (const field of ['id', 'url']) {
131
+ if (typeof options[field] !== 'string' || !options[field]) throw new Error(`createOpenAICompatibleProvider requires options.${field}.`);
132
+ }
133
+ if (typeof options.getKey !== 'function') throw new Error('createOpenAICompatibleProvider requires options.getKey.');
134
+ if (typeof options.fetch !== 'function') throw new Error('createOpenAICompatibleProvider requires options.fetch.');
135
+ const toRequest = options.toRequest || ((prompt) => ({ messages: [{ role: 'user', text: String(prompt) }] }));
136
+
137
+ return {
138
+ id: options.id,
139
+ models: options.models || [],
140
+ ...(options.external === false ? { external: false } : {}),
141
+ async call(prompt, ctx = {}, model = {}) {
142
+ const key = await options.getKey();
143
+ if (!key) {
144
+ const missing = new Error(`Provider "${options.id}" has no key.`);
145
+ missing.statusCode = 401;
146
+ throw missing;
147
+ }
148
+ const answer = await askChatModel(
149
+ { url: options.url, key, model: model.id, extra: options.extra },
150
+ { maxTokens: model.maxTokens, ...toRequest(prompt, ctx) },
151
+ { fetch: options.fetch, signal: ctx.signal, timeoutMs: options.timeoutMs }
152
+ );
153
+ if (answer.status < 200 || answer.status >= 300) {
154
+ /* The status reaches the router (429 → cooldown); the key never does. */
155
+ const failure = new Error(`Provider "${options.id}" answered ${answer.status}.`);
156
+ failure.statusCode = answer.status;
157
+ throw failure;
158
+ }
159
+ if (answer.toolCalls) return { toolCalls: answer.toolCalls };
160
+ if (!answer.text) {
161
+ const empty = new Error(`Provider "${options.id}" gave no text.`);
162
+ empty.statusCode = 502;
163
+ throw empty;
164
+ }
165
+ return answer.text;
166
+ }
167
+ };
168
+ }
169
+
170
+ module.exports = { askChatModel, createOpenAICompatibleProvider, readToolArguments };
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Handing the model passages that may not be in the reader's language.
3
+ *
4
+ * A question in English may be best answered from a text that exists only in
5
+ * French. Dropping it loses the answer; slipping it in unmarked gets it quoted
6
+ * in French, or "translated" with a reference the reader cannot find. So each
7
+ * passage says its language, in a tag the model cannot miss — `[fr]` — and one
8
+ * instruction says what to do with a tagged passage: translate what you use,
9
+ * keep the ORIGINAL reference, so the reader can go and check it.
10
+ *
11
+ * Language tags are compared on their primary subtag: `fr-FR` and `fr` are
12
+ * the same language, and marking one as foreign to the other would have the
13
+ * model "translate" French into French.
14
+ *
15
+ * No wording lives here: the header, footer, instruction and "nothing found"
16
+ * lines are the caller's, per language. `{languages}` in the instruction is
17
+ * replaced by the tags found.
18
+ */
19
+
20
+ /** 'fr-FR', 'FR', ' fr_ca ' -> 'fr'. Null for nothing usable. */
21
+ function primaryLanguage(tag) {
22
+ if (typeof tag !== 'string') return null;
23
+ const primary = tag.trim().toLowerCase().split(/[-_]/)[0];
24
+ return /^[a-z]{2,3}$/.test(primary) ? primary : null;
25
+ }
26
+
27
+ function isForeign(passageLanguage, readerLanguage) {
28
+ const passage = primaryLanguage(passageLanguage);
29
+ const reader = primaryLanguage(readerLanguage);
30
+ return Boolean(passage && reader && passage !== reader);
31
+ }
32
+
33
+ const defaultTag = (language) => `[${language}]`;
34
+
35
+ /**
36
+ * @param {Array<{title?: string, text: string, lang?: string}>} passages
37
+ * @param {object} options
38
+ * @param {string} options.lang the reader's language.
39
+ * @param {Function} [options.tag] (primaryLanguage) => string. Default "[fr]".
40
+ * @returns {{ blocks: string[], languages: string[] }} one block per passage;
41
+ * `languages` lists the foreign tags present, in order of appearance.
42
+ */
43
+ function markForeignPassages(passages, { lang, tag = defaultTag } = {}) {
44
+ const languages = [];
45
+ const blocks = (Array.isArray(passages) ? passages : []).filter((passage) => passage && passage.text).map((passage) => {
46
+ const foreign = isForeign(passage.lang, lang);
47
+ const primary = foreign ? primaryLanguage(passage.lang) : null;
48
+ if (primary && !languages.includes(primary)) languages.push(primary);
49
+ const title = [passage.title, primary ? tag(primary) : null].filter(Boolean).join(' ');
50
+ return title ? `${title}\n${passage.text}` : String(passage.text);
51
+ });
52
+ return { blocks, languages };
53
+ }
54
+
55
+ /**
56
+ * The passages block of a system prompt.
57
+ *
58
+ * @param {object} options
59
+ * @param {Array|null} options.passages null when the SEARCH failed — then
60
+ * nothing is said about the library, rather than "nothing found", which
61
+ * would be a lie; [] when it found nothing.
62
+ * @param {string} options.lang
63
+ * @param {object} options.texts { header?, footer?, foreign (required when a
64
+ * passage can be foreign), empty? } — the caller's words.
65
+ * @param {Function} [options.tag]
66
+ * @returns {string[]} lines to join into the system prompt.
67
+ */
68
+ function buildPassagesContext({ passages, lang, texts = {}, tag } = {}) {
69
+ if (passages === null || passages === undefined) return [];
70
+ const { blocks, languages } = markForeignPassages(passages, { lang, tag });
71
+ if (!blocks.length) return texts.empty ? [texts.empty] : [];
72
+ if (languages.length && !(typeof texts.foreign === 'string' && texts.foreign.trim())) {
73
+ /* A tagged passage without the instruction is worse than no tag: the
74
+ model sees "[fr]" and guesses what it means. */
75
+ throw new Error('buildPassagesContext: a passage is in another language but texts.foreign is missing.');
76
+ }
77
+ return [
78
+ ...(texts.header ? [texts.header] : []),
79
+ ...blocks,
80
+ ...(texts.footer ? [texts.footer] : []),
81
+ ...(languages.length ? [texts.foreign.replace(/\{languages\}/g, () => languages.map((language) => (tag || defaultTag)(language)).join(', '))] : [])
82
+ ];
83
+ }
84
+
85
+ /**
86
+ * The source card of a passage: its reference untouched — the original, even
87
+ * when the answer is a translation — and a short excerpt.
88
+ */
89
+ function passageSource(passage, { excerptMax = 300 } = {}) {
90
+ const text = String((passage && passage.text) || '');
91
+ return {
92
+ ...(passage.kind ? { kind: passage.kind } : {}),
93
+ ...(passage.title ? { title: passage.title } : {}),
94
+ ...(passage.ref !== undefined ? { ref: passage.ref } : {}),
95
+ ...(passage.url ? { url: passage.url } : {}),
96
+ ...(passage.lang ? { lang: passage.lang } : {}),
97
+ excerpt: text.length > excerptMax ? text.slice(0, excerptMax) : text
98
+ };
99
+ }
100
+
101
+ module.exports = { primaryLanguage, isForeignLanguage: isForeign, markForeignPassages, buildPassagesContext, passageSource };