@team-antioch/sc2-finder-kit 0.0.0-stage → 0.3.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 (51) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +36 -2
  3. package/dist/asker.d.ts +91 -0
  4. package/dist/asker.js +214 -0
  5. package/dist/cache-dir.d.ts +4 -0
  6. package/dist/cache-dir.js +17 -0
  7. package/dist/card.d.ts +35 -0
  8. package/dist/card.js +4 -0
  9. package/dist/credentials.d.ts +34 -0
  10. package/dist/credentials.js +33 -0
  11. package/dist/embedder.d.ts +39 -0
  12. package/dist/embedder.js +94 -0
  13. package/dist/embedding-index.d.ts +26 -0
  14. package/dist/embedding-index.js +129 -0
  15. package/dist/finder.d.ts +87 -0
  16. package/dist/finder.js +162 -0
  17. package/dist/gateway-translator.d.ts +21 -0
  18. package/dist/gateway-translator.js +62 -0
  19. package/dist/is-main.d.ts +6 -0
  20. package/dist/is-main.js +17 -0
  21. package/dist/jev-language-detector.d.ts +15 -0
  22. package/dist/jev-language-detector.js +44 -0
  23. package/dist/jev-ranker.d.ts +45 -0
  24. package/dist/jev-ranker.js +93 -0
  25. package/dist/key-file.d.ts +13 -0
  26. package/dist/key-file.js +62 -0
  27. package/dist/language-detector.d.ts +20 -0
  28. package/dist/language-detector.js +38 -0
  29. package/dist/load-together.d.ts +26 -0
  30. package/dist/load-together.js +39 -0
  31. package/dist/login.d.ts +34 -0
  32. package/dist/login.js +137 -0
  33. package/dist/narrow.d.ts +57 -0
  34. package/dist/narrow.js +74 -0
  35. package/dist/payload-log.d.ts +5 -0
  36. package/dist/payload-log.js +12 -0
  37. package/dist/ranker.d.ts +80 -0
  38. package/dist/ranker.js +40 -0
  39. package/dist/server.d.ts +178 -0
  40. package/dist/server.js +565 -0
  41. package/dist/settings.d.ts +7 -0
  42. package/dist/settings.js +20 -0
  43. package/dist/spend-cap.d.ts +14 -0
  44. package/dist/spend-cap.js +22 -0
  45. package/dist/test-asks.d.ts +60 -0
  46. package/dist/test-asks.js +107 -0
  47. package/dist/translator.d.ts +48 -0
  48. package/dist/translator.js +51 -0
  49. package/dist/tray.d.ts +22 -0
  50. package/dist/tray.js +12 -0
  51. package/package.json +45 -4
@@ -0,0 +1,26 @@
1
+ import { type FinderCard } from "./card.ts";
2
+ import type { Embedder } from "./embedder.ts";
3
+ export type Neighbour = {
4
+ readonly id: string;
5
+ readonly similarity: number;
6
+ };
7
+ export declare class EmbeddingIndex {
8
+ #private;
9
+ private constructor();
10
+ /** The index over the cache file's vectors for the embedder's model; none until the first update. */
11
+ static open(embedder: Embedder, file: string): Promise<EmbeddingIndex>;
12
+ /**
13
+ * Takes these cards as the whole set: embeds the ones whose embedded text (`embeddedText`:
14
+ * `embedText`, else `text`) it has no vector for, forgets the
15
+ * rest, and saves the cache when it changed. Gives these cards' own nearest, which later updates
16
+ * leave as it is, so a caller can swap it in with the cards it was made for.
17
+ */
18
+ update(cards: readonly FinderCard[]): Promise<{
19
+ embedded: number;
20
+ nearest: Nearest;
21
+ }>;
22
+ /** The last update's cards most like a unit vector (see Nearest). */
23
+ nearest(query: Float32Array, k: number, keep?: (id: string) => boolean): Neighbour[];
24
+ }
25
+ /** The k cards most like a unit vector, most alike first, among those `keep` allows. */
26
+ export type Nearest = (query: Float32Array, k: number, keep?: (id: string) => boolean) => Neighbour[];
@@ -0,0 +1,129 @@
1
+ // A finder's vectors of its cards (docs/adr/0001), and their cache: a git-ignored file keyed by
2
+ // a hash of the text each card is embedded as (`embeddedText`), so a start embeds only the cards whose embedded text changed. The vectors are
3
+ // tied to one model, and are only a copy of committed text: deleting the file costs a cold start.
4
+ //
5
+ // The file is a 4-byte header length, a JSON header ({ model, dimensions, hashes }), then each
6
+ // hash's vector as float32s, in the header's order.
7
+ import { createHash } from "node:crypto";
8
+ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
9
+ import path from "node:path";
10
+ import { embeddedText } from "./card.js";
11
+ const textHash = (text) => createHash("sha256").update(text).digest("base64url").slice(0, 22);
12
+ async function readCache(file, model) {
13
+ let bytes;
14
+ try {
15
+ bytes = await readFile(file);
16
+ }
17
+ catch {
18
+ return new Map();
19
+ }
20
+ try {
21
+ const length = bytes.readUInt32LE(0);
22
+ const header = JSON.parse(bytes.subarray(4, 4 + length).toString("utf8"));
23
+ if (header.model !== model)
24
+ return new Map();
25
+ const start = 4 + length;
26
+ // A file cut short, or of another layout, is no cache.
27
+ if (!(header.dimensions > 0) || !Array.isArray(header.hashes) || bytes.length !== start + header.hashes.length * header.dimensions * 4)
28
+ return new Map();
29
+ // A copy, aligned for Float32Array whatever the header's length.
30
+ const floats = new Float32Array(bytes.buffer.slice(bytes.byteOffset + start, bytes.byteOffset + start + header.hashes.length * header.dimensions * 4));
31
+ return new Map(header.hashes.map((hash, i) => [hash, floats.subarray(i * header.dimensions, (i + 1) * header.dimensions)]));
32
+ }
33
+ catch {
34
+ // Nor is one whose header doesn't read.
35
+ return new Map();
36
+ }
37
+ }
38
+ async function writeCache(file, model, vectors) {
39
+ const hashes = [...vectors.keys()];
40
+ const dimensions = vectors.values().next().value?.length ?? 0;
41
+ const header = Buffer.from(JSON.stringify({ model, dimensions, hashes }), "utf8");
42
+ const length = Buffer.alloc(4);
43
+ length.writeUInt32LE(header.length);
44
+ const floats = new Float32Array(hashes.length * dimensions);
45
+ hashes.forEach((hash, i) => floats.set(vectors.get(hash), i * dimensions));
46
+ await mkdir(path.dirname(file), { recursive: true });
47
+ const partial = `${file}.partial`;
48
+ await writeFile(partial, Buffer.concat([length, header, Buffer.from(floats.buffer)]));
49
+ await rename(partial, file);
50
+ }
51
+ export class EmbeddingIndex {
52
+ /** By the hash of the text a card is embedded as (`embeddedText`): every vector the cache holds that a card still uses. */
53
+ #vectors;
54
+ /** The last update's cards' nearest. */
55
+ #nearest = () => [];
56
+ #embedder;
57
+ #file;
58
+ constructor(embedder, file, vectors) {
59
+ this.#embedder = embedder;
60
+ this.#file = file;
61
+ this.#vectors = vectors;
62
+ }
63
+ /** The index over the cache file's vectors for the embedder's model; none until the first update. */
64
+ static async open(embedder, file) {
65
+ return new EmbeddingIndex(embedder, file, await readCache(file, embedder.model));
66
+ }
67
+ /**
68
+ * Takes these cards as the whole set: embeds the ones whose embedded text (`embeddedText`:
69
+ * `embedText`, else `text`) it has no vector for, forgets the
70
+ * rest, and saves the cache when it changed. Gives these cards' own nearest, which later updates
71
+ * leave as it is, so a caller can swap it in with the cards it was made for.
72
+ */
73
+ async update(cards) {
74
+ const texts = cards.map((card) => embeddedText(card));
75
+ const hashes = texts.map(textHash);
76
+ const missing = new Map();
77
+ hashes.forEach((hash, i) => {
78
+ if (!this.#vectors.has(hash))
79
+ missing.set(hash, texts[i]);
80
+ });
81
+ const vectors = new Map();
82
+ if (missing.size) {
83
+ const embedded = await this.#embedder.embed([...missing.values()], "passage");
84
+ [...missing.keys()].forEach((hash, i) => vectors.set(hash, embedded[i]));
85
+ }
86
+ for (const hash of hashes)
87
+ vectors.set(hash, vectors.get(hash) ?? this.#vectors.get(hash));
88
+ const forgot = this.#vectors.size !== vectors.size || [...this.#vectors.keys()].some((hash) => !vectors.has(hash));
89
+ const dimensions = vectors.values().next().value?.length ?? 0;
90
+ const matrix = new Float32Array(cards.length * dimensions);
91
+ hashes.forEach((hash, i) => matrix.set(vectors.get(hash), i * dimensions));
92
+ const nearest = nearestOver(cards.map((card) => card.id), matrix, dimensions);
93
+ this.#vectors = vectors;
94
+ this.#nearest = nearest;
95
+ if (missing.size || forgot)
96
+ await writeCache(this.#file, this.#embedder.model, vectors);
97
+ // Counted in cards, not texts: cards that share a text share its one vector.
98
+ return { embedded: hashes.filter((hash) => missing.has(hash)).length, nearest };
99
+ }
100
+ /** The last update's cards most like a unit vector (see Nearest). */
101
+ nearest(query, k, keep) {
102
+ return this.#nearest(query, k, keep);
103
+ }
104
+ }
105
+ /** Nearest over some cards' ids and their vectors, a row each of `matrix`. */
106
+ function nearestOver(ids, matrix, dimensions) {
107
+ return (query, k, keep) => {
108
+ const best = [];
109
+ for (let row = 0; row < ids.length; row++) {
110
+ const id = ids[row];
111
+ let similarity = 0;
112
+ const offset = row * dimensions;
113
+ for (let d = 0; d < dimensions; d++)
114
+ similarity += matrix[offset + d] * query[d];
115
+ if (best.length === k && similarity <= best[k - 1].similarity)
116
+ continue;
117
+ if (keep && !keep(id))
118
+ continue;
119
+ // Kept sorted by insertion: k is about 100, the cards a few thousand.
120
+ let at = best.length;
121
+ while (at > 0 && best[at - 1].similarity < similarity)
122
+ at--;
123
+ best.splice(at, 0, { id, similarity });
124
+ if (best.length > k)
125
+ best.pop();
126
+ }
127
+ return best;
128
+ };
129
+ }
@@ -0,0 +1,87 @@
1
+ import type { FinderCard, Tag } from "./card.ts";
2
+ import type { Embedder } from "./embedder.ts";
3
+ import { type LanguageDetector } from "./language-detector.ts";
4
+ import { type Translation, type Translator } from "./translator.ts";
5
+ import { type Narrowed, type RankBudget } from "./narrow.ts";
6
+ /** A model's vector cache: a file per model in the cache folder. */
7
+ export declare const vectorCacheFile: (model: string, cacheDir?: string) => string;
8
+ /** About a hundred from each search, as docs/adr/0001 has it. */
9
+ export declare const KEYWORD_RESULTS = 100;
10
+ export declare const NEAREST_RESULTS = 100;
11
+ /** The nearest cards the embeddings search puts the provided ones first among: its matches. */
12
+ export declare const NEAREST_MATCHES: number;
13
+ export type FinderOptions<C extends FinderCard, S> = {
14
+ /** Reads the sources afresh: on opening, and after each watched change. */
15
+ readonly load: () => Promise<S>;
16
+ /** The card for everything the sources hold. */
17
+ readonly cards: (sources: S) => readonly C[];
18
+ /**
19
+ * The keyword search over the sources: its matches for an ask, best first, with the pinned tags'
20
+ * facets it can take already applied. The kit keeps the pinned ones it couldn't, puts the provided
21
+ * ones first and cuts to a hundred.
22
+ */
23
+ readonly keyword: (sources: S, ask: string, tags: readonly Tag[]) => readonly {
24
+ readonly id: string;
25
+ }[];
26
+ /** Whether a tag matches a card. */
27
+ readonly tagMatches: (card: C, tag: Tag) => boolean;
28
+ /** Whether a map's dependencies already bring a card in. */
29
+ readonly provides: (dependencies: readonly string[], card: C) => boolean;
30
+ /**
31
+ * What the finder's ranker can take in one request. Each ask's candidates are cut to it before
32
+ * they are returned, lowest ranked first (see `fitToBudget`). None by default.
33
+ */
34
+ readonly rankBudget?: RankBudget<C>;
35
+ readonly embedder: Embedder;
36
+ /** Turns an ask in another script into English before it is searched (translator.ts). None by default: asks are searched as typed. */
37
+ readonly translator?: Translator;
38
+ /** Says whether an ask in Latin script the catalog's own words don't cover is English, so Spanish, German... are translated too (language-detector.ts). None by default: only asks in other scripts are translated. */
39
+ readonly languageDetector?: LanguageDetector;
40
+ /** The vector cache file. */
41
+ readonly cacheFile: string;
42
+ /** Files and folders whose changes write the cards again; a folder is watched with everything in it. */
43
+ readonly watch?: readonly string[];
44
+ /** Called after each reload a watched change set off, with how many cards it embedded; or with the error it met. */
45
+ readonly onReload?: (result: {
46
+ readonly embedded: number;
47
+ }) => void;
48
+ readonly onError?: (error: unknown) => void;
49
+ };
50
+ export type NarrowOptions = {
51
+ readonly tags?: readonly Tag[];
52
+ /** A map's dependencies: the cards they provide are marked, and each search takes them first among its matches. */
53
+ readonly dependencies?: readonly string[] | undefined;
54
+ /** At most this many (200 by default). */
55
+ readonly limit?: number;
56
+ };
57
+ export type Narrowing<C extends FinderCard = FinderCard> = {
58
+ readonly candidates: readonly Narrowed<C>[];
59
+ /** How many merged candidates the rank budget dropped (0 without one, or when all fit). */
60
+ readonly cut: number;
61
+ /** The ask as the searches ran it, when it was in another script and a translator was given: hand `english` to the ranker. */
62
+ readonly translation?: Translation;
63
+ /** Milliseconds: translating the ask (when it was translated), the keyword search, embedding the ask, the nearest cards, the merge, and all of them: `total` leaves out translating, which is a network call and reported on its own. */
64
+ readonly timings: {
65
+ readonly translate?: number;
66
+ readonly keyword: number;
67
+ readonly embed: number;
68
+ readonly nearest: number;
69
+ readonly merge: number;
70
+ readonly total: number;
71
+ };
72
+ };
73
+ export type Finder<C extends FinderCard, S> = {
74
+ narrow(ask: string, options?: NarrowOptions): Promise<Narrowing<C>>;
75
+ /** Reads the sources and writes the cards again, embedding the changed ones. */
76
+ reload(): Promise<{
77
+ readonly embedded: number;
78
+ }>;
79
+ /** Every card, by id. */
80
+ readonly cards: ReadonlyMap<string, C>;
81
+ /** The sources as last read: for looking up a card's picture, say. */
82
+ readonly sources: S;
83
+ /** How many cards opening embedded: none on a warm start. */
84
+ readonly embeddedOnOpen: number;
85
+ close(): void;
86
+ };
87
+ export declare function openFinder<C extends FinderCard, S>(options: FinderOptions<C, S>): Promise<Finder<C, S>>;
package/dist/finder.js ADDED
@@ -0,0 +1,162 @@
1
+ // A finder's narrowing over its sources (docs/adr/0001), as its process keeps it: the cards embedded
2
+ // when it opens (only the ones the cache hasn't seen), each ask narrowed by the finder's keyword
3
+ // search and the nearest cards, and the cards written and embedded again when a watched file changes
4
+ // (the finder's files, and any others the sources name). What the sources are, how a source makes
5
+ // its cards, what the keyword search is and what a tag or a dependency matches are the finder's:
6
+ // it passes them in.
7
+ import { watch } from "node:fs";
8
+ import { stat } from "node:fs/promises";
9
+ import path from "node:path";
10
+ import { catalogCacheDir } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
11
+ import { EmbeddingIndex } from "./embedding-index.js";
12
+ import { vocabularyOf } from "./language-detector.js";
13
+ import { translateAsk } from "./translator.js";
14
+ import { fitToBudget, mergeNarrowing, providedFirst } from "./narrow.js";
15
+ /** A model's vector cache: a file per model in the cache folder. */
16
+ export const vectorCacheFile = (model, cacheDir = catalogCacheDir()) => path.join(cacheDir, `vectors-${model.replace(/[^A-Za-z0-9.-]+/g, "_")}.bin`);
17
+ /** About a hundred from each search, as docs/adr/0001 has it. */
18
+ export const KEYWORD_RESULTS = 100;
19
+ export const NEAREST_RESULTS = 100;
20
+ /** The nearest cards the embeddings search puts the provided ones first among: its matches. */
21
+ export const NEAREST_MATCHES = 2 * NEAREST_RESULTS;
22
+ /** How long a burst of file events settles before the cards are written again. */
23
+ const SETTLE_MS = 50;
24
+ /** Watches each path: a folder with everything in it, a file through its folder, so a file replaced by a rename is still seen. */
25
+ async function watchPaths(paths, changed, onError) {
26
+ const watchers = [];
27
+ for (const target of paths) {
28
+ const isFolder = await stat(target).then((found) => found.isDirectory(), () => false);
29
+ const folder = isFolder ? target : path.dirname(target);
30
+ const name = path.basename(target);
31
+ try {
32
+ const watcher = watch(folder, { recursive: isFolder, persistent: false }, (_event, file) => (isFolder || file === null || file === name ? changed() : undefined));
33
+ // A watched folder deleted or shut off (the cache folder is safe to delete) stops its watch, not the process.
34
+ watcher.on("error", (error) => {
35
+ watcher.close();
36
+ onError(error);
37
+ });
38
+ watchers.push(watcher);
39
+ }
40
+ catch {
41
+ // A folder that isn't there (one the sources name before it exists) has nothing to watch.
42
+ }
43
+ }
44
+ return watchers;
45
+ }
46
+ export async function openFinder(options) {
47
+ const index = await EmbeddingIndex.open(options.embedder, options.cacheFile);
48
+ /** The sources and their cards, embedded: swapped whole, with the cards' own nearest, so an ask under way when they change never mixes old and new. */
49
+ const read = async () => {
50
+ const sources = await options.load();
51
+ const cards = options.cards(sources);
52
+ const { embedded, nearest } = await index.update(cards);
53
+ return { sources, cards, byId: new Map(cards.map((card) => [card.id, card])), nearest, embedded };
54
+ };
55
+ const first = await read();
56
+ let loaded = first;
57
+ const embeddedOnOpen = first.embedded;
58
+ // The English words of the cards, for the language detector's gate, made once for each reading of the sources.
59
+ let words;
60
+ const vocabularyFor = (now) => {
61
+ if (words?.of !== now)
62
+ words = { of: now, vocabulary: vocabularyOf(now.cards.map((card) => `${card.name} ${card.text}`)) };
63
+ return words.vocabulary;
64
+ };
65
+ // Cards marked for a map's dependencies, kept for the last ones asked for.
66
+ let marked;
67
+ const cardsFor = (of, dependencies) => {
68
+ if (dependencies === undefined)
69
+ return of.byId;
70
+ const key = JSON.stringify(dependencies);
71
+ if (marked?.key !== key || marked.of !== of) {
72
+ marked = { key, of, cards: new Map([...of.byId].map(([id, card]) => [id, { ...card, provided: options.provides(dependencies, card) }])) };
73
+ }
74
+ return marked.cards;
75
+ };
76
+ // One reload at a time; a change during one runs another after it.
77
+ let running;
78
+ let again = false;
79
+ const reload = async () => {
80
+ if (running) {
81
+ again = true;
82
+ return running;
83
+ }
84
+ running = (async () => {
85
+ let embedded = 0;
86
+ do {
87
+ again = false;
88
+ const next = await read();
89
+ embedded += next.embedded;
90
+ loaded = next;
91
+ } while (again);
92
+ return { embedded };
93
+ })();
94
+ try {
95
+ return await running;
96
+ }
97
+ finally {
98
+ running = undefined;
99
+ }
100
+ };
101
+ let timer;
102
+ const changed = () => {
103
+ clearTimeout(timer);
104
+ timer = setTimeout(() => {
105
+ reload().then((result) => options.onReload?.(result), (error) => options.onError?.(error));
106
+ }, SETTLE_MS);
107
+ };
108
+ const watchers = await watchPaths(options.watch ?? [], changed, (error) => options.onError?.(error));
109
+ return {
110
+ get cards() {
111
+ return loaded.byId;
112
+ },
113
+ get sources() {
114
+ return loaded.sources;
115
+ },
116
+ embeddedOnOpen,
117
+ reload,
118
+ close() {
119
+ clearTimeout(timer);
120
+ for (const watcher of watchers)
121
+ watcher.close();
122
+ },
123
+ async narrow(ask, { tags = [], dependencies, limit } = {}) {
124
+ const started = performance.now();
125
+ const now = loaded;
126
+ const translation = await translateAsk(ask, options.translator, { detector: options.languageDetector, vocabulary: options.languageDetector ? vocabularyFor(now) : undefined });
127
+ const searched = translation?.english ?? ask;
128
+ const searchStarted = performance.now();
129
+ const cards = cardsFor(now, dependencies);
130
+ const pinned = tags.filter((tag) => tag.pinned);
131
+ /** Whether every pinned tag matches a card, as the merge keeps it, so the nearest hundred are all ones it keeps. */
132
+ const keeps = (id) => {
133
+ const card = cards.get(id);
134
+ return card !== undefined && pinned.every((tag) => options.tagMatches(card, tag));
135
+ };
136
+ // Pinned tags the search can't take filter before the cut; then the map's provided matches first.
137
+ const matches = options.keyword(now.sources, searched, tags);
138
+ const keyword = providedFirst(pinned.length ? matches.filter(({ id }) => keeps(id)) : matches, cards, KEYWORD_RESULTS);
139
+ const keywordDone = performance.now();
140
+ const [vector] = searched.trim() ? await options.embedder.embed([searched], "query") : [];
141
+ const embedDone = performance.now();
142
+ const nearest = vector ? providedFirst(now.nearest(vector, NEAREST_MATCHES, pinned.length ? keeps : undefined), cards, NEAREST_RESULTS) : [];
143
+ const nearestDone = performance.now();
144
+ const merged = mergeNarrowing(keyword, nearest, cards, { tags, tagMatches: options.tagMatches, ...(limit !== undefined ? { limit } : {}) });
145
+ const { kept: candidates, cut } = options.rankBudget ? fitToBudget(merged, options.rankBudget) : { kept: merged, cut: 0 };
146
+ const done = performance.now();
147
+ return {
148
+ candidates,
149
+ cut,
150
+ ...(translation ? { translation } : {}),
151
+ timings: {
152
+ ...(translation ? { translate: searchStarted - started } : {}),
153
+ keyword: keywordDone - searchStarted,
154
+ embed: embedDone - keywordDone,
155
+ nearest: nearestDone - embedDone,
156
+ merge: done - nearestDone,
157
+ total: done - searchStarted,
158
+ },
159
+ };
160
+ },
161
+ };
162
+ }
@@ -0,0 +1,21 @@
1
+ import type { Translator } from "./translator.ts";
2
+ export declare const GATEWAY_CHAT_URL = "https://ai-gateway.vercel.sh/v1/chat/completions";
3
+ export declare const TRANSLATOR_MODEL = "amazon/nova-micro";
4
+ /**
5
+ * What the model is told. The glossary is the game's own localized names, which a general
6
+ * translation gets wrong: Russian "линкор" is the Battlecruiser, not a battleship.
7
+ */
8
+ export declare const TRANSLATE_PROMPT: string;
9
+ export type GatewayTranslatorOptions = {
10
+ readonly apiKey: string;
11
+ readonly model?: string;
12
+ readonly url?: string;
13
+ /** For tests. */
14
+ readonly fetch?: typeof globalThis.fetch;
15
+ };
16
+ export declare function gatewayTranslator({ apiKey, model, url, fetch }: GatewayTranslatorOptions): Translator;
17
+ /**
18
+ * Remembers what a translator answered for each ask (up to `max`, the oldest forgotten first), so an
19
+ * ask asked again costs no call. A failure is not remembered.
20
+ */
21
+ export declare function cachingTranslator(inner: Translator, max?: number): Translator;
@@ -0,0 +1,62 @@
1
+ // A translator (translator.ts) that asks a small model through Vercel's AI Gateway, whose
2
+ // chat-completions endpoint takes the usual OpenAI-shaped request. No SDK: one fetch. The default
3
+ // model, amazon/nova-micro, was the cheapest of eight tried that answered in about 0.6 s and
4
+ // translated 13 of 15 Russian and Korean test asks as the doodad search needs them (about $0.003
5
+ // per 1,000 asks); the others cost no more than $0.07 but took two to six times as long.
6
+ //
7
+ // A free Gateway account is held to 5 requests a minute a model and refused some models outright;
8
+ // a paid balance lifts both. Every failure is thrown with the Gateway's own words and never the
9
+ // key, and translateAsk leaves the ask as typed.
10
+ export const GATEWAY_CHAT_URL = "https://ai-gateway.vercel.sh/v1/chat/completions";
11
+ export const TRANSLATOR_MODEL = "amazon/nova-micro";
12
+ /**
13
+ * What the model is told. The glossary is the game's own localized names, which a general
14
+ * translation gets wrong: Russian "линкор" is the Battlecruiser, not a battleship.
15
+ */
16
+ export const TRANSLATE_PROMPT = [
17
+ "You translate searches typed by StarCraft II map makers into short plain English, for finding doodads (map decorations) by their descriptions.",
18
+ "Keep game terms (Zerg, Terran, Protoss, Xel'Naga) and ids as they are.",
19
+ "Use the game's English names: линкор and 전투순양함 are Battlecruiser; 'doodad' is the map decoration, never a toy or a gadget.",
20
+ "Reply with the English translation only, with no quotes, notes or explanation.",
21
+ ].join(" ");
22
+ export function gatewayTranslator({ apiKey, model = TRANSLATOR_MODEL, url = GATEWAY_CHAT_URL, fetch = globalThis.fetch }) {
23
+ return {
24
+ async translate(ask, options) {
25
+ const response = await fetch(url, {
26
+ method: "POST",
27
+ headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
28
+ body: JSON.stringify({ model, max_tokens: 200, temperature: 0, messages: [{ role: "system", content: TRANSLATE_PROMPT }, { role: "user", content: ask }] }),
29
+ ...(options?.signal ? { signal: options.signal } : {}),
30
+ });
31
+ const reply = (await response.json().catch(() => ({})));
32
+ if (!response.ok) {
33
+ const said = typeof reply.error?.message === "string" ? reply.error.message : "no reason given";
34
+ throw new Error(`AI Gateway ${response.status}: ${said}`);
35
+ }
36
+ const content = reply.choices?.[0]?.message?.content;
37
+ if (typeof content !== "string")
38
+ throw new Error("AI Gateway answered without text");
39
+ // A model sometimes quotes what it was told to leave bare.
40
+ return content.trim().replace(/^["'“”«»]+|["'“”«»]+$/g, "");
41
+ },
42
+ };
43
+ }
44
+ /**
45
+ * Remembers what a translator answered for each ask (up to `max`, the oldest forgotten first), so an
46
+ * ask asked again costs no call. A failure is not remembered.
47
+ */
48
+ export function cachingTranslator(inner, max = 500) {
49
+ const known = new Map();
50
+ return {
51
+ async translate(ask, options) {
52
+ const seen = known.get(ask);
53
+ if (seen !== undefined)
54
+ return seen;
55
+ const english = await inner.translate(ask, options);
56
+ known.set(ask, english);
57
+ if (known.size > max)
58
+ known.delete(known.keys().next().value);
59
+ return english;
60
+ },
61
+ };
62
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Whether the module at `url` is the one the process was started with (`argv1`, process.argv[1]),
3
+ * so a CLI module runs only then and is safe to import. Never throws: an argv[1] that isn't a file
4
+ * (a REPL, `node -e`, a test runner's own) is no module's.
5
+ */
6
+ export declare function isMainModule(url: string, argv1?: string | undefined): boolean;
@@ -0,0 +1,17 @@
1
+ import { realpathSync } from "node:fs";
2
+ import { pathToFileURL } from "node:url";
3
+ /**
4
+ * Whether the module at `url` is the one the process was started with (`argv1`, process.argv[1]),
5
+ * so a CLI module runs only then and is safe to import. Never throws: an argv[1] that isn't a file
6
+ * (a REPL, `node -e`, a test runner's own) is no module's.
7
+ */
8
+ export function isMainModule(url, argv1 = process.argv[1]) {
9
+ if (!argv1)
10
+ return false;
11
+ try {
12
+ return url === pathToFileURL(realpathSync(argv1)).href;
13
+ }
14
+ catch {
15
+ return false;
16
+ }
17
+ }
@@ -0,0 +1,15 @@
1
+ import { type Fetch, type Question, type SystemOneRequest } from "@typesafe-ai/sdk";
2
+ import { type LanguageDetector } from "./language-detector.ts";
3
+ import type { PayloadLog } from "./ranker.ts";
4
+ export declare const LANGUAGE_QUESTION: Question;
5
+ /** The request for one ask: what is sent and logged. */
6
+ export declare const languageRequest: (ask: string) => SystemOneRequest;
7
+ export type JevLanguageOptions = {
8
+ readonly apiKey: string;
9
+ readonly log?: PayloadLog;
10
+ /** For tests: answers in place of the API. */
11
+ readonly fetch?: Fetch;
12
+ /** Milliseconds per attempt (3 s by default). */
13
+ readonly timeout?: number;
14
+ };
15
+ export declare function jevLanguageDetector(options: JevLanguageOptions): LanguageDetector;
@@ -0,0 +1,44 @@
1
+ // A language detector (language-detector.ts) that asks Jev one Choice question: English, or another
2
+ // language. Measured on 70 asks in Spanish, German, French, Portuguese and Polish and 25 in English,
3
+ // it called all 25 English asks English and 68 of the 70 others another language (the two it
4
+ // took for English were mostly the proper name Xel'Naga, and English search finds those too), in
5
+ // about 110 ms and 350 input tokens, under two thousandths of a cent a call.
6
+ import { TypeSafeClient } from "@typesafe-ai/sdk";
7
+ import { JEV_INPUT_PRICE, JEV_MODEL } from "./jev-ranker.js";
8
+ import { ENGLISH_AT } from "./language-detector.js";
9
+ const ENGLISH = "English";
10
+ const OTHER = "Another language";
11
+ export const LANGUAGE_QUESTION = {
12
+ type: "choice",
13
+ instructions: "What language is the search in `ask` written in? A search is a few words a StarCraft II map maker types to find a map decoration. Game names such as Zerg, Protoss, Terran and Xel'Naga are used in every language.",
14
+ criteria: { [ENGLISH]: null, [OTHER]: null },
15
+ };
16
+ /** The request for one ask: what is sent and logged. */
17
+ export const languageRequest = (ask) => ({ model: JEV_MODEL, state: { ask }, questions: { language: LANGUAGE_QUESTION } });
18
+ export function jevLanguageDetector(options) {
19
+ const client = new TypeSafeClient({ apiKey: options.apiKey, logLevel: "off", ...(options.fetch ? { fetch: options.fetch } : {}), timeout: options.timeout ?? 3000 });
20
+ const hide = (text) => text.split(options.apiKey).join("[the key]");
21
+ return {
22
+ async detect(ask, { signal } = {}) {
23
+ const payload = languageRequest(ask);
24
+ const at = new Date().toISOString();
25
+ const started = performance.now();
26
+ let result;
27
+ try {
28
+ result = await client.systemOne(payload, signal ? { signal } : {});
29
+ }
30
+ catch (error) {
31
+ // The key never goes further than the client: not into the log, the terminal or the page.
32
+ const message = hide(error instanceof Error ? error.message : String(error));
33
+ options.log?.({ ranker: "jev", at, ms: performance.now() - started, request: payload, error: message });
34
+ throw new Error(`jev: the language check failed: ${message}`);
35
+ }
36
+ options.log?.({ ranker: "jev", at, ms: performance.now() - started, request: payload, response: result });
37
+ const answer = result.answers.language;
38
+ if (answer?.type !== "choice")
39
+ throw new Error("jev: the language check came back without an answer");
40
+ const pEnglish = answer.probabilities[ENGLISH] ?? (answer.choice === ENGLISH ? 1 : 0);
41
+ return { english: pEnglish >= ENGLISH_AT, pEnglish, cost: (result.usage.input_tokens ?? 0) * JEV_INPUT_PRICE };
42
+ },
43
+ };
44
+ }
@@ -0,0 +1,45 @@
1
+ import { type Fetch, type SystemOneRequest } from "@typesafe-ai/sdk";
2
+ import type { FinderCard } from "./card.ts";
3
+ import type { RankBudget } from "./narrow.ts";
4
+ import { type PayloadLog, type RankRequest, type Ranker } from "./ranker.ts";
5
+ /**
6
+ * Every word a finder has Jev judge by, in one place to audit and edit: what the ask is about, the
7
+ * Score question, the name the candidate's card goes under in each question, and the levels from 0
8
+ * up, each a situation that reads on its own.
9
+ */
10
+ export type JevWording = {
11
+ readonly about: string;
12
+ readonly question: string;
13
+ /** The question's field for the candidate's card: `doodad`, so the question can say `doodad`. */
14
+ readonly field: string;
15
+ readonly levels: readonly [string, ...string[]];
16
+ };
17
+ export declare const JEV_MODEL = "jev-latest";
18
+ /** US dollars per input token; output is free. */
19
+ export declare const JEV_INPUT_PRICE: number;
20
+ /**
21
+ * What one request to Jev can carry, as input tokens. Jev refuses a request over its limit with
22
+ * `400 max_tokens_exceeded` (docs/adr/0002). The Music Finder met it: its asks took 57k to 65.7k
23
+ * input tokens at 168 to 187 candidates and the ones with 189 to 198 candidates were refused, so
24
+ * the limit is somewhere about 65k. A request is cut to 55k estimated tokens, which leaves room for
25
+ * the estimate being off (it counts bytes, not tokens) and for the ask, tags and the state: the
26
+ * 10k tokens of headroom is about 34,000 bytes, far more than the state's note, a typed ask, its
27
+ * tags and an object, so they are not counted per candidate.
28
+ */
29
+ export declare const JEV_TOKEN_BUDGET = 55000;
30
+ /** Bytes per token for the estimate: the measured 3.66 for the music's request, rounded down so the estimate runs high. */
31
+ export declare const JEV_BYTES_PER_TOKEN = 3.4;
32
+ /** What a finder hands Jev: the budget, and each candidate's estimated tokens, counted from the question it will be sent as. */
33
+ export declare function jevRankBudget<C extends FinderCard = FinderCard>(wording: JevWording, limit?: number): RankBudget<C>;
34
+ export type JevOptions = {
35
+ readonly apiKey: string;
36
+ readonly wording: JevWording;
37
+ readonly log?: PayloadLog;
38
+ /** For tests: answers in place of the API. */
39
+ readonly fetch?: Fetch;
40
+ /** Milliseconds per attempt (10 s by default). */
41
+ readonly timeout?: number;
42
+ };
43
+ /** The request for one ask: what is sent and logged. Question i is about candidate i. */
44
+ export declare function jevRequest({ ask, object, tags, candidates }: RankRequest, wording: JevWording): SystemOneRequest;
45
+ export declare function jevRanker<C extends FinderCard = FinderCard>(options: JevOptions): Ranker<C>;