@team-antioch/sc2-finder-kit 0.0.0-stage → 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.
- package/LICENSE +21 -0
- package/README.md +36 -2
- package/dist/asker.d.ts +91 -0
- package/dist/asker.js +214 -0
- package/dist/cache-dir.d.ts +4 -0
- package/dist/cache-dir.js +17 -0
- package/dist/card.d.ts +35 -0
- package/dist/card.js +4 -0
- package/dist/credentials.d.ts +34 -0
- package/dist/credentials.js +33 -0
- package/dist/embedder.d.ts +39 -0
- package/dist/embedder.js +94 -0
- package/dist/embedding-index.d.ts +26 -0
- package/dist/embedding-index.js +129 -0
- package/dist/finder.d.ts +87 -0
- package/dist/finder.js +162 -0
- package/dist/gateway-translator.d.ts +21 -0
- package/dist/gateway-translator.js +62 -0
- package/dist/is-main.d.ts +6 -0
- package/dist/is-main.js +17 -0
- package/dist/jev-language-detector.d.ts +15 -0
- package/dist/jev-language-detector.js +44 -0
- package/dist/jev-ranker.d.ts +45 -0
- package/dist/jev-ranker.js +93 -0
- package/dist/key-file.d.ts +13 -0
- package/dist/key-file.js +62 -0
- package/dist/language-detector.d.ts +20 -0
- package/dist/language-detector.js +38 -0
- package/dist/load-together.d.ts +26 -0
- package/dist/load-together.js +39 -0
- package/dist/login.d.ts +34 -0
- package/dist/login.js +137 -0
- package/dist/narrow.d.ts +57 -0
- package/dist/narrow.js +74 -0
- package/dist/payload-log.d.ts +5 -0
- package/dist/payload-log.js +12 -0
- package/dist/ranker.d.ts +80 -0
- package/dist/ranker.js +40 -0
- package/dist/server.d.ts +178 -0
- package/dist/server.js +565 -0
- package/dist/settings.d.ts +7 -0
- package/dist/settings.js +20 -0
- package/dist/spend-cap.d.ts +14 -0
- package/dist/spend-cap.js +22 -0
- package/dist/test-asks.d.ts +60 -0
- package/dist/test-asks.js +107 -0
- package/dist/translator.d.ts +48 -0
- package/dist/translator.js +51 -0
- package/dist/tray.d.ts +22 -0
- package/dist/tray.js +12 -0
- package/package.json +45 -4
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// The Jev ranker (docs/adr/0001): one TypeSafe request per ask. The state is the ask, the object and the
|
|
2
|
+
// tags; each candidate gets one Score question with its card, on four levels. Jev judges, the
|
|
3
|
+
// code orders (ranker.ts). What it is told about the finder's cards is the finder's wording. The exact payload goes to the log, and a failed call or a missing
|
|
4
|
+
// answer is an error, never a low grade.
|
|
5
|
+
import { score, TypeSafeClient } from "@typesafe-ai/sdk";
|
|
6
|
+
import { RankerError, tagText } from "./ranker.js";
|
|
7
|
+
export const JEV_MODEL = "jev-latest";
|
|
8
|
+
/** US dollars per input token; output is free. */
|
|
9
|
+
export const JEV_INPUT_PRICE = 0.042 / 1e6;
|
|
10
|
+
/**
|
|
11
|
+
* What one request to Jev can carry, as input tokens. Jev refuses a request over its limit with
|
|
12
|
+
* `400 max_tokens_exceeded` (docs/adr/0002). The Music Finder met it: its asks took 57k to 65.7k
|
|
13
|
+
* input tokens at 168 to 187 candidates and the ones with 189 to 198 candidates were refused, so
|
|
14
|
+
* the limit is somewhere about 65k. A request is cut to 55k estimated tokens, which leaves room for
|
|
15
|
+
* the estimate being off (it counts bytes, not tokens) and for the ask, tags and the state: the
|
|
16
|
+
* 10k tokens of headroom is about 34,000 bytes, far more than the state's note, a typed ask, its
|
|
17
|
+
* tags and an object, so they are not counted per candidate.
|
|
18
|
+
*/
|
|
19
|
+
export const JEV_TOKEN_BUDGET = 55_000;
|
|
20
|
+
/** Bytes per token for the estimate: the measured 3.66 for the music's request, rounded down so the estimate runs high. */
|
|
21
|
+
export const JEV_BYTES_PER_TOKEN = 3.4;
|
|
22
|
+
/** The question's key (`"c123":`) and the comma after it. */
|
|
23
|
+
const QUESTION_KEY_BYTES = 8;
|
|
24
|
+
/** What a finder hands Jev: the budget, and each candidate's estimated tokens, counted from the question it will be sent as. */
|
|
25
|
+
export function jevRankBudget(wording, limit = JEV_TOKEN_BUDGET) {
|
|
26
|
+
// The question's levels are the same on every candidate: only the card's text varies.
|
|
27
|
+
const fixed = Buffer.byteLength(JSON.stringify(score({ question: wording.question, [wording.field]: "" }, wording.levels))) + QUESTION_KEY_BYTES;
|
|
28
|
+
return { limit, cost: (card) => Math.ceil((fixed + Buffer.byteLength(JSON.stringify(card.text)) - 2) / JEV_BYTES_PER_TOKEN) };
|
|
29
|
+
}
|
|
30
|
+
/** The request for one ask: what is sent and logged. Question i is about candidate i. */
|
|
31
|
+
export function jevRequest({ ask, object, tags, candidates }, wording) {
|
|
32
|
+
const state = { about: wording.about, ask };
|
|
33
|
+
if (object)
|
|
34
|
+
state.object = object;
|
|
35
|
+
if (tags?.length)
|
|
36
|
+
state.tags = tags.map(tagText);
|
|
37
|
+
const questions = Object.fromEntries(candidates.map((card, i) => [`c${i}`, score({ question: wording.question, [wording.field]: card.text }, wording.levels)]));
|
|
38
|
+
return { model: JEV_MODEL, state, questions };
|
|
39
|
+
}
|
|
40
|
+
export function jevRanker(options) {
|
|
41
|
+
const { wording } = options;
|
|
42
|
+
const client = new TypeSafeClient({ apiKey: options.apiKey, logLevel: "off", ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.timeout ? { timeout: options.timeout } : {}) });
|
|
43
|
+
return {
|
|
44
|
+
name: "jev",
|
|
45
|
+
async rank(request, { signal } = {}) {
|
|
46
|
+
const started = performance.now();
|
|
47
|
+
const payload = jevRequest(request, wording);
|
|
48
|
+
const sent = performance.now();
|
|
49
|
+
const at = new Date().toISOString();
|
|
50
|
+
let result;
|
|
51
|
+
try {
|
|
52
|
+
result = await client.systemOne(payload, signal ? { signal } : {});
|
|
53
|
+
}
|
|
54
|
+
catch (error) {
|
|
55
|
+
// The key never goes further than the client: not into the log, the terminal or the page.
|
|
56
|
+
const hide = (text) => (options.apiKey ? text.split(options.apiKey).join("[the key]") : text);
|
|
57
|
+
options.log?.({ ranker: "jev", at, ms: performance.now() - sent, request: payload, error: hide(String(error)) });
|
|
58
|
+
// The SDK's error is kept as a copy with the key hidden: its name, message and status.
|
|
59
|
+
// Its network code too (ENOTFOUND, say), from its own cause, so an outage still reads as one.
|
|
60
|
+
const failure = error;
|
|
61
|
+
const code = failure.cause?.code;
|
|
62
|
+
const cause = Object.assign(new Error(hide(failure.message)), {
|
|
63
|
+
name: failure.name,
|
|
64
|
+
...(failure.status !== undefined ? { status: failure.status } : {}),
|
|
65
|
+
...(typeof code === "string" ? { code } : {}),
|
|
66
|
+
});
|
|
67
|
+
throw new RankerError("jev", `the request failed: ${cause.message}`, { cause });
|
|
68
|
+
}
|
|
69
|
+
const answered = performance.now();
|
|
70
|
+
options.log?.({ ranker: "jev", at, ms: answered - sent, request: payload, response: result });
|
|
71
|
+
const logged = performance.now() - answered; // the log write is not part of the ranker's time
|
|
72
|
+
const input = result.usage.input_tokens ?? 0;
|
|
73
|
+
const cost = input * JEV_INPUT_PRICE;
|
|
74
|
+
const grades = new Map();
|
|
75
|
+
request.candidates.forEach((card, i) => {
|
|
76
|
+
const answer = result.answers[`c${i}`];
|
|
77
|
+
// Answered, so paid for: the error carries the cost for the spend cap.
|
|
78
|
+
if (answer?.type !== "score" || !Number.isFinite(answer.score))
|
|
79
|
+
throw new RankerError("jev", `no score for ${card.id}`, { cost });
|
|
80
|
+
const given = answer.probabilities;
|
|
81
|
+
grades.set(card.id, given ? { level: answer.score, probabilities: wording.levels.map((_, level) => given[level] ?? 0) } : { level: answer.score });
|
|
82
|
+
});
|
|
83
|
+
return {
|
|
84
|
+
ranker: "jev",
|
|
85
|
+
model: result.model,
|
|
86
|
+
grades,
|
|
87
|
+
timings: { request: answered - sent, total: performance.now() - started - logged },
|
|
88
|
+
usage: { input, output: result.usage.output_tokens ?? 0 },
|
|
89
|
+
cost,
|
|
90
|
+
};
|
|
91
|
+
},
|
|
92
|
+
};
|
|
93
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type CachePlatform } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
|
|
2
|
+
/** The platform, environment and home folder the config folder is worked out from, as for the cache folder. */
|
|
3
|
+
export type ConfigPlatform = CachePlatform;
|
|
4
|
+
/** This user's config folder (the catalog's, which `setup-renderer` also writes to): where the key file is kept. */
|
|
5
|
+
export declare const configDir: (on?: ConfigPlatform) => string;
|
|
6
|
+
/** The key file in the config folder. */
|
|
7
|
+
export declare const keyFile: (on?: ConfigPlatform) => string;
|
|
8
|
+
/** The saved key, trimmed, or none when there is no file or it is blank. */
|
|
9
|
+
export declare function readKeyFile(on?: ConfigPlatform): string | undefined;
|
|
10
|
+
/** Saves the key whole: to a new file beside the key file, readable by its owner alone, then over it. */
|
|
11
|
+
export declare function saveKeyFile(key: string, on?: ConfigPlatform): Promise<void>;
|
|
12
|
+
/** Deletes the key file: true when there was one. */
|
|
13
|
+
export declare function removeKeyFile(on?: ConfigPlatform): Promise<boolean>;
|
package/dist/key-file.js
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// Jev's key file: the TypeSafe key a finder's `login` saves, in the per-user config folder.
|
|
2
|
+
// That is %APPDATA%\sc2-asset-catalog on Windows and $XDG_CONFIG_HOME/sc2-asset-catalog (else
|
|
3
|
+
// ~/.config/sc2-asset-catalog) on macOS and Linux, or SC2_ASSET_CATALOG_CONFIG on any of them. Unlike
|
|
4
|
+
// the cache folder, it holds something that is not a copy of anything else. On POSIX the file is
|
|
5
|
+
// 0600, in a 0700 folder (a folder SC2_ASSET_CATALOG_CONFIG names is left as it is unless the save
|
|
6
|
+
// creates it). No OS credential manager is used.
|
|
7
|
+
import { randomBytes } from "node:crypto";
|
|
8
|
+
import { readFileSync } from "node:fs";
|
|
9
|
+
import { chmod, mkdir, rename, rm, writeFile } from "node:fs/promises";
|
|
10
|
+
import path from "node:path";
|
|
11
|
+
import { catalogConfigDir } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
|
|
12
|
+
/** This user's config folder (the catalog's, which `setup-renderer` also writes to): where the key file is kept. */
|
|
13
|
+
export const configDir = (on = {}) => catalogConfigDir(on);
|
|
14
|
+
/** The key file in the config folder. */
|
|
15
|
+
export const keyFile = (on = {}) => ((on.platform ?? process.platform) === "win32" ? path.win32 : path.posix).join(configDir(on), "typesafe-key");
|
|
16
|
+
/** The saved key, trimmed, or none when there is no file or it is blank. */
|
|
17
|
+
export function readKeyFile(on = {}) {
|
|
18
|
+
let text;
|
|
19
|
+
try {
|
|
20
|
+
text = readFileSync(keyFile(on), "utf8");
|
|
21
|
+
}
|
|
22
|
+
catch (error) {
|
|
23
|
+
if (error.code === "ENOENT")
|
|
24
|
+
return undefined;
|
|
25
|
+
throw error;
|
|
26
|
+
}
|
|
27
|
+
return text.trim() || undefined;
|
|
28
|
+
}
|
|
29
|
+
/** Saves the key whole: to a new file beside the key file, readable by its owner alone, then over it. */
|
|
30
|
+
export async function saveKeyFile(key, on = {}) {
|
|
31
|
+
const file = keyFile(on);
|
|
32
|
+
const dir = path.dirname(file);
|
|
33
|
+
const posix = (on.platform ?? process.platform) !== "win32";
|
|
34
|
+
const created = await mkdir(dir, { recursive: true, mode: 0o700 });
|
|
35
|
+
// The default folder is ours, so it is tightened; a folder SC2_ASSET_CATALOG_CONFIG names is the
|
|
36
|
+
// user's, so only the file is.
|
|
37
|
+
if (posix && (created !== undefined || !(on.env ?? process.env).SC2_ASSET_CATALOG_CONFIG))
|
|
38
|
+
await chmod(dir, 0o700);
|
|
39
|
+
const partial = `${file}.${randomBytes(6).toString("hex")}.partial`;
|
|
40
|
+
try {
|
|
41
|
+
await writeFile(partial, `${key}\n`, { mode: 0o600, flag: "wx" });
|
|
42
|
+
if (posix)
|
|
43
|
+
await chmod(partial, 0o600);
|
|
44
|
+
await rename(partial, file);
|
|
45
|
+
}
|
|
46
|
+
catch (error) {
|
|
47
|
+
await rm(partial, { force: true });
|
|
48
|
+
throw error;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** Deletes the key file: true when there was one. */
|
|
52
|
+
export async function removeKeyFile(on = {}) {
|
|
53
|
+
try {
|
|
54
|
+
await rm(keyFile(on));
|
|
55
|
+
return true;
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
if (error.code === "ENOENT")
|
|
59
|
+
return false;
|
|
60
|
+
throw error;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
export type Detection = {
|
|
2
|
+
readonly english: boolean;
|
|
3
|
+
/** The detector's probability that the ask is English, 0 to 1. */
|
|
4
|
+
readonly pEnglish: number;
|
|
5
|
+
/** US dollars, estimated, for a spend cap. */
|
|
6
|
+
readonly cost: number;
|
|
7
|
+
};
|
|
8
|
+
export interface LanguageDetector {
|
|
9
|
+
detect(ask: string, options?: {
|
|
10
|
+
readonly signal?: AbortSignal;
|
|
11
|
+
}): Promise<Detection>;
|
|
12
|
+
}
|
|
13
|
+
/** At or above this probability an ask is English; below it, it is translated. High, so a doubtful ask is translated. */
|
|
14
|
+
export declare const ENGLISH_AT = 0.8;
|
|
15
|
+
/** The words of the cards' English text, lower-cased: what an English ask in this catalog is made of. */
|
|
16
|
+
export declare function vocabularyOf(texts: Iterable<string>): Set<string>;
|
|
17
|
+
/** Whether every word of the ask is in the vocabulary, in some plural: an ask that is English with no call needed. */
|
|
18
|
+
export declare const inVocabulary: (ask: string, vocabulary: ReadonlySet<string>) => boolean;
|
|
19
|
+
/** Remembers each ask's detection (up to `max`, the oldest forgotten first), so an ask asked again costs no call and no cost. A failure is not remembered. */
|
|
20
|
+
export declare function cachingDetector(inner: LanguageDetector, max?: number): LanguageDetector;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// The finder kit's language detector slot. An ask in another script is known by its letters
|
|
2
|
+
// (translator.ts); one in Latin script (Spanish, German, French, Portuguese, Polish...) is not, and
|
|
3
|
+
// reads as English to every local check. A detector says whether an ask is English, and only asks
|
|
4
|
+
// that look English to the catalog's own vocabulary and aren't already known to be are put to it,
|
|
5
|
+
// so an English ask costs no call. It is a tiebreaker, never a gate: a detector that fails or
|
|
6
|
+
// can't tell leaves the ask to be translated, since translating English leaves it as it was and
|
|
7
|
+
// not translating a foreign ask loses its results.
|
|
8
|
+
/** At or above this probability an ask is English; below it, it is translated. High, so a doubtful ask is translated. */
|
|
9
|
+
export const ENGLISH_AT = 0.8;
|
|
10
|
+
const wordsOf = (text) => text.toLowerCase().match(/\p{L}+/gu) ?? [];
|
|
11
|
+
/** The words of the cards' English text, lower-cased: what an English ask in this catalog is made of. */
|
|
12
|
+
export function vocabularyOf(texts) {
|
|
13
|
+
const vocabulary = new Set();
|
|
14
|
+
for (const text of texts)
|
|
15
|
+
for (const word of wordsOf(text))
|
|
16
|
+
vocabulary.add(word);
|
|
17
|
+
return vocabulary;
|
|
18
|
+
}
|
|
19
|
+
/** Whether a word, or its singular, is one of the vocabulary's. */
|
|
20
|
+
const known = (word, vocabulary) => vocabulary.has(word) || (word.endsWith("ies") && vocabulary.has(`${word.slice(0, -3)}y`)) || (word.endsWith("es") && vocabulary.has(word.slice(0, -2))) || (word.endsWith("s") && vocabulary.has(word.slice(0, -1)));
|
|
21
|
+
/** Whether every word of the ask is in the vocabulary, in some plural: an ask that is English with no call needed. */
|
|
22
|
+
export const inVocabulary = (ask, vocabulary) => wordsOf(ask).every((word) => known(word, vocabulary));
|
|
23
|
+
/** Remembers each ask's detection (up to `max`, the oldest forgotten first), so an ask asked again costs no call and no cost. A failure is not remembered. */
|
|
24
|
+
export function cachingDetector(inner, max = 500) {
|
|
25
|
+
const seen = new Map();
|
|
26
|
+
return {
|
|
27
|
+
async detect(ask, options) {
|
|
28
|
+
const again = seen.get(ask);
|
|
29
|
+
if (again)
|
|
30
|
+
return { ...again, cost: 0 };
|
|
31
|
+
const detection = await inner.detect(ask, options);
|
|
32
|
+
seen.set(ask, detection);
|
|
33
|
+
if (seen.size > max)
|
|
34
|
+
seen.delete(seen.keys().next().value);
|
|
35
|
+
return detection;
|
|
36
|
+
},
|
|
37
|
+
};
|
|
38
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { type Embedder } from "./embedder.ts";
|
|
2
|
+
export type LoadTogetherOptions = {
|
|
3
|
+
/** For tests: the embeddings model in place of the local one, or what loads it. */
|
|
4
|
+
readonly embedder?: Embedder | (() => Promise<Embedder>);
|
|
5
|
+
/** For tests: the fetch the extraction downloads with (the global one by default). */
|
|
6
|
+
readonly fetch?: typeof globalThis.fetch;
|
|
7
|
+
/** Lines worth showing the user as the finder starts. */
|
|
8
|
+
readonly log: (line: string) => void;
|
|
9
|
+
/**
|
|
10
|
+
* Starts the finder's extraction (`undefined` when there is nothing to extract). It is handed a
|
|
11
|
+
* `log` that goes quiet once the model has failed, a `fetch` that can be stopped, and the signal
|
|
12
|
+
* that stops it; whatever it can't stop through those it should refuse to start once `signal` is aborted.
|
|
13
|
+
*/
|
|
14
|
+
readonly extract: ((io: {
|
|
15
|
+
readonly log: (line: string) => void;
|
|
16
|
+
readonly fetch: typeof globalThis.fetch;
|
|
17
|
+
readonly signal: AbortSignal;
|
|
18
|
+
}) => Promise<void>) | undefined;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* The extraction (done on a first start) and the model, loaded together: on a first start both
|
|
22
|
+
* download. Whichever fails first is said, and a machine that can't load the model (on Windows,
|
|
23
|
+
* without the Visual C++ runtime) is told so at once, the extraction stopped and quiet. Any other
|
|
24
|
+
* model failure waits on the extraction, whose own failure (offline, say) is the one worth saying.
|
|
25
|
+
*/
|
|
26
|
+
export declare function loadTogether(options: LoadTogetherOptions): Promise<Embedder>;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// The first-start race both finders run (docs/adr/0002): their extraction and the embeddings model,
|
|
2
|
+
// loaded together.
|
|
3
|
+
import { localEmbedder, MissingRuntimeError } from "./embedder.js";
|
|
4
|
+
/**
|
|
5
|
+
* The extraction (done on a first start) and the model, loaded together: on a first start both
|
|
6
|
+
* download. Whichever fails first is said, and a machine that can't load the model (on Windows,
|
|
7
|
+
* without the Visual C++ runtime) is told so at once, the extraction stopped and quiet. Any other
|
|
8
|
+
* model failure waits on the extraction, whose own failure (offline, say) is the one worth saying.
|
|
9
|
+
*/
|
|
10
|
+
export async function loadTogether(options) {
|
|
11
|
+
const stop = new AbortController();
|
|
12
|
+
const fetch = options.fetch ?? globalThis.fetch;
|
|
13
|
+
const stoppable = (input, init) => fetch(input, { ...init, signal: stop.signal });
|
|
14
|
+
const quiet = (line) => {
|
|
15
|
+
if (!stop.signal.aborted)
|
|
16
|
+
options.log(line);
|
|
17
|
+
};
|
|
18
|
+
const extraction = options.extract ? options.extract({ log: quiet, fetch: stoppable, signal: stop.signal }) : Promise.resolve();
|
|
19
|
+
const { embedder } = options;
|
|
20
|
+
const model = typeof embedder === "function" ? embedder() : embedder ? Promise.resolve(embedder) : localEmbedder();
|
|
21
|
+
const first = await Promise.race([
|
|
22
|
+
model.then((loaded) => ({ embedder: loaded }), (error) => ({ modelError: error })),
|
|
23
|
+
// The extraction's success doesn't end the race: only its failure does.
|
|
24
|
+
extraction.then(() => new Promise(() => { }), (error) => ({ extractionError: error })),
|
|
25
|
+
]);
|
|
26
|
+
if ("extractionError" in first)
|
|
27
|
+
throw first.extractionError;
|
|
28
|
+
if ("modelError" in first) {
|
|
29
|
+
if (first.modelError instanceof MissingRuntimeError) {
|
|
30
|
+
stop.abort();
|
|
31
|
+
extraction.catch(() => { });
|
|
32
|
+
throw first.modelError;
|
|
33
|
+
}
|
|
34
|
+
await extraction;
|
|
35
|
+
throw first.modelError;
|
|
36
|
+
}
|
|
37
|
+
await extraction;
|
|
38
|
+
return first.embedder;
|
|
39
|
+
}
|
package/dist/login.d.ts
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { type ConfigPlatform } from "./key-file.ts";
|
|
2
|
+
/** What checking a key found: it works, TypeSafe refused it, or it couldn't be checked. */
|
|
3
|
+
export type KeyCheckResult = {
|
|
4
|
+
readonly ok: true;
|
|
5
|
+
} | {
|
|
6
|
+
readonly ok: false;
|
|
7
|
+
readonly refused: boolean;
|
|
8
|
+
readonly reason: string;
|
|
9
|
+
};
|
|
10
|
+
export type KeyCheck = (key: string) => Promise<KeyCheckResult>;
|
|
11
|
+
/** Checks a key by listing the account's models (GET /v1/models): no Jev request, no tokens. */
|
|
12
|
+
export declare function typesafeKeyCheck({ fetch }?: {
|
|
13
|
+
readonly fetch?: typeof globalThis.fetch;
|
|
14
|
+
}): KeyCheck;
|
|
15
|
+
/** A terminal's input: raw mode turns its echo off. */
|
|
16
|
+
type TerminalInput = NodeJS.ReadableStream & {
|
|
17
|
+
readonly isTTY?: boolean;
|
|
18
|
+
setRawMode?(raw: boolean): unknown;
|
|
19
|
+
};
|
|
20
|
+
export type LoginOptions = ConfigPlatform & {
|
|
21
|
+
/** Where the key is read from (stdin by default). */
|
|
22
|
+
readonly input?: TerminalInput;
|
|
23
|
+
/** Where the prompt and messages go (stdout by default). */
|
|
24
|
+
readonly output?: NodeJS.WritableStream;
|
|
25
|
+
/** How the key is checked (with TypeSafe by default). */
|
|
26
|
+
readonly check?: KeyCheck;
|
|
27
|
+
/** The package whose `login` and `logout` the messages name, such as `@team-antioch/sc2-doodad-finder`. */
|
|
28
|
+
readonly command: string;
|
|
29
|
+
};
|
|
30
|
+
/** Asks for the key, checks it and saves it. Returns the exit code: 0 saved, 1 not, 130 cancelled. */
|
|
31
|
+
export declare function login(options: LoginOptions): Promise<number>;
|
|
32
|
+
/** Deletes the key file and says whether there was one. */
|
|
33
|
+
export declare function logout(options?: Pick<LoginOptions, "output" | keyof ConfigPlatform>): Promise<void>;
|
|
34
|
+
export {};
|
package/dist/login.js
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
// A finder's `login` and `logout` commands: Jev's key saved to, or deleted from, the key file in the
|
|
2
|
+
// per-user config folder (key-file.ts). On a terminal, login asks for the key in raw mode and
|
|
3
|
+
// echoes nothing, on Windows, macOS and Linux alike. From a pipe (`echo key | … login`) it reads
|
|
4
|
+
// one line. It checks the key with TypeSafe by listing the account's models, which asks Jev
|
|
5
|
+
// nothing and costs no tokens, and saves it unless TypeSafe refuses it; when TypeSafe can't be
|
|
6
|
+
// reached, it saves it unchecked and says so. Nothing they print holds the key.
|
|
7
|
+
import { createInterface } from "node:readline";
|
|
8
|
+
import { StringDecoder } from "node:string_decoder";
|
|
9
|
+
import { AuthenticationError, PermissionDeniedError, TypeSafeClient } from "@typesafe-ai/sdk";
|
|
10
|
+
import { keyFile, removeKeyFile, saveKeyFile } from "./key-file.js";
|
|
11
|
+
import { npxHint } from "@team-antioch/sc2-asset-catalog/util/npx.js";
|
|
12
|
+
/** Checks a key by listing the account's models (GET /v1/models): no Jev request, no tokens. */
|
|
13
|
+
export function typesafeKeyCheck({ fetch } = {}) {
|
|
14
|
+
return async (key) => {
|
|
15
|
+
try {
|
|
16
|
+
const client = new TypeSafeClient({ apiKey: key, logLevel: "off", timeout: 10_000, retry: { maxRetries: 0 }, ...(fetch ? { fetch } : {}) });
|
|
17
|
+
await client.models.list();
|
|
18
|
+
return { ok: true };
|
|
19
|
+
}
|
|
20
|
+
catch (error) {
|
|
21
|
+
const refused = error instanceof AuthenticationError || error instanceof PermissionDeniedError;
|
|
22
|
+
return { ok: false, refused, reason: error instanceof Error ? error.message : String(error) };
|
|
23
|
+
}
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
const CANCELLED = Symbol("cancelled");
|
|
27
|
+
/** Reads what is typed until Enter, in raw mode so nothing is echoed. Ctrl-C cancels. */
|
|
28
|
+
function readHidden(input) {
|
|
29
|
+
return new Promise((resolve, reject) => {
|
|
30
|
+
const decoder = new StringDecoder("utf8");
|
|
31
|
+
let typed = "";
|
|
32
|
+
const finish = (result) => {
|
|
33
|
+
input.removeListener("data", onData);
|
|
34
|
+
input.removeListener("end", onEnd);
|
|
35
|
+
input.removeListener("error", finish);
|
|
36
|
+
input.setRawMode?.(false);
|
|
37
|
+
input.pause();
|
|
38
|
+
if (result instanceof Error)
|
|
39
|
+
reject(result);
|
|
40
|
+
else
|
|
41
|
+
resolve(result);
|
|
42
|
+
};
|
|
43
|
+
const onEnd = () => finish(typed);
|
|
44
|
+
const onData = (chunk) => {
|
|
45
|
+
let text = typeof chunk === "string" ? chunk : decoder.write(chunk);
|
|
46
|
+
while (text) {
|
|
47
|
+
// Escape sequences (arrow keys, bracketed-paste marks) are dropped whole; an unfinished
|
|
48
|
+
// one, or a lone Esc, is dropped by itself, so what follows still counts.
|
|
49
|
+
const escape = /^\x1b(?:\[[0-?]*[ -/]*[@-~]|O[@-~])?/.exec(text);
|
|
50
|
+
if (escape) {
|
|
51
|
+
text = text.slice(escape[0].length);
|
|
52
|
+
if (escape[0] === "\x1b")
|
|
53
|
+
text = text.replace(/^\[[0-?]*[ -/]*$/, "");
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
const char = text[0];
|
|
57
|
+
text = text.slice(1);
|
|
58
|
+
if (char === "\r" || char === "\n" || char === "\x04")
|
|
59
|
+
return finish(typed);
|
|
60
|
+
if (char === "\x03")
|
|
61
|
+
return finish(CANCELLED);
|
|
62
|
+
if (char === "\x7f" || char === "\b")
|
|
63
|
+
typed = [...typed].slice(0, -1).join("");
|
|
64
|
+
else if (char >= " ")
|
|
65
|
+
typed += char;
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
input.setRawMode?.(true);
|
|
69
|
+
input.on("data", onData);
|
|
70
|
+
input.once("end", onEnd);
|
|
71
|
+
input.once("error", finish);
|
|
72
|
+
input.resume();
|
|
73
|
+
});
|
|
74
|
+
}
|
|
75
|
+
/** Reads one line from a pipe; an input that ends with none gives "". */
|
|
76
|
+
function readLine(input) {
|
|
77
|
+
return new Promise((resolve, reject) => {
|
|
78
|
+
const lines = createInterface({ input, terminal: false, crlfDelay: Infinity });
|
|
79
|
+
let line;
|
|
80
|
+
lines.once("line", (first) => {
|
|
81
|
+
line = first;
|
|
82
|
+
lines.close();
|
|
83
|
+
});
|
|
84
|
+
lines.once("close", () => resolve(line ?? ""));
|
|
85
|
+
input.once("error", reject);
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
/** Asks for the key, checks it and saves it. Returns the exit code: 0 saved, 1 not, 130 cancelled. */
|
|
89
|
+
export async function login(options) {
|
|
90
|
+
const input = options.input ?? process.stdin;
|
|
91
|
+
const output = options.output ?? process.stdout;
|
|
92
|
+
const say = (line) => void output.write(`${line}\n`);
|
|
93
|
+
const env = options.env ?? process.env;
|
|
94
|
+
let read;
|
|
95
|
+
if (input.isTTY && input.setRawMode) {
|
|
96
|
+
say("Paste your TypeSafe API key and press Enter. Nothing shows as you type or paste.");
|
|
97
|
+
output.write("TypeSafe API key: ");
|
|
98
|
+
read = await readHidden(input);
|
|
99
|
+
output.write("\n");
|
|
100
|
+
}
|
|
101
|
+
else {
|
|
102
|
+
if (output.isTTY)
|
|
103
|
+
say(`The input isn't a terminal, so the key will show as you paste it. Pipe it in instead: \`echo <key> | ${npxHint(`${options.command} login`)}\`. Or paste it and press Enter:`);
|
|
104
|
+
read = await readLine(input);
|
|
105
|
+
}
|
|
106
|
+
if (read === CANCELLED)
|
|
107
|
+
return say("Cancelled: nothing was saved."), 130;
|
|
108
|
+
const key = read.trim();
|
|
109
|
+
if (!key)
|
|
110
|
+
return say("No key given, so nothing was saved."), 1;
|
|
111
|
+
// Printable ASCII with no spaces: a key pasted with quotes or a stray character is refused here,
|
|
112
|
+
// before it is sent anywhere or saved.
|
|
113
|
+
if (!/^[!-~]+$/.test(key))
|
|
114
|
+
return say("That doesn't look like a TypeSafe key: it has spaces or characters a key can't have. Nothing was saved."), 1;
|
|
115
|
+
const hide = (text) => text.split(key).join("[the key]");
|
|
116
|
+
const checked = await (options.check ?? typesafeKeyCheck())(key);
|
|
117
|
+
if (!checked.ok && checked.refused) {
|
|
118
|
+
say(hide(`TypeSafe refused the key (${checked.reason}), so it wasn't saved. Check the key and run login again.`));
|
|
119
|
+
return 1;
|
|
120
|
+
}
|
|
121
|
+
await saveKeyFile(key, options);
|
|
122
|
+
const file = keyFile(options);
|
|
123
|
+
say(checked.ok ? `TypeSafe accepted the key. Saved it to ${file}.` : hide(`Saved the key to ${file}, but couldn't check it: ${checked.reason}`));
|
|
124
|
+
say(`The Finder ranks with Jev from its next start. \`${npxHint(`${options.command} logout`)}\` deletes the key.`);
|
|
125
|
+
if (env.TYPESAFE_API_KEY?.trim())
|
|
126
|
+
say("TYPESAFE_API_KEY is set here too, and while it is set it wins over the saved key.");
|
|
127
|
+
return 0;
|
|
128
|
+
}
|
|
129
|
+
/** Deletes the key file and says whether there was one. */
|
|
130
|
+
export async function logout(options = {}) {
|
|
131
|
+
const output = options.output ?? process.stdout;
|
|
132
|
+
const say = (line) => void output.write(`${line}\n`);
|
|
133
|
+
const file = keyFile(options);
|
|
134
|
+
say((await removeKeyFile(options)) ? `Deleted the saved TypeSafe key (${file}).` : `No saved TypeSafe key to delete (${file}).`);
|
|
135
|
+
if ((options.env ?? process.env).TYPESAFE_API_KEY?.trim())
|
|
136
|
+
say("TYPESAFE_API_KEY is still set here, so the Finder still ranks with Jev until it is unset.");
|
|
137
|
+
}
|
package/dist/narrow.d.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { FinderCard, Tag } from "./card.ts";
|
|
2
|
+
import type { Neighbour } from "./embedding-index.ts";
|
|
3
|
+
export type { Tag } from "./card.ts";
|
|
4
|
+
export type Narrowed<C extends FinderCard = FinderCard> = {
|
|
5
|
+
readonly id: string;
|
|
6
|
+
readonly card: C;
|
|
7
|
+
/** Its place among the keyword results, provided first, then by words matched (1 is first). */
|
|
8
|
+
readonly keyword?: number;
|
|
9
|
+
/** Its place among the nearest cards (1 is nearest). */
|
|
10
|
+
readonly embeddings?: number;
|
|
11
|
+
/** The merge's score: higher first. */
|
|
12
|
+
readonly score: number;
|
|
13
|
+
};
|
|
14
|
+
export type MergeOptions<C extends FinderCard = FinderCard> = {
|
|
15
|
+
/** At most this many (200 by default). */
|
|
16
|
+
readonly limit?: number;
|
|
17
|
+
readonly tags?: readonly Tag[];
|
|
18
|
+
/** Whether a tag matches a card: the finder's facets. */
|
|
19
|
+
readonly tagMatches: (card: C, tag: Tag) => boolean;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* A search's matches with the ones the map's dependencies provide first, each part in the
|
|
23
|
+
* search's order, cut to n: the search's rule for a map's dependencies. Without them no card is
|
|
24
|
+
* provided, so it is the search's order.
|
|
25
|
+
*/
|
|
26
|
+
export declare function providedFirst<T extends {
|
|
27
|
+
readonly id: string;
|
|
28
|
+
}>(matches: readonly T[], cards: ReadonlyMap<string, FinderCard>, n: number): T[];
|
|
29
|
+
/**
|
|
30
|
+
* The keyword results and nearest cards as one list, each once, cut to the limit: each list's
|
|
31
|
+
* places, in the order its search gave them, count by reciprocal rank, and every unpinned tag a
|
|
32
|
+
* candidate matches raises it. Candidates a pinned tag doesn't match are left out, as are ids
|
|
33
|
+
* with no card.
|
|
34
|
+
*/
|
|
35
|
+
export declare function mergeNarrowing<C extends FinderCard>(keyword: readonly {
|
|
36
|
+
readonly id: string;
|
|
37
|
+
}[], nearest: readonly Neighbour[], cards: ReadonlyMap<string, C>, options: MergeOptions<C>): Narrowed<C>[];
|
|
38
|
+
/**
|
|
39
|
+
* What the ranker can be handed: a budget in whatever unit `cost` counts (Jev's is input tokens,
|
|
40
|
+
* docs/adr/0002), and what one card costs of it.
|
|
41
|
+
*/
|
|
42
|
+
export type RankBudget<C extends FinderCard = FinderCard> = {
|
|
43
|
+
readonly limit: number;
|
|
44
|
+
readonly cost: (card: C) => number;
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* The candidates the ranker is handed: the best-first list cut to the longest start of it that costs
|
|
48
|
+
* no more than the budget (at least one stays). The list is already the two searches' places
|
|
49
|
+
* merged by reciprocal rank, so what is cut is the tail of both searches alternately, never one
|
|
50
|
+
* list's whole tail; and a map's provided cards come first in each search, so they are last to go.
|
|
51
|
+
* `cost` is what the kept candidates cost; `cut` how many were dropped.
|
|
52
|
+
*/
|
|
53
|
+
export declare function fitToBudget<C extends FinderCard>(candidates: readonly Narrowed<C>[], budget: RankBudget<C>): {
|
|
54
|
+
readonly kept: Narrowed<C>[];
|
|
55
|
+
readonly cut: number;
|
|
56
|
+
readonly cost: number;
|
|
57
|
+
};
|
package/dist/narrow.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
// The finder kit's narrowing merge (docs/adr/0001): a finder's keyword results and its nearest cards
|
|
2
|
+
// by embedding, merged without duplicates into about 200. Each search takes its hundred with the
|
|
3
|
+
// map's provided cards first among its matches, so they aren't cut before the ranker sees them;
|
|
4
|
+
// being provided adds nothing outside the two searches' matches. Tags raise the candidates they
|
|
5
|
+
// match; a pinned tag keeps only those it matches. What a tag matches is the finder's: it passes
|
|
6
|
+
// `tagMatches`.
|
|
7
|
+
/** The reciprocal-rank constant: how much a list's first place outweighs its tenth. */
|
|
8
|
+
const RANK_K = 60;
|
|
9
|
+
/** What a matching tag adds: about what a keyword rank near the top adds. */
|
|
10
|
+
const TAG_RAISE = 1 / RANK_K;
|
|
11
|
+
const DEFAULT_LIMIT = 200;
|
|
12
|
+
/**
|
|
13
|
+
* A search's matches with the ones the map's dependencies provide first, each part in the
|
|
14
|
+
* search's order, cut to n: the search's rule for a map's dependencies. Without them no card is
|
|
15
|
+
* provided, so it is the search's order.
|
|
16
|
+
*/
|
|
17
|
+
export function providedFirst(matches, cards, n) {
|
|
18
|
+
const provided = matches.filter(({ id }) => cards.get(id)?.provided === true);
|
|
19
|
+
const rest = matches.filter(({ id }) => cards.get(id)?.provided !== true);
|
|
20
|
+
return [...provided, ...rest].slice(0, n);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The keyword results and nearest cards as one list, each once, cut to the limit: each list's
|
|
24
|
+
* places, in the order its search gave them, count by reciprocal rank, and every unpinned tag a
|
|
25
|
+
* candidate matches raises it. Candidates a pinned tag doesn't match are left out, as are ids
|
|
26
|
+
* with no card.
|
|
27
|
+
*/
|
|
28
|
+
export function mergeNarrowing(keyword, nearest, cards, options) {
|
|
29
|
+
const { tagMatches } = options;
|
|
30
|
+
const tags = options.tags ?? [];
|
|
31
|
+
const pinned = tags.filter((tag) => tag.pinned);
|
|
32
|
+
const raising = tags.filter((tag) => !tag.pinned);
|
|
33
|
+
const merged = new Map();
|
|
34
|
+
const add = (id, field, place) => {
|
|
35
|
+
const card = cards.get(id);
|
|
36
|
+
if (!card || !pinned.every((tag) => tagMatches(card, tag)))
|
|
37
|
+
return;
|
|
38
|
+
const known = merged.get(id) ?? { card };
|
|
39
|
+
known[field] ??= place;
|
|
40
|
+
merged.set(id, known);
|
|
41
|
+
};
|
|
42
|
+
keyword.forEach(({ id }, i) => add(id, "keyword", i + 1));
|
|
43
|
+
nearest.forEach(({ id }, i) => add(id, "embeddings", i + 1));
|
|
44
|
+
const scored = [...merged].map(([id, { card, ...places }]) => {
|
|
45
|
+
let score = 0;
|
|
46
|
+
if (places.keyword !== undefined)
|
|
47
|
+
score += 1 / (RANK_K + places.keyword);
|
|
48
|
+
if (places.embeddings !== undefined)
|
|
49
|
+
score += 1 / (RANK_K + places.embeddings);
|
|
50
|
+
score += TAG_RAISE * raising.filter((tag) => tagMatches(card, tag)).length;
|
|
51
|
+
return { id, card, ...places, score };
|
|
52
|
+
});
|
|
53
|
+
scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
|
|
54
|
+
return scored.slice(0, options.limit ?? DEFAULT_LIMIT);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The candidates the ranker is handed: the best-first list cut to the longest start of it that costs
|
|
58
|
+
* no more than the budget (at least one stays). The list is already the two searches' places
|
|
59
|
+
* merged by reciprocal rank, so what is cut is the tail of both searches alternately, never one
|
|
60
|
+
* list's whole tail; and a map's provided cards come first in each search, so they are last to go.
|
|
61
|
+
* `cost` is what the kept candidates cost; `cut` how many were dropped.
|
|
62
|
+
*/
|
|
63
|
+
export function fitToBudget(candidates, budget) {
|
|
64
|
+
let cost = 0;
|
|
65
|
+
let kept = 0;
|
|
66
|
+
for (const { card } of candidates) {
|
|
67
|
+
const next = cost + budget.cost(card);
|
|
68
|
+
if (next > budget.limit && kept > 0)
|
|
69
|
+
break;
|
|
70
|
+
cost = next;
|
|
71
|
+
kept++;
|
|
72
|
+
}
|
|
73
|
+
return { kept: candidates.slice(0, kept), cut: candidates.length - kept, cost };
|
|
74
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { PayloadLog } from "./ranker.ts";
|
|
2
|
+
/** A new run's log file, named for when it started, after `prefix` (such as `finder-`). */
|
|
3
|
+
export declare const payloadLogFile: (prefix?: string, cacheDir?: string) => string;
|
|
4
|
+
/** A log that appends each entry to `file` as a line of JSON. */
|
|
5
|
+
export declare const payloadLog: (file: string) => PayloadLog;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// The ranker's payload log (docs/adr/0001): every call's exact payload and answer, a file per run in the
|
|
2
|
+
// cache folder's ranker-payloads/, so runs don't mix and old ones can be deleted whole.
|
|
3
|
+
import { appendFileSync, mkdirSync } from "node:fs";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { catalogCacheDir } from "@team-antioch/sc2-asset-catalog/catalog/catalog-dirs.js";
|
|
6
|
+
/** A new run's log file, named for when it started, after `prefix` (such as `finder-`). */
|
|
7
|
+
export const payloadLogFile = (prefix = "", cacheDir = catalogCacheDir()) => path.join(cacheDir, "ranker-payloads", `${prefix}${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`);
|
|
8
|
+
/** A log that appends each entry to `file` as a line of JSON. */
|
|
9
|
+
export const payloadLog = (file) => (entry) => {
|
|
10
|
+
mkdirSync(path.dirname(file), { recursive: true });
|
|
11
|
+
appendFileSync(file, `${JSON.stringify(entry)}\n`);
|
|
12
|
+
};
|