@drsamonline/catalog 0.0.0-stage → 0.12.3

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 (3) hide show
  1. package/package.json +26 -4
  2. package/src/index.js +205 -0
  3. package/README.md +0 -3
package/package.json CHANGED
@@ -1,6 +1,28 @@
1
1
  {
2
2
  "name": "@drsamonline/catalog",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.12.3",
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
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.