@crossworks/client-types 0.400.34 → 0.400.39

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.400.34",
3
+ "version": "0.400.39",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -9,7 +9,7 @@
9
9
  "./*": "./src/*.ts"
10
10
  },
11
11
  "devDependencies": {
12
- "@types/node": "^26.6.5"
12
+ "@types/node": "^26.6.6"
13
13
  },
14
14
  "license": "SEE LICENSE IN LICENSE.md",
15
15
  "repository": {
@@ -0,0 +1,225 @@
1
+ /**
2
+ * Decision model profiles: what we measured about each OpenRouter decision
3
+ * model, beside what the live catalog already says (context size, input
4
+ * types, price). The catalog cannot say whether a model takes Mantle's
5
+ * request at all, at what privacy level, or how it bills, so this table does.
6
+ *
7
+ * Source: the 2026-10-30 probe of all 28 models (one model at a time; a small
8
+ * request, then one full-size request of 25 passages, about 19,000 tokens,
9
+ * under the 1.5 s worker limit). One full-size timing per model, so `slow`
10
+ * and `fails_full_size` are a first read, not a verdict. A model that is not
11
+ * here is untested: it may run, and nothing claims it works.
12
+ *
13
+ * It feeds the pool's refusal (`decisionModelRefusal`, read by
14
+ * `poolModelIssue`), the decider pool's re-curation (`poolPosition`) and the
15
+ * request planner's limits (`decisionRequestLimits`, read by
16
+ * @mantle/decisions). The worker screen reads it later.
17
+ */
18
+
19
+ export type DecisionModelStatus =
20
+ /** Full-size request answered under 1.5 s with `zdr`. */
21
+ | 'works'
22
+ /** Answers only with privacy `no_training`: `zdr` returns 404. */
23
+ | 'no_training_only'
24
+ /** Answers, but a full-size request took 1.7 to 5.7 s. */
25
+ | 'slow'
26
+ /** A full-size request failed: a timeout, a 16-question limit, a
27
+ * 16,384-token limit or a byte limit. Smaller requests may pass. */
28
+ | 'fails_full_size'
29
+ /** Cannot take Mantle's request: another state shape or no live endpoint.
30
+ * The decider pool refuses it. */
31
+ | 'refused';
32
+
33
+ export type DecisionModelProfile = {
34
+ /** The OpenRouter id, lower case. */
35
+ id: string;
36
+ status: DecisionModelStatus;
37
+ /** The strictest privacy level its OpenRouter route accepts. */
38
+ privacy: 'zdr' | 'no_training';
39
+ /** Bills the state once per question: one search billed about 450,000
40
+ * tokens. */
41
+ perQuestionBilling?: true;
42
+ /** Reported exactly this many input tokens for a larger request: a
43
+ * suspected silent cut. Unsafe until checked. */
44
+ suspectedCutAt?: number;
45
+ /** Most questions it takes in one request, when measured. */
46
+ maxQuestions?: number;
47
+ /** Most input tokens it takes in one request, when measured and lower
48
+ * than the catalog's context size. */
49
+ maxInputTokens?: number;
50
+ /** A start value for passage scoring's threshold where Jev's 1.5 drops
51
+ * right passages. Tune it with eval:route. */
52
+ thresholdStart?: number;
53
+ /** Its place in the shipped decider pool. A product decision (2026-10-30),
54
+ * not a ranking: re-curation offers only these, in this order. */
55
+ poolPosition?: number;
56
+ note?: string;
57
+ };
58
+
59
+ const REFUSED =
60
+ "cannot take Mantle's decision request (another state shape, or no live endpoint; probe 2026-10-30)";
61
+
62
+ export const DECISION_MODEL_PROFILES: readonly DecisionModelProfile[] = [
63
+ // Group A: work today, under 1.5 s.
64
+ {
65
+ id: '~typesafe/jev-latest',
66
+ status: 'works',
67
+ privacy: 'zdr',
68
+ poolPosition: 0,
69
+ note: 'the shipped default',
70
+ },
71
+ { id: 'typesafe/jev-1.14', status: 'works', privacy: 'zdr' },
72
+ { id: 'typesafe/jev-1.13', status: 'works', privacy: 'zdr' },
73
+ {
74
+ id: 'perplexity/pplx-decider-v1.2',
75
+ status: 'works',
76
+ privacy: 'zdr',
77
+ poolPosition: 1,
78
+ note: 'the second choice: tied Jev on quality at about half the cost; slower (median 643 ms)',
79
+ },
80
+ {
81
+ id: 'microsoft/microsoft-decision-1',
82
+ status: 'works',
83
+ privacy: 'zdr',
84
+ note: 'tied Jev on quality; built on Qwen3.5-9B',
85
+ },
86
+ { id: 'nace-ai/drex-v1.5', status: 'works', privacy: 'zdr' },
87
+ {
88
+ id: 'cloudflare/clef-omni',
89
+ status: 'works',
90
+ privacy: 'zdr',
91
+ note: 'ranked passages worse than search alone; do not use',
92
+ },
93
+ // Group B: blocked only by zdr.
94
+ {
95
+ id: 'openai/gpt-6-luna-decisions',
96
+ status: 'no_training_only',
97
+ privacy: 'no_training',
98
+ thresholdStart: 1.0,
99
+ note: 'no zero-retention route on OpenRouter; scored some right passages near 0',
100
+ },
101
+ {
102
+ id: 'respan/span-02',
103
+ status: 'no_training_only',
104
+ privacy: 'no_training',
105
+ perQuestionBilling: true,
106
+ note: 'also 1.6 s on a full-size request',
107
+ },
108
+ // Group C: work, but too slow for 1.5 s.
109
+ { id: 'liquid/d1', status: 'slow', privacy: 'zdr' },
110
+ { id: 'liquid/d1.1', status: 'slow', privacy: 'zdr' },
111
+ { id: 'liquid/d1-ultra', status: 'slow', privacy: 'zdr' },
112
+ { id: 'inception/mercury-decide', status: 'slow', privacy: 'zdr' },
113
+ { id: 'cloudflare/clef', status: 'slow', privacy: 'zdr' },
114
+ { id: 'cloudflare/clef-flash', status: 'slow', privacy: 'zdr', suspectedCutAt: 16_384 },
115
+ {
116
+ id: 'perplexity/pplx-decider-flash-v1.2',
117
+ status: 'slow',
118
+ privacy: 'zdr',
119
+ perQuestionBilling: true,
120
+ },
121
+ { id: 'upstage/solar-decide-flash', status: 'slow', privacy: 'zdr', perQuestionBilling: true },
122
+ { id: 'jaredpalmer/kev-4b', status: 'slow', privacy: 'zdr' },
123
+ // Group D: fail on a full-size request.
124
+ { id: 'upstage/solar-decide', status: 'fails_full_size', privacy: 'zdr' },
125
+ { id: 'nace-ai/drex-v2.0', status: 'fails_full_size', privacy: 'zdr' },
126
+ { id: 'nace-ai/drex-max', status: 'fails_full_size', privacy: 'zdr' },
127
+ { id: 'baseten/joey-1', status: 'fails_full_size', privacy: 'zdr' },
128
+ { id: 'baseten/elephant-1', status: 'fails_full_size', privacy: 'zdr' },
129
+ { id: 'baseten/mammoth-1', status: 'fails_full_size', privacy: 'zdr' },
130
+ { id: 'togethercomputer/tev1-4b-experimental', status: 'fails_full_size', privacy: 'zdr' },
131
+ // Group E: cannot take our request at all.
132
+ { id: 'scaledown/classify-1', status: 'refused', privacy: 'zdr', note: REFUSED },
133
+ { id: 'respan/span-01', status: 'refused', privacy: 'zdr', note: REFUSED },
134
+ { id: 'respan/span-01-lite', status: 'refused', privacy: 'zdr', note: REFUSED },
135
+ { id: 'cloudflare/clairic', status: 'refused', privacy: 'zdr', note: REFUSED },
136
+ ];
137
+
138
+ const BY_ID = new Map(DECISION_MODEL_PROFILES.map((p) => [p.id, p]));
139
+
140
+ /** The profile of a decision model id, or null when it is untested. A
141
+ * variant suffix (`:free`) is the same model, so it shares the profile. */
142
+ export function decisionModelProfile(
143
+ model: string | null | undefined,
144
+ ): DecisionModelProfile | null {
145
+ if (!model) return null;
146
+ const id = model
147
+ .trim()
148
+ .toLowerCase()
149
+ .replace(/:[a-z0-9_-]+$/, '');
150
+ return BY_ID.get(id) ?? null;
151
+ }
152
+
153
+ /** Why the decider pool refuses this model, or null when it does not. */
154
+ export function decisionModelRefusal(model: string | null | undefined): string | null {
155
+ const p = decisionModelProfile(model);
156
+ if (p?.status !== 'refused') return null;
157
+ return (
158
+ `this model ${p.note ?? REFUSED}. ` +
159
+ 'Pick a tested decision model such as ~typesafe/jev-latest or perplexity/pplx-decider-v1.2.'
160
+ );
161
+ }
162
+
163
+ /** The size of one decision request a model takes. Null = no limit is known,
164
+ * so the use's own size stands. */
165
+ export type DecisionRequestLimits = {
166
+ maxQuestions: number | null;
167
+ maxInputTokens: number | null;
168
+ /** A reported input-token count exactly at this is a suspected silent cut:
169
+ * the answer is not used. */
170
+ cutAt: number | null;
171
+ /** `profile`: a tested model, sized from its measured profile.
172
+ * `careful`: untested, or failed at full size, so the careful limits. */
173
+ source: 'profile' | 'careful';
174
+ };
175
+
176
+ /** Limits for a model that is untested or failed at full size. The probe's
177
+ * failures were a 16-question limit and a 16,384-token limit (2026-10-30),
178
+ * so a request this size passes both. */
179
+ export const CAREFUL_DECISION_LIMITS = { maxQuestions: 16, maxInputTokens: 16_384 } as const;
180
+
181
+ /**
182
+ * The request limits of a decision model (pure). `catalogContext` is the live
183
+ * catalog's context size for the model, or null when the catalog has not
184
+ * loaded or does not list it.
185
+ *
186
+ * A tested model (it took a full-size request, as Jev takes every use's
187
+ * request in production) is sized from its measured profile only: with no
188
+ * measured limit, each use keeps the request it was measured with. The
189
+ * catalog does not size it, because the request estimate counts high and a
190
+ * catalog value would then split or refuse requests the model answers.
191
+ * Any other model gets the careful limits, lowered to the catalog's context
192
+ * size when that is smaller.
193
+ */
194
+ export function decisionRequestLimits(
195
+ model: string | null | undefined,
196
+ catalogContext: number | null,
197
+ ): DecisionRequestLimits {
198
+ const p = decisionModelProfile(model);
199
+ const ctx =
200
+ typeof catalogContext === 'number' && Number.isFinite(catalogContext) && catalogContext > 0
201
+ ? catalogContext
202
+ : null;
203
+ const low = (...xs: Array<number | null | undefined>): number | null => {
204
+ const known = xs.filter((x): x is number => typeof x === 'number');
205
+ return known.length > 0 ? Math.min(...known) : null;
206
+ };
207
+ const tested =
208
+ p !== null && (p.status === 'works' || p.status === 'no_training_only' || p.status === 'slow');
209
+ if (!tested) {
210
+ const tokens = low(CAREFUL_DECISION_LIMITS.maxInputTokens, ctx, p?.suspectedCutAt);
211
+ return {
212
+ maxQuestions: low(CAREFUL_DECISION_LIMITS.maxQuestions, p?.maxQuestions),
213
+ maxInputTokens: tokens,
214
+ cutAt: p?.suspectedCutAt ?? tokens,
215
+ source: 'careful',
216
+ };
217
+ }
218
+ const tokens = low(p.maxInputTokens, p.suspectedCutAt);
219
+ return {
220
+ maxQuestions: p.maxQuestions ?? null,
221
+ maxInputTokens: tokens,
222
+ cutAt: p.suspectedCutAt ?? tokens,
223
+ source: 'profile',
224
+ };
225
+ }
@@ -2038,5 +2038,26 @@
2038
2038
  },
2039
2039
  "rating": 5,
2040
2040
  "note": "the shipped default for this pool; auto-updating alias — tracks this vendor’s current model"
2041
+ },
2042
+ {
2043
+ "pool": "decider",
2044
+ "position": 1,
2045
+ "name": "Perplexity: Decider V1.2",
2046
+ "vendor": "Perplexity",
2047
+ "routes": [
2048
+ {
2049
+ "provider": "openrouter",
2050
+ "model": "perplexity/pplx-decider-v1.2"
2051
+ }
2052
+ ],
2053
+ "pricing": {
2054
+ "inputPerM": 0.02,
2055
+ "outputPerM": 0,
2056
+ "currency": "USD",
2057
+ "capturedAt": "2026-10-30T00:00:00.000Z",
2058
+ "source": "openrouter"
2059
+ },
2060
+ "rating": 4,
2061
+ "note": "second choice, not the default: tied Jev on quality at about half the cost in the 2026-10-30 test; slower (median 643 ms)"
2041
2062
  }
2042
2063
  ]
@@ -8,6 +8,11 @@
8
8
  import { describe, expect, it } from 'vitest';
9
9
  import { MODEL_POOLS, poolModelIssue, kindFromModalities } from './model-pools';
10
10
  import { CURATED_MODEL_POOLS } from './model-pools-data';
11
+ import {
12
+ DECISION_MODEL_PROFILES,
13
+ decisionModelProfile,
14
+ decisionModelRefusal,
15
+ } from './decision-models';
11
16
 
12
17
  const READER = { input: ['text', 'image'], output: ['text'] };
13
18
  const GENERATOR = { input: ['image', 'text'], output: ['image', 'text'] };
@@ -154,4 +159,82 @@ describe('poolModelIssue: the decider pool', () => {
154
159
  expect(poolModelIssue('decider', null)).toBeNull();
155
160
  expect(poolModelIssue('decider', { input: [], output: [] })).toBeNull();
156
161
  });
162
+
163
+ it('refuses the 4 models that cannot take the request, catalog or not', () => {
164
+ const decisions = { input: ['text'], output: ['decisions'] };
165
+ for (const id of [
166
+ 'scaledown/classify-1',
167
+ 'respan/span-01',
168
+ 'respan/span-01-lite',
169
+ 'respan/span-01-lite:free',
170
+ 'Cloudflare/Clairic',
171
+ ]) {
172
+ expect(poolModelIssue('decider', decisions, id), id).toMatch(/cannot take/);
173
+ expect(poolModelIssue('decider', null, id), id).toMatch(/cannot take/);
174
+ }
175
+ });
176
+
177
+ it('accepts the tested models, the slow ones and an untested id', () => {
178
+ const decisions = { input: ['text'], output: ['decisions'] };
179
+ for (const id of [
180
+ '~typesafe/jev-latest',
181
+ 'perplexity/pplx-decider-v1.2',
182
+ 'openai/gpt-6-luna-decisions',
183
+ 'liquid/d1',
184
+ 'some-vendor/new-decider',
185
+ ]) {
186
+ expect(poolModelIssue('decider', decisions, id), id).toBeNull();
187
+ }
188
+ });
189
+
190
+ it('the refusal is the decider pool only', () => {
191
+ expect(poolModelIssue('summarizer', null, 'respan/span-01')).toBeNull();
192
+ });
193
+ });
194
+
195
+ describe('decision model profiles', () => {
196
+ it('holds the 28 probed models once each, plus the shipped alias', () => {
197
+ const ids = DECISION_MODEL_PROFILES.map((p) => p.id);
198
+ expect(new Set(ids).size).toBe(ids.length);
199
+ expect(ids.filter((id) => !id.startsWith('~'))).toHaveLength(28);
200
+ expect(ids).toContain('~typesafe/jev-latest');
201
+ for (const id of ids) expect(id, id).toBe(id.toLowerCase());
202
+ });
203
+
204
+ it('counts each group as the probe found it', () => {
205
+ const count = (s: string) =>
206
+ DECISION_MODEL_PROFILES.filter((p) => p.status === s && !p.id.startsWith('~')).length;
207
+ expect(count('works')).toBe(6);
208
+ expect(count('no_training_only')).toBe(2);
209
+ expect(count('slow')).toBe(9);
210
+ expect(count('fails_full_size')).toBe(7);
211
+ expect(count('refused')).toBe(4);
212
+ });
213
+
214
+ it('a model that needs no_training says so, and the rest take zdr', () => {
215
+ for (const p of DECISION_MODEL_PROFILES) {
216
+ expect(p.privacy, p.id).toBe(p.status === 'no_training_only' ? 'no_training' : 'zdr');
217
+ }
218
+ });
219
+
220
+ it('looks up by id, case and variant suffix aside, and says nothing of an untested id', () => {
221
+ expect(decisionModelProfile('OpenAI/GPT-6-Luna-Decisions')?.thresholdStart).toBe(1.0);
222
+ expect(decisionModelProfile('respan/span-01-lite:free')?.status).toBe('refused');
223
+ expect(decisionModelProfile('some-vendor/new-decider')).toBeNull();
224
+ expect(decisionModelProfile(null)).toBeNull();
225
+ expect(decisionModelRefusal('typesafe/jev-1.14')).toBeNull();
226
+ });
227
+
228
+ it('every shipped decider template model is profiled as working', () => {
229
+ const shipped = CURATED_MODEL_POOLS.filter((e) => e.pool === 'decider').flatMap((e) =>
230
+ e.routes.map((r) => r.model),
231
+ );
232
+ expect(shipped).toEqual(['~typesafe/jev-latest', 'perplexity/pplx-decider-v1.2']);
233
+ for (const id of shipped) expect(decisionModelProfile(id)?.status, id).toBe('works');
234
+ // The profile's shortlist and the template agree, in order.
235
+ const shortlist = DECISION_MODEL_PROFILES.filter((p) => p.poolPosition !== undefined)
236
+ .sort((a, b) => a.poolPosition! - b.poolPosition!)
237
+ .map((p) => p.id);
238
+ expect(shortlist).toEqual(shipped);
239
+ });
157
240
  });
@@ -10,6 +10,8 @@
10
10
  * not switchable (docs/embeddings.md), so curating it would be a trap.
11
11
  */
12
12
 
13
+ import { decisionModelRefusal } from './decision-models';
14
+
13
15
  export type ModelPoolDef = {
14
16
  id: string;
15
17
  label: string;
@@ -209,9 +211,18 @@ export function kindFromModalities(output: readonly string[]): CatalogKind {
209
211
  export function poolModelIssue(
210
212
  poolId: string,
211
213
  modalities: ModelModalities | null | undefined,
214
+ /** The model id, when the caller has it: the decider pool also refuses a
215
+ * decision model our own probe found cannot take the request. That is our
216
+ * evidence, not the catalog's, so it applies with no catalog too. */
217
+ modelId?: string | null,
212
218
  ): string | null {
213
219
  const pool = POOL_BY_ID.get(poolId);
214
- if (!pool || !modalities) return null;
220
+ if (!pool) return null;
221
+ if (pool.modality.output === 'decisions') {
222
+ const refusal = decisionModelRefusal(modelId);
223
+ if (refusal) return refusal;
224
+ }
225
+ if (!modalities) return null;
215
226
  const want = pool.modality;
216
227
  const outputs = modalities.output ?? [];
217
228
  const inputs = modalities.input ?? [];