@team-antioch/sc2-doodad-finder 0.1.1 → 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 (48) hide show
  1. package/README.md +2 -0
  2. package/bin/sc2-doodad-finder.js +4 -2
  3. package/dist/asker.d.ts +1 -86
  4. package/dist/asker.js +2 -205
  5. package/dist/cache-dir.d.ts +1 -4
  6. package/dist/cache-dir.js +2 -17
  7. package/dist/cards.d.ts +2 -9
  8. package/dist/cli/doodad-finder.js +1 -2
  9. package/dist/cli/is-main.d.ts +1 -6
  10. package/dist/cli/is-main.js +2 -17
  11. package/dist/credentials.d.ts +8 -26
  12. package/dist/credentials.js +9 -29
  13. package/dist/embedder.d.ts +1 -22
  14. package/dist/embedder.js +2 -48
  15. package/dist/embedding-index.d.ts +1 -25
  16. package/dist/embedding-index.js +2 -125
  17. package/dist/finder.d.ts +5 -56
  18. package/dist/finder.js +20 -141
  19. package/dist/jev-ranker.d.ts +7 -15
  20. package/dist/jev-ranker.js +6 -61
  21. package/dist/key-file.d.ts +1 -13
  22. package/dist/key-file.js +2 -62
  23. package/dist/login.d.ts +4 -31
  24. package/dist/login.js +4 -135
  25. package/dist/narrow.d.ts +9 -35
  26. package/dist/narrow.js +8 -51
  27. package/dist/page.js +1 -1
  28. package/dist/payload-log.d.ts +1 -5
  29. package/dist/payload-log.js +2 -12
  30. package/dist/ranker.d.ts +4 -80
  31. package/dist/ranker.js +3 -40
  32. package/dist/server.d.ts +6 -143
  33. package/dist/server.js +31 -531
  34. package/dist/settings.d.ts +1 -7
  35. package/dist/settings.js +2 -20
  36. package/dist/spend-cap.d.ts +1 -14
  37. package/dist/spend-cap.js +2 -22
  38. package/dist/start.d.ts +4 -4
  39. package/dist/start.js +15 -4
  40. package/dist/stock-sources.js +2 -1
  41. package/dist/tags.d.ts +2 -14
  42. package/dist/test-asks.d.ts +1 -46
  43. package/dist/test-asks.js +2 -81
  44. package/dist/tray.d.ts +4 -17
  45. package/dist/tray.js +6 -11
  46. package/dist/wording.d.ts +7 -0
  47. package/dist/wording.js +2 -0
  48. package/package.json +4 -5
package/README.md CHANGED
@@ -6,6 +6,8 @@ Ask for StarCraft II doodads in plain words and see ranked cards at once: a loca
6
6
  npx @team-antioch/sc2-doodad-finder --open
7
7
  ```
8
8
 
9
+ On Windows, type `npx.cmd` in place of `npx` (PowerShell's default policy refuses `npx`), and install the [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist) first if the machine doesn't have it: the embeddings model needs it. Ctrl-C stops the Finder; answer Y if Windows then asks "Terminate batch job (Y/N)?".
10
+
9
11
  The first start extracts the catalog's fields from SC2GameData into your cache folder and downloads the embeddings model. `npx @team-antioch/sc2-doodad-finder extract` extracts again. `login` asks for your TypeSafe key and saves it in your config folder, and `logout` deletes it. Options: `--port <n>`, `--budget <dollars>` (Jev's spend cap per session, $1.00 by default), `--tick-log <folder>`, `--open`.
10
12
 
11
13
  Getting a TypeSafe key, where it is kept, what each ask sends, the cost and the cap, the cache folders and the platforms: see the [repo's README](https://github.com/TeamAntioch/sc2-asset-catalog#readme).
@@ -1,7 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
  import { main } from "../dist/cli/doodad-finder.js";
3
3
 
4
+ // A failed start exits once its message is written: a download still under way (the model's, the
5
+ // catalog's) would otherwise hold the terminal until it finished. Lines already sent to stdout
6
+ // are written first.
4
7
  main().catch((error) => {
5
- console.error(error instanceof Error ? error.message : error);
6
- process.exitCode = 1;
8
+ process.stdout.write("", () => process.stderr.write(`${error instanceof Error ? error.message : error}\n`, () => process.exit(1)));
7
9
  });
package/dist/asker.d.ts CHANGED
@@ -1,86 +1 @@
1
- import type { NarrowOptions, Narrowing } from "./finder.ts";
2
- import type { Narrowed, Tag } from "./narrow.ts";
3
- import { type Ranker, type RankerName, type Ranking } from "./ranker.ts";
4
- import type { SpendCap } from "./spend-cap.ts";
5
- export type AskMode = "type" | "enter" | "refresh";
6
- /** What an ask runs with, besides its text: the page's state when it was made. */
7
- export type AskContext = {
8
- readonly tags?: readonly Tag[] | undefined;
9
- /** The object the ask is a part of, when there is one: context for the ranker. */
10
- readonly object?: string | undefined;
11
- /** A map's dependencies: their doodads are marked and kept first. */
12
- readonly dependencies?: readonly string[] | undefined;
13
- };
14
- export type AskRequest = AskContext & {
15
- readonly text: string;
16
- /** `type` for a keystroke, `enter` to rank now, `refresh` to narrow again now (the tags changed). */
17
- readonly mode: AskMode;
18
- /** The page state's version: an ask is its text and version. */
19
- readonly version: number;
20
- /** How long typing pauses before the ranker runs, in ms: the page's setting. */
21
- readonly idleMs?: number | undefined;
22
- };
23
- export type RankedCandidate = Narrowed & {
24
- readonly level: number;
25
- };
26
- export type AskEvent = {
27
- readonly type: "narrowed";
28
- readonly text: string;
29
- readonly version: number;
30
- readonly candidates: readonly Narrowed[];
31
- readonly ms: number;
32
- } | {
33
- readonly type: "ranked";
34
- readonly text: string;
35
- readonly version: number;
36
- readonly ranker: RankerName;
37
- /** The tags it ran with. */
38
- readonly tags: readonly Tag[];
39
- readonly candidates: readonly RankedCandidate[];
40
- /** From the ranker being asked for to its order: the narrowing, the call and the order. */
41
- readonly ms: number;
42
- readonly cost: number;
43
- } | {
44
- readonly type: "failed";
45
- readonly text: string;
46
- readonly version: number;
47
- readonly ranker: RankerName;
48
- readonly error: string;
49
- } | {
50
- readonly type: "capped";
51
- readonly text: string;
52
- readonly version: number;
53
- readonly reason: string;
54
- };
55
- export type AskTiming = {
56
- readonly debounceMs: number;
57
- readonly idleMs: number;
58
- readonly budgetMs: number;
59
- };
60
- /** The spec's timings: narrow after 250 ms, rank after 1.5 s idle, wait 300 ms for the ranker. */
61
- export declare const ASK_TIMING: AskTiming;
62
- /** An ask's ranking: the ranker's answer and the narrowed candidates in its order. */
63
- export type AskRanking = {
64
- readonly ranking: Ranking;
65
- readonly tags: readonly Tag[];
66
- readonly candidates: readonly RankedCandidate[];
67
- readonly ms: number;
68
- };
69
- export type AskerOptions = {
70
- readonly narrow: (text: string, options: NarrowOptions) => Promise<Narrowing>;
71
- /** The ranker; with none, asks are narrowed only. */
72
- readonly ranker?: Ranker | undefined;
73
- /** The session's spend cap: past it, no more ranker calls. Each ranking's cost is recorded in it. */
74
- readonly budget?: SpendCap;
75
- readonly emit: (event: AskEvent) => void;
76
- readonly timing?: Partial<AskTiming>;
77
- /** Called with each ranker's answer. */
78
- readonly onRanking?: (ranking: Ranking) => void;
79
- };
80
- export type Asker = {
81
- ask(request: AskRequest): void;
82
- /** The ranking for an ask, for ticking a card from it: the one it has, else one made now. */
83
- ranked(request: AskRequest): Promise<AskRanking>;
84
- close(): void;
85
- };
86
- export declare function createAsker(options: AskerOptions): Asker;
1
+ export * from "@team-antioch/sc2-finder-kit/asker.js";
package/dist/asker.js CHANGED
@@ -1,205 +1,2 @@
1
- // The Doodad Finder process's asks (docs/adr/0001), behind the page's ask endpoint. The page sends
2
- // each change to the ask as it is typed; the process decides when to narrow and when to rank:
3
- //
4
- // typing the narrowing runs 250 ms after typing pauses, and its cards are shown
5
- // idle 1.5 s after typing pauses (a setting), the ranker runs
6
- // Enter the narrowing runs at once if it hasn't, then the ranker
7
- // ranking the page waits up to 300 ms for the ranker; past that it is shown the narrowing's
8
- // order, and the ranked order replaces it once, when the ranker answers
9
- //
10
- // A newer ask cancels the older one: its timers stop, its ranker call is aborted, and nothing it
11
- // finds afterwards is sent. Asks are known by their text and the state version they were made in
12
- // (its tags and the map's dependencies), and by the tags it runs with, so a change of tags is a new ask too. Once the session's spend cap is
13
- // reached, an ask that would rank shows the narrowing's order and a `capped` event says why.
14
- import { orderByFit, RankerError } from "./ranker.js";
15
- /** The spec's timings: narrow after 250 ms, rank after 1.5 s idle, wait 300 ms for the ranker. */
16
- export const ASK_TIMING = { debounceMs: 250, idleMs: 1500, budgetMs: 300 };
17
- /** An ask's key: its version, its tags and its text. The version moves when the page's tags do, but a ticked card's ask can be ranked with the tags it was ticked with. */
18
- const keyOf = ({ text, version, tags }) => `${version}\n${JSON.stringify((tags ?? []).map(({ facet, value, pinned }) => [facet, value, pinned === true]))}\n${text.trim()}`;
19
- /** How many past asks' rankings are kept: going back to an earlier ask costs no call. */
20
- const KEPT_RANKINGS = 50;
21
- const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
22
- export function createAsker(options) {
23
- const timing = { ...ASK_TIMING, ...options.timing };
24
- const kept = new Map();
25
- let current;
26
- const { budget } = options;
27
- const stale = (ask) => current !== ask;
28
- const narrowNow = (ask) => {
29
- if (ask.narrowing)
30
- return ask.narrowing;
31
- const { text, tags, dependencies } = ask.request;
32
- const narrowing = options.narrow(text, { ...(tags ? { tags } : {}), dependencies });
33
- ask.narrowing = narrowing;
34
- // A failed narrowing isn't kept either: the next Enter or idle pause on this ask narrows again.
35
- narrowing.catch(() => {
36
- if (ask.narrowing === narrowing)
37
- delete ask.narrowing;
38
- });
39
- return narrowing;
40
- };
41
- const showNarrowing = async (ask) => {
42
- const narrowing = await narrowNow(ask);
43
- if (stale(ask) || ask.shown)
44
- return;
45
- ask.shown = "narrowed";
46
- options.emit({ type: "narrowed", text: ask.request.text, version: ask.request.version, candidates: narrowing.candidates, ms: narrowing.timings.total });
47
- };
48
- const rankingOf = (ask, ranker) => {
49
- if (ask.ranking)
50
- return ask.ranking;
51
- const known = kept.get(ask.key);
52
- if (known?.ranking.ranker === ranker.name)
53
- return (ask.ranking = Promise.resolve(known));
54
- const started = performance.now();
55
- ask.ranking = (async () => {
56
- const { candidates: narrowed } = await narrowNow(ask);
57
- const { text, object, tags } = ask.request;
58
- let ranking;
59
- try {
60
- ranking = narrowed.length ? await ranker.rank({ ask: text, object, tags, candidates: narrowed.map(({ card }) => card) }, { signal: ask.controller.signal }) : undefined;
61
- }
62
- catch (error) {
63
- // A call answered (and paid for) but not read still counts against the cap.
64
- if (error instanceof RankerError && error.cost > 0)
65
- budget?.record(error.cost);
66
- throw error;
67
- }
68
- if (ranking) {
69
- budget?.record(ranking.cost);
70
- options.onRanking?.(ranking);
71
- }
72
- const candidates = ranking ? orderByFit(narrowed, ranking.grades) : [];
73
- const result = {
74
- ranking: ranking ?? { ranker: ranker.name, model: "", grades: new Map(), timings: { request: 0, total: 0 }, usage: { input: 0, output: 0 }, cost: 0 },
75
- tags: tags ?? [],
76
- candidates,
77
- ms: performance.now() - started,
78
- };
79
- kept.delete(ask.key);
80
- kept.set(ask.key, result);
81
- if (kept.size > KEPT_RANKINGS)
82
- kept.delete(kept.keys().next().value);
83
- return result;
84
- })();
85
- // A ranking no one waits for (it was cancelled) mustn't be an unhandled rejection.
86
- ask.ranking.catch(() => { });
87
- return ask.ranking;
88
- };
89
- /** Whether the ask's ranking is known, so no call is needed for it. */
90
- const known = (ask, ranker) => ask.ranking !== undefined || kept.get(ask.key)?.ranking.ranker === ranker.name;
91
- const rankNow = async (ask) => {
92
- const { ranker } = options;
93
- if (!ranker)
94
- return showNarrowing(ask);
95
- if (ask.rankStarted)
96
- return;
97
- ask.rankStarted = true;
98
- if (budget && !budget.allows() && !known(ask, ranker)) {
99
- await showNarrowing(ask);
100
- if (!stale(ask))
101
- options.emit({ type: "capped", text: ask.request.text, version: ask.request.version, reason: budget.reason });
102
- return;
103
- }
104
- const ranking = rankingOf(ask, ranker);
105
- const late = await Promise.race([ranking.then(() => false, () => false), sleep(timing.budgetMs).then(() => true)]);
106
- try {
107
- if (late)
108
- await showNarrowing(ask);
109
- const { candidates, ranking: answer, ms, tags } = await ranking;
110
- if (stale(ask))
111
- return;
112
- ask.shown = "ranked";
113
- options.emit({ type: "ranked", text: ask.request.text, version: ask.request.version, ranker: ranker.name, tags, candidates, ms, cost: answer.cost });
114
- }
115
- catch (error) {
116
- if (stale(ask))
117
- return;
118
- // A failed ranking isn't kept: the next Enter or idle pause on this ask calls the ranker again.
119
- delete ask.ranking;
120
- ask.rankStarted = false;
121
- // The narrowing's order is shown when the narrowing worked; when it failed, it isn't run again now.
122
- if (ask.narrowing)
123
- await showNarrowing(ask).catch(() => { });
124
- if (stale(ask))
125
- return;
126
- options.emit({ type: "failed", text: ask.request.text, version: ask.request.version, ranker: ranker.name, error: error.message });
127
- }
128
- };
129
- const later = (ask, timer, ms, run) => {
130
- clearTimeout(ask[timer]);
131
- ask[timer] = setTimeout(() => void run(ask).catch(() => { }), ms);
132
- };
133
- const stopTimers = (ask) => {
134
- clearTimeout(ask.debounce);
135
- clearTimeout(ask.idle);
136
- };
137
- const cancel = (ask) => {
138
- if (!ask)
139
- return;
140
- stopTimers(ask);
141
- ask.controller.abort(new Error("A newer ask replaced this one"));
142
- };
143
- return {
144
- ask(request) {
145
- const key = keyOf(request);
146
- let ask = current;
147
- if (ask?.key !== key) {
148
- cancel(current);
149
- current = undefined;
150
- if (!request.text.trim())
151
- return;
152
- ask = { key, request, controller: new AbortController() };
153
- current = ask;
154
- if (request.mode === "type")
155
- later(ask, "debounce", timing.debounceMs, showNarrowing);
156
- }
157
- const idle = request.idleMs ?? timing.idleMs;
158
- if (request.mode === "type") {
159
- // The same ask typed again (a trailing space): the idle wait starts over.
160
- if (!ask.rankStarted)
161
- later(ask, "idle", idle, rankNow);
162
- }
163
- else if (request.mode === "enter") {
164
- stopTimers(ask);
165
- void rankNow(ask).catch(() => { });
166
- }
167
- else {
168
- stopTimers(ask);
169
- void showNarrowing(ask).catch(() => { });
170
- if (!ask.rankStarted)
171
- later(ask, "idle", idle, rankNow);
172
- }
173
- },
174
- async ranked(request) {
175
- const key = keyOf(request);
176
- const known = kept.get(key);
177
- if (known)
178
- return known;
179
- const { ranker } = options;
180
- if (!ranker)
181
- throw new Error("No ranker is on");
182
- // A ranking already under way for the current ask was paid for before the cap was reached.
183
- if (budget && !budget.allows() && !(current?.key === key && current.ranking))
184
- throw new Error(`No ranking: ${budget.reason}`);
185
- if (current?.key === key) {
186
- const ask = current;
187
- void rankNow(ask).catch(() => { });
188
- try {
189
- return await rankingOf(ask, ranker);
190
- }
191
- catch (error) {
192
- // A newer ask cancelled it: the tick still needs it, so it is ranked on its own below.
193
- if (!ask.controller.signal.aborted)
194
- throw error;
195
- }
196
- }
197
- // An ask no longer current: ranked on its own, its results not sent.
198
- return rankingOf({ key, request, controller: new AbortController() }, ranker);
199
- },
200
- close() {
201
- cancel(current);
202
- current = undefined;
203
- },
204
- };
205
- }
1
+ // Moved to @team-antioch/sc2-finder-kit; kept here so deep imports of this package still resolve.
2
+ export * from "@team-antioch/sc2-finder-kit/asker.js";
@@ -1,4 +1 @@
1
- import { type CachePlatform } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
2
- export type { CachePlatform } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
3
- /** Where the model's weights are kept: $SC2_ASSET_CATALOG_MODEL_CACHE (or, for sc2-adjutant, $SC2_ADJUTANT_MODEL_CACHE), else the cache folder's models. */
4
- export declare function modelCacheDir(on?: CachePlatform): string;
1
+ export * from "@team-antioch/sc2-finder-kit/cache-dir.js";
package/dist/cache-dir.js CHANGED
@@ -1,17 +1,2 @@
1
- // The Finder keeps its files in the catalog's cache folder (catalogCacheDir, catalog-dirs.ts in
2
- // @team-antioch/sc2-asset-catalog), on each platform where that platform keeps caches: %LOCALAPPDATA%
3
- // on Windows, ~/Library/Caches on macOS, $XDG_CACHE_HOME (else ~/.cache) elsewhere, or
4
- // SC2_ASSET_CATALOG_CACHE on any of them. It holds the extracted catalog fields, the embeddings
5
- // model's weights, the card vectors, Jev's payload logs and the page's settings: all of it a copy
6
- // of something else, safe to delete.
7
- import path from "node:path";
8
- import { catalogCacheDir } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
9
- /** Where the model's weights are kept: $SC2_ASSET_CATALOG_MODEL_CACHE (or, for sc2-adjutant, $SC2_ADJUTANT_MODEL_CACHE), else the cache folder's models. */
10
- export function modelCacheDir(on = {}) {
11
- const env = on.env ?? process.env;
12
- const moved = env.SC2_ASSET_CATALOG_MODEL_CACHE || env.SC2_ADJUTANT_MODEL_CACHE;
13
- if (moved)
14
- return moved;
15
- const dir = catalogCacheDir(on);
16
- return (on.platform ?? process.platform) === "win32" ? path.win32.join(dir, "models") : path.posix.join(dir, "models");
17
- }
1
+ // Moved to @team-antioch/sc2-finder-kit; kept here so deep imports of this package still resolve.
2
+ export * from "@team-antioch/sc2-finder-kit/cache-dir.js";
package/dist/cards.d.ts CHANGED
@@ -1,16 +1,9 @@
1
+ import type { FinderCard } from "@team-antioch/sc2-finder-kit/card.js";
1
2
  import { type DoodadEntry, type DoodadSearchSources } from "@team-antioch/sc2-asset-catalog/catalog/doodad-search.js";
2
- export type CandidateCard = {
3
- readonly id: string;
4
- readonly name: string;
3
+ export type CandidateCard = FinderCard & {
5
4
  readonly source: DoodadEntry["source"];
6
- /** The card's text: what is embedded and what the ranker reads. */
7
- readonly text: string;
8
5
  /** The entry the card was written from: its facets, for tags, and its look, for the page. */
9
6
  readonly entry: DoodadEntry;
10
- /** The map dependency it needs, absent when the default Void (Mod) brings it in. */
11
- readonly dependency?: string;
12
- /** For a map's dependencies: whether its dependencies already bring it in. */
13
- readonly provided?: boolean;
14
7
  /** A mod doodad its index has no description of for its current model. */
15
8
  readonly pending?: true;
16
9
  };
@@ -89,7 +89,6 @@ export async function main(argv = process.argv.slice(2)) {
89
89
  // Run as a file in a checkout (node src/cli/doodad-finder.ts); the package's bin calls main.
90
90
  if (isMainModule(import.meta.url)) {
91
91
  main().catch((error) => {
92
- console.error(error instanceof Error ? error.message : error);
93
- process.exitCode = 1;
92
+ process.stdout.write("", () => process.stderr.write(`${error instanceof Error ? error.message : error}\n`, () => process.exit(1)));
94
93
  });
95
94
  }
@@ -1,6 +1 @@
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;
1
+ export { isMainModule } from "@team-antioch/sc2-finder-kit/is-main.js";
@@ -1,17 +1,2 @@
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
- }
1
+ // Moved to the kit (docs/adr/0002); kept so the old import path still resolves.
2
+ export { isMainModule } from "@team-antioch/sc2-finder-kit/is-main.js";
@@ -1,29 +1,11 @@
1
- import { type ConfigPlatform } from "./key-file.ts";
2
- import type { PayloadLog, Ranker } from "./ranker.ts";
3
- export declare const NO_JEV_KEY = "no TypeSafe key: run `npx @team-antioch/sc2-doodad-finder login`, or set TYPESAFE_API_KEY, to rank with Jev; until then the narrowing's order is shown";
4
- /** Where a key came from: what /status and the CLI may say, never the key. */
5
- export type KeySource = "environment" | "key file";
6
- /** Jev's key and where it came from: TYPESAFE_API_KEY, else the key file, else none. */
7
- export declare function jevKey(on?: ConfigPlatform): {
8
- readonly key: string;
9
- readonly source: KeySource;
10
- } | undefined;
11
- /** Jev's key alone: TYPESAFE_API_KEY, else the key file, else none. */
12
- export declare const jevApiKey: (on?: ConfigPlatform) => string | undefined;
13
- /** The ranker when it has its credential, and where that came from, else why it is off. */
14
- export type OpenedRanker = {
15
- readonly ranker: Ranker;
16
- readonly keySource: KeySource;
17
- readonly off?: undefined;
18
- } | {
19
- readonly ranker?: undefined;
20
- readonly keySource?: undefined;
21
- readonly off: string;
22
- };
23
- /** Where a key came from, in words. */
24
- export declare const keySourceText: (source: KeySource) => string;
1
+ import { type OpenedRanker as KitOpenedRanker } from "@team-antioch/sc2-finder-kit/credentials.js";
2
+ import type { PayloadLog } from "@team-antioch/sc2-finder-kit/ranker.js";
3
+ import type { CandidateCard } from "./cards.ts";
4
+ export { type KeySource, jevApiKey, jevKey, keySourceText } from "@team-antioch/sc2-finder-kit/credentials.js";
5
+ export declare const NO_JEV_KEY: string;
6
+ export type OpenedRanker = KitOpenedRanker<CandidateCard>;
25
7
  /** Jev with its key, else off: with no key, or (Jev being optional) a key file that can't be read. */
26
- export declare function openRanker({ env, log }?: {
8
+ export declare const openRanker: ({ env, log }?: {
27
9
  readonly env?: Readonly<Record<string, string | undefined>>;
28
10
  readonly log?: PayloadLog;
29
- }): OpenedRanker;
11
+ }) => OpenedRanker;
@@ -1,31 +1,11 @@
1
- // The ranker's credential (docs/adr/0001), held by the Finder's process alone: Jev's key from
2
- // TYPESAFE_API_KEY in the environment, else the key file `sc2-doodad-finder login` saved
3
- // (key-file.ts), on every platform. The variable wins. With no key, Jev is off, with a message
1
+ // The ranker's credential (docs/adr/0001), held by the Finder's process alone: the kit's, for this
2
+ // finder: Jev's key from TYPESAFE_API_KEY in the environment, else the key file
3
+ // `sc2-doodad-finder login` saved, on every platform. With no key, Jev is off, with a message
4
4
  // saying how to give it one, and asks are narrowed only.
5
- import { keyFile, readKeyFile } from "./key-file.js";
6
- import { jevRanker } from "./jev-ranker.js";
7
- export const NO_JEV_KEY = "no TypeSafe key: run `npx @team-antioch/sc2-doodad-finder login`, or set TYPESAFE_API_KEY, to rank with Jev; until then the narrowing's order is shown";
8
- /** Jev's key and where it came from: TYPESAFE_API_KEY, else the key file, else none. */
9
- export function jevKey(on = {}) {
10
- const fromEnv = (on.env ?? process.env).TYPESAFE_API_KEY?.trim();
11
- if (fromEnv)
12
- return { key: fromEnv, source: "environment" };
13
- const fromFile = readKeyFile(on);
14
- return fromFile ? { key: fromFile, source: "key file" } : undefined;
15
- }
16
- /** Jev's key alone: TYPESAFE_API_KEY, else the key file, else none. */
17
- export const jevApiKey = (on = {}) => jevKey(on)?.key;
18
- /** Where a key came from, in words. */
19
- export const keySourceText = (source) => (source === "environment" ? "the key in TYPESAFE_API_KEY" : "the saved key");
5
+ import { noJevKey, openRanker as kitOpenRanker } from "@team-antioch/sc2-finder-kit/credentials.js";
6
+ import { JEV_WORDING } from "./wording.js";
7
+ export { jevApiKey, jevKey, keySourceText } from "@team-antioch/sc2-finder-kit/credentials.js";
8
+ const COMMAND = "@team-antioch/sc2-doodad-finder";
9
+ export const NO_JEV_KEY = noJevKey(COMMAND);
20
10
  /** Jev with its key, else off: with no key, or (Jev being optional) a key file that can't be read. */
21
- export function openRanker({ env, log } = {}) {
22
- const on = env ? { env } : {};
23
- let found;
24
- try {
25
- found = jevKey(on);
26
- }
27
- catch (error) {
28
- return { off: `can't read the key file ${keyFile(on)} (${error.message}): run \`npx @team-antioch/sc2-doodad-finder login\` again, or set TYPESAFE_API_KEY` };
29
- }
30
- return found ? { ranker: jevRanker({ apiKey: found.key, ...(log ? { log } : {}) }), keySource: found.source } : { off: NO_JEV_KEY };
31
- }
11
+ export const openRanker = ({ env, log } = {}) => kitOpenRanker({ ...(env ? { env } : {}), ...(log ? { log } : {}), wording: JEV_WORDING, command: COMMAND });
@@ -1,22 +1 @@
1
- export { modelCacheDir } from "./cache-dir.ts";
2
- /** Embeds texts as unit vectors: an ask as a query, a card as a passage. */
3
- export type Embedder = {
4
- /** The model's name: vectors from two models aren't comparable, so the cache keeps them apart. */
5
- readonly model: string;
6
- embed(texts: readonly string[], as: "query" | "passage"): Promise<Float32Array[]>;
7
- };
8
- export declare const FINDER_MODEL = "Xenova/gte-small";
9
- /**
10
- * How each model the test command can compare pools its tokens into one vector, and what it puts
11
- * before a query: bge pools by its first token and asks for an instruction before a short query
12
- * searched against passages; gte averages its tokens and takes none.
13
- */
14
- export declare const MODELS: Readonly<Record<string, {
15
- readonly pooling: "cls" | "mean";
16
- readonly queryPrefix: string;
17
- }>>;
18
- /** The local model, loaded once (downloading its weights the first time). */
19
- export declare function localEmbedder(options?: {
20
- readonly model?: string;
21
- readonly cacheDir?: string;
22
- }): Promise<Embedder>;
1
+ export * from "@team-antioch/sc2-finder-kit/embedder.js";
package/dist/embedder.js CHANGED
@@ -1,48 +1,2 @@
1
- // The Doodad Finder's embeddings model (docs/adr/0001): it runs on this machine, with no network call
2
- // once its weights are downloaded. The model is Alibaba's gte-small (384 dimensions, about 34 MB
3
- // quantized to 8 bits), run by transformers.js on ONNX Runtime for Node. On the test asks
4
- // it found as many candidates as bge-small and bge-base, and more of the top-ranked than
5
- // bge-small, at the fastest narrowing (the test command's --model compares them). Its weights
6
- // download to a machine cache the first time it runs, never into the repo. Tests use a fake behind
7
- // the same interface, so they need no model.
8
- import { modelCacheDir } from "./cache-dir.js";
9
- export { modelCacheDir } from "./cache-dir.js";
10
- export const FINDER_MODEL = "Xenova/gte-small";
11
- /**
12
- * How each model the test command can compare pools its tokens into one vector, and what it puts
13
- * before a query: bge pools by its first token and asks for an instruction before a short query
14
- * searched against passages; gte averages its tokens and takes none.
15
- */
16
- export const MODELS = {
17
- "Xenova/bge-small-en-v1.5": { pooling: "cls", queryPrefix: "Represent this sentence for searching relevant passages: " },
18
- "Xenova/bge-base-en-v1.5": { pooling: "cls", queryPrefix: "Represent this sentence for searching relevant passages: " },
19
- "Xenova/gte-small": { pooling: "mean", queryPrefix: "" },
20
- "Xenova/gte-base": { pooling: "mean", queryPrefix: "" },
21
- };
22
- /** At most this many texts per call to the model, so a cold start's thousands of cards don't make one huge batch. */
23
- const BATCH = 32;
24
- /** The local model, loaded once (downloading its weights the first time). */
25
- export async function localEmbedder(options = {}) {
26
- const model = options.model ?? FINDER_MODEL;
27
- const settings = MODELS[model];
28
- if (!settings)
29
- throw new Error(`No settings for the embeddings model ${model}: it takes one of ${Object.keys(MODELS).join(", ")}`);
30
- const { env, pipeline } = await import("@huggingface/transformers");
31
- env.cacheDir = options.cacheDir ?? modelCacheDir();
32
- const extract = await pipeline("feature-extraction", model, { dtype: "q8" });
33
- return {
34
- model,
35
- async embed(texts, as) {
36
- const vectors = [];
37
- for (let start = 0; start < texts.length; start += BATCH) {
38
- const batch = texts.slice(start, start + BATCH).map((text) => (as === "query" ? settings.queryPrefix + text : text));
39
- const output = await extract(batch, { pooling: settings.pooling, normalize: true });
40
- const [rows, dimensions] = output.dims;
41
- const data = output.data;
42
- for (let row = 0; row < rows; row++)
43
- vectors.push(data.slice(row * dimensions, (row + 1) * dimensions));
44
- }
45
- return vectors;
46
- },
47
- };
48
- }
1
+ // Moved to @team-antioch/sc2-finder-kit; kept here so deep imports of this package still resolve.
2
+ export * from "@team-antioch/sc2-finder-kit/embedder.js";
@@ -1,25 +1 @@
1
- import type { CandidateCard } from "./cards.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 text it has no vector for, forgets the
14
- * rest, and saves the cache when it changed. Gives these cards' own nearest, which later updates
15
- * leave as it is, so a caller can swap it in with the cards it was made for.
16
- */
17
- update(cards: readonly CandidateCard[]): Promise<{
18
- embedded: number;
19
- nearest: Nearest;
20
- }>;
21
- /** The last update's cards most like a unit vector (see Nearest). */
22
- nearest(query: Float32Array, k: number, keep?: (id: string) => boolean): Neighbour[];
23
- }
24
- /** The k cards most like a unit vector, most alike first, among those `keep` allows. */
25
- export type Nearest = (query: Float32Array, k: number, keep?: (id: string) => boolean) => Neighbour[];
1
+ export * from "@team-antioch/sc2-finder-kit/embedding-index.js";