@drsamonline/catalog 0.0.0-stage → 0.12.2
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 +26 -4
- package/src/index.js +205 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@drsamonline/catalog",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.12.2",
|
|
4
|
+
"description": "Provider catalog: schema, dedupe, ToS policy, scoring.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"main": "./src/index.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./src/index.js",
|
|
10
|
+
"./src/*": "./src/*"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"src",
|
|
14
|
+
"web",
|
|
15
|
+
"bin",
|
|
16
|
+
"LICENSE"
|
|
17
|
+
],
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git://github.com/drsamonline/sui.git",
|
|
21
|
+
"directory": "packages/catalog"
|
|
22
|
+
},
|
|
23
|
+
"homepage": "https://github.com/drsamonline/sui#readme",
|
|
24
|
+
"publishConfig": {
|
|
25
|
+
"access": "public",
|
|
26
|
+
"registry": "https://registry.npmjs.org/"
|
|
27
|
+
}
|
|
28
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @drsamonline/catalog — the provider catalogue.
|
|
3
|
+
*
|
|
4
|
+
* Rules this package encodes:
|
|
5
|
+
* - an entry is only routable once it has been probed (verification before use)
|
|
6
|
+
* - ToS posture is a first-class field: allowed / review / avoid, default review
|
|
7
|
+
* - dedupe is by pool_key, so the same upstream behind two names collapses
|
|
8
|
+
* - scoring is a pure function of measured facts, never of vibes
|
|
9
|
+
*
|
|
10
|
+
* Nothing here ships a base URL it has not been given. A catalogue entry with
|
|
11
|
+
* `needs_probe: true` is an identity, not an endpoint.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import { readFileSync } from 'node:fs';
|
|
15
|
+
|
|
16
|
+
export const TOS_STATES = ['allowed', 'review', 'avoid'];
|
|
17
|
+
export const RETENTION_LEVELS = ['none', 'session', 'short', 'long', 'unknown'];
|
|
18
|
+
export const CAPABILITIES = [
|
|
19
|
+
'chat',
|
|
20
|
+
'streaming',
|
|
21
|
+
'tools',
|
|
22
|
+
'json_schema',
|
|
23
|
+
'vision',
|
|
24
|
+
'embeddings',
|
|
25
|
+
'rerank',
|
|
26
|
+
'stt',
|
|
27
|
+
'tts',
|
|
28
|
+
'image',
|
|
29
|
+
'video',
|
|
30
|
+
'web_search',
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
/** Scoring weights. Sum to 1; change them only with an ADR. */
|
|
34
|
+
export const WEIGHTS = {
|
|
35
|
+
availability: 0.3,
|
|
36
|
+
quota: 0.2,
|
|
37
|
+
latency: 0.15,
|
|
38
|
+
quality: 0.15,
|
|
39
|
+
tos: 0.1,
|
|
40
|
+
privacy: 0.1,
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* A stable identity for "this exact upstream pool", used for dedupe.
|
|
45
|
+
* Two catalogue rows pointing at the same host + path + model family are one pool.
|
|
46
|
+
* @param {any} entry
|
|
47
|
+
*/
|
|
48
|
+
export function poolKey(entry) {
|
|
49
|
+
const base = entry.base_url ? new URL(entry.base_url).host + new URL(entry.base_url).pathname.replace(/\/+$/, '') : `unverified:${entry.provider}`;
|
|
50
|
+
return `${base}|${entry.model_family ?? entry.provider}`;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* @param {any} raw
|
|
55
|
+
* @returns {any}
|
|
56
|
+
*/
|
|
57
|
+
export function normalizeEntry(raw) {
|
|
58
|
+
if (!raw || typeof raw !== 'object') throw new TypeError('catalogue entry must be an object');
|
|
59
|
+
if (!raw.provider) throw new TypeError('catalogue entry needs a provider name');
|
|
60
|
+
const tos = TOS_STATES.includes(raw.tos) ? raw.tos : 'review';
|
|
61
|
+
const retention = RETENTION_LEVELS.includes(raw.privacy_retention) ? raw.privacy_retention : 'unknown';
|
|
62
|
+
return {
|
|
63
|
+
provider: String(raw.provider),
|
|
64
|
+
label: raw.label ?? String(raw.provider),
|
|
65
|
+
base_url: raw.base_url ?? null,
|
|
66
|
+
docs_url: raw.docs_url ?? null,
|
|
67
|
+
model_family: raw.model_family ?? null,
|
|
68
|
+
auth: raw.auth === 'key' ? 'key' : 'none',
|
|
69
|
+
key_env: raw.key_env ?? null,
|
|
70
|
+
local: Boolean(raw.local),
|
|
71
|
+
tos,
|
|
72
|
+
privacy_retention: retention,
|
|
73
|
+
capabilities: (raw.capabilities ?? ['chat']).filter((c) => CAPABILITIES.includes(c)),
|
|
74
|
+
context_window: raw.context_window ?? null,
|
|
75
|
+
quota: raw.quota ?? null,
|
|
76
|
+
needs_probe: raw.base_url ? Boolean(raw.needs_probe) : true,
|
|
77
|
+
verified_at: raw.verified_at ?? null,
|
|
78
|
+
notes: raw.notes ?? null,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** @param {any[]} entries */
|
|
83
|
+
export function dedupeEntries(entries) {
|
|
84
|
+
/** @type {Map<string, any>} */
|
|
85
|
+
const byKey = new Map();
|
|
86
|
+
for (const raw of entries) {
|
|
87
|
+
const entry = normalizeEntry(raw);
|
|
88
|
+
const key = poolKey(entry);
|
|
89
|
+
const existing = byKey.get(key);
|
|
90
|
+
if (!existing) {
|
|
91
|
+
byKey.set(key, { ...entry, pool_key: key, aliases: [entry.provider] });
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
// keep the better ToS posture, the more specific retention, and record the alias
|
|
95
|
+
existing.tos = betterTos(existing.tos, entry.tos);
|
|
96
|
+
if (existing.privacy_retention === 'unknown') existing.privacy_retention = entry.privacy_retention;
|
|
97
|
+
if (!existing.aliases.includes(entry.provider)) existing.aliases.push(entry.provider);
|
|
98
|
+
if (!existing.base_url && entry.base_url) existing.base_url = entry.base_url;
|
|
99
|
+
existing.capabilities = [...new Set([...existing.capabilities, ...entry.capabilities])];
|
|
100
|
+
}
|
|
101
|
+
return [...byKey.values()];
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function betterTos(a, b) {
|
|
105
|
+
const rank = { allowed: 3, review: 2, avoid: 1 };
|
|
106
|
+
return rank[b] > rank[a] ? b : a;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Is this entry allowed to answer an automatic route?
|
|
111
|
+
* @param {any} entry
|
|
112
|
+
*/
|
|
113
|
+
export function isRoutable(entry) {
|
|
114
|
+
if (!entry || entry.tos === 'avoid') return false;
|
|
115
|
+
if (entry.needs_probe) return false;
|
|
116
|
+
return Boolean(entry.base_url);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Health score in [0,1] from measured facts.
|
|
121
|
+
* Missing measurements do not score as zero — they score as unknown and the
|
|
122
|
+
* entry stays out of the pool until probed, so a gap cannot look like health.
|
|
123
|
+
*
|
|
124
|
+
* @param {any} entry
|
|
125
|
+
* @param {{probe?: {ok: boolean, latencyMs?: number, checkedAt?: number}, quality?: number, now?: number}} [facts]
|
|
126
|
+
*/
|
|
127
|
+
export function scoreEntry(entry, facts = {}) {
|
|
128
|
+
const probe = facts.probe ?? null;
|
|
129
|
+
const now = facts.now ?? Date.now();
|
|
130
|
+
|
|
131
|
+
const availability = probe ? (probe.ok ? 1 : 0) : 0;
|
|
132
|
+
const quota = entry.quota == null ? 0.5 : Math.max(0, Math.min(1, Number(entry.quota.remaining ?? 1) / Number(entry.quota.limit ?? 1)));
|
|
133
|
+
const latency = probe?.latencyMs == null ? 0.5 : Math.max(0, 1 - Math.min(1, probe.latencyMs / 4000));
|
|
134
|
+
const quality = facts.quality == null ? 0.5 : Math.max(0, Math.min(1, facts.quality / 5));
|
|
135
|
+
const tos = entry.tos === 'allowed' ? 1 : entry.tos === 'review' ? 0.4 : 0;
|
|
136
|
+
const privacy = { none: 1, session: 0.8, short: 0.6, long: 0.2, unknown: 0.4 }[entry.privacy_retention] ?? 0.4;
|
|
137
|
+
|
|
138
|
+
const score =
|
|
139
|
+
availability * WEIGHTS.availability +
|
|
140
|
+
quota * WEIGHTS.quota +
|
|
141
|
+
latency * WEIGHTS.latency +
|
|
142
|
+
quality * WEIGHTS.quality +
|
|
143
|
+
tos * WEIGHTS.tos +
|
|
144
|
+
privacy * WEIGHTS.privacy;
|
|
145
|
+
|
|
146
|
+
return {
|
|
147
|
+
score: Math.round(score * 1000) / 1000,
|
|
148
|
+
routable: isRoutable(entry) && availability > 0,
|
|
149
|
+
parts: { availability, quota, latency, quality, tos, privacy },
|
|
150
|
+
checkedAt: probe?.checkedAt ?? now,
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** Load a seed catalogue from disk. Accepts {entries:[...]} or a bare array. */
|
|
155
|
+
/**
|
|
156
|
+
* Merge observed facts over imported ones.
|
|
157
|
+
*
|
|
158
|
+
* `seed.json` holds what a source recorded; `verified.json` holds what this
|
|
159
|
+
* gateway measured. Keeping them apart means a probe can never rewrite
|
|
160
|
+
* provenance, and revoking a route is deleting one row rather than editing a
|
|
161
|
+
* curated file.
|
|
162
|
+
*
|
|
163
|
+
* @param {any[]} entries
|
|
164
|
+
* @param {any[]} observed
|
|
165
|
+
*/
|
|
166
|
+
export function applyVerified(entries, observed = []) {
|
|
167
|
+
const byProvider = new Map(observed.map((row) => [row.provider, row]));
|
|
168
|
+
return entries.map((entry) => {
|
|
169
|
+
const seen = byProvider.get(entry.provider);
|
|
170
|
+
if (!seen) return entry;
|
|
171
|
+
return {
|
|
172
|
+
...entry,
|
|
173
|
+
base_url: seen.base_url ?? entry.base_url,
|
|
174
|
+
probe_model: seen.probe_model ?? entry.probe_model ?? null,
|
|
175
|
+
models: seen.models ?? entry.models ?? [],
|
|
176
|
+
verified_at: seen.verified_at ?? entry.verified_at ?? null,
|
|
177
|
+
// a verified entry is routable: the probe is what makes it so
|
|
178
|
+
needs_probe: seen.verified_at ? false : entry.needs_probe,
|
|
179
|
+
tos: seen.tos ?? entry.tos,
|
|
180
|
+
capabilities: seen.capabilities ? [...new Set([...entry.capabilities, ...seen.capabilities])] : entry.capabilities,
|
|
181
|
+
};
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export function loadSeed(path) {
|
|
186
|
+
const parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
187
|
+
const entries = Array.isArray(parsed) ? parsed : parsed.entries ?? [];
|
|
188
|
+
return dedupeEntries(entries);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Group a catalogue by routability, for the Weather Map and for `sui doctor`.
|
|
193
|
+
* @param {any[]} entries
|
|
194
|
+
* @param {Record<string, any>} [probes] keyed by pool_key
|
|
195
|
+
*/
|
|
196
|
+
export function summarise(entries, probes = {}) {
|
|
197
|
+
const rows = entries.map((e) => ({ ...e, health: scoreEntry(e, { probe: probes[e.pool_key] }) }));
|
|
198
|
+
return {
|
|
199
|
+
total: rows.length,
|
|
200
|
+
routable: rows.filter((r) => r.health.routable).length,
|
|
201
|
+
awaiting_probe: rows.filter((r) => r.needs_probe).length,
|
|
202
|
+
tos_avoid: rows.filter((r) => r.tos === 'avoid').length,
|
|
203
|
+
rows,
|
|
204
|
+
};
|
|
205
|
+
}
|
package/README.md
DELETED