pi-smart-router 1.2.2 → 1.4.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/.pi/extensions/smart-router/fleet-bootstrap.ts +22 -0
- package/README.md +51 -5
- package/config/benchmark-profiles.json +126 -3
- package/dist/config/defaults.d.ts +2 -2
- package/dist/config/defaults.d.ts.map +1 -1
- package/dist/config/defaults.js +6 -3
- package/dist/config/defaults.js.map +1 -1
- package/dist/config/pi-model-mapper.d.ts +37 -1
- package/dist/config/pi-model-mapper.d.ts.map +1 -1
- package/dist/config/pi-model-mapper.js +123 -7
- package/dist/config/pi-model-mapper.js.map +1 -1
- package/dist/domain/judgment/answer-mapper.d.ts +49 -0
- package/dist/domain/judgment/answer-mapper.d.ts.map +1 -0
- package/dist/domain/judgment/answer-mapper.js +124 -0
- package/dist/domain/judgment/answer-mapper.js.map +1 -0
- package/dist/domain/judgment/index.d.ts +8 -0
- package/dist/domain/judgment/index.d.ts.map +1 -0
- package/dist/domain/judgment/index.js +8 -0
- package/dist/domain/judgment/index.js.map +1 -0
- package/dist/domain/judgment/judge-state.d.ts +70 -0
- package/dist/domain/judgment/judge-state.d.ts.map +1 -0
- package/dist/domain/judgment/judge-state.js +227 -0
- package/dist/domain/judgment/judge-state.js.map +1 -0
- package/dist/domain/judgment/questions.d.ts +58 -0
- package/dist/domain/judgment/questions.d.ts.map +1 -0
- package/dist/domain/judgment/questions.js +157 -0
- package/dist/domain/judgment/questions.js.map +1 -0
- package/dist/domain/pipeline/pipeline-stage.d.ts +11 -0
- package/dist/domain/pipeline/pipeline-stage.d.ts.map +1 -1
- package/dist/domain/pipeline/pipeline-stage.js +3 -0
- package/dist/domain/pipeline/pipeline-stage.js.map +1 -1
- package/dist/domain/pipeline/router-pipeline.d.ts +32 -6
- package/dist/domain/pipeline/router-pipeline.d.ts.map +1 -1
- package/dist/domain/pipeline/router-pipeline.js +49 -4
- package/dist/domain/pipeline/router-pipeline.js.map +1 -1
- package/dist/domain/pipeline/typed-judgment-stage.d.ts +44 -0
- package/dist/domain/pipeline/typed-judgment-stage.d.ts.map +1 -0
- package/dist/domain/pipeline/typed-judgment-stage.js +144 -0
- package/dist/domain/pipeline/typed-judgment-stage.js.map +1 -0
- package/dist/domain/ports/typed-judgment-port.d.ts +138 -0
- package/dist/domain/ports/typed-judgment-port.d.ts.map +1 -0
- package/dist/domain/ports/typed-judgment-port.js +28 -0
- package/dist/domain/ports/typed-judgment-port.js.map +1 -0
- package/dist/domain/types/entities.d.ts +42 -1
- package/dist/domain/types/entities.d.ts.map +1 -1
- package/dist/domain/types/index.d.ts +1 -1
- package/dist/domain/types/index.d.ts.map +1 -1
- package/dist/domain/types/schemas.d.ts +140 -0
- package/dist/domain/types/schemas.d.ts.map +1 -1
- package/dist/domain/types/schemas.js +191 -0
- package/dist/domain/types/schemas.js.map +1 -1
- package/dist/index.d.ts +4 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/infrastructure/judgment/jev-typed-judgment-adapter.d.ts +67 -0
- package/dist/infrastructure/judgment/jev-typed-judgment-adapter.d.ts.map +1 -0
- package/dist/infrastructure/judgment/jev-typed-judgment-adapter.js +411 -0
- package/dist/infrastructure/judgment/jev-typed-judgment-adapter.js.map +1 -0
- package/package.json +3 -3
- package/src/config/defaults.ts +8 -1
- package/src/config/pi-model-mapper.ts +149 -7
- package/src/domain/judgment/answer-mapper.ts +210 -0
- package/src/domain/judgment/index.ts +32 -0
- package/src/domain/judgment/judge-state.ts +294 -0
- package/src/domain/judgment/questions.ts +198 -0
- package/src/domain/pipeline/pipeline-stage.ts +17 -0
- package/src/domain/pipeline/router-pipeline.ts +83 -6
- package/src/domain/pipeline/typed-judgment-stage.ts +165 -0
- package/src/domain/ports/typed-judgment-port.ts +186 -0
- package/src/domain/types/entities.ts +54 -0
- package/src/domain/types/index.ts +1 -0
- package/src/domain/types/schemas.ts +206 -0
- package/src/index.ts +13 -2
- package/src/infrastructure/judgment/jev-typed-judgment-adapter.ts +564 -0
package/src/index.ts
CHANGED
|
@@ -171,8 +171,19 @@ export type {
|
|
|
171
171
|
TurnType,
|
|
172
172
|
} from './domain/types/index.js';
|
|
173
173
|
export type { QuotaWindowPosition } from './domain/types/entities.js';
|
|
174
|
-
export type { OperatorConfig } from './domain/types/schemas.js';
|
|
175
|
-
export {
|
|
174
|
+
export type { OperatorConfig, TypedJudgmentConfig } from './domain/types/schemas.js';
|
|
175
|
+
export {
|
|
176
|
+
DEFAULT_PLANNING_DELEGATE_CONFIG,
|
|
177
|
+
DEFAULT_TYPED_JUDGMENT_CONFIG,
|
|
178
|
+
resolveTypedJudgmentConfigFromEnv,
|
|
179
|
+
} from './domain/types/schemas.js';
|
|
180
|
+
|
|
181
|
+
// Typed judgment (SP-308, #187): composition-root adapter binding
|
|
182
|
+
export {
|
|
183
|
+
createTypedJudgmentPort,
|
|
184
|
+
type CreateTypedJudgmentPortResult,
|
|
185
|
+
} from './infrastructure/judgment/jev-typed-judgment-adapter.js';
|
|
186
|
+
export type { TypedJudgmentPort } from './domain/ports/typed-judgment-port.js';
|
|
176
187
|
|
|
177
188
|
// Config
|
|
178
189
|
export {
|
|
@@ -0,0 +1,564 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jev-compatible typed judgment HTTP adapter (SP-305, #184).
|
|
3
|
+
*
|
|
4
|
+
* Implements the domain `TypedJudgmentPort` over Node's global `fetch`
|
|
5
|
+
* (Node ≥ 22.19; no new npm dependencies) against `POST /v1/systemone`.
|
|
6
|
+
* Local OpenJev is the default endpoint; hosted Jev (TypeSafe / Codiv) is
|
|
7
|
+
* opt-in via `allow_remote` (enforced by the config schema) plus a key from
|
|
8
|
+
* the env var named by `api_key_env` (enforced by the factory — fail closed).
|
|
9
|
+
*
|
|
10
|
+
* Wire notes (OpenJev README + `openjev/api.py`, `openjev/engine.py`):
|
|
11
|
+
* - Request: `{model, state, questions: {id: {type, instructions, criteria}}}`
|
|
12
|
+
* plus the OpenJev-only `samples` extension, sent for loopback endpoints
|
|
13
|
+
* only (hosted Jev rejects unknown fields).
|
|
14
|
+
* - Success: `{model, answers: {id: {type, …}}, usage}`. `noul` answers carry
|
|
15
|
+
* P(yes) ∈ [0,1]; `score` answers are 0-indexed expected levels — this
|
|
16
|
+
* adapter lifts them onto the question's anchor scores.
|
|
17
|
+
* - Errors: 400 (`detail` string or `{error_type, message}`), 422 (FastAPI
|
|
18
|
+
* validation list), 401/403 (`{detail: {error_type, message}}`), 429, 529.
|
|
19
|
+
* Only 429/529 are retried (max 2, linear backoff, inside `timeout_ms`).
|
|
20
|
+
*
|
|
21
|
+
* Privacy: thrown errors and logs never include state or question prompt
|
|
22
|
+
* text; every constructed message passes through `redactPromptFromError`.
|
|
23
|
+
* The API key is read from the environment at construction, never from
|
|
24
|
+
* config files, and is never logged.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
import { z } from 'zod';
|
|
28
|
+
|
|
29
|
+
import {
|
|
30
|
+
TypedJudgmentError,
|
|
31
|
+
type TypedJudgmentAnswer,
|
|
32
|
+
type TypedJudgmentAnswers,
|
|
33
|
+
type TypedJudgmentChoiceQuestion,
|
|
34
|
+
type TypedJudgmentNoulQuestion,
|
|
35
|
+
type TypedJudgmentPort,
|
|
36
|
+
type TypedJudgmentQuestion,
|
|
37
|
+
type TypedJudgmentScoreQuestion,
|
|
38
|
+
} from '../../domain/ports/typed-judgment-port.js';
|
|
39
|
+
import { redactPromptFromError } from '../../domain/pipeline/stage-helpers.js';
|
|
40
|
+
import type { TypedJudgmentConfig } from '../../domain/types/index.js';
|
|
41
|
+
|
|
42
|
+
// ─── Constants ───────────────────────────────────────────────────────────────
|
|
43
|
+
|
|
44
|
+
/** Max retries after the initial attempt (429/529 only). */
|
|
45
|
+
const MAX_RETRIES = 2;
|
|
46
|
+
|
|
47
|
+
/** Linear backoff base: retry N waits `BACKOFF_BASE_MS * N` (250 ms, 500 ms). */
|
|
48
|
+
const BACKOFF_BASE_MS = 250;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Loopback hosts matching `TypedJudgmentConfigSchema` in
|
|
52
|
+
* `src/domain/types/schemas.ts` (duplicated: the schema's helper is
|
|
53
|
+
* module-private and the schema file is out of this task's change scope).
|
|
54
|
+
*/
|
|
55
|
+
const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(['127.0.0.1', 'localhost', '::1']);
|
|
56
|
+
|
|
57
|
+
type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
|
|
58
|
+
|
|
59
|
+
// ─── Endpoint classification ─────────────────────────────────────────────────
|
|
60
|
+
|
|
61
|
+
/** Normalized hostname of an endpoint URL, or undefined when unparseable. */
|
|
62
|
+
function parseEndpointHostname(endpoint: string): string | undefined {
|
|
63
|
+
let url: URL;
|
|
64
|
+
try {
|
|
65
|
+
url = new URL(endpoint);
|
|
66
|
+
} catch {
|
|
67
|
+
return undefined;
|
|
68
|
+
}
|
|
69
|
+
const hostname = url.hostname;
|
|
70
|
+
return hostname.startsWith('[') && hostname.endsWith(']')
|
|
71
|
+
? hostname.slice(1, -1)
|
|
72
|
+
: hostname;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** True when the endpoint is loopback (local OpenJev). */
|
|
76
|
+
export function isLoopbackEndpoint(endpoint: string): boolean {
|
|
77
|
+
const hostname = parseEndpointHostname(endpoint);
|
|
78
|
+
return hostname !== undefined && LOOPBACK_HOSTS.has(hostname);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// ─── Wire question translation ───────────────────────────────────────────────
|
|
82
|
+
|
|
83
|
+
/** Jev wire question shapes (`openjev/api.py` SystemOneRequest). */
|
|
84
|
+
type WireQuestion =
|
|
85
|
+
| { type: 'choice'; instructions: string; criteria: Record<string, string> }
|
|
86
|
+
| { type: 'score'; instructions: string; criteria: string[] }
|
|
87
|
+
| { type: 'noul'; instructions: string; criteria: { true: string; false: string } };
|
|
88
|
+
|
|
89
|
+
function toWireQuestion(question: TypedJudgmentQuestion): WireQuestion {
|
|
90
|
+
switch (question.kind) {
|
|
91
|
+
case 'choice':
|
|
92
|
+
// Jev choice criteria map each option name to a description; the
|
|
93
|
+
// domain carries option labels only, so each option describes itself.
|
|
94
|
+
return {
|
|
95
|
+
type: 'choice',
|
|
96
|
+
instructions: question.prompt,
|
|
97
|
+
criteria: Object.fromEntries(question.options.map((option) => [option, option])),
|
|
98
|
+
};
|
|
99
|
+
case 'score':
|
|
100
|
+
// Jev score criteria are level descriptions in ascending order
|
|
101
|
+
// (0-indexed on the wire; the domain anchors carry explicit scores).
|
|
102
|
+
return {
|
|
103
|
+
type: 'score',
|
|
104
|
+
instructions: question.prompt,
|
|
105
|
+
criteria: question.anchors.map((anchor) => anchor.description),
|
|
106
|
+
};
|
|
107
|
+
case 'noul':
|
|
108
|
+
return {
|
|
109
|
+
type: 'noul',
|
|
110
|
+
instructions: question.prompt,
|
|
111
|
+
criteria: { true: question.criteria_true, false: question.criteria_false },
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// ─── Wire response validation (zod) ─────────────────────────────────────────
|
|
117
|
+
|
|
118
|
+
const probabilityRecordSchema = z.record(z.string(), z.number());
|
|
119
|
+
|
|
120
|
+
/** Wire `choice` answer: `{type, choice, probabilities, confidence}`. */
|
|
121
|
+
const wireChoiceAnswerSchema = z.object({
|
|
122
|
+
type: z.literal('choice'),
|
|
123
|
+
choice: z.string(),
|
|
124
|
+
probabilities: probabilityRecordSchema,
|
|
125
|
+
confidence: z.number().min(0).max(1),
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
/** Wire `score` answer: `{type, score, legend, probabilities, confidence}` (0-indexed levels). */
|
|
129
|
+
const wireScoreAnswerSchema = z.object({
|
|
130
|
+
type: z.literal('score'),
|
|
131
|
+
score: z.number(),
|
|
132
|
+
legend: z.record(z.string(), z.string()),
|
|
133
|
+
probabilities: probabilityRecordSchema,
|
|
134
|
+
confidence: z.number().min(0).max(1),
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
/** Wire `noul` answer: `{type, noul}` where `noul` is P(yes) ∈ [0,1]. */
|
|
138
|
+
const wireNoulAnswerSchema = z.object({
|
|
139
|
+
type: z.literal('noul'),
|
|
140
|
+
noul: z.number().min(0).max(1),
|
|
141
|
+
});
|
|
142
|
+
|
|
143
|
+
const wireAnswerSchema = z.discriminatedUnion('type', [
|
|
144
|
+
wireChoiceAnswerSchema,
|
|
145
|
+
wireScoreAnswerSchema,
|
|
146
|
+
wireNoulAnswerSchema,
|
|
147
|
+
]);
|
|
148
|
+
|
|
149
|
+
type WireAnswer = z.infer<typeof wireAnswerSchema>;
|
|
150
|
+
|
|
151
|
+
/** Success envelope; `model`/`usage` are informational and ignored. */
|
|
152
|
+
const wireResponseSchema = z.object({
|
|
153
|
+
answers: z.record(z.string(), wireAnswerSchema),
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
/** `{detail: {error_type, message}}` — auth errors (401/403) and api errors. */
|
|
157
|
+
const wireObjectErrorSchema = z.object({
|
|
158
|
+
detail: z.object({
|
|
159
|
+
error_type: z.string(),
|
|
160
|
+
message: z.string().optional(),
|
|
161
|
+
}),
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
/** `{detail: "plain text reason"}` — 400 semantic errors (unaskable question). */
|
|
165
|
+
const wireStringErrorSchema = z.object({
|
|
166
|
+
detail: z.string(),
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
/** `{detail: [{type, loc, msg, …}]}` — 422 FastAPI validation list. */
|
|
170
|
+
const wireValidationErrorSchema = z.object({
|
|
171
|
+
detail: z.array(
|
|
172
|
+
z.object({
|
|
173
|
+
loc: z.array(z.union([z.string(), z.number()])).optional(),
|
|
174
|
+
msg: z.string().optional(),
|
|
175
|
+
type: z.string().optional(),
|
|
176
|
+
}),
|
|
177
|
+
),
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
// ─── Answer mapping ──────────────────────────────────────────────────────────
|
|
181
|
+
|
|
182
|
+
type Redact = (message: string) => string;
|
|
183
|
+
|
|
184
|
+
function invalidResponse(redact: Redact, message: string): TypedJudgmentError {
|
|
185
|
+
return new TypedJudgmentError('invalid_response', redact(message));
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
function mapChoiceAnswer(
|
|
189
|
+
question: TypedJudgmentChoiceQuestion,
|
|
190
|
+
wire: Extract<WireAnswer, { type: 'choice' }>,
|
|
191
|
+
redact: Redact,
|
|
192
|
+
): TypedJudgmentAnswer {
|
|
193
|
+
if (!question.options.includes(wire.choice)) {
|
|
194
|
+
throw invalidResponse(
|
|
195
|
+
redact,
|
|
196
|
+
`judge answered choice '${wire.choice}' for question '${question.id}', ` +
|
|
197
|
+
'which is not one of the declared options',
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
for (const key of Object.keys(wire.probabilities)) {
|
|
201
|
+
if (!question.options.includes(key)) {
|
|
202
|
+
throw invalidResponse(
|
|
203
|
+
redact,
|
|
204
|
+
`judge returned a probability for unknown option '${key}' ` +
|
|
205
|
+
`on question '${question.id}'`,
|
|
206
|
+
);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
return {
|
|
210
|
+
kind: 'choice',
|
|
211
|
+
choice: wire.choice,
|
|
212
|
+
probabilities: wire.probabilities,
|
|
213
|
+
confidence: wire.confidence,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function mapScoreAnswer(
|
|
218
|
+
question: TypedJudgmentScoreQuestion,
|
|
219
|
+
wire: Extract<WireAnswer, { type: 'score' }>,
|
|
220
|
+
redact: Redact,
|
|
221
|
+
): TypedJudgmentAnswer {
|
|
222
|
+
// The wire is 0-indexed over the level list; the domain carries explicit
|
|
223
|
+
// anchor scores. Re-key legend/probabilities onto anchor scores and lift
|
|
224
|
+
// the expected level into anchor-score space (Σ pᵢ·anchorᵢ.score).
|
|
225
|
+
const legend: Record<string, string> = {};
|
|
226
|
+
const probabilities: Record<string, number> = {};
|
|
227
|
+
let expected = 0;
|
|
228
|
+
question.anchors.forEach((anchor, index) => {
|
|
229
|
+
const wireKey = String(index);
|
|
230
|
+
const probability = wire.probabilities[wireKey];
|
|
231
|
+
if (probability === undefined) {
|
|
232
|
+
throw invalidResponse(
|
|
233
|
+
redact,
|
|
234
|
+
`judge score answer for question '${question.id}' is missing ` +
|
|
235
|
+
`a probability for level ${wireKey}`,
|
|
236
|
+
);
|
|
237
|
+
}
|
|
238
|
+
const domainKey = String(anchor.score);
|
|
239
|
+
legend[domainKey] = wire.legend[wireKey] ?? anchor.description;
|
|
240
|
+
probabilities[domainKey] = probability;
|
|
241
|
+
expected += probability * anchor.score;
|
|
242
|
+
});
|
|
243
|
+
return {
|
|
244
|
+
kind: 'score',
|
|
245
|
+
score: expected,
|
|
246
|
+
legend,
|
|
247
|
+
probabilities,
|
|
248
|
+
confidence: wire.confidence,
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function mapNoulAnswer(
|
|
253
|
+
_question: TypedJudgmentNoulQuestion,
|
|
254
|
+
wire: Extract<WireAnswer, { type: 'noul' }>,
|
|
255
|
+
): TypedJudgmentAnswer {
|
|
256
|
+
return { kind: 'noul', noul: wire.noul };
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
function mapAnswer(
|
|
260
|
+
question: TypedJudgmentQuestion,
|
|
261
|
+
wire: WireAnswer,
|
|
262
|
+
redact: Redact,
|
|
263
|
+
): TypedJudgmentAnswer {
|
|
264
|
+
if (wire.type !== question.kind) {
|
|
265
|
+
throw invalidResponse(
|
|
266
|
+
redact,
|
|
267
|
+
`judge answered question '${question.id}' with type '${wire.type}', ` +
|
|
268
|
+
`expected '${question.kind}'`,
|
|
269
|
+
);
|
|
270
|
+
}
|
|
271
|
+
switch (question.kind) {
|
|
272
|
+
case 'choice':
|
|
273
|
+
return mapChoiceAnswer(question, wire as Extract<WireAnswer, { type: 'choice' }>, redact);
|
|
274
|
+
case 'score':
|
|
275
|
+
return mapScoreAnswer(question, wire as Extract<WireAnswer, { type: 'score' }>, redact);
|
|
276
|
+
case 'noul':
|
|
277
|
+
return mapNoulAnswer(question, wire as Extract<WireAnswer, { type: 'noul' }>);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
// ─── HTTP error mapping ──────────────────────────────────────────────────────
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Map an HTTP error status + parsed body to a `TypedJudgmentError`. Auth
|
|
285
|
+
* errors carry `detail.error_type` only (never the provider message); all
|
|
286
|
+
* messages are redacted by the caller.
|
|
287
|
+
*/
|
|
288
|
+
function mapHttpError(status: number, body: unknown, redact: Redact): TypedJudgmentError {
|
|
289
|
+
if (status === 400) {
|
|
290
|
+
const objectError = wireObjectErrorSchema.safeParse(body);
|
|
291
|
+
if (objectError.success) {
|
|
292
|
+
const { error_type, message } = objectError.data.detail;
|
|
293
|
+
return new TypedJudgmentError(
|
|
294
|
+
'bad_request',
|
|
295
|
+
redact(
|
|
296
|
+
`judge rejected the request (${error_type})` + (message ? `: ${message}` : ''),
|
|
297
|
+
),
|
|
298
|
+
);
|
|
299
|
+
}
|
|
300
|
+
const stringError = wireStringErrorSchema.safeParse(body);
|
|
301
|
+
const reason = stringError.success ? `: ${stringError.data.detail}` : '';
|
|
302
|
+
return new TypedJudgmentError('bad_request', redact(`judge rejected the request${reason}`));
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
if (status === 422) {
|
|
306
|
+
const validationError = wireValidationErrorSchema.safeParse(body);
|
|
307
|
+
const summary = validationError.success
|
|
308
|
+
? validationError.data.detail
|
|
309
|
+
.map((item) => {
|
|
310
|
+
const loc = item.loc?.join('.') ?? '';
|
|
311
|
+
const parts = [loc, item.type, item.msg].filter(
|
|
312
|
+
(part): part is string => part !== undefined && part !== '',
|
|
313
|
+
);
|
|
314
|
+
return parts.join(': ');
|
|
315
|
+
})
|
|
316
|
+
.join('; ')
|
|
317
|
+
: '';
|
|
318
|
+
return new TypedJudgmentError(
|
|
319
|
+
'validation',
|
|
320
|
+
redact(`judge could not validate the request${summary ? `: ${summary}` : ''}`),
|
|
321
|
+
);
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
if (status === 401 || status === 403) {
|
|
325
|
+
// Carry detail.error_type only — the provider message is not forwarded.
|
|
326
|
+
const objectError = wireObjectErrorSchema.safeParse(body);
|
|
327
|
+
const errorType = objectError.success ? objectError.data.detail.error_type : 'unknown';
|
|
328
|
+
return new TypedJudgmentError('auth', `judge authentication failed (${errorType})`);
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
if (status === 429) {
|
|
332
|
+
return new TypedJudgmentError('rate_limited', 'judge rate limited the request');
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
if (status === 529) {
|
|
336
|
+
return new TypedJudgmentError('overloaded', 'judge is overloaded');
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
return new TypedJudgmentError('transport', `judge returned unexpected HTTP ${status}`);
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
// ─── Abort helpers ───────────────────────────────────────────────────────────
|
|
343
|
+
|
|
344
|
+
/** True for the abort/timeout reasons fetch rejects with. */
|
|
345
|
+
function isAbortError(error: unknown): boolean {
|
|
346
|
+
return (
|
|
347
|
+
error instanceof Error &&
|
|
348
|
+
(error.name === 'AbortError' || error.name === 'TimeoutError')
|
|
349
|
+
);
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** Sleep, rejecting with the signal's reason when the signal aborts. */
|
|
353
|
+
function sleep(ms: number, signal: AbortSignal): Promise<void> {
|
|
354
|
+
return new Promise((resolve, reject) => {
|
|
355
|
+
if (signal.aborted) {
|
|
356
|
+
reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
|
|
357
|
+
return;
|
|
358
|
+
}
|
|
359
|
+
const timer = setTimeout(() => {
|
|
360
|
+
signal.removeEventListener('abort', onAbort);
|
|
361
|
+
resolve();
|
|
362
|
+
}, ms);
|
|
363
|
+
const onAbort = () => {
|
|
364
|
+
clearTimeout(timer);
|
|
365
|
+
reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
|
|
366
|
+
};
|
|
367
|
+
signal.addEventListener('abort', onAbort, { once: true });
|
|
368
|
+
});
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
// ─── Adapter ─────────────────────────────────────────────────────────────────
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* `TypedJudgmentPort` over global fetch against a Jev-compatible endpoint.
|
|
375
|
+
*
|
|
376
|
+
* Construction is cheap and side-effect free apart from reading no env —
|
|
377
|
+
* the API key (remote endpoints only) is handed in by
|
|
378
|
+
* {@link createTypedJudgmentPort}, which is the fail-closed composition path.
|
|
379
|
+
* Direct construction is intended for tests; the factory enforces remote-key
|
|
380
|
+
* gating.
|
|
381
|
+
*/
|
|
382
|
+
export class JevTypedJudgmentAdapter implements TypedJudgmentPort {
|
|
383
|
+
readonly #config: TypedJudgmentConfig;
|
|
384
|
+
readonly #apiKey: string | undefined;
|
|
385
|
+
readonly #remote: boolean;
|
|
386
|
+
readonly #fetchImpl: FetchLike | undefined;
|
|
387
|
+
|
|
388
|
+
constructor(
|
|
389
|
+
config: TypedJudgmentConfig,
|
|
390
|
+
apiKey?: string,
|
|
391
|
+
fetchImpl?: FetchLike,
|
|
392
|
+
) {
|
|
393
|
+
this.#config = config;
|
|
394
|
+
this.#apiKey = apiKey;
|
|
395
|
+
this.#remote = !isLoopbackEndpoint(config.endpoint);
|
|
396
|
+
this.#fetchImpl = fetchImpl;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
async judge(
|
|
400
|
+
state: string,
|
|
401
|
+
questions: readonly TypedJudgmentQuestion[],
|
|
402
|
+
options: { signal: AbortSignal },
|
|
403
|
+
): Promise<TypedJudgmentAnswers> {
|
|
404
|
+
const redact: Redact = (message) => {
|
|
405
|
+
let out = redactPromptFromError(message, state);
|
|
406
|
+
for (const question of questions) {
|
|
407
|
+
out = redactPromptFromError(out, question.prompt);
|
|
408
|
+
}
|
|
409
|
+
return out;
|
|
410
|
+
};
|
|
411
|
+
|
|
412
|
+
// One deadline covers the whole call including retries; the caller's
|
|
413
|
+
// signal composes with it so either can abort the in-flight request.
|
|
414
|
+
const timeoutSignal = AbortSignal.timeout(this.#config.timeout_ms);
|
|
415
|
+
const callerSignal = options.signal;
|
|
416
|
+
const signal = AbortSignal.any([callerSignal, timeoutSignal]);
|
|
417
|
+
|
|
418
|
+
const headers: Record<string, string> = {
|
|
419
|
+
'content-type': 'application/json',
|
|
420
|
+
accept: 'application/json',
|
|
421
|
+
};
|
|
422
|
+
// Remote endpoints authenticate; loopback (local OpenJev) never sees the
|
|
423
|
+
// key. The key itself never appears in errors or logs.
|
|
424
|
+
if (this.#remote && this.#apiKey !== undefined) {
|
|
425
|
+
headers.authorization = `Bearer ${this.#apiKey}`;
|
|
426
|
+
}
|
|
427
|
+
|
|
428
|
+
const wireQuestions: Record<string, WireQuestion> = {};
|
|
429
|
+
for (const question of questions) {
|
|
430
|
+
wireQuestions[question.id] = toWireQuestion(question);
|
|
431
|
+
}
|
|
432
|
+
const body: Record<string, unknown> = {
|
|
433
|
+
model: this.#config.model,
|
|
434
|
+
state,
|
|
435
|
+
questions: wireQuestions,
|
|
436
|
+
};
|
|
437
|
+
// `samples` is an OpenJev extension; hosted Jev rejects unknown fields.
|
|
438
|
+
if (!this.#remote) {
|
|
439
|
+
body.samples = this.#config.samples;
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
try {
|
|
443
|
+
const response = await this.#postWithRetry(
|
|
444
|
+
JSON.stringify(body),
|
|
445
|
+
headers,
|
|
446
|
+
signal,
|
|
447
|
+
timeoutSignal,
|
|
448
|
+
);
|
|
449
|
+
|
|
450
|
+
if (!response.ok) {
|
|
451
|
+
const errorBody: unknown = await response.json().catch(() => undefined);
|
|
452
|
+
throw mapHttpError(response.status, errorBody, redact);
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
const payload: unknown = await response.json().catch(() => undefined);
|
|
456
|
+
const parsed = wireResponseSchema.safeParse(payload);
|
|
457
|
+
if (!parsed.success) {
|
|
458
|
+
throw invalidResponse(redact, 'judge returned a malformed response envelope');
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
const answers: Record<string, TypedJudgmentAnswer> = {};
|
|
462
|
+
for (const question of questions) {
|
|
463
|
+
const wire = parsed.data.answers[question.id];
|
|
464
|
+
if (wire === undefined) {
|
|
465
|
+
throw invalidResponse(
|
|
466
|
+
redact,
|
|
467
|
+
`judge response is missing an answer for question '${question.id}'`,
|
|
468
|
+
);
|
|
469
|
+
}
|
|
470
|
+
answers[question.id] = mapAnswer(question, wire, redact);
|
|
471
|
+
}
|
|
472
|
+
return answers;
|
|
473
|
+
} catch (error) {
|
|
474
|
+
if (error instanceof TypedJudgmentError) {
|
|
475
|
+
throw error;
|
|
476
|
+
}
|
|
477
|
+
if (isAbortError(error) || signal.aborted) {
|
|
478
|
+
// Caller abort wins over timeout when both fired together.
|
|
479
|
+
if (callerSignal.aborted) {
|
|
480
|
+
throw new TypedJudgmentError('aborted', 'typed judgment aborted by caller');
|
|
481
|
+
}
|
|
482
|
+
if (timeoutSignal.aborted) {
|
|
483
|
+
throw new TypedJudgmentError(
|
|
484
|
+
'timeout',
|
|
485
|
+
`typed judgment timed out after ${this.#config.timeout_ms} ms`,
|
|
486
|
+
);
|
|
487
|
+
}
|
|
488
|
+
}
|
|
489
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
490
|
+
throw new TypedJudgmentError(
|
|
491
|
+
'transport',
|
|
492
|
+
redact(`typed judgment transport failure: ${message}`),
|
|
493
|
+
);
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
/** POST with bounded retries on 429/529 (linear backoff, shared deadline). */
|
|
498
|
+
async #postWithRetry(
|
|
499
|
+
body: string,
|
|
500
|
+
headers: Record<string, string>,
|
|
501
|
+
signal: AbortSignal,
|
|
502
|
+
timeoutSignal: AbortSignal,
|
|
503
|
+
): Promise<Response> {
|
|
504
|
+
const doFetch = this.#fetchImpl ?? ((url: string, init: RequestInit) => globalThis.fetch(url, init));
|
|
505
|
+
let retries = 0;
|
|
506
|
+
for (;;) {
|
|
507
|
+
if (signal.aborted) {
|
|
508
|
+
throw signal.reason ?? new DOMException('Aborted', 'AbortError');
|
|
509
|
+
}
|
|
510
|
+
const response = await doFetch(this.#config.endpoint, {
|
|
511
|
+
method: 'POST',
|
|
512
|
+
headers,
|
|
513
|
+
body,
|
|
514
|
+
signal,
|
|
515
|
+
});
|
|
516
|
+
const retryable = response.status === 429 || response.status === 529;
|
|
517
|
+
// Retry only while retries remain and the deadline has not passed —
|
|
518
|
+
// the backoff sleep and the next attempt share `timeoutSignal`.
|
|
519
|
+
if (!retryable || retries >= MAX_RETRIES || timeoutSignal.aborted) {
|
|
520
|
+
return response;
|
|
521
|
+
}
|
|
522
|
+
retries += 1;
|
|
523
|
+
await sleep(BACKOFF_BASE_MS * retries, signal);
|
|
524
|
+
}
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
// ─── Fail-closed factory ─────────────────────────────────────────────────────
|
|
529
|
+
|
|
530
|
+
/** Why no typed judgment port was created. */
|
|
531
|
+
export type TypedJudgmentUnavailableReason =
|
|
532
|
+
| 'typed_judgment_disabled'
|
|
533
|
+
| 'typed_judgment_remote_key_missing';
|
|
534
|
+
|
|
535
|
+
export type CreateTypedJudgmentPortResult =
|
|
536
|
+
| { port: TypedJudgmentPort }
|
|
537
|
+
| { port: null; reason: TypedJudgmentUnavailableReason };
|
|
538
|
+
|
|
539
|
+
/**
|
|
540
|
+
* Composition-root factory (SP-305, #184). Fails closed:
|
|
541
|
+
* - `enabled: false` → `{ port: null, reason: 'typed_judgment_disabled' }`
|
|
542
|
+
* - remote endpoint with an empty/missing `api_key_env` value →
|
|
543
|
+
* `{ port: null, reason: 'typed_judgment_remote_key_missing' }`
|
|
544
|
+
*
|
|
545
|
+
* The key is read from `env[config.api_key_env]` here (at construction) and
|
|
546
|
+
* only ever lives inside the adapter; it is never read from config files
|
|
547
|
+
* and never logged.
|
|
548
|
+
*/
|
|
549
|
+
export function createTypedJudgmentPort(
|
|
550
|
+
config: TypedJudgmentConfig,
|
|
551
|
+
env: Readonly<Record<string, string | undefined>> = process.env,
|
|
552
|
+
): CreateTypedJudgmentPortResult {
|
|
553
|
+
if (!config.enabled) {
|
|
554
|
+
return { port: null, reason: 'typed_judgment_disabled' };
|
|
555
|
+
}
|
|
556
|
+
if (!isLoopbackEndpoint(config.endpoint)) {
|
|
557
|
+
const key = env[config.api_key_env];
|
|
558
|
+
if (key === undefined || key.trim() === '') {
|
|
559
|
+
return { port: null, reason: 'typed_judgment_remote_key_missing' };
|
|
560
|
+
}
|
|
561
|
+
return { port: new JevTypedJudgmentAdapter(config, key) };
|
|
562
|
+
}
|
|
563
|
+
return { port: new JevTypedJudgmentAdapter(config) };
|
|
564
|
+
}
|