@astratra/ai 1.6.0 → 1.8.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/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Astratra
3
+ Copyright (c) 2026 Astratra contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -4,12 +4,77 @@ Routing IA multi-provider générique, registre d'outils et une boucle
4
4
  d'agent minimale à tool-calling. Dépend de `@astratra/core`.
5
5
 
6
6
  Ce package ne fournit volontairement aucun catalogue de modèles, aucun SDK
7
- provider, aucun outil métier — tout ça vient du projet consommateur. Ce
7
+ provider, aucun outil métier — tout ça vient du projet consommateur. Le routeur
8
+ configuré, les clients de modèles locaux et les services vocaux ci-dessous
9
+ partagent désormais les mécanismes utilisés par deux assistants d'IA en production. Ce
8
10
  qu'il fournit, c'est le mécanisme durement acquis : suivi de quota, ordre de
9
11
  fallback, cooldown/dégradation, deux adaptateurs HTTP sans dépendance (le
10
12
  format OpenAI et Gemini), et deux boucles d'agent (protocole écrit, ou
11
13
  appels d'outils natifs).
12
14
 
15
+ ## Gardes d'agent / Agent guards (`@astratra/ai/guards`)
16
+
17
+ Protections prêtes à brancher sur un agent, indépendantes du fournisseur d'IA.
18
+ Elles s'appuient sur le client de `@astratra/models` **injecté** (`models`) :
19
+ aucune dépendance dure. `@astratra/rag` (`verifySources`) est une dépendance
20
+ de pair facultative, ou s'injecte avec l'option `verifySources`.
21
+
22
+ ```js
23
+ const { recommendedGuards } = require('@astratra/ai/guards');
24
+ const { createModelsClient, assertModelsReady } = require('@astratra/models');
25
+
26
+ assertModelsReady({ required: ['entities', 'injection', 'moderation', 'nli'] }); // en production, refuse de partir sans les modèles
27
+ const guards = recommendedGuards({ models: createModelsClient({ token: () => process.env.MODELS_TOKEN }), onEvent: log });
28
+
29
+ const run = guards.newRun(); // une par conversation ou exécution d'agent
30
+ const safe = await guards.input(question, run); // noms et données personnelles masqués, réversible
31
+ if (safe.decision === 'block') return refuse();
32
+ // ... l'agent appelle ses outils ...
33
+ const seen = await guards.toolResult(page, run, { tool: 'web_search', external: true });
34
+ messages.push({ role: 'tool', content: seen.content }); // masqué, encadré comme donnée non fiable
35
+ const action = await guards.beforeAction({ name: 'send_email' }, run);
36
+ if (action.decision === 'block') askAHuman(); // après une injection suspectée : jamais sans humain
37
+ const reply = await guards.output(modelAnswer, run); // démasqué, puis ancrage, fuite, modération
38
+ ```
39
+
40
+ | Garde | Ce qu'elle fait |
41
+ |---|---|
42
+ | `input(text, run)` | masque les noms (détecteur d'entités + `names` du registre) et les données structurées (e-mail, IBAN, carte, téléphone) ; le texte revient démasqué dans `output`. Rend `text: null` si elle bloque. |
43
+ | `toolResult(result, run, { tool, external })` | pour un résultat **externe** (ou marqué `{ untrusted: true, content }`) : détection d'injection (texte long lu par fenêtres, jamais passé sans contrôle), contenu encadré par des marqueurs à nonce comme *données non fiables*. Injection suspectée : `run.requiresConfirmation = true` pour tout le reste de l'exécution. |
44
+ | `output(text, run)` | démasque ; **ancrage** (chaque phrase contre les sources lues, NLI, via `verifySources` de rag) avec `groundingScore` et la liste `unsupported` ; **fuite** de données personnelles que la personne n'a pas données (`onLeak`: `block`, `redact`, `flag`) ; **modération**. |
45
+ | `beforeAction(action, run, { humanConfirmed })` | refuse toute action tant qu'une injection est suspectée et qu'aucun humain n'a confirmé (`humanConfirmed: true` vient de votre interface, jamais du modèle). |
46
+
47
+ **Panne** : `policy.failure = { action: 'failClosed', read: 'failClosed' }` par
48
+ défaut (bloquer et signaler). `failOpen` laisse passer en signalant
49
+ `degraded` ; `recommendedGuards({ readOnly: true })` l'applique à un agent qui
50
+ ne fait que lire. Le mode d'une exécution est `newRun({ mode: 'action' | 'read' })`.
51
+
52
+ **Événements** : chaque décision appelle `onEvent({ type: 'guard', guard, decision,
53
+ reasons, degraded, metrics, runId, mode, at })`. Ils ne contiennent jamais le
54
+ texte (ni saisie, ni résultat d'outil, ni réponse) : des nombres, des codes et
55
+ des noms de catégories. La réponse de `output` rend, elle, les phrases non
56
+ soutenues à l'appelant.
57
+
58
+ **Tests** : `@astratra/ai/guards/testing` fournit `createFakeModels` (un client
59
+ sans modèle : règles par mots-clés, pannes simulées), `createMockGuards` (les
60
+ vraies gardes sur ce client, avec un enregistreur d'événements) et
61
+ `createEventRecorder`.
62
+
63
+ Limites : les gardes réduisent le risque, elles ne le suppriment pas. Les
64
+ règles de fuite ne couvrent que les données structurées ; l'ancrage compte
65
+ aussi comme « non soutenues » des phrases de liaison ; la détection d'injection
66
+ lit un texte isolé.
67
+
68
+ English: ready-to-use guards for an agent, independent of the AI provider.
69
+ Inject the `@astratra/models` client as `models`; nothing is imported. `input`
70
+ masks names and personal data (reversible), `toolResult` scans untrusted
71
+ content for injection, frames it as untrusted data and, when an injection is
72
+ suspected, forbids every action without a human for the rest of the run
73
+ (`beforeAction`), `output` unmasks the reply and checks grounding against the
74
+ sources, personal-data leaks and moderation. Failure policy is `failClosed` for
75
+ actions by default, `failOpen` possible for read-only runs. Events never carry
76
+ the text. Mocks for tests: `@astratra/ai/guards/testing`.
77
+
13
78
  ## Routeur de providers
14
79
 
15
80
  ```js
@@ -260,10 +325,9 @@ plus élevé entre l'outil et les analyseurs l'emporte. Les appels à confirmer
260
325
  sont enregistrés par `pendingActions.propose()` et attendent l'approbation
261
326
  via le cycle de vie déjà fourni par `createPendingActions`.
262
327
 
263
- **Périmètre V0 — toujours volontairement exclu :** gestion d'images/vision.
264
- Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
265
- mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
266
- construire dans votre propre boucle, ou à couvrir dans un futur spec.
328
+ **Vision :** les adaptateurs HTTP et `runToolLoop` acceptent les images.
329
+ `createConfiguredRouter` les filtre selon les capacités déclarées. La boucle
330
+ textuelle historique `runAgentLoop` garde son protocole de texte.
267
331
 
268
332
  ## Un disjoncteur par fournisseur, jamais un pour tous
269
333
 
@@ -308,7 +372,7 @@ const { createReversibleMasker } = require('@astratra/ai');
308
372
  const masker = createReversibleMasker({
309
373
  names: registreDeLEcole, // sensible à la casse
310
374
  patterns: [{ type: 'EMAIL', pattern: /[\w.+-]+@[\w-]+\.[\w.]+/g }],
311
- detect: (texte) => serviceLocal.entites(texte), // NER local, jamais distant
375
+ detect: (texte) => serviceLocal.entities(texte, ['person']), // NER local, jamais distant
312
376
  });
313
377
 
314
378
  // Routeur : un fournisseur externe reçoit le texte masqué, la réponse revient démasquée
@@ -629,3 +693,345 @@ absente ou inconnue vaut **téléphone** : se tromper vers le petit coûte une l
629
693
  là où un tableau tenait, se tromper vers le grand coûte un tableau illisible.
630
694
  La règle `paragraphs` est **obligatoire** : un pack de langue qui ne l'a pas est
631
695
  refusé à la création, pas découvert sur un écran.
696
+
697
+ ## Configured routing (two production assistants)
698
+
699
+ `createConfiguredRouter` builds HTTP providers and routes by usage on top of
700
+ `createProviderRouter`. Existing exports and their defaults remain compatible.
701
+ The model catalogue belongs to your application: names, quotas and capabilities
702
+ are explicit configuration, not historical assumptions baked into the package.
703
+
704
+ ```js
705
+ const { createConfiguredRouter } = require('@astratra/ai');
706
+ const router = createConfiguredRouter({
707
+ providers: [
708
+ { id: 'groq', format: 'openai',
709
+ url: 'https://api.groq.com/openai/v1/chat/completions',
710
+ keys: () => [process.env.GROQ_API_KEY, process.env.GROQ_API_KEY_2],
711
+ models: [{ id: 'your-fast-model', rpm: 30, rpd: 1000, tpd: 200000,
712
+ complexity: ['simple', 'medium'], extra: { include_reasoning: false } }] },
713
+ { id: 'gemini', format: 'gemini',
714
+ url: 'https://generativelanguage.googleapis.com/v1beta/models',
715
+ keys: () => [process.env.GEMINI_API_KEY, process.env.GEMINI_API_KEY_2],
716
+ keysByUsage: { news: () => [process.env.GEMINI_NEWS_KEY] },
717
+ vision: true,
718
+ models: [{ id: 'your-vision-model', rpm: 10, rpd: 200 }] },
719
+ { id: 'ollama', format: 'openai', local: true,
720
+ url: 'http://127.0.0.1:11434/v1/chat/completions',
721
+ models: [{ id: 'your-local-model' }] }
722
+ ],
723
+ usages: {
724
+ quick: [{ provider: 'groq', model: 'your-fast-model' }, { provider: 'ollama', model: 'your-local-model' }],
725
+ chat: [{ provider: 'gemini', model: 'your-vision-model' }, { provider: 'groq', model: 'your-fast-model' }],
726
+ tools: [{ provider: 'groq', model: 'your-fast-model' }], // pilot is an alias list
727
+ json: [{ provider: 'groq', model: 'your-fast-model', extra: { response_format: { type: 'json_object' } } }],
728
+ vision: [{ provider: 'gemini', model: 'your-vision-model' }]
729
+ },
730
+ intentRouting: { report: { preferred: ['gemini:your-vision-model'] } },
731
+ quotaMargin: { rpm: 0.75, rpd: 0.90, tpd: 0.85 },
732
+ tokenBuffer: 1.2, cooldownMs: 120000, maxFailures: 3, degradedMs: 300000,
733
+ waitedTimeoutMs: 12000, backgroundTimeoutMs: 45000,
734
+ statePrefix: 'my-app:', whenAllCooling: 'skip'
735
+ });
736
+
737
+ const result = await router.route({
738
+ system: 'Answer from the supplied information.',
739
+ messages: [{ role: 'user', text: 'Compare these proposals.' }], maxTokens: 1200
740
+ }, { usage: 'chat', waitedOn: true, intent: 'report', signal });
741
+ // { value: { text, toolCalls, cut }, provider, model, key, stateKey,
742
+ // usage, complexity, partial, fallback }
743
+ await router.ask('Hello'); // detailed answer only
744
+ await router.getStats(); // async, counters and rests; never credentials
745
+ await router.reset(); // only state keys used by this router
746
+ router.stop(); // rejects subsequent calls; no owned DB connection
747
+ ```
748
+
749
+ Without `usage`, tools select `tools`, images select `vision`, explicit `json:
750
+ true` selects `json`, simple requests select `quick`, and the rest selects
751
+ `chat`. `estimateRequestComplexity` retains the word/keyword rules of the reference assistant (with
752
+ English equivalents); you can override `complexity`. Within a list, intent
753
+ preferences come first, then compatible complexity, then other models; preview
754
+ models come last. Without a usage list, provider/model declaration order is the
755
+ fallback order. Thus one assistant's Groq → Mistral → Gemini → Vercel → Ollama and
756
+ another assistant's distinct quick/chat/pilot orders are both expressible.
757
+
758
+ Model fields: `vision`, `visionOnly`, `complexity`, `extra`, `maxTokens`,
759
+ `maxInputTokens`, `noAnalytics`, `languages`, `preview`, `disabled`, `rpm`, `rpd`,
760
+ `tpd`. `exclude` uses `provider:model`. Declared models are required; unknown
761
+ candidates are ignored. Provider and candidate `extra` objects merge, with
762
+ candidate values taking precedence (nested values replace whole fields).
763
+ Gemini `extra` fields merge at the top of its JSON body. JSON usage is an
764
+ explicit selection, not a keyword guess or automatic validation: configure its
765
+ format through `extra` and/or supply `accepts`.
766
+
767
+ Images are filtered for every usage, including tool fallback. Vision capability
768
+ must be declared on the provider or model; `vision: false` on a model overrides
769
+ a provider's capability. With `reserveVision: true`, `visionOnly` models are
770
+ kept for images. `local: true` works without credentials and preserves the
771
+ existing masking boundary: only external providers receive masked requests.
772
+ Ollama uses `/v1/chat/completions`; `createLlamaCppProvider` remains available
773
+ for health, loading, streaming and direct llama.cpp calls.
774
+
775
+ Reservations happen atomically before sending. RPM uses a rolling 60-second
776
+ window; RPD/TPD reset on the UTC date. Quotas with no field are unlimited;
777
+ zero or a margin-rounded limit of zero forbids calls. Reservations include the
778
+ system prompt, transcript, tool schemas and output ceiling; explicit
779
+ `estimatedTokens` must already include the full call. Failed calls conservatively
780
+ keep their reservation. A 429 or 503 or timeout rests the credential/model;
781
+ three consecutive actual failures exclude it for five minutes. A 429 does not
782
+ count as an actual failure. Request errors 400/413/414/422 do not penalize health;
783
+ 404 excludes the model until `reset()`. Caller cancellation stops immediately
784
+ and does not mark a failure. `whenAllCooling: 'try'` can retry resting models
785
+ when all rest; it never bypasses quotas, exclusion or degradation.
786
+
787
+ Keys are deduplicated, re-read per request and tried in rotating order, with a
788
+ fallback to the next credential. State identifies credentials by ordinal
789
+ (`provider:model@key-1`), never by any part of a key. Replacing a credential in
790
+ one slot keeps that slot's existing accounting until it expires or is reset.
791
+ `keysByUsage` isolates dedicated pools (for example news from chat);
792
+ `keyLane(ctx)` identifies custom dynamic pools. Keys default to independent
793
+ quotas; set `sharedKeyQuotas: true` when they share one account's model quota.
794
+ All instances sharing a store must use the same pool order and state prefix.
795
+
796
+ `route` rejects empty answers and unknown tool names, keeps partial text as a
797
+ last resort, and trims it to whole sentences. If no tool-capable answer is
798
+ accepted, it retries the chat/vision list with `tools: []` and keeps the read
799
+ transcript. `fallbackWithoutTools: false` disables that retry. Tools are never
800
+ executed by the router. An agent can use `runToolLoop({ turn: async request => {
801
+ const r = await router.route(request); return { ...r.value, model: r.key }; },
802
+ ... })`. Business retrieval and source collection remain injected.
803
+
804
+ Errors have clean codes: `AI_NO_PROVIDER`, `AI_NO_MATCH`, `AI_UNAVAILABLE`,
805
+ `AI_STATE_UNAVAILABLE`, `AI_ROUTER_STOPPED`. State outages fail closed instead of
806
+ silently losing a distributed quota. Transport messages and credentials are
807
+ not included in these errors.
808
+
809
+ ### Injectable state: memory, Redis, PostgreSQL
810
+
811
+ ```js
812
+ const { createMemoryRoutingStore, createRedisRoutingStore,
813
+ createPostgresRoutingStore } = require('@astratra/ai');
814
+ const memory = createMemoryRoutingStore();
815
+ const redisStore = createRedisRoutingStore({ client: connectedRedis, prefix: 'app:ai:' });
816
+ const postgresStore = createPostgresRoutingStore({ pool, table: 'ai_routing_state' });
817
+ await postgresStore.initialize(); // explicit table creation, once during setup
818
+ const router = createConfiguredRouter({ ...config, store: postgresStore });
819
+ ```
820
+
821
+ Memory is local to a process unless you share the same object. Redis uses
822
+ optimistic CAS in Lua with a two-day TTL (configurable, at least one day), and
823
+ retries contention. PostgreSQL locks even first insertion using a transaction
824
+ advisory lock and stores JSONB. Connections and database drivers belong to the
825
+ consumer; the package does not connect, install a driver, or close their pool.
826
+ A custom Redis/PostgreSQL/other adapter implements:
827
+
828
+ ```ts
829
+ interface RoutingStateStore {
830
+ read(key: string): Promise<RoutingState | null>;
831
+ update<T>(key: string, change: (old: RoutingState | null) => {
832
+ state: RoutingState | null; value?: T;
833
+ }): Promise<T | undefined>;
834
+ }
835
+ ```
836
+
837
+ `update` must serialize each key across processes. The synchronous callback
838
+ must be side-effect free and may run multiple times. `state: null` deletes the
839
+ key. `read` returns an independent snapshot.
840
+
841
+ ### Environment configuration
842
+
843
+ `readAiConfigFromEnv({ env: process.env, prefix: 'IA_' })` reads only the supplied
844
+ object, never an `.env` file. `ARIA_` or another prefix works identically.
845
+
846
+ | Variable (default prefix) | Value |
847
+ | --- | --- |
848
+ | `IA_PROVIDERS` | JSON array of `{ id, format, url, local?, vision?, models, extra?, sharedKeyQuotas?, envName? }` |
849
+ | `IA_<ID>_URL`, `IA_<ID>_LOCAL` | Optional provider overrides; local accepts true/false/1/0 |
850
+ | `IA_<ID>_KEY`, `IA_<ID>_KEY_2` … | Keys, read at every request; sparse suffixes are supported; ID uppercased with non-alphanumeric characters replaced by `_` (or `envName`) |
851
+ | `IA_MODELS_QUICK`, `IA_MODELS_CHAT`, `IA_MODELS_TOOLS`, `IA_MODELS_PILOT`, `IA_MODELS_JSON`, `IA_MODELS_VISION` | JSON arrays of `{ provider, model, extra? }` |
852
+ | `IA_INTENT_ROUTING` | JSON object `{ intent: { preferred: ['provider:model'] } }` |
853
+ | `IA_QUOTA_MARGIN` | JSON number or object `{ rpm, rpd, tpd }`; defaults .75/.90/.85 |
854
+ | `IA_TOKEN_BUFFER` | Number; default 1.2 |
855
+ | `IA_WAITED_TIMEOUT_MS`, `IA_BACKGROUND_TIMEOUT_MS` | Defaults 12000/45000 |
856
+ | `IA_COOLDOWN_MS`, `IA_DEGRADED_MS`, `IA_MAX_FAILURES` | Defaults 120000/300000/3 |
857
+ | `IA_STATE_PREFIX`, `IA_WHEN_ALL_COOLING`, `IA_RESERVE_VISION` | Namespace, skip/try, true/false |
858
+ | `IA_MODELS_URL`, `IA_MODELS_TOKEN_FILE` | Optional local model server and its Bearer file |
859
+ | `IA_TTS_URL`, `IA_TTS_TOKEN_FILE` | Optional Piper server and Bearer file |
860
+ | `IA_LANGUAGE_URL`, `IA_LANGUAGE_TIMEOUT_MS` | Optional fastText server; default timeout 800 |
861
+ | `IA_GROQ_WHISPER_URL`, `IA_GROQ_WHISPER_MODELS` | Full endpoint, JSON model IDs; defaults Groq transcription endpoint and turbo/large-v3 |
862
+ | `IA_CLOUDFLARE_ACCOUNT_ID`, `IA_CLOUDFLARE_WHISPER_URL` | Account for the default Whisper run URL, or explicit full URL |
863
+ | `IA_GEMINI_TTS_ENDPOINT`, `IA_GEMINI_TTS_MODELS`, `IA_GEMINI_TTS_VOICE` | Models base URL, JSON model IDs, voice; defaults Gemini endpoint, gemini-2.5-flash-preview-tts, Aoede |
864
+
865
+ Voice uses `IA_GROQ_KEY[_N]`, `IA_CLOUDFLARE_KEY[_N]` and
866
+ `IA_GEMINI_KEY[_N]`. No provider catalogue is auto-created: `IA_PROVIDERS`
867
+ is required to configure text routing. Voice/local sections are returned as
868
+ `config.voice`, `config.localModels`, `config.language`. Inject the store in
869
+ code after reading the configuration. Invalid JSON is reported by variable
870
+ name only, never by its value. Endpoint/model defaults are configurable
871
+ protocol examples, not a claim that a model or free tier remains available.
872
+
873
+ ```js
874
+ const { readAiConfigFromEnv, createConfiguredRouter } = require('@astratra/ai');
875
+ const config = readAiConfigFromEnv({ prefix: 'ARIA_' });
876
+ const router = createConfiguredRouter({ ...config, store });
877
+ ```
878
+
879
+ ## Local models (HTTP protocol)
880
+
881
+ ```js
882
+ const { createLocalModelsClient } = require('@astratra/ai');
883
+ const models = createLocalModelsClient({
884
+ baseUrl: 'http://127.0.0.1:5007', tokenFile: '/etc/my-app/models-token',
885
+ onError: (error, route) => metrics.count(route, error.code)
886
+ });
887
+ await models.reclasser('question', ['passage']); // number[] | null
888
+ await models.nli([{ premisse: 'premise', hypothese: 'claim' }]); // comparer alias
889
+ await models.entites('Ada', ['person']); // UTF-16 spans
890
+ const vectors = await models.vecteurs(['text']); // vectors.modele/dimensions
891
+ await models.transcrire(pcm16Base64, { langue: 'fr', vocabulaire: '', timeoutMs: 15000 });
892
+ models.disponible('/vecteurs'); // available alias
893
+ ```
894
+
895
+ Without `baseUrl`, each operation returns `null` and availability is false.
896
+ Invalid input, malformed results, downtime or deadlines also return `null`;
897
+ `onError` receives a clean `AiServiceError` and route. Caller abort throws its
898
+ reason. Limits match the source server: 50 passages, 20 NLI pairs, entity text
899
+ 8000 UTF-16 units, 10 labels of 50 characters, 32 vector texts of 2000 characters,
900
+ and PCM16 mono 16kHz for .2–30 seconds, vocabulary 600 characters. Whisper accepts
901
+ fr/en/es/ln. Vector results must come from `bge-m3-onnx-int8`, 1024 dimensions
902
+ (configurable when the server's embedding space changes); mismatches are refused.
903
+
904
+ The Bearer file is cached for one minute, including concurrent reads. If a file
905
+ is explicitly configured but unreadable, calls fail closed; without a file no
906
+ authentication header is sent. The server receives `X-Delai-Ms`. Defaults per
907
+ route: rerank 1000ms, NLI/vector 1500ms, entities 800ms, transcription 15000ms.
908
+ Each route has its own three-failure/60-second circuit, with one recovery probe;
909
+ 4xx refusals do not open it. Python engines, ONNX runtimes and weights are not
910
+ bundled or downloaded by this client. A generic in-process embedding
911
+ and native voice primitives remain in `@astratra/rag` and `@astratra/voice`.
912
+
913
+ ## Transcription, speech and language
914
+
915
+ ```js
916
+ const { readAiConfigFromEnv, createTranscriptionService,
917
+ createSpeechService, createServiceLanguageDetector } = require('@astratra/ai');
918
+ const config = readAiConfigFromEnv({ prefix: 'IA_' });
919
+ const transcription = createTranscriptionService({ ...config.voice, localModels: config.localModels });
920
+ const heard = await transcription.transcribe({
921
+ audio: pcm16Bytes, format: 'pcm16', language: 'fr', vocabulary: '', signal,
922
+ allowRemote: false // optional: confidential calls remain on this machine
923
+ });
924
+ const speech = createSpeechService(config.voice);
925
+ const spoken = await speech.synthesize({ text: '**Hello**', language: 'en', signal });
926
+ // { audio: Buffer, format: 'wav', mimeType: 'audio/wav', sampleRate, channels,
927
+ // provider: 'piper' | 'gemini', model, fallback }
928
+ const language = createServiceLanguageDetector(config.language);
929
+ await language.reply('hello', 'fr'); // fastText first, then small-word heuristic
930
+ ```
931
+
932
+ Transcription tries local Whisper, then Groq (multipart with a WAV file for PCM),
933
+ then Cloudflare (raw file base64 in `{ audio }`, including `success:false` checks).
934
+ `format: 'pcm16'` is little-endian 16kHz mono; `'wav'` can use the local server
935
+ when it contains that same PCM format. `'file'` forwards compressed audio to
936
+ remote services; this client does not transcode it. Base64 or byte input works.
937
+ Local silence is a valid empty transcription and stops the chain. Low logprob,
938
+ stock subtitle hallucinations or repeated words are rejected; `stockPhrases`,
939
+ `noSpeechThreshold`, `logprobThreshold` are configurable. Remote language remains
940
+ `null` if the service did not identify it. Limits, timeouts, key rotation and
941
+ rests are enforced, and an aborted request never proceeds to the next provider.
942
+
943
+ Speech tries Gemini TTS first (online, rotating keys/models), then Piper `/tts`
944
+ (`{ text, lang }` → validated WAV) as the local fallback. `order: ['piper', 'gemini']`
945
+ reverses it; `allowRemote: false` keeps everything local. Gemini PCM is wrapped in a WAV header with the supplied
946
+ sample rate (24kHz by default), never mislabeled as an existing WAV file.
947
+ `speakableText` removes markup/emoji and limits text to 6000 characters;
948
+ `prepareText` can provide your app's pronunciation rules. A missing Piper
949
+ language rests only that language. Local timeout is 30s, Gemini timeout 45s;
950
+ keys/models rest for 120s after failure, configurable per provider. A whole
951
+ synthesis uses one provider. Native segmentation, prosody, AAC finishing and
952
+ voice caching are separate existing `@astratra/voice` primitives.
953
+
954
+ `AI_TRANSCRIPTION_UNAVAILABLE` and `AI_SPEECH_UNAVAILABLE` identify exhausted
955
+ chains; input errors use `AI_AUDIO_INPUT`/`AI_SPEECH_INPUT`. Unconfigured optional
956
+ services never initiate an implicit local request. Language supports fr/en/es
957
+ by default; custom word lists can extend it. Statistical confidence defaults to
958
+ 0.5, or 0.9 for fewer than three words; unsupported/uncertain results keep the
959
+ app language or a clear heuristic result.
960
+
961
+ ## Native tool risk and confirmation
962
+
963
+ ```js
964
+ validateNativeTools(tools, { requireSummary: true, requireRisk: true });
965
+ const ledger = createSourceLedger();
966
+ const exposure = { untrusted: false };
967
+ const callTool = createToolCaller({
968
+ tools, context: { userId }, timeoutMs: 20000, signal,
969
+ confirmationPolicy: { threshold: 'MEDIUM' }, exposure,
970
+ readsUntrusted: (tool, result) => tool.name === 'read_shared_page'
971
+ || result?.sources?.some((source) => source.kind === 'web'),
972
+ keep: ledger.keep,
973
+ record: async ({ tool, args, found }) => saveAction(tool.kind, args, found)
974
+ });
975
+ await runToolLoop({ system, messages, tools: toolSpecs(tools), turn, callTool,
976
+ maxTurns: 6, maxMs: 60000, signal,
977
+ finalInstruction: 'Answer now with what you have read: no more tools.' });
978
+ ledger.sources(); ledger.evidence();
979
+ ```
980
+
981
+ All new options are opt-in. `requireRisk` enforces LOW/MEDIUM/HIGH, LOW-only
982
+ standalone writes, and undo for LOW confirmation tools. Under a confirmation
983
+ policy, a `confirm` tool runs its preparation; MEDIUM/HIGH (or UNKNOWN),
984
+ untrusted exposure or a result's `confirm: true` wait and never run `perform`.
985
+ A LOW tool below the threshold can perform immediately, only with an undo
986
+ handler; `record` then receives its effective `kind: 'write'` and undo data.
987
+ The preparation must be read-only. Without a policy, the original behavior
988
+ remains: all `confirm` tools prepare and wait. `toolRiskOf` and
989
+ `waitsForToolConfirmation` expose the same decisions. Unknown risk always waits,
990
+ even under `'never'`; untrusted exposure also forces waiting.
991
+
992
+ `readsUntrusted` is application policy, not a fixed list of business tools. All
993
+ calls share `exposure`; subsequent tools see the reads already completed.
994
+ Tools in a parallel batch are concurrent: do not schedule a write alongside
995
+ an untrusted read when its decision depends on that read. Tool handlers must
996
+ honor their injected AbortSignal; timed-out preparation cannot subsequently
997
+ start `perform`. Existing source ledger, legacy registry risk policy/pending
998
+ actions, and loop budgets are reused. Loop `maxMs` is checked between turns;
999
+ model and tool deadlines bound individual operations, and the final no-tool
1000
+ turn remains allowed after the budget boundary.
1001
+
1002
+ ### Verification commands
1003
+
1004
+ ```sh
1005
+ cd packages/ai
1006
+ npm test -- --runInBand
1007
+ node scripts/verify-mutations.cjs
1008
+ cd ../..
1009
+ npm run typecheck
1010
+ ```
1011
+
1012
+ HTTP contract tests start only loopback servers. If the execution environment
1013
+ forbids sockets, `AI_TEST_TRANSPORT=memory` explicitly uses simulated HTTP
1014
+ responses for the new suites. That mode proves behavior and serialization,
1015
+ not actual socket transport; the existing socket suites still require loopback
1016
+ permission. No test makes a remote provider call.
1017
+
1018
+ Local configured providers also accept `maxConcurrent` (default 8) and
1019
+ `maxQueue` (default 20): inference is bounded and queued cancellation consumes
1020
+ no quota. The queue wait is bounded by the model deadline. `Retry-After`
1021
+ (seconds or HTTP date) takes precedence over the configured 429/503 rest;
1022
+ `cooldownJitterMs` (environment: `IA_COOLDOWN_JITTER_MS`, default 0) adds optional
1023
+ jitter only when no provider delay was announced. `readRetryAfter` and
1024
+ `createInferenceQueue` are available separately.
1025
+
1026
+ The local client also exposes English adapters: `rerank`/`embed` are aliases;
1027
+ `compare` maps `{ premise, hypothesis }` to `{ entailment, neutral,
1028
+ contradiction }`; `entities` maps UTF-16 spans to `{ text, type, start, end,
1029
+ score }`. They connect directly to existing package primitives:
1030
+
1031
+ ```js
1032
+ await rerankResults(query, found, { score: models.rerank });
1033
+ await findContradiction(answer, excerpts, { compare: models.compare });
1034
+ const masker = createReversibleMasker({
1035
+ detect: (text) => models.entities(text, ['person'])
1036
+ });
1037
+ ```
@@ -0,0 +1,4 @@
1
+ {
2
+ "main": "../src/guards/index.js",
3
+ "types": "../src/guards/index.d.ts"
4
+ }
@@ -0,0 +1,4 @@
1
+ {
2
+ "main": "../../src/guards/testing/index.js",
3
+ "types": "../../src/guards/testing/index.d.ts"
4
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.6.0",
4
- "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
3
+ "version": "1.8.0",
4
+ "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra, plus agent guards (@astratra/ai/guards): outbound masking, prompt-injection handling for untrusted tool results, reply checks.",
5
5
  "engines": {
6
6
  "node": ">=20"
7
7
  },
@@ -10,7 +10,8 @@
10
10
  "type": "commonjs",
11
11
  "files": [
12
12
  "src",
13
- "deploy"
13
+ "deploy",
14
+ "guards"
14
15
  ],
15
16
  "scripts": {
16
17
  "test": "jest"
@@ -25,7 +26,9 @@
25
26
  "ai",
26
27
  "agents",
27
28
  "llama.cpp",
28
- "cpu-inference"
29
+ "cpu-inference",
30
+ "guardrails",
31
+ "prompt-injection"
29
32
  ],
30
33
  "license": "MIT",
31
34
  "publishConfig": {
@@ -35,16 +38,36 @@
35
38
  "@astratra/core": "^1.0.0"
36
39
  },
37
40
  "peerDependencies": {
38
- "redis": ">=4"
41
+ "redis": ">=4",
42
+ "@astratra/rag": ">=1.0.0"
39
43
  },
40
44
  "peerDependenciesMeta": {
41
45
  "redis": {
42
46
  "optional": true
47
+ },
48
+ "@astratra/rag": {
49
+ "optional": true
43
50
  }
44
51
  },
45
52
  "devDependencies": {
46
53
  "@astratra/resilience": "^1.0.0",
47
54
  "jest": "30.4.2",
48
- "redis": "^4.7.0"
55
+ "redis": "^4.7.0",
56
+ "@astratra/rag": "^1.0.0"
57
+ },
58
+ "exports": {
59
+ ".": {
60
+ "types": "./src/index.d.ts",
61
+ "default": "./src/index.js"
62
+ },
63
+ "./guards": {
64
+ "types": "./src/guards/index.d.ts",
65
+ "default": "./src/guards/index.js"
66
+ },
67
+ "./guards/testing": {
68
+ "types": "./src/guards/testing/index.d.ts",
69
+ "default": "./src/guards/testing/index.js"
70
+ },
71
+ "./package.json": "./package.json"
49
72
  }
50
73
  }
@@ -0,0 +1,72 @@
1
+ 'use strict';
2
+
3
+ // Only reads the supplied environment object. Never opens an .env file.
4
+ function readAiConfigFromEnv({ env = process.env, prefix = 'IA_' } = {}) {
5
+ const read = (name) => env[prefix + name];
6
+ const json = (name, fallback) => {
7
+ if (!read(name)) return fallback;
8
+ try { return JSON.parse(read(name)); }
9
+ catch { throw new TypeError(`INVALID_AI_CONFIG_${name}`); }
10
+ };
11
+ const number = (name, fallback) => {
12
+ if (read(name) == null || read(name) === '') return fallback;
13
+ const value = Number(read(name));
14
+ if (!Number.isFinite(value) || value < 0) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
15
+ return value;
16
+ };
17
+ const boolean = (name, fallback) => {
18
+ if (!read(name)) return fallback;
19
+ if (!['true', 'false', '1', '0'].includes(read(name))) throw new TypeError(`INVALID_AI_CONFIG_${name}`);
20
+ return ['true', '1'].includes(read(name));
21
+ };
22
+ const providers = json('PROVIDERS', []);
23
+ if (!Array.isArray(providers)) throw new TypeError('INVALID_AI_CONFIG_PROVIDERS');
24
+ const usages = {};
25
+ for (const usage of ['quick', 'chat', 'tools', 'pilot', 'json', 'vision']) {
26
+ const list = json(`MODELS_${usage.toUpperCase()}`, undefined);
27
+ if (list !== undefined) {
28
+ if (!Array.isArray(list) || list.some((entry) => !entry?.provider || !entry.model)) throw new TypeError(`INVALID_AI_CONFIG_MODELS_${usage.toUpperCase()}`);
29
+ usages[usage] = list;
30
+ }
31
+ }
32
+ const config = {
33
+ providers: providers.map((provider) => {
34
+ const stem = provider.envName || provider.id?.toUpperCase().replace(/[^A-Z0-9]/g, '_');
35
+ if (!stem) throw new TypeError('INVALID_AI_CONFIG_PROVIDER_ID');
36
+ // Re-read keys at every request: settings screens can replace them live.
37
+ const keys = (ctx = {}) => readEnvironmentKeys(ctx.env || env, `${prefix}${stem}_KEY`);
38
+ return { ...provider, url: read(`${stem}_URL`) || provider.url, local: boolean(`${stem}_LOCAL`, provider.local), keys };
39
+ }),
40
+ usages,
41
+ intentRouting: json('INTENT_ROUTING', {}),
42
+ statePrefix: read('STATE_PREFIX') || 'routing:',
43
+ quotaMargin: json('QUOTA_MARGIN', { rpm: 0.75, rpd: 0.9, tpd: 0.85 }),
44
+ tokenBuffer: number('TOKEN_BUFFER', 1.2),
45
+ waitedTimeoutMs: number('WAITED_TIMEOUT_MS', 12000),
46
+ backgroundTimeoutMs: number('BACKGROUND_TIMEOUT_MS', 45000),
47
+ cooldownMs: number('COOLDOWN_MS', 120000),
48
+ cooldownJitterMs: number('COOLDOWN_JITTER_MS', 0),
49
+ degradedMs: number('DEGRADED_MS', 300000),
50
+ maxFailures: number('MAX_FAILURES', 3),
51
+ whenAllCooling: read('WHEN_ALL_COOLING') || 'skip',
52
+ reserveVision: boolean('RESERVE_VISION', false),
53
+ localModels: { baseUrl: read('MODELS_URL'), tokenFile: read('MODELS_TOKEN_FILE') },
54
+ language: { baseUrl: read('LANGUAGE_URL'), timeoutMs: number('LANGUAGE_TIMEOUT_MS', 800) },
55
+ voice: {
56
+ piper: { baseUrl: read('TTS_URL'), tokenFile: read('TTS_TOKEN_FILE') },
57
+ groq: { url: read('GROQ_WHISPER_URL') || 'https://api.groq.com/openai/v1/audio/transcriptions', keys: () => readEnvironmentKeys(env, prefix + 'GROQ_KEY'), models: json('GROQ_WHISPER_MODELS', ['whisper-large-v3-turbo', 'whisper-large-v3']) },
58
+ cloudflare: { url: read('CLOUDFLARE_WHISPER_URL') || (read('CLOUDFLARE_ACCOUNT_ID') ? `https://api.cloudflare.com/client/v4/accounts/${read('CLOUDFLARE_ACCOUNT_ID')}/ai/run/@cf/openai/whisper-large-v3-turbo` : undefined), keys: () => readEnvironmentKeys(env, prefix + 'CLOUDFLARE_KEY') },
59
+ gemini: { endpoint: read('GEMINI_TTS_ENDPOINT'), keys: () => readEnvironmentKeys(env, prefix + 'GEMINI_KEY'), models: json('GEMINI_TTS_MODELS', ['gemini-2.5-flash-preview-tts']), voice: read('GEMINI_TTS_VOICE') || 'Aoede' }
60
+ }
61
+ };
62
+ if (!['skip', 'try'].includes(config.whenAllCooling)) throw new TypeError('INVALID_AI_CONFIG_WHEN_ALL_COOLING');
63
+ return config;
64
+ }
65
+
66
+ function readEnvironmentKeys(env, name) {
67
+ // Sparse suffixes work as well; a missing _2 must not hide _3.
68
+ const names = Object.keys(env).filter((key) => key === name || (key.startsWith(name + '_') && /^\d+$/.test(key.slice(name.length + 1))))
69
+ .sort((a, b) => (a === name ? 0 : Number(a.slice(name.length + 1))) - (b === name ? 0 : Number(b.slice(name.length + 1))));
70
+ return [...new Set(names.map((key) => env[key]).filter((key) => typeof key === 'string' && key.trim()))];
71
+ }
72
+ module.exports = { readAiConfigFromEnv, readEnvironmentKeys };
package/src/gemini.js CHANGED
@@ -1,3 +1,4 @@
1
+ const { readRetryAfter } = require('./providerLimits');
1
2
  /**
2
3
  * L'API Gemini de Google (generateContent) : la même requête que le format
3
4
  * OpenAI (consigne, transcription, outils, photos), traduite dans la sienne,
@@ -80,10 +81,13 @@ async function askGeminiModel(model, request, io = {}) {
80
81
  const response = await io.fetch(`${io.endpoint || DEFAULT_ENDPOINT}/${model}:generateContent`, {
81
82
  method: 'POST',
82
83
  headers: { 'content-type': 'application/json', 'x-goog-api-key': io.key },
83
- body: JSON.stringify(requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault)),
84
+ body: JSON.stringify({ ...requestBody(model, request, io.noSystemInstruction || noSystemInstructionByDefault), ...(io.extra || {}) }),
84
85
  signal
85
86
  });
86
- if (!response.ok) return { status: response.status };
87
+ if (!response.ok) {
88
+ const retryAfterMs = readRetryAfter(response);
89
+ return { status: response.status, ...(retryAfterMs === null ? {} : { retryAfterMs }) };
90
+ }
87
91
  const answer = await response.json();
88
92
  const candidate = (answer && answer.candidates && answer.candidates[0]) || {};
89
93
  const parts = (candidate.content && candidate.content.parts) || [];
@@ -125,6 +129,7 @@ function createGeminiProvider(options = {}) {
125
129
  return {
126
130
  id,
127
131
  models: options.models || [],
132
+ ...(options.external === false ? { external: false } : {}),
128
133
  ...(typeof options.lane === 'function' ? { lane: options.lane } : {}),
129
134
  async available(ctx = {}) {
130
135
  return Boolean(await options.getKey(ctx));
@@ -142,7 +147,8 @@ function createGeminiProvider(options = {}) {
142
147
  signal: ctx.signal,
143
148
  timeoutMs: ctx.timeoutMs || options.timeoutMs,
144
149
  endpoint: options.endpoint,
145
- noSystemInstruction: options.noSystemInstruction
150
+ noSystemInstruction: options.noSystemInstruction,
151
+ extra: { ...(options.extra || {}), ...(model.extra || {}) }
146
152
  });
147
153
  return providerResult(id, answer, options.detailed);
148
154
  }