@astratra/ai 1.7.0 → 1.9.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.
@@ -0,0 +1,63 @@
1
+ 'use strict';
2
+
3
+ /* Personal data a reply must not carry unless the person gave it in this run.
4
+ Small on purpose: structured data that can be recognised without a model. */
5
+
6
+ function luhnValid(digits) {
7
+ if (digits.length < 13 || digits.length > 19) return false;
8
+ let sum = 0;
9
+ let double = false;
10
+ for (let i = digits.length - 1; i >= 0; i -= 1) {
11
+ let d = digits.charCodeAt(i) - 48;
12
+ if (double) { d *= 2; if (d > 9) d -= 9; }
13
+ sum += d;
14
+ double = !double;
15
+ }
16
+ return sum % 10 === 0;
17
+ }
18
+
19
+ function ibanValid(value) {
20
+ const compact = value.replace(/\s/g, '').toUpperCase();
21
+ if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(compact)) return false;
22
+ const moved = compact.slice(4) + compact.slice(0, 4);
23
+ let remainder = 0;
24
+ for (const char of moved) {
25
+ const chunk = /[A-Z]/.test(char) ? String(char.charCodeAt(0) - 55) : char;
26
+ for (const digit of chunk) remainder = (remainder * 10 + (digit.charCodeAt(0) - 48)) % 97;
27
+ }
28
+ return remainder === 1;
29
+ }
30
+
31
+ const DATE_LIKE = /^\d{4}-\d{2}-\d{2}/;
32
+
33
+ const DETECTORS = [
34
+ { type: 'email', pattern: () => /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/g, valid: () => true },
35
+ { type: 'iban', pattern: () => /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{2,5}){3,8}\b/g, valid: ibanValid },
36
+ { type: 'card', pattern: () => /\b(?:\d[ -]?){13,19}\b/g, valid: (value) => luhnValid(value.replace(/\D/g, '')) },
37
+ {
38
+ type: 'phone',
39
+ pattern: () => /(?<![\w@])\+?\d[\d .()-]{7,17}\d(?![\w@])/g,
40
+ valid: (value) => {
41
+ const digits = value.replace(/\D/g, '');
42
+ return digits.length >= 9 && digits.length <= 15 && !DATE_LIKE.test(value) && !luhnValid(digits);
43
+ }
44
+ }
45
+ ];
46
+
47
+ const normal = (type, value) => (type === 'email' ? value.toLowerCase() : value.replace(/[\s.()-]/g, '').toUpperCase());
48
+
49
+ /** Structured personal data in a text: [{ type, value, start, end }] (values stay in memory, never in events). */
50
+ function findPersonalData(text, types) {
51
+ const found = [];
52
+ for (const detector of DETECTORS) {
53
+ if (types && !types.includes(detector.type)) continue;
54
+ for (const match of String(text).matchAll(detector.pattern())) {
55
+ const overlaps = found.some((f) => match.index < f.end && match.index + match[0].length > f.start);
56
+ if (overlaps || !detector.valid(match[0])) continue;
57
+ found.push({ type: detector.type, value: match[0], key: normal(detector.type, match[0]), start: match.index, end: match.index + match[0].length });
58
+ }
59
+ }
60
+ return found.sort((a, b) => a.start - b.start);
61
+ }
62
+
63
+ module.exports = { findPersonalData, luhnValid, ibanValid };
@@ -0,0 +1,31 @@
1
+ 'use strict';
2
+ const { createGuards } = require('./createGuards');
3
+
4
+ /**
5
+ * The preset: every check on, `failClosed` for anything that acts, a lower
6
+ * injection threshold before an action (0.3: flagged content only goes to
7
+ * review) than for plain reading (0.5), personal-data leaks blocked, unsafe
8
+ * replies blocked, unsupported claims flagged. Pass `readOnly: true` for an
9
+ * agent that cannot act: it then fails open when a model of the service is down.
10
+ *
11
+ * @param {object} options { models, onEvent?, names?, readOnly?, verifySources?, policy?, injection?, output? }
12
+ */
13
+ function recommendedGuards(options = {}) {
14
+ const { readOnly, policy, injection, output, ...rest } = options;
15
+ return createGuards({
16
+ defaultMode: readOnly ? 'read' : 'action',
17
+ ...rest,
18
+ policy: {
19
+ failure: { action: 'failClosed', read: readOnly ? 'failOpen' : 'failClosed' },
20
+ onInjection: 'flag',
21
+ onLeak: 'block',
22
+ onModeration: 'block',
23
+ onUnsupported: 'flag',
24
+ ...(policy || {})
25
+ },
26
+ injection: { threshold: 0.5, actionThreshold: 0.3, ...(injection || {}) },
27
+ output: { grounding: true, leak: true, moderation: true, minSupport: 0.6, ...(output || {}) }
28
+ });
29
+ }
30
+
31
+ module.exports = { recommendedGuards };
@@ -0,0 +1,30 @@
1
+ import type { CreateGuardsOptions, GuardEvent, GuardModels, Guards } from '../index';
2
+
3
+ export interface FakeModelsRules {
4
+ /** Texts `entities` finds. */
5
+ names?: string[];
6
+ injectionScore?(text: string): number;
7
+ moderate?(text: string): { unsafe: number; categories: Record<string, number> };
8
+ entails?(premise: string, claim: string): boolean;
9
+ /** Endpoints that answer a failure. */
10
+ down?: string[];
11
+ }
12
+ export interface FakeModels extends Required<GuardModels> {
13
+ calls: Array<{ endpoint: string; size: number }>;
14
+ setDown(endpoint: string, down?: boolean): void;
15
+ }
16
+ export function createFakeModels(rules?: FakeModelsRules): FakeModels;
17
+
18
+ export interface EventRecorder {
19
+ (event: GuardEvent): void;
20
+ events: GuardEvent[];
21
+ last(): GuardEvent | undefined;
22
+ decisions(guard?: string): string[];
23
+ }
24
+ export function createEventRecorder(): EventRecorder;
25
+ export function createMockGuards(options?: Omit<CreateGuardsOptions, 'models'> & { rules?: FakeModelsRules; models?: GuardModels }): {
26
+ guards: Guards;
27
+ models: GuardModels;
28
+ events: GuardEvent[];
29
+ recorder: EventRecorder;
30
+ };
@@ -0,0 +1,116 @@
1
+ 'use strict';
2
+ const { createGuards } = require('../createGuards');
3
+
4
+ /**
5
+ * Light stand-ins for tests: no model, no network, no service.
6
+ *
7
+ * createFakeModels(rules) a client shaped like @astratra/models' (entities, injection,
8
+ * moderation, nli) answering from simple rules you can override
9
+ * createMockGuards(options) the real guards over that fake client, plus an event recorder
10
+ * createEventRecorder() collects the events the guards emit
11
+ *
12
+ * The fakes are keyword rules, not detectors: they exist so the code around the guards
13
+ * (an agent loop, a route) can be tested for what it does with a decision.
14
+ */
15
+
16
+ const INJECTION_WORDS = /ignore (all )?(the )?(previous|prior|above) (instructions|rules)|ignore(z)? (toutes )?(les )?(instructions|consignes) pr[ée]c[ée]dentes|system prompt|invite syst[èe]me/i;
17
+ const UNSAFE_WORDS = /\b(kill you|je vais te tuer|suicide|suicider)\b/i;
18
+
19
+ const ok = (data) => ({ ok: true, ...data });
20
+ const fail = (endpoint, code = 'unavailable') => ({ ok: false, code, endpoint, retryable: true });
21
+
22
+ /**
23
+ * @param {object} [rules] each optional:
24
+ * names: string[] texts `entities` finds (default: none)
25
+ * injectionScore(text) 0..1 (default: 0.97 on a classic override phrase, else 0.01)
26
+ * moderate(text) { unsafe, categories } (default: flagged on a few violent words)
27
+ * entails(premise, claim) boolean (default: every word of the claim appears in the premise)
28
+ * down: string[] endpoints that answer a failure, e.g. ['injection']
29
+ */
30
+ function createFakeModels(rules = {}) {
31
+ const down = new Set(rules.down || []);
32
+ const calls = [];
33
+ const score = rules.injectionScore || ((text) => (INJECTION_WORDS.test(text) ? 0.97 : 0.01));
34
+ const moderate = rules.moderate || ((text) => (UNSAFE_WORDS.test(text) ? { unsafe: 0.95, categories: { violence: 0.9 } } : { unsafe: 0.01, categories: {} }));
35
+ const words = (t) => new Set(String(t).toLowerCase().match(/[\p{L}\p{N}]+/gu) || []);
36
+ const entails = rules.entails || ((premise, claim) => {
37
+ const have = words(premise);
38
+ return [...words(claim)].every((w) => have.has(w));
39
+ });
40
+ const wrap = (endpoint, run) => async (...args) => {
41
+ calls.push({ endpoint, size: Array.isArray(args[0]) ? args[0].length : 1 });
42
+ if (down.has(endpoint)) return fail(endpoint);
43
+ return run(...args);
44
+ };
45
+ const list = (input) => (typeof input === 'string' ? [input] : input);
46
+ return {
47
+ calls,
48
+ setDown: (endpoint, isDown = true) => (isDown ? down.add(endpoint) : down.delete(endpoint)),
49
+ entities: wrap('entities', (text) => ok({
50
+ entities: (rules.names || []).flatMap((name) => {
51
+ const start = text.indexOf(name);
52
+ return start < 0 ? [] : [{ text: name, label: 'person', start, end: start + name.length, score: 0.95 }];
53
+ }),
54
+ model: 'fake-entities'
55
+ })),
56
+ injection: wrap('injection', (input) => {
57
+ const results = list(input).map((text) => { const s = score(text); return { score: s, verdict: s >= 0.5 ? 'injection' : 'safe' }; });
58
+ return ok({ results, threshold: 0.5, model: 'fake-injection' });
59
+ }),
60
+ moderation: wrap('moderation', (input) => {
61
+ const results = list(input).map((text) => {
62
+ const r = moderate(text);
63
+ return { flagged: r.unsafe >= 0.5, unsafe: r.unsafe, categories: r.categories, flaggedCategories: r.unsafe >= 0.5 ? Object.keys(r.categories) : [] };
64
+ });
65
+ return ok({ results, model: 'fake-moderation' });
66
+ }),
67
+ nli: wrap('nli', (pairs) => ok({
68
+ results: pairs.map((p) => (entails(p.premise, p.hypothesis)
69
+ ? { entailment: 0.95, neutral: 0.04, contradiction: 0.01 }
70
+ : { entailment: 0.05, neutral: 0.9, contradiction: 0.05 })),
71
+ model: 'fake-nli'
72
+ }))
73
+ };
74
+ }
75
+
76
+ function createEventRecorder() {
77
+ const events = [];
78
+ const record = (event) => { events.push(event); };
79
+ record.events = events;
80
+ record.last = () => events[events.length - 1];
81
+ record.decisions = (guard) => events.filter((e) => !guard || e.guard === guard).map((e) => e.decision);
82
+ return record;
83
+ }
84
+
85
+ /**
86
+ * The real guards over a fake models client. Returns `{ guards, models, events }`.
87
+ * @param {object} [options] { rules (see createFakeModels), models, ...createGuards options }
88
+ */
89
+ function createMockGuards(options = {}) {
90
+ const { rules, models, ...rest } = options;
91
+ const fake = models || createFakeModels(rules);
92
+ const events = createEventRecorder();
93
+ const guards = createGuards({
94
+ onEvent: (event) => { events(event); if (rest.onEvent) rest.onEvent(event); },
95
+ ...rest,
96
+ models: fake,
97
+ verifySources: rest.verifySources || simpleVerifySources
98
+ });
99
+ return { guards, models: fake, events: events.events, recorder: events };
100
+ }
101
+
102
+ /* The same contract as verifySources of @astratra/rag, minimal: one claim per sentence,
103
+ checked against every source. Keeps the testing entry point free of other packages. */
104
+ async function simpleVerifySources(answer, sources, { nli }) {
105
+ const claims = String(answer).split(/(?<=[.!?])\s+|\n+/).map((c) => c.trim()).filter((c) => c && !/\?$/.test(c));
106
+ const claimsOut = [];
107
+ for (const claim of claims) {
108
+ const pairs = sources.map((premise) => ({ premise, hypothesis: claim }));
109
+ const scores = pairs.length ? await nli(pairs) : [];
110
+ const best = Math.max(0, ...scores.map((s) => s.entailment));
111
+ claimsOut.push({ category: best >= 0.5 ? 'SUPPORTED' : 'UNSUPPORTED', claim, source: null });
112
+ }
113
+ return { code: 'OK', claims: claimsOut, flags: [] };
114
+ }
115
+
116
+ module.exports = { createFakeModels, createMockGuards, createEventRecorder };
package/src/index.d.ts CHANGED
@@ -422,6 +422,10 @@ export interface ReversibleMasker {
422
422
  unmaskStream(chunks: AsyncIterable<unknown>): AsyncGenerator<string>;
423
423
  detectNames(text: string): Promise<string[]>;
424
424
  size(): number;
425
+ /** The table as JSON (it holds the real values: store it like the data it protects). */
426
+ snapshot(): unknown;
427
+ /** Put a table from `snapshot()` back, replacing what was known. */
428
+ restore(snapshot: unknown): void;
425
429
  }
426
430
 
427
431
  export function createReversibleMasker(options?: {
@@ -611,12 +615,41 @@ export function readWrittenToolCalls(text: string): Array<{ id: string; name: st
611
615
  /** Le raisonnement entre balises think retiré, même ouvert sans fin ou fermé sans ouverture. */
612
616
  export function withoutThinking(content: unknown): string;
613
617
 
618
+ /**
619
+ * La recherche Google intégrée de Gemini (outil `google_search`). Ignorée par
620
+ * les fournisseurs au format OpenAI.
621
+ * - 'combine' : la recherche part avec les fonctions de l'application ;
622
+ * - 'alone' : la recherche seule pour ce tour (les fonctions ne partent pas) ;
623
+ * - 'auto' : ensemble d'abord, puis la recherche seule si l'API refuse le mélange (400).
624
+ */
625
+ export type GoogleSearchOption = boolean | { functions?: 'auto' | 'combine' | 'alone' };
626
+
627
+ /** Une page citée par la recherche : titre (une ligne, bornée) et adresse http(s). Données non fiables. */
628
+ export interface GroundingSource {
629
+ title: string;
630
+ url: string;
631
+ }
632
+
633
+ /** Les sources d'une réponse Gemini avec recherche Google. */
634
+ export interface GeminiGrounding {
635
+ /** Vrai quand le modèle a vraiment cherché (requêtes ou pages). */
636
+ searched: boolean;
637
+ /** Les recherches faites, dédoublonnées, au plus 10. */
638
+ queries: string[];
639
+ /** Les pages, dédoublonnées par adresse, au plus 20. */
640
+ sources: GroundingSource[];
641
+ /** Les suggestions de recherche que Google demande d'afficher (HTML tel que rendu par l'API), ou null. */
642
+ searchSuggestionsHtml: string | null;
643
+ }
644
+
614
645
  export interface ChatRequest {
615
646
  system?: string;
616
647
  messages: ChatMessage[];
617
648
  tools?: Array<Record<string, unknown>>;
618
649
  maxTokens?: number;
619
650
  temperature?: number;
651
+ /** Gemini seulement : active la recherche Google intégrée pour cette requête. */
652
+ googleSearch?: GoogleSearchOption;
620
653
  }
621
654
 
622
655
  /** Ce qu'un fournisseur `detailed` rend au routeur. */
@@ -624,6 +657,8 @@ export interface DetailedAnswer {
624
657
  text: string | null;
625
658
  toolCalls: ChatToolCall[];
626
659
  cut: boolean;
660
+ /** Présent quand la requête demandait `googleSearch` à un fournisseur Gemini. */
661
+ grounding?: GeminiGrounding & { functionsDropped: boolean };
627
662
  }
628
663
 
629
664
  export interface ChatProviderOptions {
@@ -651,7 +686,10 @@ export function askGeminiModel(
651
686
  model: string,
652
687
  request: ChatRequest,
653
688
  io: { key: string; fetch: FetchLike; signal?: AbortSignal; timeoutMs?: number; endpoint?: string; noSystemInstruction?: (model: string) => boolean; extra?: Record<string, unknown> }
654
- ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number }>;
689
+ ): Promise<{ status: number; text?: string | null; toolCalls?: ChatToolCall[]; cut?: boolean; retryAfterMs?: number; grounding?: GeminiGrounding & { functionsDropped: boolean } }>;
690
+
691
+ /** Les sources d'une réponse generateContent (ou d'un de ses candidats), nettoyées et bornées. Ne lève jamais. */
692
+ export function readGeminiGrounding(answer: unknown): GeminiGrounding;
655
693
 
656
694
  export function createGeminiProvider(options: ChatProviderOptions & {
657
695
  id?: string;
package/src/masking.js CHANGED
@@ -248,6 +248,37 @@ function createReversibleMasker(options = {}) {
248
248
  return 0;
249
249
  }
250
250
 
251
+ /**
252
+ * The table as plain JSON, to keep a run across a restart. It holds the real
253
+ * values (that is what lets the answer be unmasked), so store it like the
254
+ * data it protects.
255
+ */
256
+ function snapshot() {
257
+ return {
258
+ version: 1,
259
+ sequence,
260
+ tokens: [...byToken.entries()],
261
+ loose: [...loose],
262
+ register: [...register],
263
+ types: [...typeOverride.entries()]
264
+ };
265
+ }
266
+
267
+ /** Put a table from `snapshot()` back; what was known before is replaced. */
268
+ function restore(state) {
269
+ const list = (value) => Array.isArray(value) && value.every((item) => item !== null && item !== undefined);
270
+ if (!state || state.version !== 1 || !Number.isInteger(state.sequence) || !list(state.tokens) || !list(state.loose) || !list(state.register) || !list(state.types)
271
+ || ![...state.tokens, ...state.types].every((pair) => Array.isArray(pair) && pair.length === 2 && pair.every((part) => typeof part === 'string'))) {
272
+ throw new TypeError('createReversibleMasker: invalid snapshot.');
273
+ }
274
+ byToken.clear(); byValue.clear(); loose.clear(); register.clear(); typeOverride.clear();
275
+ for (const [token, value] of state.tokens) { byToken.set(token, value); byValue.set(value, token); }
276
+ for (const value of state.loose) loose.add(value);
277
+ for (const value of state.register) register.add(value);
278
+ for (const [value, type] of state.types) typeOverride.set(value, type);
279
+ sequence = state.sequence;
280
+ }
281
+
251
282
  return {
252
283
  mask,
253
284
  maskAsync,
@@ -257,7 +288,9 @@ function createReversibleMasker(options = {}) {
257
288
  unmaskStream,
258
289
  detectNames,
259
290
  /** How many values are masked so far — never the values. */
260
- size: () => byToken.size
291
+ size: () => byToken.size,
292
+ snapshot,
293
+ restore
261
294
  };
262
295
  }
263
296
 
@@ -107,7 +107,14 @@ function providerResult(id, answer, detailed) {
107
107
  if (answer.retryAfterMs != null) failure.retryAfterMs = answer.retryAfterMs;
108
108
  throw failure;
109
109
  }
110
- if (detailed) return { text: answer.text === undefined ? null : answer.text, toolCalls: answer.toolCalls || [], cut: Boolean(answer.cut) };
110
+ if (detailed) {
111
+ return {
112
+ text: answer.text === undefined ? null : answer.text,
113
+ toolCalls: answer.toolCalls || [],
114
+ cut: Boolean(answer.cut),
115
+ ...(answer.grounding ? { grounding: answer.grounding } : {})
116
+ };
117
+ }
111
118
  if (answer.toolCalls && answer.toolCalls.length) return { toolCalls: answer.toolCalls };
112
119
  if (!answer.text) {
113
120
  const empty = new Error(`Provider "${id}" gave no text.`);