dsh-jev-tools-continued 0.0.0-stage → 0.2.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 (122) hide show
  1. package/CHANGELOG.en.md +449 -0
  2. package/CHANGELOG.i18n.yaml +13 -0
  3. package/CHANGELOG.md +357 -0
  4. package/LICENSE +21 -0
  5. package/README.en.md +210 -0
  6. package/README.i18n.yaml +13 -0
  7. package/README.md +209 -2
  8. package/client/client.js +755 -0
  9. package/cordis.patch.yml +30 -0
  10. package/docs/banner.png +0 -0
  11. package/docs/dev-workflow.md +414 -0
  12. package/docs/s0-trigger-rate.md +168 -0
  13. package/icon.svg +16 -0
  14. package/lib/backends/jev.d.ts +69 -0
  15. package/lib/backends/jev.d.ts.map +1 -0
  16. package/lib/backends/jev.js +151 -0
  17. package/lib/backends/jev.js.map +1 -0
  18. package/lib/backends/types.d.ts +104 -0
  19. package/lib/backends/types.d.ts.map +1 -0
  20. package/lib/backends/types.js +12 -0
  21. package/lib/backends/types.js.map +1 -0
  22. package/lib/budget.d.ts +60 -0
  23. package/lib/budget.d.ts.map +1 -0
  24. package/lib/budget.js +70 -0
  25. package/lib/budget.js.map +1 -0
  26. package/lib/calibrate.d.ts +162 -0
  27. package/lib/calibrate.d.ts.map +1 -0
  28. package/lib/calibrate.js +269 -0
  29. package/lib/calibrate.js.map +1 -0
  30. package/lib/config.d.ts +261 -0
  31. package/lib/config.d.ts.map +1 -0
  32. package/lib/config.js +194 -0
  33. package/lib/config.js.map +1 -0
  34. package/lib/context-cache.d.ts +59 -0
  35. package/lib/context-cache.d.ts.map +1 -0
  36. package/lib/context-cache.js +116 -0
  37. package/lib/context-cache.js.map +1 -0
  38. package/lib/credentials.d.ts +32 -0
  39. package/lib/credentials.d.ts.map +1 -0
  40. package/lib/credentials.js +44 -0
  41. package/lib/credentials.js.map +1 -0
  42. package/lib/degrade.d.ts +36 -0
  43. package/lib/degrade.d.ts.map +1 -0
  44. package/lib/degrade.js +41 -0
  45. package/lib/degrade.js.map +1 -0
  46. package/lib/features/prune.d.ts +116 -0
  47. package/lib/features/prune.d.ts.map +1 -0
  48. package/lib/features/prune.js +574 -0
  49. package/lib/features/prune.js.map +1 -0
  50. package/lib/features/screen.d.ts +112 -0
  51. package/lib/features/screen.d.ts.map +1 -0
  52. package/lib/features/screen.js +130 -0
  53. package/lib/features/screen.js.map +1 -0
  54. package/lib/features/skill-suggest.d.ts +68 -0
  55. package/lib/features/skill-suggest.d.ts.map +1 -0
  56. package/lib/features/skill-suggest.js +283 -0
  57. package/lib/features/skill-suggest.js.map +1 -0
  58. package/lib/host.d.ts +280 -0
  59. package/lib/host.d.ts.map +1 -0
  60. package/lib/host.js +15 -0
  61. package/lib/host.js.map +1 -0
  62. package/lib/http.d.ts +71 -0
  63. package/lib/http.d.ts.map +1 -0
  64. package/lib/http.js +162 -0
  65. package/lib/http.js.map +1 -0
  66. package/lib/i18n.d.ts +372 -0
  67. package/lib/i18n.d.ts.map +1 -0
  68. package/lib/i18n.js +254 -0
  69. package/lib/i18n.js.map +1 -0
  70. package/lib/index.d.ts +44 -0
  71. package/lib/index.d.ts.map +1 -0
  72. package/lib/index.js +268 -0
  73. package/lib/index.js.map +1 -0
  74. package/lib/keys.d.ts +90 -0
  75. package/lib/keys.d.ts.map +1 -0
  76. package/lib/keys.js +131 -0
  77. package/lib/keys.js.map +1 -0
  78. package/lib/ledger-domain.d.ts +169 -0
  79. package/lib/ledger-domain.d.ts.map +1 -0
  80. package/lib/ledger-domain.js +338 -0
  81. package/lib/ledger-domain.js.map +1 -0
  82. package/lib/ledger.d.ts +243 -0
  83. package/lib/ledger.d.ts.map +1 -0
  84. package/lib/ledger.js +239 -0
  85. package/lib/ledger.js.map +1 -0
  86. package/lib/memo.d.ts +32 -0
  87. package/lib/memo.d.ts.map +1 -0
  88. package/lib/memo.js +62 -0
  89. package/lib/memo.js.map +1 -0
  90. package/lib/notify.d.ts +78 -0
  91. package/lib/notify.d.ts.map +1 -0
  92. package/lib/notify.js +122 -0
  93. package/lib/notify.js.map +1 -0
  94. package/lib/proxy.d.ts +40 -0
  95. package/lib/proxy.d.ts.map +1 -0
  96. package/lib/proxy.js +136 -0
  97. package/lib/proxy.js.map +1 -0
  98. package/lib/request.d.ts +99 -0
  99. package/lib/request.d.ts.map +1 -0
  100. package/lib/request.js +168 -0
  101. package/lib/request.js.map +1 -0
  102. package/lib/source.d.ts +46 -0
  103. package/lib/source.d.ts.map +1 -0
  104. package/lib/source.js +35 -0
  105. package/lib/source.js.map +1 -0
  106. package/lib/status.d.ts +42 -0
  107. package/lib/status.d.ts.map +1 -0
  108. package/lib/status.js +214 -0
  109. package/lib/status.js.map +1 -0
  110. package/lib/tokens.d.ts +26 -0
  111. package/lib/tokens.d.ts.map +1 -0
  112. package/lib/tokens.js +57 -0
  113. package/lib/tokens.js.map +1 -0
  114. package/lib/tools/jev-ask.d.ts +44 -0
  115. package/lib/tools/jev-ask.d.ts.map +1 -0
  116. package/lib/tools/jev-ask.js +208 -0
  117. package/lib/tools/jev-ask.js.map +1 -0
  118. package/lib/tools/jev-gate.d.ts +79 -0
  119. package/lib/tools/jev-gate.d.ts.map +1 -0
  120. package/lib/tools/jev-gate.js +412 -0
  121. package/lib/tools/jev-gate.js.map +1 -0
  122. package/package.json +169 -4
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The TypeSafe System One backend.
3
+ *
4
+ * One endpoint serves every model; the body's `model` field selects. The
5
+ * response's own `model` is the only durable record of what answered, because
6
+ * aliases move between releases.
7
+ *
8
+ * Requests are validated before they are sent (`request.ts`), and a failure is
9
+ * always a typed {@link JevError} carrying a machine-readable problem, so every
10
+ * caller can degrade visibly instead of guessing from a message string.
11
+ *
12
+ * @module dsh-jev-tools/backends/jev
13
+ */
14
+ import { type HttpDeps } from '../http.js';
15
+ import { DEFAULT_BASE_URL } from '../config.js';
16
+ import { type Violation } from '../request.js';
17
+ import type { Answer, DecisionBackend } from './types.js';
18
+ /**
19
+ * Default API root.
20
+ *
21
+ * Declared in `config.ts` so the setting's default and this backend's fallback
22
+ * cannot drift into two different hosts; re-exported here because this module is
23
+ * where a caller reads the backend's contract.
24
+ */
25
+ export { DEFAULT_BASE_URL };
26
+ /** Default per-request timeout, in milliseconds. */
27
+ export declare const DEFAULT_TIMEOUT_MS = 10000;
28
+ /** Everything that can go wrong, as a value rather than a message. */
29
+ export type JevProblem = 'invalid-request' | 'unauthorized' | 'bad-request' | 'rate-limited' | 'overloaded' | 'server' | 'network' | 'aborted' | 'malformed-response';
30
+ /** A failed judgment. */
31
+ export declare class JevError extends Error {
32
+ readonly problem: JevProblem;
33
+ /** Present for `invalid-request`: which questions were unsendable and why. */
34
+ readonly violations?: readonly Violation[];
35
+ constructor(problem: JevProblem, message: string, violations?: readonly Violation[]);
36
+ }
37
+ /** Construction options for {@link createJevBackend}. */
38
+ export interface JevBackendOptions {
39
+ /** Bearer token. Callers resolve this per operation; it is never cached here. */
40
+ readonly apiKey: string;
41
+ /** Model id or alias. */
42
+ readonly model: string;
43
+ /** System One API root, a bare host. Defaults to the vendor's own. */
44
+ readonly baseUrl?: string;
45
+ readonly timeoutMs?: number;
46
+ /** undici dispatcher (a `ProxyAgent`) when the request has to leave through a proxy. */
47
+ readonly dispatcher?: unknown;
48
+ /** Injectable transport, for tests. */
49
+ readonly deps?: HttpDeps;
50
+ }
51
+ /**
52
+ * Classify one wire answer.
53
+ *
54
+ * The three primitives are structurally disjoint, so an unrecognised `type`
55
+ * means a newer server: it is reported through `unknownAnswers` rather than
56
+ * dropped silently or allowed to poison the rest of the batch.
57
+ *
58
+ * @param raw - the answer as it arrived.
59
+ * @returns the typed answer, or `undefined` when this client cannot read it.
60
+ */
61
+ export declare function classifyAnswer(raw: unknown): Answer | undefined;
62
+ /**
63
+ * Create a Jev-backed {@link DecisionBackend}.
64
+ *
65
+ * @param options - credentials, model and transport overrides.
66
+ * @returns the backend.
67
+ */
68
+ export declare function createJevBackend(options: JevBackendOptions): DecisionBackend;
69
+ //# sourceMappingURL=jev.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jev.d.ts","sourceRoot":"","sources":["../../src/backends/jev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAY,KAAK,QAAQ,EAAoB,MAAM,YAAY,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAA+C,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAmC,MAAM,YAAY,CAAA;AAE1F;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,CAAA;AAE3B,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,QAAS,CAAA;AAExC,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAClB,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,cAAc,GACnE,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,oBAAoB,CAAA;AAE1E,yBAAyB;AACzB,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IAE1C,YAAa,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,EAKnF;CACF;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CACzB;AAuBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAE,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAwBhE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAE,OAAO,EAAE,iBAAiB,GAAG,eAAe,CA2D7E"}
@@ -0,0 +1,151 @@
1
+ /**
2
+ * The TypeSafe System One backend.
3
+ *
4
+ * One endpoint serves every model; the body's `model` field selects. The
5
+ * response's own `model` is the only durable record of what answered, because
6
+ * aliases move between releases.
7
+ *
8
+ * Requests are validated before they are sent (`request.ts`), and a failure is
9
+ * always a typed {@link JevError} carrying a machine-readable problem, so every
10
+ * caller can degrade visibly instead of guessing from a message string.
11
+ *
12
+ * @module dsh-jev-tools/backends/jev
13
+ */
14
+ import { postJson } from '../http.js';
15
+ import { DEFAULT_BASE_URL } from '../config.js';
16
+ import { SYSTEM_ONE_PATH, buildBody, validateRequest } from '../request.js';
17
+ /**
18
+ * Default API root.
19
+ *
20
+ * Declared in `config.ts` so the setting's default and this backend's fallback
21
+ * cannot drift into two different hosts; re-exported here because this module is
22
+ * where a caller reads the backend's contract.
23
+ */
24
+ export { DEFAULT_BASE_URL };
25
+ /** Default per-request timeout, in milliseconds. */
26
+ export const DEFAULT_TIMEOUT_MS = 10_000;
27
+ /** A failed judgment. */
28
+ export class JevError extends Error {
29
+ problem;
30
+ /** Present for `invalid-request`: which questions were unsendable and why. */
31
+ violations;
32
+ constructor(problem, message, violations) {
33
+ super(message);
34
+ this.name = 'JevError';
35
+ this.problem = problem;
36
+ if (violations !== undefined)
37
+ this.violations = violations;
38
+ }
39
+ }
40
+ /** Map the transport's classification onto this backend's. */
41
+ const PROBLEM_MAP = {
42
+ unauthorized: 'unauthorized',
43
+ 'bad-request': 'bad-request',
44
+ 'rate-limited': 'rate-limited',
45
+ overloaded: 'overloaded',
46
+ server: 'server',
47
+ network: 'network',
48
+ aborted: 'aborted',
49
+ };
50
+ /** Whether a value is a plain object. */
51
+ function isRecord(value) {
52
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
53
+ }
54
+ /** Whether a value is a finite number. */
55
+ function isNumber(value) {
56
+ return typeof value === 'number' && Number.isFinite(value);
57
+ }
58
+ /**
59
+ * Classify one wire answer.
60
+ *
61
+ * The three primitives are structurally disjoint, so an unrecognised `type`
62
+ * means a newer server: it is reported through `unknownAnswers` rather than
63
+ * dropped silently or allowed to poison the rest of the batch.
64
+ *
65
+ * @param raw - the answer as it arrived.
66
+ * @returns the typed answer, or `undefined` when this client cannot read it.
67
+ */
68
+ export function classifyAnswer(raw) {
69
+ if (!isRecord(raw))
70
+ return undefined;
71
+ if (raw.type === 'noul' && isNumber(raw.noul)) {
72
+ // A Noul answer carries no `confidence` by design; the value is thresholded directly.
73
+ return { type: 'noul', noul: raw.noul };
74
+ }
75
+ if (raw.type === 'choice' && typeof raw.choice === 'string' && isRecord(raw.probabilities) && isNumber(raw.confidence)) {
76
+ return {
77
+ type: 'choice',
78
+ choice: raw.choice,
79
+ probabilities: raw.probabilities,
80
+ confidence: raw.confidence,
81
+ };
82
+ }
83
+ if (raw.type === 'score' && isNumber(raw.score) && isRecord(raw.legend) && isRecord(raw.probabilities) && isNumber(raw.confidence)) {
84
+ return {
85
+ type: 'score',
86
+ score: raw.score,
87
+ legend: raw.legend,
88
+ probabilities: raw.probabilities,
89
+ confidence: raw.confidence,
90
+ };
91
+ }
92
+ return undefined;
93
+ }
94
+ /**
95
+ * Create a Jev-backed {@link DecisionBackend}.
96
+ *
97
+ * @param options - credentials, model and transport overrides.
98
+ * @returns the backend.
99
+ */
100
+ export function createJevBackend(options) {
101
+ const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
102
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
103
+ const deps = options.dispatcher === undefined
104
+ ? options.deps ?? {}
105
+ : { ...options.deps, dispatcher: options.dispatcher };
106
+ return {
107
+ id: 'jev',
108
+ async judge(request, signal) {
109
+ const violations = validateRequest(request);
110
+ if (violations.length > 0) {
111
+ throw new JevError('invalid-request', `请求在发送前被拒绝:${violations.map(v => v.detail).join(';')}`, violations);
112
+ }
113
+ const model = request.model ?? options.model;
114
+ const outcome = await postJson({
115
+ url: `${baseUrl}${SYSTEM_ONE_PATH}`,
116
+ body: buildBody(request, model),
117
+ headers: { authorization: `Bearer ${options.apiKey}` },
118
+ signal,
119
+ timeoutMs,
120
+ }, deps);
121
+ if (outcome.kind === 'error') {
122
+ throw new JevError(PROBLEM_MAP[outcome.problem], outcome.message);
123
+ }
124
+ const body = outcome.body;
125
+ if (!isRecord(body) || typeof body.model !== 'string' || !isRecord(body.answers)) {
126
+ throw new JevError('malformed-response', '响应缺少 model 或 answers 字段');
127
+ }
128
+ const answers = {};
129
+ const unknownAnswers = [];
130
+ for (const [id, raw] of Object.entries(body.answers)) {
131
+ const answer = classifyAnswer(raw);
132
+ if (answer === undefined)
133
+ unknownAnswers.push(id);
134
+ else
135
+ answers[id] = answer;
136
+ }
137
+ const result = {
138
+ // The version that answered, not the alias that was asked for.
139
+ model: body.model,
140
+ answers,
141
+ requestedModel: model,
142
+ ...(unknownAnswers.length > 0 ? { unknownAnswers } : {}),
143
+ ...(isRecord(body.usage) && isNumber(body.usage.input_tokens)
144
+ ? { usage: { inputTokens: body.usage.input_tokens, outputTokens: isNumber(body.usage.output_tokens) ? body.usage.output_tokens : 0 } }
145
+ : {}),
146
+ };
147
+ return result;
148
+ },
149
+ };
150
+ }
151
+ //# sourceMappingURL=jev.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jev.js","sourceRoot":"","sources":["../../src/backends/jev.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,104 @@
1
+ /**
2
+ * The judgment vocabulary and the neutral backend seam.
3
+ *
4
+ * Kept separate from the TypeSafe implementation so the vendor is a swappable
5
+ * detail rather than a foundation: Jev is an early-access model from a young
6
+ * company with no published SLA, and the whole point of this seam is that
7
+ * replacing it is a config change, not a rewrite.
8
+ *
9
+ * @module dsh-jev-tools/backends/types
10
+ */
11
+ /** Values Jev accepts as `instructions`: a string, an object, or an array of either. */
12
+ export type InstructionValue = string | {
13
+ readonly [key: string]: unknown;
14
+ } | readonly unknown[];
15
+ /** A yes/no question. `criteria` is optional and extends the instruction. */
16
+ export interface NoulQuestion {
17
+ readonly type: 'noul';
18
+ readonly instructions: InstructionValue;
19
+ readonly criteria?: {
20
+ readonly true?: unknown;
21
+ readonly false?: unknown;
22
+ };
23
+ }
24
+ /** Choose exactly one of a bounded, caller-defined set. */
25
+ export interface ChoiceQuestion {
26
+ readonly type: 'choice';
27
+ readonly instructions: InstructionValue;
28
+ /** Option → rubric. At most 255 entries. */
29
+ readonly criteria: {
30
+ readonly [option: string]: unknown;
31
+ };
32
+ }
33
+ /** Rate along an ordered scale. */
34
+ export interface ScoreQuestion {
35
+ readonly type: 'score';
36
+ readonly instructions: InstructionValue;
37
+ /** Ordered levels, most severe last. Between 2 and 10 entries. */
38
+ readonly criteria: readonly unknown[];
39
+ }
40
+ /** One typed question. The map key is the caller's own id and never reaches the model. */
41
+ export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
42
+ /** Answer to a {@link NoulQuestion}. Carries no `confidence` — threshold the value itself. */
43
+ export interface NoulAnswer {
44
+ readonly type: 'noul';
45
+ readonly noul: number;
46
+ }
47
+ /** Answer to a {@link ChoiceQuestion}. */
48
+ export interface ChoiceAnswer {
49
+ readonly type: 'choice';
50
+ readonly choice: string;
51
+ readonly probabilities: {
52
+ readonly [option: string]: number;
53
+ };
54
+ readonly confidence: number;
55
+ }
56
+ /** Answer to a {@link ScoreQuestion}. `score` is probability-weighted and may land between levels. */
57
+ export interface ScoreAnswer {
58
+ readonly type: 'score';
59
+ readonly score: number;
60
+ readonly legend: {
61
+ readonly [level: string]: string;
62
+ };
63
+ readonly probabilities: {
64
+ readonly [level: string]: number;
65
+ };
66
+ readonly confidence: number;
67
+ }
68
+ /** One answer of any kind. */
69
+ export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
70
+ /** What to judge. */
71
+ export interface JudgmentRequest {
72
+ /** The material to assess: a string, an object, or an array of values. */
73
+ readonly state: string | {
74
+ readonly [key: string]: unknown;
75
+ } | readonly unknown[];
76
+ /** Caller-keyed questions. Ids are echoed back and are never sent to the model. */
77
+ readonly questions: {
78
+ readonly [id: string]: Question;
79
+ };
80
+ /** Model id or alias. The response's own `model` is what gets recorded. */
81
+ readonly model?: string;
82
+ }
83
+ /** What came back. */
84
+ export interface JudgmentResult {
85
+ /** The version that actually answered. Aliases move, so this is the only durable fact. */
86
+ readonly model: string;
87
+ readonly answers: {
88
+ readonly [id: string]: Answer;
89
+ };
90
+ readonly usage?: {
91
+ readonly inputTokens: number;
92
+ readonly outputTokens: number;
93
+ };
94
+ /** The alias or id that was requested, for detecting that an alias moved. */
95
+ readonly requestedModel?: string;
96
+ /** Answer ids whose type this client does not understand, reported rather than dropped silently. */
97
+ readonly unknownAnswers?: readonly string[];
98
+ }
99
+ /** A swappable judgment backend. */
100
+ export interface DecisionBackend {
101
+ readonly id: string;
102
+ judge(request: JudgmentRequest, signal: AbortSignal): Promise<JudgmentResult>;
103
+ }
104
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * The judgment vocabulary and the neutral backend seam.
3
+ *
4
+ * Kept separate from the TypeSafe implementation so the vendor is a swappable
5
+ * detail rather than a foundation: Jev is an early-access model from a young
6
+ * company with no published SLA, and the whole point of this seam is that
7
+ * replacing it is a config change, not a rewrite.
8
+ *
9
+ * @module dsh-jev-tools/backends/types
10
+ */
11
+ export {};
12
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Judgment quotas.
3
+ *
4
+ * S0 measured what happens without one: a single turn can present 27
5
+ * oversized read-family results, which at roughly 300 ms each is 8.1 seconds
6
+ * of added serial latency. The per-turn ceiling is therefore not an
7
+ * optimisation but the mechanism that bounds the cost — measured, it is what
8
+ * holds the worst turn to 0.9 s.
9
+ *
10
+ * The session ceiling exists for a different reason: it is the hard stop on
11
+ * how much content leaves the machine and how much the user's key is spent,
12
+ * across every capability that judges.
13
+ *
14
+ * @module dsh-jev-tools/budget
15
+ */
16
+ /** Why a judgment was refused. */
17
+ export type BudgetRefusal = 'budget-turn' | 'budget-session';
18
+ /** The result of asking for one judgment. */
19
+ export type BudgetGrant = {
20
+ readonly ok: true;
21
+ } | {
22
+ readonly ok: false;
23
+ readonly reason: BudgetRefusal;
24
+ };
25
+ /** A per-turn and per-session allowance. */
26
+ export interface Budget {
27
+ /**
28
+ * Consume one allowance for an automatic capability, bounded per turn as well
29
+ * as per session.
30
+ */
31
+ tryConsume(agentId: string, turn: number): BudgetGrant;
32
+ /**
33
+ * Consume one allowance for an explicit call, bounded per session only.
34
+ *
35
+ * The per-turn ceiling exists to bound the latency an *automatic* capability
36
+ * can add to a turn — measured, 27 uncapped triggers ≈ 8.1 s against 0.9 s at
37
+ * a cap of three. An explicit `jev_ask` / `jev_gate` is the caller asking for
38
+ * one answer, so that ceiling has no rationale there. Worse, such a call
39
+ * carries no turn number, and passing a placeholder turned the per-turn
40
+ * ceiling into a session-long cap of three: the fourth call onwards was
41
+ * refused with `budget-turn` for the rest of the session.
42
+ */
43
+ tryConsumeSession(agentId: string): BudgetGrant;
44
+ /** Judgments consumed in this session so far. */
45
+ sessionUsage(agentId: string): number;
46
+ /** Judgments consumed in one turn so far. */
47
+ turnUsage(agentId: string, turn: number): number;
48
+ /** Forget an agent's counters. */
49
+ forget(agentId: string): void;
50
+ }
51
+ /**
52
+ * Create a quota tracker.
53
+ *
54
+ * @param perTurn - maximum judgments in one turn.
55
+ * @param perSession - maximum judgments in one session.
56
+ * @param maxAgents - ceiling on tracked agents, so a long-lived host does not leak.
57
+ * @returns the budget.
58
+ */
59
+ export declare function createBudget(perTurn: number, perSession: number, maxAgents?: number): Budget;
60
+ //# sourceMappingURL=budget.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,gBAAgB,CAAA;AAE5D,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAE1D,4CAA4C;AAC5C,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,UAAU,CAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IACvD;;;;;;;;;;OAUG;IACH,iBAAiB,CAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAAA;IAChD,iDAAiD;IACjD,YAAY,CAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACtC,6CAA6C;IAC7C,SAAS,CAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACjD,kCAAkC;IAClC,MAAM,CAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CA2CzF"}
package/lib/budget.js ADDED
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Judgment quotas.
3
+ *
4
+ * S0 measured what happens without one: a single turn can present 27
5
+ * oversized read-family results, which at roughly 300 ms each is 8.1 seconds
6
+ * of added serial latency. The per-turn ceiling is therefore not an
7
+ * optimisation but the mechanism that bounds the cost — measured, it is what
8
+ * holds the worst turn to 0.9 s.
9
+ *
10
+ * The session ceiling exists for a different reason: it is the hard stop on
11
+ * how much content leaves the machine and how much the user's key is spent,
12
+ * across every capability that judges.
13
+ *
14
+ * @module dsh-jev-tools/budget
15
+ */
16
+ /**
17
+ * Create a quota tracker.
18
+ *
19
+ * @param perTurn - maximum judgments in one turn.
20
+ * @param perSession - maximum judgments in one session.
21
+ * @param maxAgents - ceiling on tracked agents, so a long-lived host does not leak.
22
+ * @returns the budget.
23
+ */
24
+ export function createBudget(perTurn, perSession, maxAgents = 64) {
25
+ const byAgent = new Map();
26
+ const countersFor = (agentId) => {
27
+ const existing = byAgent.get(agentId);
28
+ if (existing !== undefined)
29
+ return existing;
30
+ const fresh = { session: 0, turns: new Map() };
31
+ byAgent.set(agentId, fresh);
32
+ while (byAgent.size > maxAgents) {
33
+ const oldest = byAgent.keys().next();
34
+ if (oldest.done === true)
35
+ break;
36
+ byAgent.delete(oldest.value);
37
+ }
38
+ return fresh;
39
+ };
40
+ return {
41
+ tryConsume(agentId, turn) {
42
+ const counters = countersFor(agentId);
43
+ if (counters.session >= perSession)
44
+ return { ok: false, reason: 'budget-session' };
45
+ const used = counters.turns.get(turn) ?? 0;
46
+ if (used >= perTurn)
47
+ return { ok: false, reason: 'budget-turn' };
48
+ counters.session += 1;
49
+ counters.turns.set(turn, used + 1);
50
+ return { ok: true };
51
+ },
52
+ tryConsumeSession(agentId) {
53
+ const counters = countersFor(agentId);
54
+ if (counters.session >= perSession)
55
+ return { ok: false, reason: 'budget-session' };
56
+ counters.session += 1;
57
+ return { ok: true };
58
+ },
59
+ sessionUsage(agentId) {
60
+ return byAgent.get(agentId)?.session ?? 0;
61
+ },
62
+ turnUsage(agentId, turn) {
63
+ return byAgent.get(agentId)?.turns.get(turn) ?? 0;
64
+ },
65
+ forget(agentId) {
66
+ byAgent.delete(agentId);
67
+ },
68
+ };
69
+ }
70
+ //# sourceMappingURL=budget.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqCH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAE,OAAe,EAAE,UAAkB,EAAE,SAAS,GAAG,EAAE;IAE/E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAA;IAE3C,MAAM,WAAW,GAAG,CAAC,OAAe,EAAY,EAAE;QAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACrC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QAC3C,MAAM,KAAK,GAAa,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,CAAA;QACxD,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC3B,OAAO,OAAO,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;YACpC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;gBAAE,MAAK;YAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9B,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO;QACL,UAAU,CAAE,OAAO,EAAE,IAAI;YACvB,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;YACrC,IAAI,QAAQ,CAAC,OAAO,IAAI,UAAU;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;YAClF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC1C,IAAI,IAAI,IAAI,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAA;YAChE,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAA;YACrB,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;YAClC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;QACrB,CAAC;QACD,iBAAiB,CAAE,OAAO;YACxB,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;YACrC,IAAI,QAAQ,CAAC,OAAO,IAAI,UAAU;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAA;YAClF,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAA;YACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;QACrB,CAAC;QACD,YAAY,CAAE,OAAO;YACnB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI,CAAC,CAAA;QAC3C,CAAC;QACD,SAAS,CAAE,OAAO,EAAE,IAAI;YACtB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnD,CAAC;QACD,MAAM,CAAE,OAAO;YACb,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACzB,CAAC;KACF,CAAA;AACH,CAAC"}
@@ -0,0 +1,162 @@
1
+ /**
2
+ * Probability calibration.
3
+ *
4
+ * Jev's raw numbers are not usable as probabilities, and the two independent
5
+ * observations point in opposite directions depending on difficulty: on a hard
6
+ * detection task its scores run *low* (a monitoring experiment found it "quite
7
+ * shy"), while on an easy three-way classification it saturates at 1.000. So
8
+ * neither a fixed threshold nor the raw value travels between tasks.
9
+ *
10
+ * What does travel is a *fitted* mapping on your own labelled data. This module
11
+ * fits one and applies it — and binds the result to the model version that
12
+ * answered, because an alias such as `jev-latest` moves between releases and a
13
+ * mapping fitted on one version is meaningless on the next.
14
+ *
15
+ * v0.1 does not use this: pruning only *ranks*, and ranking needs no
16
+ * calibration. It exists so the thresholds a gate will need are a fit away
17
+ * rather than a guess, and so the runtime that produced the samples is on
18
+ * record.
19
+ *
20
+ * @module dsh-jev-tools/calibrate
21
+ */
22
+ /** One labelled observation: a raw probability and what actually happened. */
23
+ export interface Sample {
24
+ /** The raw value the model reported, in [0, 1]. */
25
+ readonly p: number;
26
+ /** The truth: 1 when the positive outcome occurred, otherwise 0. */
27
+ readonly y: 0 | 1;
28
+ }
29
+ /** A monotone step in an isotonic fit. */
30
+ export interface IsotonicKnot {
31
+ readonly x: number;
32
+ readonly y: number;
33
+ }
34
+ /** A fitted mapping, bound to the model version it came from. */
35
+ export interface CalibrationParams {
36
+ /** The `model` field of the responses these samples came from. */
37
+ readonly model: string;
38
+ /** Which fitter produced this. */
39
+ readonly method: 'isotonic' | 'platt';
40
+ /** Knots for `isotonic`, ascending in `x`. */
41
+ readonly knots?: readonly IsotonicKnot[];
42
+ /** Sigmoid coefficients for `platt`: `1 / (1 + exp(-(a * p + b)))`. */
43
+ readonly a?: number;
44
+ readonly b?: number;
45
+ /** How many samples went into the fit. */
46
+ readonly samples: number;
47
+ readonly fittedAt: number;
48
+ }
49
+ /** The outcome of applying a mapping. */
50
+ export interface Calibrated {
51
+ readonly p: number;
52
+ /** False when the mapping was ignored — unknown or fitted on another version. */
53
+ readonly calibrated: boolean;
54
+ /** Why it was ignored, when it was. */
55
+ readonly reason?: 'none' | 'version-mismatch' | 'too-few-samples';
56
+ }
57
+ /**
58
+ * Fit by pool-adjacent-violators.
59
+ *
60
+ * Produces the best monotone non-decreasing step function under squared error —
61
+ * which is exactly the shape wanted, because a monotone mapping can reorder
62
+ * nothing: it changes the *values* while leaving the ranking that pruning
63
+ * depends on completely intact.
64
+ *
65
+ * @param samples - the labelled observations.
66
+ * @returns ascending knots.
67
+ */
68
+ export declare function fitIsotonic(samples: readonly Sample[]): IsotonicKnot[];
69
+ /**
70
+ * Fit a logistic mapping by gradient descent.
71
+ *
72
+ * @param samples - the labelled observations.
73
+ * @returns the sigmoid coefficients.
74
+ */
75
+ export declare function fitPlatt(samples: readonly Sample[]): {
76
+ a: number;
77
+ b: number;
78
+ };
79
+ /**
80
+ * Fit a mapping from labelled data.
81
+ *
82
+ * @param samples - the labelled observations.
83
+ * @param model - the model version they came from; recorded, never inferred.
84
+ * @param now - clock injection, for deterministic tests.
85
+ * @returns the fitted parameters.
86
+ */
87
+ export declare function fit(samples: readonly Sample[], model: string, now?: () => number): CalibrationParams;
88
+ /**
89
+ * Apply a mapping to a raw probability.
90
+ *
91
+ * Refuses to apply a mapping fitted on a different model version: aliases move
92
+ * between releases, and silently reusing a stale mapping would be worse than
93
+ * returning the raw value, because nothing downstream could tell.
94
+ *
95
+ * @param params - the fitted mapping, if any.
96
+ * @param p - the raw probability.
97
+ * @param model - the version that produced `p`.
98
+ * @returns the mapped value and whether the mapping was actually used.
99
+ */
100
+ export declare function apply(params: CalibrationParams | undefined, p: number, model: string): Calibrated;
101
+ /**
102
+ * Mean absolute gap between predicted and observed, in ten equal-width bins.
103
+ *
104
+ * This is the number a threshold decision should be based on. A well-calibrated
105
+ * model scores near zero; a model that always says 1.000 on a task it gets
106
+ * right 70% of the time scores around 0.3.
107
+ *
108
+ * @param samples - the labelled observations, already mapped if that is the question.
109
+ * @returns expected calibration error in [0, 1].
110
+ */
111
+ export declare function expectedCalibrationError(samples: readonly Sample[]): number;
112
+ /**
113
+ * Area under the ROC curve, by rank.
114
+ *
115
+ * This is the Mann–Whitney U statistic, and it answers the one question a
116
+ * calibration error cannot: **can this model tell the two classes apart at
117
+ * all?** A perfectly calibrated but useless model scores 0.5 here, and a
118
+ * saturated-but-informative one can score high while its ECE is terrible.
119
+ *
120
+ * Ties are given their average rank, so a model that answers a constant gets
121
+ * 0.5 rather than a number that depends on the input order.
122
+ *
123
+ * @param samples - the labelled observations.
124
+ * @returns AUC in [0, 1], or 0.5 when one class is absent — nothing can be
125
+ * ranked, and 0.5 is the value that says so instead of implying a skill.
126
+ */
127
+ export declare function auc(samples: readonly Sample[]): number;
128
+ /** One operating point: what a threshold does to a labelled set. */
129
+ export interface OperatingPoint {
130
+ readonly threshold: number;
131
+ /** Of the samples called positive, the share that are. */
132
+ readonly precision: number;
133
+ /** Of the truly positive samples, the share that were called. */
134
+ readonly recall: number;
135
+ readonly f1: number;
136
+ /** How many samples this threshold calls positive. */
137
+ readonly predicted: number;
138
+ readonly truePositives: number;
139
+ }
140
+ /**
141
+ * Score every threshold in a sweep.
142
+ *
143
+ * This is the step between "the model is calibrated" and "here is the cut-off
144
+ * to use": pruning only ranks and needs no threshold, but a gate does, and the
145
+ * sweep is what turns the choice into a measurement rather than a preference.
146
+ *
147
+ * @param samples - the labelled observations.
148
+ * @param steps - how many thresholds to try, spread strictly inside (0, 1).
149
+ * @returns one point per threshold, ascending.
150
+ */
151
+ export declare function sweepThresholds(samples: readonly Sample[], steps?: number): OperatingPoint[];
152
+ /**
153
+ * The sweep's best F1.
154
+ *
155
+ * A tie goes to the **higher** threshold: at the same F1 the stricter cut-off
156
+ * spends less of the reader's attention on the cases that do not need it.
157
+ *
158
+ * @param points - a sweep, ascending in threshold.
159
+ * @returns the chosen point, or `undefined` for an empty sweep.
160
+ */
161
+ export declare function bestOperatingPoint(points: readonly OperatingPoint[]): OperatingPoint | undefined;
162
+ //# sourceMappingURL=calibrate.d.ts.map