nexus-ai-pro 2.13.0 → 2.14.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/API_STABILITY.md +30 -0
- package/CHANGELOG.md +44 -1
- package/README.md +11 -6
- package/dist/batch/anthropic.js +3 -1
- package/dist/batch/manager.d.ts +5 -0
- package/dist/batch/manager.js +25 -9
- package/dist/batch/openai-client.js +3 -1
- package/dist/cli/policy.d.ts +10 -0
- package/dist/cli/policy.js +116 -0
- package/dist/cli.js +15 -7
- package/dist/core/lifecycle.d.ts +23 -3
- package/dist/core/lifecycle.js +76 -13
- package/dist/core/nexus.d.ts +14 -14
- package/dist/core/nexus.js +26 -26
- package/dist/embeddings/batch-google.js +7 -1
- package/dist/embeddings/batch.d.ts +7 -0
- package/dist/embeddings/batch.js +32 -9
- package/dist/embeddings/engine.js +1 -1
- package/dist/evaluate/emulate.d.ts +143 -0
- package/dist/evaluate/emulate.js +214 -0
- package/dist/images/operation.js +1 -1
- package/dist/lifecycle/continue.d.ts +12 -0
- package/dist/lifecycle/continue.js +14 -0
- package/dist/media/index.d.ts +14 -1
- package/dist/media/index.js +16 -6
- package/dist/media/mistral.js +3 -1
- package/dist/policy/index.d.ts +184 -0
- package/dist/policy/index.js +490 -0
- package/dist/realtime/gemini-live.transport.js +3 -0
- package/dist/realtime/openai-websocket.transport.d.ts +1 -0
- package/dist/realtime/openai-websocket.transport.js +12 -7
- package/dist/realtime/session.js +8 -2
- package/dist/realtime/types.d.ts +8 -1
- package/dist/telephony/manager.js +21 -15
- package/dist/telephony/providers/telnyx.d.ts +14 -13
- package/dist/telephony/providers/telnyx.js +36 -20
- package/dist/telephony/providers/twilio.d.ts +18 -13
- package/dist/telephony/providers/twilio.js +48 -24
- package/dist/types/batch.d.ts +5 -0
- package/dist/types/config.d.ts +3 -1
- package/dist/types/lifecycle.d.ts +40 -0
- package/dist/types/residency.d.ts +19 -7
- package/dist/types/telephony.d.ts +26 -0
- package/dist/types/voice.d.ts +4 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/video/google.js +11 -2
- package/dist/video/index.d.ts +10 -0
- package/dist/video/index.js +39 -14
- package/dist/video/runway.js +4 -1
- package/dist/voice/manager.js +14 -2
- package/dist/voice/providers/openai.d.ts +3 -2
- package/dist/voice/providers/openai.js +9 -10
- package/dist-cjs/batch/anthropic.js +3 -1
- package/dist-cjs/batch/manager.d.ts +5 -0
- package/dist-cjs/batch/manager.js +25 -9
- package/dist-cjs/batch/openai-client.js +3 -1
- package/dist-cjs/cli/policy.d.ts +10 -0
- package/dist-cjs/cli/policy.js +122 -0
- package/dist-cjs/core/lifecycle.d.ts +23 -3
- package/dist-cjs/core/lifecycle.js +77 -13
- package/dist-cjs/core/nexus.d.ts +14 -14
- package/dist-cjs/core/nexus.js +34 -34
- package/dist-cjs/embeddings/batch-google.js +7 -1
- package/dist-cjs/embeddings/batch.d.ts +7 -0
- package/dist-cjs/embeddings/batch.js +32 -9
- package/dist-cjs/embeddings/engine.js +1 -1
- package/dist-cjs/evaluate/emulate.d.ts +143 -0
- package/dist-cjs/evaluate/emulate.js +221 -0
- package/dist-cjs/images/operation.js +1 -1
- package/dist-cjs/lifecycle/continue.d.ts +12 -0
- package/dist-cjs/lifecycle/continue.js +17 -0
- package/dist-cjs/media/index.d.ts +14 -1
- package/dist-cjs/media/index.js +16 -6
- package/dist-cjs/media/mistral.js +3 -1
- package/dist-cjs/policy/index.d.ts +184 -0
- package/dist-cjs/policy/index.js +500 -0
- package/dist-cjs/realtime/gemini-live.transport.js +3 -0
- package/dist-cjs/realtime/openai-websocket.transport.d.ts +1 -0
- package/dist-cjs/realtime/openai-websocket.transport.js +12 -7
- package/dist-cjs/realtime/session.js +8 -2
- package/dist-cjs/realtime/types.d.ts +8 -1
- package/dist-cjs/telephony/manager.js +21 -15
- package/dist-cjs/telephony/providers/telnyx.d.ts +14 -13
- package/dist-cjs/telephony/providers/telnyx.js +36 -20
- package/dist-cjs/telephony/providers/twilio.d.ts +18 -13
- package/dist-cjs/telephony/providers/twilio.js +48 -24
- package/dist-cjs/types/batch.d.ts +5 -0
- package/dist-cjs/types/config.d.ts +3 -1
- package/dist-cjs/types/lifecycle.d.ts +40 -0
- package/dist-cjs/types/residency.d.ts +19 -7
- package/dist-cjs/types/telephony.d.ts +26 -0
- package/dist-cjs/types/voice.d.ts +4 -0
- package/dist-cjs/version.d.ts +1 -1
- package/dist-cjs/version.js +1 -1
- package/dist-cjs/video/google.js +11 -2
- package/dist-cjs/video/index.d.ts +10 -0
- package/dist-cjs/video/index.js +39 -14
- package/dist-cjs/video/runway.js +4 -1
- package/dist-cjs/voice/manager.js +14 -2
- package/dist-cjs/voice/providers/openai.d.ts +3 -2
- package/dist-cjs/voice/providers/openai.js +9 -10
- package/llms.txt +3 -2
- package/package.json +27 -1
package/dist/core/nexus.d.ts
CHANGED
|
@@ -1,23 +1,23 @@
|
|
|
1
|
+
import { EmbeddingManager } from '../embeddings/manager.js';
|
|
2
|
+
import type { EvalCase, EvalRunResult } from '../evals/runner.js';
|
|
3
|
+
import type { SelfConsistencyOptions } from '../hallucination/consistency.js';
|
|
4
|
+
import type { VerificationOptions } from '../hallucination/verification.js';
|
|
5
|
+
import { ImageManager } from '../images/manager.js';
|
|
6
|
+
import { type BatchItemResult, type BatchOptions } from '../jobs/batch.js';
|
|
7
|
+
import { JobQueue, type QueueOptions } from '../jobs/queue.js';
|
|
8
|
+
import type { PipelineStep } from '../pipeline/types.js';
|
|
9
|
+
import type { BaseProvider } from '../providers/base.js';
|
|
10
|
+
import { TelephonyManager } from '../telephony/manager.js';
|
|
11
|
+
import type { AgentConfig, AgentResult } from '../types/agent.js';
|
|
1
12
|
import type { NexusAIConfig } from '../types/config.js';
|
|
13
|
+
import type { EmbeddingRequest, EmbeddingResponse, EmbeddingsProvider } from '../types/embeddings.js';
|
|
14
|
+
import type { ImageProvider } from '../types/images.js';
|
|
2
15
|
import type { CompletionRequest } from '../types/messages.js';
|
|
3
16
|
import type { NexusPlan } from '../types/planning.js';
|
|
4
17
|
import type { NexusResponse, NexusStream } from '../types/response.js';
|
|
5
|
-
import type { AgentConfig, AgentResult } from '../types/agent.js';
|
|
6
|
-
import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
|
|
7
|
-
import type { ImageProvider } from '../types/images.js';
|
|
8
|
-
import type { EmbeddingRequest, EmbeddingResponse, EmbeddingsProvider } from '../types/embeddings.js';
|
|
9
18
|
import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../types/telephony.js';
|
|
10
|
-
import type {
|
|
11
|
-
import type { BaseProvider } from '../providers/base.js';
|
|
19
|
+
import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
|
|
12
20
|
import type { VoiceSession } from '../voice/session.js';
|
|
13
|
-
import { ImageManager } from '../images/manager.js';
|
|
14
|
-
import { EmbeddingManager } from '../embeddings/manager.js';
|
|
15
|
-
import { TelephonyManager } from '../telephony/manager.js';
|
|
16
|
-
import type { VerificationOptions } from '../hallucination/verification.js';
|
|
17
|
-
import type { SelfConsistencyOptions } from '../hallucination/consistency.js';
|
|
18
|
-
import { type BatchOptions, type BatchItemResult } from '../jobs/batch.js';
|
|
19
|
-
import { JobQueue, type QueueOptions } from '../jobs/queue.js';
|
|
20
|
-
import type { EvalCase, EvalRunResult } from '../evals/runner.js';
|
|
21
21
|
import type { SummarizeVerifyFormatOptions, WorkflowResult } from '../workflow/chains.js';
|
|
22
22
|
import { OperationLifecycle } from './lifecycle.js';
|
|
23
23
|
/**
|
package/dist/core/nexus.js
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { Router, FailoverExecutor } from '../router/index.js';
|
|
4
|
-
import { Logger } from '../utils/logger.js';
|
|
5
|
-
import { SecurityPipeline } from '../security/index.js';
|
|
1
|
+
import { createCacheKey, MemoryCache } from '../cache/memory-cache.js';
|
|
2
|
+
import { negotiateCompletionRequest } from '../capabilities/negotiate.js';
|
|
6
3
|
import { ContextWindowManager } from '../context/index.js';
|
|
7
|
-
import { VoiceManager } from '../voice/manager.js';
|
|
8
|
-
import { ImageManager } from '../images/manager.js';
|
|
9
4
|
import { EmbeddingManager } from '../embeddings/manager.js';
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
5
|
+
import { ImageManager } from '../images/manager.js';
|
|
6
|
+
import { runBatch } from '../jobs/batch.js';
|
|
7
|
+
import { JobQueue } from '../jobs/queue.js';
|
|
12
8
|
import { resolveModel } from '../models/registry.js';
|
|
13
|
-
import { createCacheKey, MemoryCache } from '../cache/memory-cache.js';
|
|
14
|
-
import { applyResponseFormat, withResponseFormat } from './response-format.js';
|
|
15
|
-
import { protectStreamOutput } from './secure-stream.js';
|
|
16
9
|
import { AuditLogger } from '../ops/audit-logger.js';
|
|
10
|
+
import { CircuitBreaker } from '../ops/circuit-breaker.js';
|
|
11
|
+
import { ProviderHealthMonitor } from '../ops/health.js';
|
|
12
|
+
import { MetricsCollector } from '../ops/metrics.js';
|
|
17
13
|
import { RateLimiter } from '../ops/rate-limiter.js';
|
|
18
14
|
import { assertWithinCostBudget, estimateCost } from '../optimizer/cost.js';
|
|
19
|
-
import {
|
|
15
|
+
import { TokenOptimizer } from '../optimizer/index.js';
|
|
16
|
+
import { createPipelineContext, PipelineRunner } from '../pipeline/pipeline.js';
|
|
17
|
+
import { configuredProviders } from '../providers/lazy.js';
|
|
18
|
+
import { ResidencyError } from '../residency/errors.js';
|
|
19
|
+
import { FailoverExecutor, Router } from '../router/index.js';
|
|
20
|
+
import { SecurityPipeline } from '../security/index.js';
|
|
21
|
+
import { TelephonyManager } from '../telephony/manager.js';
|
|
22
|
+
import { Logger } from '../utils/logger.js';
|
|
23
|
+
import { VoiceManager } from '../voice/manager.js';
|
|
24
|
+
import { OperationLifecycle } from './lifecycle.js';
|
|
25
|
+
import { applyResponseFormat, withResponseFormat } from './response-format.js';
|
|
26
|
+
import { protectStreamOutput } from './secure-stream.js';
|
|
20
27
|
import { buildUsage, costAmount, priceUsage } from './usage.js';
|
|
21
|
-
import { PipelineRunner, createPipelineContext } from '../pipeline/pipeline.js';
|
|
22
|
-
import { MetricsCollector } from '../ops/metrics.js';
|
|
23
|
-
import { ProviderHealthMonitor } from '../ops/health.js';
|
|
24
|
-
import { CircuitBreaker } from '../ops/circuit-breaker.js';
|
|
25
|
-
import { runBatch } from '../jobs/batch.js';
|
|
26
|
-
import { JobQueue } from '../jobs/queue.js';
|
|
27
|
-
import { callResidency, OperationLifecycle } from './lifecycle.js';
|
|
28
28
|
export class NexusAI {
|
|
29
29
|
images;
|
|
30
30
|
lifecycle;
|
|
@@ -649,7 +649,7 @@ export class NexusAI {
|
|
|
649
649
|
const placed = [];
|
|
650
650
|
const seen = new Set();
|
|
651
651
|
for (const attempt of attempts) {
|
|
652
|
-
const where = residency.place(attempt.providerName);
|
|
652
|
+
const where = residency.place(attempt.providerName, attempt.model);
|
|
653
653
|
if (!where || !this.providers.has(where.provider))
|
|
654
654
|
continue;
|
|
655
655
|
const key = `${where.provider}\u0000${attempt.model}`;
|
|
@@ -660,7 +660,10 @@ export class NexusAI {
|
|
|
660
660
|
}
|
|
661
661
|
const [first, ...rest] = placed;
|
|
662
662
|
if (!first) {
|
|
663
|
-
residency.
|
|
663
|
+
const refused = residency.refusal?.(decision.providerName, decision.model);
|
|
664
|
+
if (refused)
|
|
665
|
+
throw refused;
|
|
666
|
+
residency.check(decision.providerName, decision.model);
|
|
664
667
|
throw new ResidencyError({ kind: 'provider', name: decision.providerName }, residency.decision, 'its twin is not registered');
|
|
665
668
|
}
|
|
666
669
|
const { providerName, model, ...limits } = first;
|
|
@@ -827,11 +830,8 @@ export class NexusAI {
|
|
|
827
830
|
contextWindowSummary: true,
|
|
828
831
|
},
|
|
829
832
|
};
|
|
830
|
-
const policy = this.config.lifecycle?.residency;
|
|
831
833
|
const routed = this.router.route(summaryRequest, this.config, this.providers, this.health.snapshot());
|
|
832
|
-
const decision =
|
|
833
|
-
? this.placeRoute(routed, callResidency(policy, await policy.regionsFor(summaryRequest.tenantId)))
|
|
834
|
-
: routed;
|
|
834
|
+
const decision = this.placeRoute(routed, await this.lifecycle.access(this.describe(summaryRequest, 'summarize')));
|
|
835
835
|
const routedRequest = { ...summaryRequest, model: resolveModel(decision.model, this.config).model };
|
|
836
836
|
const response = await this.lifecycle.run({ ...this.describe(routedRequest, 'summarize'), provider: decision.providerName }, {
|
|
837
837
|
execute: (callContext) => this.failover.complete(routedRequest, decision, this.providers, this.executionOptions(callContext)),
|
|
@@ -114,9 +114,15 @@ export class GoogleEmbeddingBatchProvider {
|
|
|
114
114
|
async request(path, init, context) {
|
|
115
115
|
const fetchImpl = this.options.fetch ?? fetch;
|
|
116
116
|
const base = (this.options.baseUrl ?? 'https://generativelanguage.googleapis.com/v1beta').replace(/\/+$/, '');
|
|
117
|
+
const credential = await context.credential?.(this.info.name);
|
|
117
118
|
const response = await fetchImpl(`${base}${path}`, {
|
|
118
119
|
...init,
|
|
119
|
-
headers: {
|
|
120
|
+
headers: {
|
|
121
|
+
'content-type': 'application/json',
|
|
122
|
+
'x-goog-api-key': credential?.apiKey ?? this.options.apiKey,
|
|
123
|
+
...this.options.headers,
|
|
124
|
+
...credential?.headers,
|
|
125
|
+
},
|
|
120
126
|
signal: context.signal,
|
|
121
127
|
});
|
|
122
128
|
const text = await response.text();
|
|
@@ -28,6 +28,11 @@ export interface EmbeddingBatchSubmitRequest {
|
|
|
28
28
|
completionWindow?: string;
|
|
29
29
|
/** Replays the operation accepted under this key instead of submitting a second batch. */
|
|
30
30
|
idempotencyKey?: string;
|
|
31
|
+
/**
|
|
32
|
+
* The tenant it runs for: its credentials, regions, and budget apply, and its ref records it, so
|
|
33
|
+
* every later call on the batch uses the tenant's key.
|
|
34
|
+
*/
|
|
35
|
+
tenantId?: string;
|
|
31
36
|
/** Labels attached to the batch on the provider's side. */
|
|
32
37
|
metadata?: Record<string, string>;
|
|
33
38
|
/** Overrides the manager's poll interval. */
|
|
@@ -189,6 +194,8 @@ export declare class EmbeddingBatchManager {
|
|
|
189
194
|
status(ref: BatchJobRef): Promise<BatchJobState>;
|
|
190
195
|
/** Cancels a batch. Throws when the adapter cannot cancel. */
|
|
191
196
|
cancel(ref: BatchJobRef): Promise<BatchJobState>;
|
|
197
|
+
/** A call on a batch outside its operation: with its tenant's key, inside its regions. */
|
|
198
|
+
private continuing;
|
|
192
199
|
private prepare;
|
|
193
200
|
private collect;
|
|
194
201
|
private price;
|
package/dist/embeddings/batch.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { BatchCapabilityError, BatchProviderNotFoundError, BatchValidationError } from '../batch/errors.js';
|
|
2
2
|
import { pollUntilSettled } from '../batch/poll.js';
|
|
3
|
+
import { continuing } from '../lifecycle/continue.js';
|
|
3
4
|
import { generateRequestId } from '../utils/ids.js';
|
|
4
5
|
import { Tokenizer } from '../utils/tokenizer.js';
|
|
5
6
|
import { acceptedModalities, normalizeInputs } from './inputs.js';
|
|
@@ -50,6 +51,7 @@ export class EmbeddingBatchManager {
|
|
|
50
51
|
requestId,
|
|
51
52
|
provider: providerName,
|
|
52
53
|
model: request.model,
|
|
54
|
+
...(request.tenantId !== undefined ? { tenantId: request.tenantId } : {}),
|
|
53
55
|
metadata: { items: request.items.length },
|
|
54
56
|
}, { signal: operation.signal, ...(request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {}) }, async (ticket) => {
|
|
55
57
|
const context = {
|
|
@@ -77,34 +79,51 @@ export class EmbeddingBatchManager {
|
|
|
77
79
|
async start(request) {
|
|
78
80
|
const [providerName, provider] = this.resolveProvider(request.provider);
|
|
79
81
|
const prepared = this.prepare(request, providerName, provider);
|
|
80
|
-
|
|
82
|
+
return this.continuing('embedding.batch.submit', providerName, request.model, request.tenantId, async (context) => withNotes(await provider.submit(prepared.request, {
|
|
83
|
+
...context,
|
|
81
84
|
requestId: generateRequestId(),
|
|
82
85
|
signal: request.signal ?? new AbortController().signal,
|
|
83
86
|
idempotencyKey: request.idempotencyKey,
|
|
84
87
|
attempt: 1,
|
|
85
|
-
});
|
|
86
|
-
return withNotes(ref, prepared.notes);
|
|
88
|
+
}), prepared.notes));
|
|
87
89
|
}
|
|
88
90
|
async resume(ref, options = {}) {
|
|
89
91
|
const provider = this.providerFor(ref);
|
|
90
|
-
return this.collect(provider, ref, options.pollIntervalMs, {
|
|
92
|
+
return this.continuing('embedding.batch.collect', ref.provider, notesOf(ref).model, notesOf(ref).tenant, (context) => this.collect(provider, ref, options.pollIntervalMs, {
|
|
93
|
+
...context,
|
|
91
94
|
requestId: generateRequestId(),
|
|
92
95
|
signal: options.signal ?? new AbortController().signal,
|
|
93
96
|
attempt: 1,
|
|
94
|
-
});
|
|
97
|
+
}));
|
|
95
98
|
}
|
|
96
99
|
async status(ref) {
|
|
97
|
-
return this.providerFor(ref).poll(ref, {
|
|
100
|
+
return this.continuing('embedding.batch.status', ref.provider, notesOf(ref).model, notesOf(ref).tenant, (context) => this.providerFor(ref).poll(ref, {
|
|
101
|
+
...context,
|
|
98
102
|
requestId: generateRequestId(),
|
|
99
103
|
signal: new AbortController().signal,
|
|
100
104
|
attempt: 1,
|
|
101
|
-
});
|
|
105
|
+
}));
|
|
102
106
|
}
|
|
103
107
|
async cancel(ref) {
|
|
104
108
|
const provider = this.providerFor(ref);
|
|
105
|
-
|
|
109
|
+
const cancel = provider.cancel;
|
|
110
|
+
if (!cancel)
|
|
106
111
|
throw new BatchCapabilityError(ref.provider, 'cancel');
|
|
107
|
-
return
|
|
112
|
+
return this.continuing('embedding.batch.cancel', ref.provider, notesOf(ref).model, notesOf(ref).tenant, (context) => cancel.call(provider, ref, {
|
|
113
|
+
...context,
|
|
114
|
+
requestId: generateRequestId(),
|
|
115
|
+
signal: new AbortController().signal,
|
|
116
|
+
attempt: 1,
|
|
117
|
+
}));
|
|
118
|
+
}
|
|
119
|
+
continuing(operation, provider, model, tenant, call) {
|
|
120
|
+
return continuing(this.runtime.lifecycle, {
|
|
121
|
+
family: 'embedding',
|
|
122
|
+
operation,
|
|
123
|
+
provider,
|
|
124
|
+
...(model !== undefined ? { model } : {}),
|
|
125
|
+
...(tenant !== undefined ? { tenantId: tenant } : {}),
|
|
126
|
+
}, call);
|
|
108
127
|
}
|
|
109
128
|
prepare(request, providerName, provider) {
|
|
110
129
|
if (!Array.isArray(request.items) || request.items.length === 0) {
|
|
@@ -154,6 +173,7 @@ export class EmbeddingBatchManager {
|
|
|
154
173
|
images: inputs.images.reduce((total, count) => total + count, 0),
|
|
155
174
|
items: request.items.length,
|
|
156
175
|
...(request.normalize ? { normalize: true } : {}),
|
|
176
|
+
...(request.tenantId !== undefined ? { tenant: request.tenantId } : {}),
|
|
157
177
|
},
|
|
158
178
|
};
|
|
159
179
|
}
|
|
@@ -235,6 +255,9 @@ export class EmbeddingBatchManager {
|
|
|
235
255
|
function withNotes(ref, notes) {
|
|
236
256
|
return { ...ref, metadata: { ...ref.metadata, embedding: notes } };
|
|
237
257
|
}
|
|
258
|
+
function notesOf(ref) {
|
|
259
|
+
return (ref.metadata?.embedding ?? {});
|
|
260
|
+
}
|
|
238
261
|
function unitLength(vector) {
|
|
239
262
|
let sum = 0;
|
|
240
263
|
for (const value of vector)
|
|
@@ -290,7 +290,7 @@ export class EmbeddingEngine {
|
|
|
290
290
|
const provider = this.providers.get(providerName);
|
|
291
291
|
const model = fallback.model || route.resolved.model;
|
|
292
292
|
if (provider &&
|
|
293
|
-
(callContext.residency?.allows(providerName) ?? true) &&
|
|
293
|
+
(callContext.residency?.allows(providerName, model) ?? true) &&
|
|
294
294
|
takesMedia(resolveEmbeddingModel(model, this.config.models).capabilities, provider, inputs)) {
|
|
295
295
|
attempts.push({ providerName, provider, model });
|
|
296
296
|
}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tools emulated by a model, for evaluations that must not touch the world: an agent that would
|
|
3
|
+
* charge a card or write to a production database runs against a model playing each tool instead,
|
|
4
|
+
* with nothing sent, and the emulator's answers recorded so a run replays them exactly.
|
|
5
|
+
*/
|
|
6
|
+
import type { CompletionRequest, ToolDefinition } from '../types/messages.js';
|
|
7
|
+
import type { NexusResponse } from '../types/response.js';
|
|
8
|
+
/** The model that plays the tools: the client, or anything with its `complete()`. */
|
|
9
|
+
export interface EmulatorClient {
|
|
10
|
+
/** Runs one completion. */
|
|
11
|
+
complete(request: CompletionRequest): Promise<NexusResponse>;
|
|
12
|
+
}
|
|
13
|
+
/** One call to an emulated or passed-through tool, as `onCall` reports it. */
|
|
14
|
+
export interface EmulatedToolCall {
|
|
15
|
+
/** The tool's name. */
|
|
16
|
+
tool: string;
|
|
17
|
+
/** The arguments the agent called it with. */
|
|
18
|
+
args: Record<string, unknown>;
|
|
19
|
+
/** What it returned, when it did not fail. */
|
|
20
|
+
result?: unknown;
|
|
21
|
+
/** The error it failed with, when it did. */
|
|
22
|
+
error?: string;
|
|
23
|
+
/** Who answered: the emulating model, the store, replaying an earlier answer, or the real tool. */
|
|
24
|
+
source: 'model' | 'store' | 'real';
|
|
25
|
+
/** The call's key in the store. */
|
|
26
|
+
key: string;
|
|
27
|
+
}
|
|
28
|
+
/** An emulated answer, as a store keeps it. */
|
|
29
|
+
export interface EmulatedResult {
|
|
30
|
+
/** The tool's name. */
|
|
31
|
+
tool: string;
|
|
32
|
+
/** The arguments it was called with. */
|
|
33
|
+
args: Record<string, unknown>;
|
|
34
|
+
/** What it returned. */
|
|
35
|
+
result?: unknown;
|
|
36
|
+
/** The error it failed with. */
|
|
37
|
+
error?: string;
|
|
38
|
+
}
|
|
39
|
+
/** Where emulated answers are kept, by `emulationKey()`, so a later run replays them. */
|
|
40
|
+
export interface EmulationStore {
|
|
41
|
+
/** The answer kept for a key. */
|
|
42
|
+
get(key: string): Promise<EmulatedResult | undefined> | EmulatedResult | undefined;
|
|
43
|
+
/** Keeps an answer. */
|
|
44
|
+
set(key: string, value: EmulatedResult): Promise<void> | void;
|
|
45
|
+
}
|
|
46
|
+
/** Options for `emulatedTools()`. */
|
|
47
|
+
export interface EmulatedToolsOptions {
|
|
48
|
+
/** The model that plays each tool. */
|
|
49
|
+
client: EmulatorClient;
|
|
50
|
+
/** The model to ask. Defaults to `auto`, the client's routing. */
|
|
51
|
+
model?: string;
|
|
52
|
+
/**
|
|
53
|
+
* The world the tools act on, as the emulator reads it, such as `Order 1042 was delivered on
|
|
54
|
+
* 3 October and cost $59.` Part of each call's key, so one store holds answers for many scenarios.
|
|
55
|
+
*/
|
|
56
|
+
scenario?: string;
|
|
57
|
+
/** Each tool's own notes, by name: what it returns, when it fails, and its rules. */
|
|
58
|
+
instructions?: Readonly<Record<string, string>>;
|
|
59
|
+
/** Real calls to imitate, by tool: their arguments and what the real tool returned. */
|
|
60
|
+
examples?: Readonly<Record<string, ReadonlyArray<{
|
|
61
|
+
args: Record<string, unknown>;
|
|
62
|
+
result: unknown;
|
|
63
|
+
}>>>;
|
|
64
|
+
/** JSON Schema of each tool's result, by name, shown to the emulator. */
|
|
65
|
+
results?: Readonly<Record<string, Record<string, unknown>>>;
|
|
66
|
+
/**
|
|
67
|
+
* Checks each tool's emulated result, by name: `true`, or why not. A result that fails is asked
|
|
68
|
+
* for again once, with the reason, and then fails the call with an `EmulationError`.
|
|
69
|
+
*/
|
|
70
|
+
validate?: Readonly<Record<string, (result: unknown) => true | string>>;
|
|
71
|
+
/** Tools that run for real, by name: ones that read and change nothing. Defaults to none. */
|
|
72
|
+
passthrough?: readonly string[];
|
|
73
|
+
/** Where answers are kept and replayed from. */
|
|
74
|
+
store?: EmulationStore;
|
|
75
|
+
/**
|
|
76
|
+
* `auto`, the default with a store, replays a kept answer and asks the model for the rest, keeping
|
|
77
|
+
* them; `replay` answers only from the store, failing a call it has no answer for; `record` asks the
|
|
78
|
+
* model every time and keeps each answer; `emulate`, the default without a store, asks the model.
|
|
79
|
+
*/
|
|
80
|
+
mode?: 'auto' | 'replay' | 'record' | 'emulate';
|
|
81
|
+
/**
|
|
82
|
+
* How many earlier calls of this set the emulator sees, so a refund it reported shows when the
|
|
83
|
+
* order is looked up again. Defaults to 20; 0 shows none.
|
|
84
|
+
*/
|
|
85
|
+
history?: number;
|
|
86
|
+
/** Sampling temperature for the emulator. Defaults to 0. */
|
|
87
|
+
temperature?: number;
|
|
88
|
+
/** Longest answer, in tokens. */
|
|
89
|
+
maxTokens?: number;
|
|
90
|
+
/** Called after each call, with who answered it. */
|
|
91
|
+
onCall?: (call: EmulatedToolCall) => void;
|
|
92
|
+
}
|
|
93
|
+
/** Raised when a call cannot be emulated: no kept answer in `replay`, or no valid answer from the model. */
|
|
94
|
+
export declare class EmulationError extends Error {
|
|
95
|
+
/** `EMULATION_MISS` when the store has no answer, `EMULATION_INVALID` when the model gave none usable. */
|
|
96
|
+
readonly code: 'EMULATION_MISS' | 'EMULATION_INVALID';
|
|
97
|
+
/** The tool. */
|
|
98
|
+
readonly tool: string;
|
|
99
|
+
/** The arguments. */
|
|
100
|
+
readonly args: Record<string, unknown>;
|
|
101
|
+
constructor(
|
|
102
|
+
/** `EMULATION_MISS` when the store has no answer, `EMULATION_INVALID` when the model gave none usable. */
|
|
103
|
+
code: 'EMULATION_MISS' | 'EMULATION_INVALID',
|
|
104
|
+
/** The tool. */
|
|
105
|
+
tool: string,
|
|
106
|
+
/** The arguments. */
|
|
107
|
+
args: Record<string, unknown>, message: string);
|
|
108
|
+
}
|
|
109
|
+
/** Emulated answers in memory, from an earlier run's `toJSON()` when given one. */
|
|
110
|
+
export declare class MemoryEmulationStore implements EmulationStore {
|
|
111
|
+
private readonly entries;
|
|
112
|
+
constructor(entries?: Readonly<Record<string, EmulatedResult>>);
|
|
113
|
+
/** The answer kept for a key. */
|
|
114
|
+
get(key: string): EmulatedResult | undefined;
|
|
115
|
+
/** Keeps an answer, replacing the one kept for its key. */
|
|
116
|
+
set(key: string, value: EmulatedResult): void;
|
|
117
|
+
/** How many answers it keeps. */
|
|
118
|
+
get size(): number;
|
|
119
|
+
/** Every answer, by key, to write to a file the next run reads back. */
|
|
120
|
+
toJSON(): Record<string, EmulatedResult>;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The key of a call: its tool, its arguments, its scenario, and which call with those arguments it
|
|
124
|
+
* is, so an order looked up before and after a refund keeps both answers.
|
|
125
|
+
*/
|
|
126
|
+
export declare function emulationKey(call: {
|
|
127
|
+
tool: string;
|
|
128
|
+
args: Record<string, unknown>;
|
|
129
|
+
scenario?: string;
|
|
130
|
+
ordinal?: number;
|
|
131
|
+
}): string;
|
|
132
|
+
/**
|
|
133
|
+
* Tools that look the same to the agent, by name, description, parameters, and capabilities, but are
|
|
134
|
+
* answered by a model playing each one, or by the answers a store kept, and never run: nothing they
|
|
135
|
+
* would send is sent. Tools in `passthrough` run for real. A tool the emulator says fails throws its
|
|
136
|
+
* error, so the agent sees a failure as it would from the real tool.
|
|
137
|
+
*
|
|
138
|
+
* ```ts
|
|
139
|
+
* const tools = emulatedTools([chargeCard, lookupOrder], { client: ai, model: 'gpt-5-mini', scenario, store });
|
|
140
|
+
* const agent = createAgent({ client: ai, model: 'gpt-5', tools });
|
|
141
|
+
* ```
|
|
142
|
+
*/
|
|
143
|
+
export declare function emulatedTools(tools: readonly ToolDefinition[], options: EmulatedToolsOptions): ToolDefinition[];
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
import { sha256Hex } from '../utils/sha256.js';
|
|
2
|
+
export class EmulationError extends Error {
|
|
3
|
+
code;
|
|
4
|
+
tool;
|
|
5
|
+
args;
|
|
6
|
+
constructor(code, tool, args, message) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.code = code;
|
|
9
|
+
this.tool = tool;
|
|
10
|
+
this.args = args;
|
|
11
|
+
this.name = 'EmulationError';
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
export class MemoryEmulationStore {
|
|
15
|
+
entries;
|
|
16
|
+
constructor(entries = {}) {
|
|
17
|
+
this.entries = new Map(Object.entries(entries));
|
|
18
|
+
}
|
|
19
|
+
get(key) {
|
|
20
|
+
return this.entries.get(key);
|
|
21
|
+
}
|
|
22
|
+
set(key, value) {
|
|
23
|
+
this.entries.set(key, value);
|
|
24
|
+
}
|
|
25
|
+
get size() {
|
|
26
|
+
return this.entries.size;
|
|
27
|
+
}
|
|
28
|
+
toJSON() {
|
|
29
|
+
return Object.fromEntries(this.entries);
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
export function emulationKey(call) {
|
|
33
|
+
return sha256Hex(canonical({ tool: call.tool, args: call.args, scenario: call.scenario ?? '', ordinal: call.ordinal ?? 0 }));
|
|
34
|
+
}
|
|
35
|
+
export function emulatedTools(tools, options) {
|
|
36
|
+
const mode = options.mode ?? (options.store ? 'auto' : 'emulate');
|
|
37
|
+
if (mode !== 'emulate' && !options.store)
|
|
38
|
+
throw new TypeError(`Emulation mode "${mode}" needs a store`);
|
|
39
|
+
const passthrough = new Set(options.passthrough ?? []);
|
|
40
|
+
const limit = Math.max(0, options.history ?? 20);
|
|
41
|
+
const history = [];
|
|
42
|
+
const ordinals = new Map();
|
|
43
|
+
const report = (call) => {
|
|
44
|
+
try {
|
|
45
|
+
options.onCall?.(call);
|
|
46
|
+
}
|
|
47
|
+
catch {
|
|
48
|
+
}
|
|
49
|
+
};
|
|
50
|
+
return tools.map((definition) => {
|
|
51
|
+
const { execute: run, stream, ...shape } = definition;
|
|
52
|
+
if (passthrough.has(definition.name)) {
|
|
53
|
+
if (!run && !stream)
|
|
54
|
+
return definition;
|
|
55
|
+
return {
|
|
56
|
+
...shape,
|
|
57
|
+
execute: async (args, context) => {
|
|
58
|
+
const key = emulationKey({ tool: definition.name, args, scenario: options.scenario });
|
|
59
|
+
try {
|
|
60
|
+
const result = run ? await run(args, context) : await drain(definition, args, context);
|
|
61
|
+
report({ tool: definition.name, args, result, source: 'real', key });
|
|
62
|
+
return result;
|
|
63
|
+
}
|
|
64
|
+
catch (error) {
|
|
65
|
+
report({ tool: definition.name, args, error: messageOf(error), source: 'real', key });
|
|
66
|
+
throw error;
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
...shape,
|
|
73
|
+
execute: async (args, context) => {
|
|
74
|
+
const identity = `${definition.name}\u0000${canonical(args)}`;
|
|
75
|
+
const ordinal = ordinals.get(identity) ?? 0;
|
|
76
|
+
ordinals.set(identity, ordinal + 1);
|
|
77
|
+
const key = emulationKey({ tool: definition.name, args, scenario: options.scenario, ordinal });
|
|
78
|
+
let answer;
|
|
79
|
+
let source = 'store';
|
|
80
|
+
if (mode === 'auto' || mode === 'replay')
|
|
81
|
+
answer = await options.store?.get(key);
|
|
82
|
+
if (!answer) {
|
|
83
|
+
if (mode === 'replay') {
|
|
84
|
+
throw new EmulationError('EMULATION_MISS', definition.name, args, `No kept answer for ${definition.name}(${canonical(args)}), call ${ordinal + 1}: record it first`);
|
|
85
|
+
}
|
|
86
|
+
answer = await emulate(definition, args, context, limit === 0 ? [] : history.slice(-limit), options);
|
|
87
|
+
source = 'model';
|
|
88
|
+
if (mode !== 'emulate')
|
|
89
|
+
await options.store?.set(key, answer);
|
|
90
|
+
}
|
|
91
|
+
history.push(answer);
|
|
92
|
+
report({
|
|
93
|
+
tool: definition.name,
|
|
94
|
+
args,
|
|
95
|
+
...(answer.error === undefined ? { result: answer.result } : { error: answer.error }),
|
|
96
|
+
source,
|
|
97
|
+
key,
|
|
98
|
+
});
|
|
99
|
+
if (answer.error !== undefined)
|
|
100
|
+
throw new Error(answer.error);
|
|
101
|
+
return answer.result;
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
async function emulate(definition, args, context, earlier, options) {
|
|
107
|
+
const messages = [
|
|
108
|
+
{ role: 'system', content: brief(definition, earlier, options) },
|
|
109
|
+
{ role: 'user', content: `Arguments: ${JSON.stringify(args)}` },
|
|
110
|
+
];
|
|
111
|
+
let problem = '';
|
|
112
|
+
for (let attempt = 0; attempt < 2; attempt += 1) {
|
|
113
|
+
const response = await options.client.complete({
|
|
114
|
+
model: options.model ?? 'auto',
|
|
115
|
+
messages: [...messages],
|
|
116
|
+
responseFormat: { type: 'json' },
|
|
117
|
+
temperature: options.temperature ?? 0,
|
|
118
|
+
...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
|
|
119
|
+
...(context?.signal ? { signal: context.signal } : {}),
|
|
120
|
+
...(context?.tenantId ? { tenantId: context.tenantId } : {}),
|
|
121
|
+
metadata: { emulatedTool: definition.name },
|
|
122
|
+
});
|
|
123
|
+
const text = typeof response.content === 'string' ? response.content : '';
|
|
124
|
+
const parsed = parseAnswer(text);
|
|
125
|
+
if (parsed === undefined)
|
|
126
|
+
problem = 'The answer was not JSON. Reply with JSON only.';
|
|
127
|
+
else if ('error' in parsed)
|
|
128
|
+
return { tool: definition.name, args, error: parsed.error };
|
|
129
|
+
else {
|
|
130
|
+
const verdict = options.validate?.[definition.name]?.(parsed.result) ?? true;
|
|
131
|
+
if (verdict === true)
|
|
132
|
+
return { tool: definition.name, args, result: parsed.result };
|
|
133
|
+
problem = `The result does not fit what ${definition.name} returns: ${verdict}. Answer again.`;
|
|
134
|
+
}
|
|
135
|
+
messages.push({ role: 'assistant', content: text }, { role: 'user', content: problem });
|
|
136
|
+
}
|
|
137
|
+
throw new EmulationError('EMULATION_INVALID', definition.name, args, `The emulator gave no usable answer for ${definition.name}: ${problem}`);
|
|
138
|
+
}
|
|
139
|
+
function brief(definition, earlier, options) {
|
|
140
|
+
const lines = [
|
|
141
|
+
`You are emulating the tool "${definition.name}" for a test, in place of the real one.`,
|
|
142
|
+
'Reply with exactly what the real tool would return for the arguments you are given, as JSON:',
|
|
143
|
+
'{"result": <what it returns>}, or, when the real tool would fail, {"error": "<its error message>"}.',
|
|
144
|
+
'Never explain. Stay consistent with the scenario, the examples, and the earlier calls.',
|
|
145
|
+
'',
|
|
146
|
+
`Tool: ${definition.name}`,
|
|
147
|
+
`Description: ${definition.description}`,
|
|
148
|
+
`Arguments schema: ${JSON.stringify(definition.parameters)}`,
|
|
149
|
+
];
|
|
150
|
+
const result = options.results?.[definition.name];
|
|
151
|
+
if (result)
|
|
152
|
+
lines.push(`Result schema: ${JSON.stringify(result)}`);
|
|
153
|
+
const notes = options.instructions?.[definition.name];
|
|
154
|
+
if (notes)
|
|
155
|
+
lines.push(`Notes: ${notes}`);
|
|
156
|
+
if (options.scenario)
|
|
157
|
+
lines.push('', `Scenario: ${options.scenario}`);
|
|
158
|
+
const examples = options.examples?.[definition.name] ?? [];
|
|
159
|
+
if (examples.length > 0) {
|
|
160
|
+
lines.push('', 'Real calls of this tool:');
|
|
161
|
+
for (const example of examples) {
|
|
162
|
+
lines.push(`- arguments ${JSON.stringify(example.args)} returned ${JSON.stringify(example.result)}`);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
if (earlier.length > 0) {
|
|
166
|
+
lines.push('', 'Earlier calls in this run, oldest first:');
|
|
167
|
+
for (const call of earlier) {
|
|
168
|
+
const outcome = call.error === undefined ? `returned ${JSON.stringify(call.result)}` : `failed: ${call.error}`;
|
|
169
|
+
lines.push(`- ${call.tool} ${JSON.stringify(call.args)} ${outcome}`);
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return lines.join('\n');
|
|
173
|
+
}
|
|
174
|
+
function parseAnswer(text) {
|
|
175
|
+
const trimmed = text
|
|
176
|
+
.trim()
|
|
177
|
+
.replace(/^```(?:json)?\s*/i, '')
|
|
178
|
+
.replace(/\s*```$/, '');
|
|
179
|
+
let value;
|
|
180
|
+
try {
|
|
181
|
+
value = JSON.parse(trimmed);
|
|
182
|
+
}
|
|
183
|
+
catch {
|
|
184
|
+
return undefined;
|
|
185
|
+
}
|
|
186
|
+
if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
|
|
187
|
+
const record = value;
|
|
188
|
+
const keys = Object.keys(record);
|
|
189
|
+
if (keys.length === 1 && keys[0] === 'error' && typeof record.error === 'string')
|
|
190
|
+
return { error: record.error };
|
|
191
|
+
if (keys.length === 1 && keys[0] === 'result')
|
|
192
|
+
return { result: record.result };
|
|
193
|
+
}
|
|
194
|
+
return { result: value };
|
|
195
|
+
}
|
|
196
|
+
async function drain(definition, args, context) {
|
|
197
|
+
const generator = definition.stream(args, context);
|
|
198
|
+
for (;;) {
|
|
199
|
+
const step = await generator.next();
|
|
200
|
+
if (step.done)
|
|
201
|
+
return step.value;
|
|
202
|
+
context?.progress?.(step.value);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
function messageOf(error) {
|
|
206
|
+
return error instanceof Error ? error.message : String(error);
|
|
207
|
+
}
|
|
208
|
+
function canonical(value) {
|
|
209
|
+
return (JSON.stringify(value, (_key, item) => item !== null && typeof item === 'object' && !Array.isArray(item)
|
|
210
|
+
? Object.fromEntries(Object.keys(item)
|
|
211
|
+
.sort()
|
|
212
|
+
.map((key) => [key, item[key]]))
|
|
213
|
+
: item) ?? 'undefined');
|
|
214
|
+
}
|
package/dist/images/operation.js
CHANGED
|
@@ -6,7 +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
|
+
callContext.residency?.check(registeredName, request.model);
|
|
10
10
|
assertCapabilities(registeredName, provider, operation, request);
|
|
11
11
|
const context = { ...callContext, operationId };
|
|
12
12
|
const startedAt = state.now();
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { OperationDescriptor, OperationLifecycleLike, ProviderCallContext } from '../types/lifecycle.js';
|
|
2
|
+
/** What a continued call adds to the context its family gives the provider. */
|
|
3
|
+
export type ContinuedFields = Pick<ProviderCallContext, 'tenantId' | 'credential' | 'residency'>;
|
|
4
|
+
/**
|
|
5
|
+
* Runs a provider call that continues an operation outside it, such as polling a job by its ref:
|
|
6
|
+
* with the tenant's credentials and inside its regions when the lifecycle can give them, and its
|
|
7
|
+
* errors cleaned of every credential it resolved. Without a lifecycle, or one that cannot, the call
|
|
8
|
+
* runs as it is, on the configured key.
|
|
9
|
+
*/
|
|
10
|
+
export declare function continuing<T>(lifecycle: OperationLifecycleLike | undefined, operation: Omit<OperationDescriptor, 'requestId'> & {
|
|
11
|
+
requestId?: string;
|
|
12
|
+
}, call: (context: ContinuedFields) => Promise<T>): Promise<T>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export async function continuing(lifecycle, operation, call) {
|
|
2
|
+
const continued = await lifecycle?.callContext?.(operation);
|
|
3
|
+
if (!continued)
|
|
4
|
+
return call({});
|
|
5
|
+
const { scrub, ...context } = continued;
|
|
6
|
+
try {
|
|
7
|
+
if (operation.provider)
|
|
8
|
+
context.residency?.check(operation.provider, operation.model);
|
|
9
|
+
return await call(context);
|
|
10
|
+
}
|
|
11
|
+
catch (error) {
|
|
12
|
+
throw scrub(error);
|
|
13
|
+
}
|
|
14
|
+
}
|