@astratra/ai 1.6.0 → 1.7.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 CHANGED
@@ -4,7 +4,9 @@ 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 Oracle et Tertius. 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
@@ -260,10 +262,9 @@ plus élevé entre l'outil et les analyseurs l'emporte. Les appels à confirmer
260
262
  sont enregistrés par `pendingActions.propose()` et attendent l'approbation
261
263
  via le cycle de vie déjà fourni par `createPendingActions`.
262
264
 
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.
265
+ **Vision :** les adaptateurs HTTP et `runToolLoop` acceptent les images.
266
+ `createConfiguredRouter` les filtre selon les capacités déclarées. La boucle
267
+ textuelle historique `runAgentLoop` garde son protocole de texte.
267
268
 
268
269
  ## Un disjoncteur par fournisseur, jamais un pour tous
269
270
 
@@ -308,7 +309,7 @@ const { createReversibleMasker } = require('@astratra/ai');
308
309
  const masker = createReversibleMasker({
309
310
  names: registreDeLEcole, // sensible à la casse
310
311
  patterns: [{ type: 'EMAIL', pattern: /[\w.+-]+@[\w-]+\.[\w.]+/g }],
311
- detect: (texte) => serviceLocal.entites(texte), // NER local, jamais distant
312
+ detect: (texte) => serviceLocal.entities(texte, ['person']), // NER local, jamais distant
312
313
  });
313
314
 
314
315
  // Routeur : un fournisseur externe reçoit le texte masqué, la réponse revient démasquée
@@ -629,3 +630,345 @@ absente ou inconnue vaut **téléphone** : se tromper vers le petit coûte une l
629
630
  là où un tableau tenait, se tromper vers le grand coûte un tableau illisible.
630
631
  La règle `paragraphs` est **obligatoire** : un pack de langue qui ne l'a pas est
631
632
  refusé à la création, pas découvert sur un écran.
633
+
634
+ ## Configured routing (Oracle and Tertius)
635
+
636
+ `createConfiguredRouter` builds HTTP providers and routes by usage on top of
637
+ `createProviderRouter`. Existing exports and their defaults remain compatible.
638
+ The model catalogue belongs to your application: names, quotas and capabilities
639
+ are explicit configuration, not historical assumptions baked into the package.
640
+
641
+ ```js
642
+ const { createConfiguredRouter } = require('@astratra/ai');
643
+ const router = createConfiguredRouter({
644
+ providers: [
645
+ { id: 'groq', format: 'openai',
646
+ url: 'https://api.groq.com/openai/v1/chat/completions',
647
+ keys: () => [process.env.GROQ_API_KEY, process.env.GROQ_API_KEY_2],
648
+ models: [{ id: 'your-fast-model', rpm: 30, rpd: 1000, tpd: 200000,
649
+ complexity: ['simple', 'medium'], extra: { include_reasoning: false } }] },
650
+ { id: 'gemini', format: 'gemini',
651
+ url: 'https://generativelanguage.googleapis.com/v1beta/models',
652
+ keys: () => [process.env.GEMINI_API_KEY, process.env.GEMINI_API_KEY_2],
653
+ keysByUsage: { news: () => [process.env.GEMINI_NEWS_KEY] },
654
+ vision: true,
655
+ models: [{ id: 'your-vision-model', rpm: 10, rpd: 200 }] },
656
+ { id: 'ollama', format: 'openai', local: true,
657
+ url: 'http://127.0.0.1:11434/v1/chat/completions',
658
+ models: [{ id: 'your-local-model' }] }
659
+ ],
660
+ usages: {
661
+ quick: [{ provider: 'groq', model: 'your-fast-model' }, { provider: 'ollama', model: 'your-local-model' }],
662
+ chat: [{ provider: 'gemini', model: 'your-vision-model' }, { provider: 'groq', model: 'your-fast-model' }],
663
+ tools: [{ provider: 'groq', model: 'your-fast-model' }], // pilot is an alias list
664
+ json: [{ provider: 'groq', model: 'your-fast-model', extra: { response_format: { type: 'json_object' } } }],
665
+ vision: [{ provider: 'gemini', model: 'your-vision-model' }]
666
+ },
667
+ intentRouting: { report: { preferred: ['gemini:your-vision-model'] } },
668
+ quotaMargin: { rpm: 0.75, rpd: 0.90, tpd: 0.85 },
669
+ tokenBuffer: 1.2, cooldownMs: 120000, maxFailures: 3, degradedMs: 300000,
670
+ waitedTimeoutMs: 12000, backgroundTimeoutMs: 45000,
671
+ statePrefix: 'my-app:', whenAllCooling: 'skip'
672
+ });
673
+
674
+ const result = await router.route({
675
+ system: 'Answer from the supplied information.',
676
+ messages: [{ role: 'user', text: 'Compare these proposals.' }], maxTokens: 1200
677
+ }, { usage: 'chat', waitedOn: true, intent: 'report', signal });
678
+ // { value: { text, toolCalls, cut }, provider, model, key, stateKey,
679
+ // usage, complexity, partial, fallback }
680
+ await router.ask('Hello'); // detailed answer only
681
+ await router.getStats(); // async, counters and rests; never credentials
682
+ await router.reset(); // only state keys used by this router
683
+ router.stop(); // rejects subsequent calls; no owned DB connection
684
+ ```
685
+
686
+ Without `usage`, tools select `tools`, images select `vision`, explicit `json:
687
+ true` selects `json`, simple requests select `quick`, and the rest selects
688
+ `chat`. `estimateRequestComplexity` retains Oracle's word/keyword rules (with
689
+ English equivalents); you can override `complexity`. Within a list, intent
690
+ preferences come first, then compatible complexity, then other models; preview
691
+ models come last. Without a usage list, provider/model declaration order is the
692
+ fallback order. Thus Oracle's Groq → Mistral → Gemini → Vercel → Ollama and
693
+ Tertius's distinct quick/chat/pilot orders are both expressible.
694
+
695
+ Model fields: `vision`, `visionOnly`, `complexity`, `extra`, `maxTokens`,
696
+ `maxInputTokens`, `noAnalytics`, `languages`, `preview`, `disabled`, `rpm`, `rpd`,
697
+ `tpd`. `exclude` uses `provider:model`. Declared models are required; unknown
698
+ candidates are ignored. Provider and candidate `extra` objects merge, with
699
+ candidate values taking precedence (nested values replace whole fields).
700
+ Gemini `extra` fields merge at the top of its JSON body. JSON usage is an
701
+ explicit selection, not a keyword guess or automatic validation: configure its
702
+ format through `extra` and/or supply `accepts`.
703
+
704
+ Images are filtered for every usage, including tool fallback. Vision capability
705
+ must be declared on the provider or model; `vision: false` on a model overrides
706
+ a provider's capability. With `reserveVision: true`, `visionOnly` models are
707
+ kept for images. `local: true` works without credentials and preserves the
708
+ existing masking boundary: only external providers receive masked requests.
709
+ Ollama uses `/v1/chat/completions`; `createLlamaCppProvider` remains available
710
+ for health, loading, streaming and direct llama.cpp calls.
711
+
712
+ Reservations happen atomically before sending. RPM uses a rolling 60-second
713
+ window; RPD/TPD reset on the UTC date. Quotas with no field are unlimited;
714
+ zero or a margin-rounded limit of zero forbids calls. Reservations include the
715
+ system prompt, transcript, tool schemas and output ceiling; explicit
716
+ `estimatedTokens` must already include the full call. Failed calls conservatively
717
+ keep their reservation. A 429 or 503 or timeout rests the credential/model;
718
+ three consecutive actual failures exclude it for five minutes. A 429 does not
719
+ count as an actual failure. Request errors 400/413/414/422 do not penalize health;
720
+ 404 excludes the model until `reset()`. Caller cancellation stops immediately
721
+ and does not mark a failure. `whenAllCooling: 'try'` can retry resting models
722
+ when all rest; it never bypasses quotas, exclusion or degradation.
723
+
724
+ Keys are deduplicated, re-read per request and tried in rotating order, with a
725
+ fallback to the next credential. State identifies credentials by ordinal
726
+ (`provider:model@key-1`), never by any part of a key. Replacing a credential in
727
+ one slot keeps that slot's existing accounting until it expires or is reset.
728
+ `keysByUsage` isolates dedicated pools (for example news from chat);
729
+ `keyLane(ctx)` identifies custom dynamic pools. Keys default to independent
730
+ quotas; set `sharedKeyQuotas: true` when they share one account's model quota.
731
+ All instances sharing a store must use the same pool order and state prefix.
732
+
733
+ `route` rejects empty answers and unknown tool names, keeps partial text as a
734
+ last resort, and trims it to whole sentences. If no tool-capable answer is
735
+ accepted, it retries the chat/vision list with `tools: []` and keeps the read
736
+ transcript. `fallbackWithoutTools: false` disables that retry. Tools are never
737
+ executed by the router. An agent can use `runToolLoop({ turn: async request => {
738
+ const r = await router.route(request); return { ...r.value, model: r.key }; },
739
+ ... })`. Business retrieval and source collection remain injected.
740
+
741
+ Errors have clean codes: `AI_NO_PROVIDER`, `AI_NO_MATCH`, `AI_UNAVAILABLE`,
742
+ `AI_STATE_UNAVAILABLE`, `AI_ROUTER_STOPPED`. State outages fail closed instead of
743
+ silently losing a distributed quota. Transport messages and credentials are
744
+ not included in these errors.
745
+
746
+ ### Injectable state: memory, Redis, PostgreSQL
747
+
748
+ ```js
749
+ const { createMemoryRoutingStore, createRedisRoutingStore,
750
+ createPostgresRoutingStore } = require('@astratra/ai');
751
+ const memory = createMemoryRoutingStore();
752
+ const redisStore = createRedisRoutingStore({ client: connectedRedis, prefix: 'app:ai:' });
753
+ const postgresStore = createPostgresRoutingStore({ pool, table: 'ai_routing_state' });
754
+ await postgresStore.initialize(); // explicit table creation, once during setup
755
+ const router = createConfiguredRouter({ ...config, store: postgresStore });
756
+ ```
757
+
758
+ Memory is local to a process unless you share the same object. Redis uses
759
+ optimistic CAS in Lua with a two-day TTL (configurable, at least one day), and
760
+ retries contention. PostgreSQL locks even first insertion using a transaction
761
+ advisory lock and stores JSONB. Connections and database drivers belong to the
762
+ consumer; the package does not connect, install a driver, or close their pool.
763
+ A custom Redis/PostgreSQL/other adapter implements:
764
+
765
+ ```ts
766
+ interface RoutingStateStore {
767
+ read(key: string): Promise<RoutingState | null>;
768
+ update<T>(key: string, change: (old: RoutingState | null) => {
769
+ state: RoutingState | null; value?: T;
770
+ }): Promise<T | undefined>;
771
+ }
772
+ ```
773
+
774
+ `update` must serialize each key across processes. The synchronous callback
775
+ must be side-effect free and may run multiple times. `state: null` deletes the
776
+ key. `read` returns an independent snapshot.
777
+
778
+ ### Environment configuration
779
+
780
+ `readAiConfigFromEnv({ env: process.env, prefix: 'IA_' })` reads only the supplied
781
+ object, never an `.env` file. `ARIA_` or another prefix works identically.
782
+
783
+ | Variable (default prefix) | Value |
784
+ | --- | --- |
785
+ | `IA_PROVIDERS` | JSON array of `{ id, format, url, local?, vision?, models, extra?, sharedKeyQuotas?, envName? }` |
786
+ | `IA_<ID>_URL`, `IA_<ID>_LOCAL` | Optional provider overrides; local accepts true/false/1/0 |
787
+ | `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`) |
788
+ | `IA_MODELS_QUICK`, `IA_MODELS_CHAT`, `IA_MODELS_TOOLS`, `IA_MODELS_PILOT`, `IA_MODELS_JSON`, `IA_MODELS_VISION` | JSON arrays of `{ provider, model, extra? }` |
789
+ | `IA_INTENT_ROUTING` | JSON object `{ intent: { preferred: ['provider:model'] } }` |
790
+ | `IA_QUOTA_MARGIN` | JSON number or object `{ rpm, rpd, tpd }`; defaults .75/.90/.85 |
791
+ | `IA_TOKEN_BUFFER` | Number; default 1.2 |
792
+ | `IA_WAITED_TIMEOUT_MS`, `IA_BACKGROUND_TIMEOUT_MS` | Defaults 12000/45000 |
793
+ | `IA_COOLDOWN_MS`, `IA_DEGRADED_MS`, `IA_MAX_FAILURES` | Defaults 120000/300000/3 |
794
+ | `IA_STATE_PREFIX`, `IA_WHEN_ALL_COOLING`, `IA_RESERVE_VISION` | Namespace, skip/try, true/false |
795
+ | `IA_MODELS_URL`, `IA_MODELS_TOKEN_FILE` | Optional Scolaris model server and its Bearer file |
796
+ | `IA_TTS_URL`, `IA_TTS_TOKEN_FILE` | Optional Piper server and Bearer file |
797
+ | `IA_LANGUAGE_URL`, `IA_LANGUAGE_TIMEOUT_MS` | Optional fastText server; default timeout 800 |
798
+ | `IA_GROQ_WHISPER_URL`, `IA_GROQ_WHISPER_MODELS` | Full endpoint, JSON model IDs; defaults Groq transcription endpoint and turbo/large-v3 |
799
+ | `IA_CLOUDFLARE_ACCOUNT_ID`, `IA_CLOUDFLARE_WHISPER_URL` | Account for the default Whisper run URL, or explicit full URL |
800
+ | `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 |
801
+
802
+ Voice uses `IA_GROQ_KEY[_N]`, `IA_CLOUDFLARE_KEY[_N]` and
803
+ `IA_GEMINI_KEY[_N]`. No provider catalogue is auto-created: `IA_PROVIDERS`
804
+ is required to configure text routing. Voice/local sections are returned as
805
+ `config.voice`, `config.localModels`, `config.language`. Inject the store in
806
+ code after reading the configuration. Invalid JSON is reported by variable
807
+ name only, never by its value. Endpoint/model defaults are configurable
808
+ protocol examples, not a claim that a model or free tier remains available.
809
+
810
+ ```js
811
+ const { readAiConfigFromEnv, createConfiguredRouter } = require('@astratra/ai');
812
+ const config = readAiConfigFromEnv({ prefix: 'ARIA_' });
813
+ const router = createConfiguredRouter({ ...config, store });
814
+ ```
815
+
816
+ ## Local models (Scolaris HTTP protocol)
817
+
818
+ ```js
819
+ const { createLocalModelsClient } = require('@astratra/ai');
820
+ const models = createLocalModelsClient({
821
+ baseUrl: 'http://127.0.0.1:5007', tokenFile: '/etc/my-app/models-token',
822
+ onError: (error, route) => metrics.count(route, error.code)
823
+ });
824
+ await models.reclasser('question', ['passage']); // number[] | null
825
+ await models.nli([{ premisse: 'premise', hypothese: 'claim' }]); // comparer alias
826
+ await models.entites('Ada', ['person']); // UTF-16 spans
827
+ const vectors = await models.vecteurs(['text']); // vectors.modele/dimensions
828
+ await models.transcrire(pcm16Base64, { langue: 'fr', vocabulaire: '', timeoutMs: 15000 });
829
+ models.disponible('/vecteurs'); // available alias
830
+ ```
831
+
832
+ Without `baseUrl`, each operation returns `null` and availability is false.
833
+ Invalid input, malformed results, downtime or deadlines also return `null`;
834
+ `onError` receives a clean `AiServiceError` and route. Caller abort throws its
835
+ reason. Limits match the source server: 50 passages, 20 NLI pairs, entity text
836
+ 8000 UTF-16 units, 10 labels of 50 characters, 32 vector texts of 2000 characters,
837
+ and PCM16 mono 16kHz for .2–30 seconds, vocabulary 600 characters. Whisper accepts
838
+ fr/en/es/ln. Vector results must come from `bge-m3-onnx-int8`, 1024 dimensions
839
+ (configurable when the server's embedding space changes); mismatches are refused.
840
+
841
+ The Bearer file is cached for one minute, including concurrent reads. If a file
842
+ is explicitly configured but unreadable, calls fail closed; without a file no
843
+ authentication header is sent. The server receives `X-Delai-Ms`. Defaults per
844
+ route: rerank 1000ms, NLI/vector 1500ms, entities 800ms, transcription 15000ms.
845
+ Each route has its own three-failure/60-second circuit, with one recovery probe;
846
+ 4xx refusals do not open it. Python engines, ONNX runtimes and weights are not
847
+ bundled or downloaded by this client. Tertius's generic in-process embedding
848
+ and native voice primitives remain in `@astratra/rag` and `@astratra/voice`.
849
+
850
+ ## Transcription, speech and language
851
+
852
+ ```js
853
+ const { readAiConfigFromEnv, createTranscriptionService,
854
+ createSpeechService, createServiceLanguageDetector } = require('@astratra/ai');
855
+ const config = readAiConfigFromEnv({ prefix: 'IA_' });
856
+ const transcription = createTranscriptionService({ ...config.voice, localModels: config.localModels });
857
+ const heard = await transcription.transcribe({
858
+ audio: pcm16Bytes, format: 'pcm16', language: 'fr', vocabulary: '', signal,
859
+ allowRemote: false // optional: confidential calls remain on this machine
860
+ });
861
+ const speech = createSpeechService(config.voice);
862
+ const spoken = await speech.synthesize({ text: '**Hello**', language: 'en', signal });
863
+ // { audio: Buffer, format: 'wav', mimeType: 'audio/wav', sampleRate, channels,
864
+ // provider: 'piper' | 'gemini', model, fallback }
865
+ const language = createServiceLanguageDetector(config.language);
866
+ await language.reply('hello', 'fr'); // fastText first, then small-word heuristic
867
+ ```
868
+
869
+ Transcription tries local Whisper, then Groq (multipart with a WAV file for PCM),
870
+ then Cloudflare (raw file base64 in `{ audio }`, including `success:false` checks).
871
+ `format: 'pcm16'` is little-endian 16kHz mono; `'wav'` can use the local server
872
+ when it contains that same PCM format. `'file'` forwards compressed audio to
873
+ remote services; this client does not transcode it. Base64 or byte input works.
874
+ Local silence is a valid empty transcription and stops the chain. Low logprob,
875
+ stock subtitle hallucinations or repeated words are rejected; `stockPhrases`,
876
+ `noSpeechThreshold`, `logprobThreshold` are configurable. Remote language remains
877
+ `null` if the service did not identify it. Limits, timeouts, key rotation and
878
+ rests are enforced, and an aborted request never proceeds to the next provider.
879
+
880
+ Speech tries Gemini TTS first (online, rotating keys/models), then Piper `/tts`
881
+ (`{ text, lang }` → validated WAV) as the local fallback. `order: ['piper', 'gemini']`
882
+ reverses it; `allowRemote: false` keeps everything local. Gemini PCM is wrapped in a WAV header with the supplied
883
+ sample rate (24kHz by default), never mislabeled as an existing WAV file.
884
+ `speakableText` removes markup/emoji and limits text to 6000 characters;
885
+ `prepareText` can provide your app's pronunciation rules. A missing Piper
886
+ language rests only that language. Local timeout is 30s, Gemini timeout 45s;
887
+ keys/models rest for 120s after failure, configurable per provider. A whole
888
+ synthesis uses one provider. Native segmentation, prosody, AAC finishing and
889
+ voice caching are separate existing `@astratra/voice` primitives.
890
+
891
+ `AI_TRANSCRIPTION_UNAVAILABLE` and `AI_SPEECH_UNAVAILABLE` identify exhausted
892
+ chains; input errors use `AI_AUDIO_INPUT`/`AI_SPEECH_INPUT`. Unconfigured optional
893
+ services never initiate an implicit local request. Language supports fr/en/es
894
+ by default; custom word lists can extend it. Statistical confidence defaults to
895
+ 0.5, or 0.9 for fewer than three words; unsupported/uncertain results keep the
896
+ app language or a clear heuristic result.
897
+
898
+ ## Native tool risk and confirmation
899
+
900
+ ```js
901
+ validateNativeTools(tools, { requireSummary: true, requireRisk: true });
902
+ const ledger = createSourceLedger();
903
+ const exposure = { untrusted: false };
904
+ const callTool = createToolCaller({
905
+ tools, context: { userId }, timeoutMs: 20000, signal,
906
+ confirmationPolicy: { threshold: 'MEDIUM' }, exposure,
907
+ readsUntrusted: (tool, result) => tool.name === 'read_shared_page'
908
+ || result?.sources?.some((source) => source.kind === 'web'),
909
+ keep: ledger.keep,
910
+ record: async ({ tool, args, found }) => saveAction(tool.kind, args, found)
911
+ });
912
+ await runToolLoop({ system, messages, tools: toolSpecs(tools), turn, callTool,
913
+ maxTurns: 6, maxMs: 60000, signal,
914
+ finalInstruction: 'Answer now with what you have read: no more tools.' });
915
+ ledger.sources(); ledger.evidence();
916
+ ```
917
+
918
+ All new options are opt-in. `requireRisk` enforces LOW/MEDIUM/HIGH, LOW-only
919
+ standalone writes, and undo for LOW confirmation tools. Under a confirmation
920
+ policy, a `confirm` tool runs its preparation; MEDIUM/HIGH (or UNKNOWN),
921
+ untrusted exposure or a result's `confirm: true` wait and never run `perform`.
922
+ A LOW tool below the threshold can perform immediately, only with an undo
923
+ handler; `record` then receives its effective `kind: 'write'` and undo data.
924
+ The preparation must be read-only. Without a policy, the original behavior
925
+ remains: all `confirm` tools prepare and wait. `toolRiskOf` and
926
+ `waitsForToolConfirmation` expose the same decisions. Unknown risk always waits,
927
+ even under `'never'`; untrusted exposure also forces waiting.
928
+
929
+ `readsUntrusted` is application policy, not a fixed list of business tools. All
930
+ calls share `exposure`; subsequent tools see the reads already completed.
931
+ Tools in a parallel batch are concurrent: do not schedule a write alongside
932
+ an untrusted read when its decision depends on that read. Tool handlers must
933
+ honor their injected AbortSignal; timed-out preparation cannot subsequently
934
+ start `perform`. Existing source ledger, legacy registry risk policy/pending
935
+ actions, and loop budgets are reused. Loop `maxMs` is checked between turns;
936
+ model and tool deadlines bound individual operations, and the final no-tool
937
+ turn remains allowed after the budget boundary.
938
+
939
+ ### Verification commands
940
+
941
+ ```sh
942
+ cd packages/ai
943
+ npm test -- --runInBand
944
+ node scripts/verify-mutations.cjs
945
+ cd ../..
946
+ npm run typecheck
947
+ ```
948
+
949
+ HTTP contract tests start only loopback servers. If the execution environment
950
+ forbids sockets, `AI_TEST_TRANSPORT=memory` explicitly uses simulated HTTP
951
+ responses for the new suites. That mode proves behavior and serialization,
952
+ not actual socket transport; the existing socket suites still require loopback
953
+ permission. No test makes a remote provider call.
954
+
955
+ Local configured providers also accept `maxConcurrent` (default 8) and
956
+ `maxQueue` (default 20): inference is bounded and queued cancellation consumes
957
+ no quota. The queue wait is bounded by the model deadline. `Retry-After`
958
+ (seconds or HTTP date) takes precedence over the configured 429/503 rest;
959
+ `cooldownJitterMs` (environment: `IA_COOLDOWN_JITTER_MS`, default 0) adds optional
960
+ jitter only when no provider delay was announced. `readRetryAfter` and
961
+ `createInferenceQueue` are available separately.
962
+
963
+ The local client also exposes English adapters: `rerank`/`embed` are aliases;
964
+ `compare` maps `{ premise, hypothesis }` to `{ entailment, neutral,
965
+ contradiction }`; `entities` maps UTF-16 spans to `{ text, type, start, end,
966
+ score }`. They connect directly to existing package primitives:
967
+
968
+ ```js
969
+ await rerankResults(query, found, { score: models.rerank });
970
+ await findContradiction(answer, excerpts, { compare: models.compare });
971
+ const masker = createReversibleMasker({
972
+ detect: (text) => models.entities(text, ['person'])
973
+ });
974
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.6.0",
3
+ "version": "1.7.0",
4
4
  "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
5
5
  "engines": {
6
6
  "node": ">=20"
@@ -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
  }