nexus-ai-pro 2.12.0 → 2.13.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.
Files changed (95) hide show
  1. package/API_STABILITY.md +25 -0
  2. package/CHANGELOG.md +69 -1
  3. package/README.md +10 -5
  4. package/dist/core/lifecycle.d.ts +3 -0
  5. package/dist/core/lifecycle.js +108 -5
  6. package/dist/core/nexus.d.ts +11 -1
  7. package/dist/core/nexus.js +54 -8
  8. package/dist/credentials/index.d.ts +179 -0
  9. package/dist/credentials/index.js +206 -0
  10. package/dist/embeddings/adapters.d.ts +3 -3
  11. package/dist/embeddings/adapters.js +16 -10
  12. package/dist/embeddings/engine.js +7 -2
  13. package/dist/embeddings/errors.d.ts +5 -1
  14. package/dist/embeddings/errors.js +3 -1
  15. package/dist/images/google.js +6 -1
  16. package/dist/images/manager.js +3 -0
  17. package/dist/images/openai.js +4 -1
  18. package/dist/images/operation.js +1 -0
  19. package/dist/providers/anthropic.js +11 -5
  20. package/dist/providers/azure-openai.js +1 -0
  21. package/dist/providers/cohere.d.ts +3 -2
  22. package/dist/providers/cohere.js +6 -4
  23. package/dist/providers/google.d.ts +3 -2
  24. package/dist/providers/google.js +9 -7
  25. package/dist/providers/openai.js +17 -7
  26. package/dist/residency/errors.d.ts +18 -0
  27. package/dist/residency/errors.js +18 -0
  28. package/dist/residency/index.d.ts +93 -0
  29. package/dist/residency/index.js +225 -0
  30. package/dist/router/failover.d.ts +13 -0
  31. package/dist/router/failover.js +26 -4
  32. package/dist/server/http.js +3 -0
  33. package/dist/server/regions.d.ts +88 -0
  34. package/dist/server/regions.js +167 -0
  35. package/dist/server/runs.d.ts +18 -0
  36. package/dist/server/runs.js +21 -2
  37. package/dist/server/server.js +3 -2
  38. package/dist/types/config.d.ts +5 -0
  39. package/dist/types/embeddings.d.ts +5 -0
  40. package/dist/types/images.d.ts +5 -0
  41. package/dist/types/lifecycle.d.ts +71 -0
  42. package/dist/types/residency.d.ts +66 -0
  43. package/dist/types/residency.js +1 -0
  44. package/dist/types/server.d.ts +6 -0
  45. package/dist/utils/scrub.d.ts +12 -0
  46. package/dist/utils/scrub.js +49 -0
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/dist-cjs/core/lifecycle.d.ts +3 -0
  50. package/dist-cjs/core/lifecycle.js +109 -5
  51. package/dist-cjs/core/nexus.d.ts +11 -1
  52. package/dist-cjs/core/nexus.js +53 -7
  53. package/dist-cjs/credentials/index.d.ts +179 -0
  54. package/dist-cjs/credentials/index.js +219 -0
  55. package/dist-cjs/embeddings/adapters.d.ts +3 -3
  56. package/dist-cjs/embeddings/adapters.js +16 -10
  57. package/dist-cjs/embeddings/engine.js +7 -2
  58. package/dist-cjs/embeddings/errors.d.ts +5 -1
  59. package/dist-cjs/embeddings/errors.js +3 -1
  60. package/dist-cjs/images/google.js +6 -1
  61. package/dist-cjs/images/manager.js +3 -0
  62. package/dist-cjs/images/openai.js +4 -1
  63. package/dist-cjs/images/operation.js +1 -0
  64. package/dist-cjs/providers/anthropic.js +11 -5
  65. package/dist-cjs/providers/azure-openai.js +1 -0
  66. package/dist-cjs/providers/cohere.d.ts +3 -2
  67. package/dist-cjs/providers/cohere.js +6 -4
  68. package/dist-cjs/providers/google.d.ts +3 -2
  69. package/dist-cjs/providers/google.js +9 -7
  70. package/dist-cjs/providers/openai.js +17 -7
  71. package/dist-cjs/residency/errors.d.ts +18 -0
  72. package/dist-cjs/residency/errors.js +22 -0
  73. package/dist-cjs/residency/index.d.ts +93 -0
  74. package/dist-cjs/residency/index.js +232 -0
  75. package/dist-cjs/router/failover.d.ts +13 -0
  76. package/dist-cjs/router/failover.js +26 -4
  77. package/dist-cjs/server/http.js +3 -0
  78. package/dist-cjs/server/regions.d.ts +88 -0
  79. package/dist-cjs/server/regions.js +170 -0
  80. package/dist-cjs/server/runs.d.ts +18 -0
  81. package/dist-cjs/server/runs.js +21 -2
  82. package/dist-cjs/server/server.js +3 -2
  83. package/dist-cjs/types/config.d.ts +5 -0
  84. package/dist-cjs/types/embeddings.d.ts +5 -0
  85. package/dist-cjs/types/images.d.ts +5 -0
  86. package/dist-cjs/types/lifecycle.d.ts +71 -0
  87. package/dist-cjs/types/residency.d.ts +66 -0
  88. package/dist-cjs/types/residency.js +2 -0
  89. package/dist-cjs/types/server.d.ts +6 -0
  90. package/dist-cjs/utils/scrub.d.ts +12 -0
  91. package/dist-cjs/utils/scrub.js +53 -0
  92. package/dist-cjs/version.d.ts +1 -1
  93. package/dist-cjs/version.js +1 -1
  94. package/llms.txt +2 -1
  95. package/package.json +40 -1
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Credentials per tenant: each provider's key resolved when a call is made, for the tenant it runs
3
+ * for, from a secret manager the application supplies, cached for a bounded time and rotated without
4
+ * a restart.
5
+ */
6
+ import type { CredentialRequest, CredentialResolver, OperationDescriptor, ProviderCredential } from '../types/lifecycle.js';
7
+ export type { CredentialRequest, CredentialResolver, ProviderCredential } from '../types/lifecycle.js';
8
+ /** Where secrets are read: a secret manager, the environment, or memory. */
9
+ export interface SecretSource {
10
+ /** The secret with this name, or `undefined` when there is none. Throws when the source cannot be read. */
11
+ get(name: string, options?: {
12
+ signal?: AbortSignal;
13
+ }): Promise<string | undefined> | string | undefined;
14
+ }
15
+ /** Raised when a call's credential cannot be resolved, so the call is refused rather than sent with another. */
16
+ export declare class CredentialError extends Error {
17
+ /** The provider the call was for. */
18
+ readonly provider: string;
19
+ /** The tenant it ran for. */
20
+ readonly tenantId?: string | undefined;
21
+ constructor(message: string,
22
+ /** The provider the call was for. */
23
+ provider: string,
24
+ /** The tenant it ran for. */
25
+ tenantId?: string | undefined, options?: {
26
+ cause?: unknown;
27
+ });
28
+ }
29
+ /** Options for `tenantCredentials()`. */
30
+ export interface TenantCredentialsOptions {
31
+ /** Where the secrets are. */
32
+ secrets: SecretSource;
33
+ /**
34
+ * The secret's name for a request. Defaults to `<tenant>/<provider>`, or `<provider>` for a call
35
+ * with no tenant.
36
+ */
37
+ name?: (request: CredentialRequest) => string;
38
+ /**
39
+ * Reads a secret into a credential. Defaults to a plain string as the key, or a JSON object with
40
+ * `apiKey` and `headers`.
41
+ */
42
+ parse?: (secret: string, request: CredentialRequest) => ProviderCredential;
43
+ /**
44
+ * What happens when a tenant has no secret: `refuse`, the default, fails the call with a
45
+ * `CredentialError`; `config` sends the provider's configured key. A call with no tenant always
46
+ * falls back to the configured key.
47
+ */
48
+ missing?: 'refuse' | 'config';
49
+ /** How long a resolved credential is reused, in milliseconds. Defaults to 5 minutes. */
50
+ cacheMs?: number;
51
+ /** How long a missing secret is remembered as missing, in milliseconds. Defaults to 30 seconds. */
52
+ missingCacheMs?: number;
53
+ /**
54
+ * When the source fails, keeps using a credential resolved before, for up to this long after it
55
+ * was due again, in milliseconds. Defaults to 1 hour; 0 fails the call instead.
56
+ */
57
+ staleMs?: number;
58
+ /** Most credentials cached at once. Defaults to 1,000. */
59
+ maxEntries?: number;
60
+ /** Hears each failure of the source, including those a stale credential covered. */
61
+ onError?: (error: unknown, request: CredentialRequest) => void;
62
+ /** Replaces the system clock, for tests. */
63
+ now?: () => number;
64
+ }
65
+ /** A credential resolver over a secret source, with `stats()` and a way to forget what it cached. */
66
+ export interface TenantCredentials extends CredentialResolver {
67
+ /** Forgets every cached credential, or those of one tenant, so the next calls read the source again. */
68
+ clear(tenantId?: string): void;
69
+ /** What the cache did: reads of the source, hits, stale credentials served, and refusals. */
70
+ stats(): TenantCredentialStats;
71
+ }
72
+ /** Counts from `TenantCredentials.stats()`. */
73
+ export interface TenantCredentialStats {
74
+ /** Times the source was read. */
75
+ reads: number;
76
+ /** Calls answered from the cache. */
77
+ hits: number;
78
+ /** Calls answered with a credential past its time, because the source failed. */
79
+ stale: number;
80
+ /** Calls refused for want of a credential. */
81
+ refused: number;
82
+ /** Credentials cached now. */
83
+ cached: number;
84
+ }
85
+ /**
86
+ * Resolves each provider's credential per tenant from a secret source, at call time: a key in the
87
+ * source is used from the next call that reads it, so a key rotated there takes over within
88
+ * `cacheMs`, at once after `clear()`, and at once for a call whose provider refused the old one.
89
+ * Concurrent calls for one credential share one read.
90
+ *
91
+ * ```ts
92
+ * const ai = new NexusAI({
93
+ * providers: { openai: { apiKey: process.env.OPENAI_KEY } },
94
+ * lifecycle: { credentials: tenantCredentials({ secrets: awsSecrets(new SecretsManager({})) }) },
95
+ * });
96
+ * await ai.complete({ model: 'gpt-5', tenantId: 'acme', messages }); // acme's own key
97
+ * ```
98
+ */
99
+ export declare function tenantCredentials(options: TenantCredentialsOptions): TenantCredentials;
100
+ /** A secret as a credential: a plain string is the key; a JSON object carries `apiKey` and `headers`. */
101
+ export declare function parseSecret(secret: string): ProviderCredential;
102
+ /**
103
+ * Secrets in environment variables: `acme/openai` is read from `ACME_OPENAI`, with `prefix`
104
+ * before it, such as `NEXUS_SECRET_`.
105
+ */
106
+ export declare function envSecrets(options?: {
107
+ prefix?: string;
108
+ env?: Record<string, string | undefined>;
109
+ }): SecretSource;
110
+ /** Secrets held in this process, which `set()` changes: for tests, and for keys an application rotates itself. */
111
+ export interface MemorySecrets extends SecretSource {
112
+ /** Stores or replaces a secret. */
113
+ set(name: string, value: string): void;
114
+ /** Removes a secret. */
115
+ delete(name: string): void;
116
+ }
117
+ /** Secrets held in this process. */
118
+ export declare function memorySecrets(initial?: Record<string, string>): MemorySecrets;
119
+ /** The part of AWS Secrets Manager's client a source needs, as `@aws-sdk/client-secrets-manager`'s `SecretsManager` has it. */
120
+ export interface AwsSecretsClient {
121
+ /** Reads one secret's current value. */
122
+ getSecretValue(input: {
123
+ SecretId: string;
124
+ VersionStage?: string;
125
+ }): Promise<{
126
+ SecretString?: string;
127
+ }>;
128
+ }
129
+ /** Secrets in AWS Secrets Manager, each named `<prefix><name>`. A secret that does not exist reads as none. */
130
+ export declare function awsSecrets(client: AwsSecretsClient, options?: {
131
+ prefix?: string;
132
+ }): SecretSource;
133
+ /** The part of Google Secret Manager's client a source needs, as `@google-cloud/secret-manager`'s has it. */
134
+ export interface GcpSecretsClient {
135
+ /** Reads one version of a secret. */
136
+ accessSecretVersion(request: {
137
+ name: string;
138
+ }): Promise<[{
139
+ payload?: {
140
+ data?: Uint8Array | string | null;
141
+ } | null;
142
+ }, ...unknown[]]>;
143
+ }
144
+ /**
145
+ * Secrets in Google Secret Manager under `projects/<project>/secrets/<name>/versions/<version>`. Names
146
+ * may hold only letters, digits, `-`, and `_`, so `/` becomes `-`.
147
+ */
148
+ export declare function gcpSecrets(client: GcpSecretsClient, options: {
149
+ project: string;
150
+ version?: string;
151
+ }): SecretSource;
152
+ /** The part of Azure Key Vault's client a source needs, as `@azure/keyvault-secrets`'s `SecretClient` has it. */
153
+ export interface AzureSecretsClient {
154
+ /** Reads one secret's current value. */
155
+ getSecret(name: string): Promise<{
156
+ value?: string;
157
+ }>;
158
+ }
159
+ /** Secrets in Azure Key Vault. Names may hold only letters, digits, and `-`, so anything else becomes `-`. */
160
+ export declare function azureSecrets(client: AzureSecretsClient): SecretSource;
161
+ /** Options for `vaultSecrets()`. */
162
+ export interface VaultSecretsOptions {
163
+ /** The Vault server, such as `https://vault.internal:8200`. */
164
+ address: string;
165
+ /** A token, or a function that returns the current one, for a token that is renewed. */
166
+ token: string | (() => string | Promise<string>);
167
+ /** The KV version 2 mount. Defaults to `secret`. */
168
+ mount?: string;
169
+ /** The field of the secret's data that holds the value. Defaults to `value`; with none present, the data as JSON. */
170
+ field?: string;
171
+ /** A Vault Enterprise namespace. */
172
+ namespace?: string;
173
+ /** Replaces the global `fetch`. */
174
+ fetch?: typeof globalThis.fetch;
175
+ }
176
+ /** Secrets in HashiCorp Vault's KV version 2 engine, over its HTTP API. A secret that does not exist reads as none. */
177
+ export declare function vaultSecrets(options: VaultSecretsOptions): SecretSource;
178
+ /** The parts of an operation a credential request names, for code that resolves one itself. */
179
+ export declare function credentialRequest(provider: string, operation: Pick<OperationDescriptor, 'family' | 'operation' | 'tenantId'>): CredentialRequest;
@@ -0,0 +1,206 @@
1
+ export class CredentialError extends Error {
2
+ provider;
3
+ tenantId;
4
+ constructor(message, provider, tenantId, options) {
5
+ super(message, options);
6
+ this.provider = provider;
7
+ this.tenantId = tenantId;
8
+ this.name = 'CredentialError';
9
+ }
10
+ }
11
+ export function tenantCredentials(options) {
12
+ const now = options.now ?? (() => Date.now());
13
+ const cacheMs = options.cacheMs ?? 5 * 60_000;
14
+ const missingCacheMs = options.missingCacheMs ?? 30_000;
15
+ const staleMs = options.staleMs ?? 60 * 60_000;
16
+ const maxEntries = Math.max(1, options.maxEntries ?? 1_000);
17
+ const nameOf = options.name ?? ((request) => (request.tenantId ? `${request.tenantId}/${request.provider}` : request.provider));
18
+ const parse = options.parse ?? parseSecret;
19
+ const cache = new Map();
20
+ const reading = new Map();
21
+ const counts = { reads: 0, hits: 0, stale: 0, refused: 0 };
22
+ const keyOf = (request) => `${request.tenantId ?? ''}\u0000${request.provider}`;
23
+ const keep = (key, entry) => {
24
+ cache.delete(key);
25
+ cache.set(key, entry);
26
+ while (cache.size > maxEntries)
27
+ cache.delete(cache.keys().next().value);
28
+ };
29
+ const read = async (request, key, previous) => {
30
+ counts.reads += 1;
31
+ try {
32
+ const secret = await options.secrets.get(nameOf(request));
33
+ const credential = secret === undefined || secret === '' ? undefined : parse(secret, request);
34
+ keep(key, { credential, dueAt: now() + (credential ? cacheMs : missingCacheMs) });
35
+ return credential;
36
+ }
37
+ catch (error) {
38
+ options.onError?.(error, request);
39
+ if (previous?.credential && staleMs > 0 && now() - previous.dueAt <= staleMs) {
40
+ counts.stale += 1;
41
+ return previous.credential;
42
+ }
43
+ throw new CredentialError(`The credential for ${request.provider}${request.tenantId ? ` for tenant ${request.tenantId}` : ''} could not be read`, request.provider, request.tenantId, { cause: error });
44
+ }
45
+ };
46
+ const resolver = {
47
+ async resolve(request) {
48
+ const key = keyOf(request);
49
+ const cached = cache.get(key);
50
+ let credential;
51
+ if (cached && cached.dueAt > now()) {
52
+ counts.hits += 1;
53
+ credential = cached.credential;
54
+ }
55
+ else {
56
+ let pending = reading.get(key);
57
+ if (!pending) {
58
+ pending = read(request, key, cached).finally(() => reading.delete(key));
59
+ reading.set(key, pending);
60
+ }
61
+ credential = await pending;
62
+ }
63
+ if (credential || request.tenantId === undefined || options.missing === 'config')
64
+ return credential;
65
+ counts.refused += 1;
66
+ throw new CredentialError(`Tenant ${request.tenantId} has no credential for ${request.provider}`, request.provider, request.tenantId);
67
+ },
68
+ invalidate(request) {
69
+ cache.delete(keyOf(request));
70
+ },
71
+ clear(tenantId) {
72
+ if (tenantId === undefined)
73
+ cache.clear();
74
+ else
75
+ for (const key of [...cache.keys()])
76
+ if (key.startsWith(`${tenantId}\u0000`))
77
+ cache.delete(key);
78
+ },
79
+ stats() {
80
+ return { ...counts, cached: cache.size };
81
+ },
82
+ };
83
+ return resolver;
84
+ }
85
+ export function parseSecret(secret) {
86
+ const text = secret.trim();
87
+ if (text.startsWith('{')) {
88
+ try {
89
+ const value = JSON.parse(text);
90
+ const headers = value.headers && typeof value.headers === 'object'
91
+ ? Object.fromEntries(Object.entries(value.headers).filter((entry) => typeof entry[1] === 'string'))
92
+ : undefined;
93
+ return {
94
+ ...(typeof value.apiKey === 'string' ? { apiKey: value.apiKey } : {}),
95
+ ...(headers && Object.keys(headers).length > 0 ? { headers } : {}),
96
+ };
97
+ }
98
+ catch {
99
+ }
100
+ }
101
+ return { apiKey: text };
102
+ }
103
+ export function envSecrets(options = {}) {
104
+ const env = options.env ?? globalThis.process?.env ?? {};
105
+ return {
106
+ get: (name) => env[`${options.prefix ?? ''}${name.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}`],
107
+ };
108
+ }
109
+ export function memorySecrets(initial = {}) {
110
+ const values = new Map(Object.entries(initial));
111
+ return {
112
+ get: (name) => values.get(name),
113
+ set: (name, value) => void values.set(name, value),
114
+ delete: (name) => void values.delete(name),
115
+ };
116
+ }
117
+ export function awsSecrets(client, options = {}) {
118
+ return {
119
+ async get(name) {
120
+ try {
121
+ return (await client.getSecretValue({ SecretId: `${options.prefix ?? ''}${name}` })).SecretString;
122
+ }
123
+ catch (error) {
124
+ if (errorName(error) === 'ResourceNotFoundException')
125
+ return undefined;
126
+ throw error;
127
+ }
128
+ },
129
+ };
130
+ }
131
+ export function gcpSecrets(client, options) {
132
+ return {
133
+ async get(name) {
134
+ const id = name.replace(/[^A-Za-z0-9_-]/g, '-');
135
+ try {
136
+ const [version] = await client.accessSecretVersion({
137
+ name: `projects/${options.project}/secrets/${id}/versions/${options.version ?? 'latest'}`,
138
+ });
139
+ const data = version.payload?.data;
140
+ if (data === undefined || data === null)
141
+ return undefined;
142
+ return typeof data === 'string' ? data : new TextDecoder().decode(data);
143
+ }
144
+ catch (error) {
145
+ if (error.code === 5)
146
+ return undefined;
147
+ throw error;
148
+ }
149
+ },
150
+ };
151
+ }
152
+ export function azureSecrets(client) {
153
+ return {
154
+ async get(name) {
155
+ try {
156
+ return (await client.getSecret(name.replace(/[^A-Za-z0-9-]/g, '-'))).value;
157
+ }
158
+ catch (error) {
159
+ const status = error.statusCode;
160
+ if (status === 404 || errorName(error) === 'SecretNotFound')
161
+ return undefined;
162
+ throw error;
163
+ }
164
+ },
165
+ };
166
+ }
167
+ export function vaultSecrets(options) {
168
+ const fetchImpl = options.fetch ?? globalThis.fetch;
169
+ return {
170
+ async get(name, getOptions) {
171
+ const token = typeof options.token === 'string' ? options.token : await options.token();
172
+ const path = name
173
+ .split('/')
174
+ .map((part) => encodeURIComponent(part))
175
+ .join('/');
176
+ const response = await fetchImpl(`${options.address.replace(/\/+$/, '')}/v1/${options.mount ?? 'secret'}/data/${path}`, {
177
+ headers: { 'x-vault-token': token, ...(options.namespace ? { 'x-vault-namespace': options.namespace } : {}) },
178
+ ...(getOptions?.signal ? { signal: getOptions.signal } : {}),
179
+ });
180
+ if (response.status === 404)
181
+ return undefined;
182
+ if (!response.ok)
183
+ throw new Error(`Vault answered ${response.status} reading a secret`);
184
+ const body = (await response.json());
185
+ const data = body.data?.data;
186
+ if (!data)
187
+ return undefined;
188
+ const value = data[options.field ?? 'value'];
189
+ if (typeof value === 'string')
190
+ return value;
191
+ return JSON.stringify(data);
192
+ },
193
+ };
194
+ }
195
+ function errorName(error) {
196
+ const named = error;
197
+ return typeof named?.name === 'string' ? named.name : typeof named?.code === 'string' ? named.code : undefined;
198
+ }
199
+ export function credentialRequest(provider, operation) {
200
+ return {
201
+ provider,
202
+ family: operation.family,
203
+ operation: operation.operation,
204
+ ...(operation.tenantId !== undefined ? { tenantId: operation.tenantId } : {}),
205
+ };
206
+ }
@@ -29,8 +29,8 @@ declare abstract class HttpEmbeddingProvider implements EmbeddingsProvider {
29
29
  abstract readonly info: EmbeddingProviderInfo;
30
30
  constructor(options?: EmbeddingAdapterOptions);
31
31
  abstract embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
32
- protected post(url: string, body: unknown, model: string, signal: AbortSignal): Promise<unknown>;
33
- protected authHeaders(): Record<string, string>;
32
+ protected post(url: string, body: unknown, model: string, signal: AbortSignal, context?: EmbeddingProviderCallContext): Promise<unknown>;
33
+ protected authHeaders(key: string | undefined): Record<string, string>;
34
34
  protected baseUrl(fallback: string): string;
35
35
  }
36
36
  /**
@@ -51,7 +51,7 @@ export declare class GoogleEmbeddingProvider extends HttpEmbeddingProvider {
51
51
  /** Provider name, capabilities, and models. */
52
52
  readonly info: EmbeddingProviderInfo;
53
53
  constructor(options?: EmbeddingAdapterOptions);
54
- protected authHeaders(): Record<string, string>;
54
+ protected authHeaders(key: string | undefined): Record<string, string>;
55
55
  /** Embeds a batch of inputs: texts, or parts with images, audio, and documents. */
56
56
  embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
57
57
  }
@@ -7,13 +7,19 @@ class HttpEmbeddingProvider {
7
7
  constructor(options = {}) {
8
8
  this.options = options;
9
9
  }
10
- async post(url, body, model, signal) {
10
+ async post(url, body, model, signal, context) {
11
11
  const fetchImpl = this.options.fetch ?? fetch;
12
+ const credential = await context?.credential?.(this.info.name);
12
13
  let response;
13
14
  try {
14
15
  response = await fetchImpl(url, {
15
16
  method: 'POST',
16
- headers: { 'content-type': 'application/json', ...this.authHeaders(), ...this.options.headers },
17
+ headers: {
18
+ 'content-type': 'application/json',
19
+ ...this.authHeaders(credential?.apiKey ?? this.options.apiKey),
20
+ ...this.options.headers,
21
+ ...credential?.headers,
22
+ },
17
23
  body: JSON.stringify(body),
18
24
  signal,
19
25
  });
@@ -25,8 +31,8 @@ class HttpEmbeddingProvider {
25
31
  throw await createProviderHttpError(this.info.name, model, response);
26
32
  return response.json();
27
33
  }
28
- authHeaders() {
29
- return this.options.apiKey ? { authorization: `Bearer ${this.options.apiKey}` } : {};
34
+ authHeaders(key) {
35
+ return key ? { authorization: `Bearer ${key}` } : {};
30
36
  }
31
37
  baseUrl(fallback) {
32
38
  return (this.options.baseUrl || fallback).replace(/\/$/, '');
@@ -70,7 +76,7 @@ export class OpenAIEmbeddingProvider extends HttpEmbeddingProvider {
70
76
  encoding_format: request.encodingFormat,
71
77
  user: request.user,
72
78
  ...request.providerOptions,
73
- }, request.model, context.signal));
79
+ }, request.model, context.signal, context));
74
80
  const data = payload.data;
75
81
  if (!Array.isArray(data))
76
82
  throw new EmbeddingProviderResponseError(this.info.name, 'the response carried no data');
@@ -102,8 +108,8 @@ export class GoogleEmbeddingProvider extends HttpEmbeddingProvider {
102
108
  },
103
109
  };
104
110
  }
105
- authHeaders() {
106
- return this.options.apiKey ? { 'x-goog-api-key': this.options.apiKey } : {};
111
+ authHeaders(key) {
112
+ return key ? { 'x-goog-api-key': key } : {};
107
113
  }
108
114
  async embed(request, context) {
109
115
  const model = request.model;
@@ -118,7 +124,7 @@ export class GoogleEmbeddingProvider extends HttpEmbeddingProvider {
118
124
  outputDimensionality: request.dimensions,
119
125
  ...request.providerOptions,
120
126
  })),
121
- }, model, context.signal));
127
+ }, model, context.signal, context));
122
128
  const embeddings = payload.embeddings;
123
129
  if (!Array.isArray(embeddings)) {
124
130
  throw new EmbeddingProviderResponseError(this.info.name, 'the response carried no embeddings');
@@ -165,7 +171,7 @@ export class CohereEmbeddingProvider extends HttpEmbeddingProvider {
165
171
  output_dimension: request.dimensions,
166
172
  truncate: request.truncate ? request.truncate.toUpperCase() : undefined,
167
173
  ...request.providerOptions,
168
- }, request.model, context.signal));
174
+ }, request.model, context.signal, context));
169
175
  const raw = payload.embeddings;
170
176
  const vectors = Array.isArray(raw) ? raw : raw?.float;
171
177
  if (!Array.isArray(vectors)) {
@@ -228,7 +234,7 @@ export class OllamaEmbeddingProvider extends HttpEmbeddingProvider {
228
234
  input: request.input,
229
235
  truncate: request.truncate === undefined ? undefined : request.truncate !== 'none',
230
236
  ...request.providerOptions,
231
- }, request.model, context.signal));
237
+ }, request.model, context.signal, context));
232
238
  if (!Array.isArray(payload.embeddings)) {
233
239
  throw new EmbeddingProviderResponseError(this.info.name, 'the response carried no embeddings');
234
240
  }
@@ -49,6 +49,7 @@ export class EmbeddingEngine {
49
49
  ...(request.model || this.config.defaultModel ? { model: request.model || this.config.defaultModel } : {}),
50
50
  ...(request.provider ? { provider: request.provider } : {}),
51
51
  ...(request.userId ? { userId: request.userId } : {}),
52
+ ...(request.tenantId ? { tenantId: request.tenantId } : {}),
52
53
  }, {
53
54
  route: () => {
54
55
  route = this.resolveRoute(request);
@@ -288,11 +289,14 @@ export class EmbeddingEngine {
288
289
  const providerName = fallback.provider || route.providerName;
289
290
  const provider = this.providers.get(providerName);
290
291
  const model = fallback.model || route.resolved.model;
291
- if (provider && takesMedia(resolveEmbeddingModel(model, this.config.models).capabilities, provider, inputs)) {
292
+ if (provider &&
293
+ (callContext.residency?.allows(providerName) ?? true) &&
294
+ takesMedia(resolveEmbeddingModel(model, this.config.models).capabilities, provider, inputs)) {
292
295
  attempts.push({ providerName, provider, model });
293
296
  }
294
297
  }
295
298
  const errors = [];
299
+ const failures = [];
296
300
  let used = 0;
297
301
  for (const attempt of attempts) {
298
302
  for (let retryIndex = 0; retryIndex <= (retry.enabled ? retry.maxRetries : 0); retryIndex += 1) {
@@ -306,6 +310,7 @@ export class EmbeddingEngine {
306
310
  if (isAbortError(error))
307
311
  throw error;
308
312
  used += 1;
313
+ failures.push(error);
309
314
  errors.push(`${attempt.providerName}/${attempt.model}: ${describe(error)}`);
310
315
  if (!retry.enabled || !isRetryable(error) || retryIndex >= retry.maxRetries)
311
316
  break;
@@ -314,7 +319,7 @@ export class EmbeddingEngine {
314
319
  }
315
320
  }
316
321
  onRetries(Math.max(0, used - 1));
317
- throw new EmbeddingProviderError(`All embedding attempts failed: ${errors.join(' | ')}`, route.providerName, errors);
322
+ throw new EmbeddingProviderError(`All embedding attempts failed: ${errors.join(' | ')}`, route.providerName, errors, failures);
318
323
  }
319
324
  async callProvider(batch, inputs, batchIndex, attempt, request, callContext, attemptNumber) {
320
325
  const timeoutMs = request.timeoutMs ?? this.config.timeoutMs;
@@ -18,9 +18,13 @@ export declare class EmbeddingValidationError extends EmbeddingError {
18
18
  export declare class EmbeddingProviderError extends EmbeddingError {
19
19
  /** The provider. */
20
20
  readonly provider?: string | undefined;
21
+ /** Each attempt's error, in order, when every attempt failed. */
22
+ readonly attempts?: readonly unknown[] | undefined;
21
23
  constructor(message: string,
22
24
  /** The provider. */
23
- provider?: string | undefined, cause?: unknown);
25
+ provider?: string | undefined, cause?: unknown,
26
+ /** Each attempt's error, in order, when every attempt failed. */
27
+ attempts?: readonly unknown[] | undefined);
24
28
  }
25
29
  /** Raised when no provider, or no provider by the requested name, is registered. */
26
30
  export declare class EmbeddingProviderNotFoundError extends EmbeddingProviderError {
@@ -16,9 +16,11 @@ export class EmbeddingValidationError extends EmbeddingError {
16
16
  }
17
17
  export class EmbeddingProviderError extends EmbeddingError {
18
18
  provider;
19
- constructor(message, provider, cause) {
19
+ attempts;
20
+ constructor(message, provider, cause, attempts) {
20
21
  super(message, 'EMBEDDING_PROVIDER_ERROR', cause);
21
22
  this.provider = provider;
23
+ this.attempts = attempts;
22
24
  this.name = 'EmbeddingProviderError';
23
25
  }
24
26
  }
@@ -122,10 +122,15 @@ export class GoogleImageProvider {
122
122
  }
123
123
  const headers = new Headers(this.config.defaultHeaders);
124
124
  headers.set('content-type', 'application/json');
125
- if (this.config.accessToken)
125
+ const credential = await context.credential?.(this.info.name);
126
+ if (credential?.apiKey)
127
+ headers.set('x-goog-api-key', credential.apiKey);
128
+ else if (this.config.accessToken)
126
129
  headers.set('authorization', `Bearer ${this.config.accessToken}`);
127
130
  else if (this.config.apiKey)
128
131
  headers.set('x-goog-api-key', this.config.apiKey);
132
+ for (const [name, value] of Object.entries(credential?.headers ?? {}))
133
+ headers.set(name, value);
129
134
  let response;
130
135
  try {
131
136
  response = await this.fetchImplementation(`${this.baseUrl}/models/${encodeURIComponent(model)}:predict`, {
@@ -75,6 +75,9 @@ export class ImageManager {
75
75
  operation: `images.${submission.operation}`,
76
76
  model: submission.request.model,
77
77
  provider: submission.request.provider,
78
+ ...((submission.request.tenantId ?? this.config.tenantId)
79
+ ? { tenantId: submission.request.tenantId ?? this.config.tenantId }
80
+ : {}),
78
81
  requestId: submission.request.requestId ?? operationId,
79
82
  metadata: { count: submission.request.count },
80
83
  signal,
@@ -162,7 +162,10 @@ export class OpenAIImageProvider {
162
162
  throw new ImageProviderError('OpenAI image request deadline has already elapsed', 'openai');
163
163
  }
164
164
  const headers = new Headers(this.config.defaultHeaders);
165
- headers.set('authorization', `Bearer ${this.config.apiKey}`);
165
+ const credential = await context.credential?.(this.info.name);
166
+ headers.set('authorization', `Bearer ${credential?.apiKey ?? this.config.apiKey}`);
167
+ for (const [name, value] of Object.entries(credential?.headers ?? {}))
168
+ headers.set(name, value);
166
169
  if (this.config.organization)
167
170
  headers.set('openai-organization', this.config.organization);
168
171
  if (this.config.project)
@@ -6,6 +6,7 @@ export async function runImageOperation(state, submission, operationId, callCont
6
6
  validateRequest(operation, submission.request);
7
7
  const request = await resolveInputs(state, operation, submission.request, signal);
8
8
  const [registeredName, provider] = resolveProvider(state, operation, request.provider);
9
+ callContext.residency?.check(registeredName);
9
10
  assertCapabilities(registeredName, provider, operation, request);
10
11
  const context = { ...callContext, operationId };
11
12
  const startedAt = state.now();
@@ -301,7 +301,7 @@ export class AnthropicProvider extends BaseProvider {
301
301
  const client = await this.getClient();
302
302
  const startTime = Date.now();
303
303
  const params = this.createParams(providerRequest);
304
- const result = await client.messages.create(params, this.requestOptions(providerRequest, context));
304
+ const result = await client.messages.create(params, await this.requestOptions(providerRequest, context));
305
305
  const latency = Date.now() - startTime;
306
306
  let content = '';
307
307
  const toolCalls = [];
@@ -346,7 +346,7 @@ export class AnthropicProvider extends BaseProvider {
346
346
  const stream = client.messages.stream({
347
347
  ...self.createParams(providerRequest),
348
348
  stream: true,
349
- }, self.requestOptions(providerRequest, context));
349
+ }, await self.requestOptions(providerRequest, context));
350
350
  let usage = {};
351
351
  for await (const event of stream) {
352
352
  if (event.type === 'message_start') {
@@ -446,14 +446,20 @@ export class AnthropicProvider extends BaseProvider {
446
446
  .map((part) => part.text)
447
447
  .join('\n');
448
448
  }
449
- requestOptions(request, context) {
449
+ async requestOptions(request, context) {
450
450
  const options = {};
451
451
  if (request.signal)
452
452
  options.signal = request.signal;
453
453
  if (context?.idempotencyKey)
454
454
  options.idempotencyKey = context.idempotencyKey;
455
- if (context?.traceContext)
456
- options.headers = context.traceContext;
455
+ const credential = await context?.credential?.(this.info.name);
456
+ const headers = {
457
+ ...context?.traceContext,
458
+ ...credential?.headers,
459
+ ...(credential?.apiKey ? { 'x-api-key': credential.apiKey } : {}),
460
+ };
461
+ if (Object.keys(headers).length > 0)
462
+ options.headers = headers;
457
463
  return options.signal || options.idempotencyKey || options.headers ? options : undefined;
458
464
  }
459
465
  withProviderModel(request) {
@@ -15,6 +15,7 @@ export class AzureOpenAIProvider extends OpenAIProvider {
15
15
  },
16
16
  providerName: 'azure-openai',
17
17
  modelPrefix: ['azure-openai', 'azure'],
18
+ credentialHeader: 'api-key',
18
19
  });
19
20
  }
20
21
  }