@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.
- 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
package/dist/ranker.d.ts
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { FinderCard, Tag } from "./card.ts";
|
|
2
|
+
/** The ranker's name, as the page and the test command name it. */
|
|
3
|
+
export type RankerName = "jev";
|
|
4
|
+
export type RankRequest<C extends FinderCard = FinderCard> = {
|
|
5
|
+
readonly ask: string;
|
|
6
|
+
/** The object the ask is a part of, once the mapper has named one. */
|
|
7
|
+
readonly object?: string | undefined;
|
|
8
|
+
readonly tags?: readonly Tag[] | undefined;
|
|
9
|
+
readonly candidates: readonly C[];
|
|
10
|
+
};
|
|
11
|
+
/** A candidate's grade: a level from 0 to 3, which Jev gives as an expected value between levels. */
|
|
12
|
+
export type Grade = {
|
|
13
|
+
readonly level: number;
|
|
14
|
+
/** Jev's probability for each level, 0 to 3. */
|
|
15
|
+
readonly probabilities?: readonly number[];
|
|
16
|
+
};
|
|
17
|
+
export type Usage = {
|
|
18
|
+
readonly input: number;
|
|
19
|
+
readonly output: number;
|
|
20
|
+
readonly cacheRead?: number;
|
|
21
|
+
readonly cacheWrite?: number;
|
|
22
|
+
};
|
|
23
|
+
export type Ranking = {
|
|
24
|
+
readonly ranker: RankerName;
|
|
25
|
+
/** The model that answered, as its API names it. */
|
|
26
|
+
readonly model: string;
|
|
27
|
+
/** A grade for every candidate's id. */
|
|
28
|
+
readonly grades: ReadonlyMap<string, Grade>;
|
|
29
|
+
/** Milliseconds: the API call, and the whole ranking with building the request and reading the answer. */
|
|
30
|
+
readonly timings: {
|
|
31
|
+
readonly request: number;
|
|
32
|
+
readonly total: number;
|
|
33
|
+
};
|
|
34
|
+
readonly usage: Usage;
|
|
35
|
+
/** US dollars, estimated from the usage at the ranker's list prices. */
|
|
36
|
+
readonly cost: number;
|
|
37
|
+
};
|
|
38
|
+
export type RankOptions = {
|
|
39
|
+
readonly signal?: AbortSignal;
|
|
40
|
+
};
|
|
41
|
+
export interface Ranker<C extends FinderCard = FinderCard> {
|
|
42
|
+
readonly name: RankerName;
|
|
43
|
+
rank(request: RankRequest<C>, options?: RankOptions): Promise<Ranking>;
|
|
44
|
+
}
|
|
45
|
+
/** One call's exact payload, as sent, and what came back, for the log. No credential is in either. */
|
|
46
|
+
export type PayloadEntry = {
|
|
47
|
+
readonly ranker: RankerName;
|
|
48
|
+
readonly at: string;
|
|
49
|
+
readonly ms: number;
|
|
50
|
+
readonly request: unknown;
|
|
51
|
+
readonly response?: unknown;
|
|
52
|
+
readonly error?: string;
|
|
53
|
+
};
|
|
54
|
+
export type PayloadLog = (entry: PayloadEntry) => void;
|
|
55
|
+
/**
|
|
56
|
+
* A ranker's call failed or its answer can't be read: the ask has no ranking, not low grades.
|
|
57
|
+
* `cost` is what the call cost when it was answered (and so paid for) but couldn't be read.
|
|
58
|
+
*/
|
|
59
|
+
export declare class RankerError extends Error {
|
|
60
|
+
readonly ranker: RankerName;
|
|
61
|
+
readonly cost: number;
|
|
62
|
+
constructor(ranker: RankerName, message: string, options?: ErrorOptions & {
|
|
63
|
+
readonly cost?: number;
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
/** A tag as the rankers read it: `story: industry`. */
|
|
67
|
+
export declare const tagText: (tag: Tag) => string;
|
|
68
|
+
/** How far below a candidate an already-provided one can grade and still come first. */
|
|
69
|
+
export declare const PROVIDED_RAISE = 0.25;
|
|
70
|
+
/**
|
|
71
|
+
* The narrowed candidates in the ranker's order: fit first, an already-provided card first over
|
|
72
|
+
* any that grades no more than 0.25 above it, then the narrowing's order. Every candidate needs a
|
|
73
|
+
* grade.
|
|
74
|
+
*/
|
|
75
|
+
export declare function orderByFit<T extends {
|
|
76
|
+
readonly id: string;
|
|
77
|
+
readonly card: FinderCard;
|
|
78
|
+
}>(narrowed: readonly T[], grades: ReadonlyMap<string, Grade>): (T & {
|
|
79
|
+
readonly level: number;
|
|
80
|
+
})[];
|
package/dist/ranker.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// The finder kit's ranker slot (docs/adr/0001): a ranker grades each narrowed candidate against the
|
|
2
|
+
// ask on four levels (a finder's wording), and the finder orders the candidates by those levels. Jev
|
|
3
|
+
// (jev-ranker.ts) fills the slot; the slot stays internal, for tests' fakes. A failed call is an
|
|
4
|
+
// error, never a low level.
|
|
5
|
+
/**
|
|
6
|
+
* A ranker's call failed or its answer can't be read: the ask has no ranking, not low grades.
|
|
7
|
+
* `cost` is what the call cost when it was answered (and so paid for) but couldn't be read.
|
|
8
|
+
*/
|
|
9
|
+
export class RankerError extends Error {
|
|
10
|
+
ranker;
|
|
11
|
+
cost;
|
|
12
|
+
constructor(ranker, message, options) {
|
|
13
|
+
super(`${ranker}: ${message}`, options);
|
|
14
|
+
this.name = "RankerError";
|
|
15
|
+
this.ranker = ranker;
|
|
16
|
+
this.cost = options?.cost ?? 0;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
/** A tag as the rankers read it: `story: industry`. */
|
|
20
|
+
export const tagText = (tag) => `${tag.facet}: ${tag.value}`;
|
|
21
|
+
/** How far below a candidate an already-provided one can grade and still come first. */
|
|
22
|
+
export const PROVIDED_RAISE = 0.25;
|
|
23
|
+
/**
|
|
24
|
+
* The narrowed candidates in the ranker's order: fit first, an already-provided card first over
|
|
25
|
+
* any that grades no more than 0.25 above it, then the narrowing's order. Every candidate needs a
|
|
26
|
+
* grade.
|
|
27
|
+
*/
|
|
28
|
+
export function orderByFit(narrowed, grades) {
|
|
29
|
+
const keyed = narrowed.map((candidate, place) => {
|
|
30
|
+
const grade = grades.get(candidate.id);
|
|
31
|
+
if (!grade)
|
|
32
|
+
throw new Error(`No grade for ${candidate.id}`);
|
|
33
|
+
const provided = candidate.card.provided === true;
|
|
34
|
+
return { candidate: { ...candidate, level: grade.level }, key: grade.level + (provided ? PROVIDED_RAISE : 0), provided, place };
|
|
35
|
+
});
|
|
36
|
+
// Keys within a hair of each other are equal: 1.89 + 0.25 falls just short of 2.14 in floating point.
|
|
37
|
+
const fit = (a, b) => (Math.abs(b.key - a.key) < 1e-9 ? 0 : b.key - a.key);
|
|
38
|
+
keyed.sort((a, b) => fit(a, b) || Number(b.provided) - Number(a.provided) || a.place - b.place);
|
|
39
|
+
return keyed.map(({ candidate }) => candidate);
|
|
40
|
+
}
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import { type IncomingMessage, type ServerResponse } from "node:http";
|
|
2
|
+
import { type AskTiming } from "./asker.ts";
|
|
3
|
+
import type { FinderCard, ObjectTag, Tag, TagChoice, TagChoices } from "./card.ts";
|
|
4
|
+
import type { KeySource } from "./credentials.ts";
|
|
5
|
+
import type { NarrowOptions, Narrowing } from "./finder.ts";
|
|
6
|
+
import type { Ranker, RankerName } from "./ranker.ts";
|
|
7
|
+
import type { FinderSettings } from "./settings.ts";
|
|
8
|
+
import type { SpendCap } from "./spend-cap.ts";
|
|
9
|
+
import { type CopyText, type TrayItem } from "./tray.ts";
|
|
10
|
+
/**
|
|
11
|
+
* Badges for a choice the page offers, such as a project's maps: with one chosen, the cards
|
|
12
|
+
* its dependencies provide say so, and come first. With no choice, a card says the package it needs.
|
|
13
|
+
*/
|
|
14
|
+
export type Badges = {
|
|
15
|
+
/** What the choice is called on the page, such as "Map". */
|
|
16
|
+
readonly label: string;
|
|
17
|
+
readonly choices: readonly string[];
|
|
18
|
+
/** The badge of a card the chosen one provides, such as "in this map". */
|
|
19
|
+
readonly provided: string;
|
|
20
|
+
dependenciesOf(choice: string): Promise<readonly string[]>;
|
|
21
|
+
};
|
|
22
|
+
/** A field a tray action asks for before it runs. */
|
|
23
|
+
export type TrayActionInput = {
|
|
24
|
+
readonly name: string;
|
|
25
|
+
readonly label: string;
|
|
26
|
+
readonly placeholder?: string;
|
|
27
|
+
readonly required?: boolean;
|
|
28
|
+
};
|
|
29
|
+
export type TrayActionContext = {
|
|
30
|
+
readonly items: readonly TrayItem[];
|
|
31
|
+
/** The badges' choice, if any. */
|
|
32
|
+
readonly choice: string | undefined;
|
|
33
|
+
readonly inputs: Readonly<Record<string, string>>;
|
|
34
|
+
/** The open object, as last saved, when there is one. */
|
|
35
|
+
readonly object?: TrayObject | undefined;
|
|
36
|
+
/** The ranker's levels for an ask's cards, ranked now if it wasn't: rejects with no ranker, or past the spend cap. */
|
|
37
|
+
levels(ask: string, tags: readonly Tag[]): Promise<ReadonlyMap<string, number>>;
|
|
38
|
+
};
|
|
39
|
+
export type TrayActionResult = {
|
|
40
|
+
/** Shown on the page. */
|
|
41
|
+
readonly message: string;
|
|
42
|
+
/** Text for the mapper to take away, shown selected when `copied` isn't true. */
|
|
43
|
+
readonly text?: string;
|
|
44
|
+
readonly copied?: boolean;
|
|
45
|
+
/** Empties the tray afterwards: what it held is handed over. */
|
|
46
|
+
readonly clearTray?: boolean;
|
|
47
|
+
/** Puts the open object away afterwards, emptying the tray. */
|
|
48
|
+
readonly putAway?: boolean;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* For sc2-adjutant, may change: an object the tray is kept for, such as one of sc2-adjutant's searches. Its
|
|
52
|
+
* title is context for the ranker, and its ticks and lines are saved on every change, so a tick
|
|
53
|
+
* from it carries the ranker's level.
|
|
54
|
+
*/
|
|
55
|
+
export type TrayObject = {
|
|
56
|
+
/** What it is reopened by. */
|
|
57
|
+
readonly key: string;
|
|
58
|
+
readonly title: string;
|
|
59
|
+
/** The badges' choice it is for (its map): the page's choice while it is open. */
|
|
60
|
+
readonly choice?: string | undefined;
|
|
61
|
+
readonly ticks: readonly ObjectTick[];
|
|
62
|
+
/** Each ask's line, where the mapper edited it from the ask as typed. */
|
|
63
|
+
readonly lines: Readonly<Record<string, string>>;
|
|
64
|
+
/** The tags to pin when it is opened: for a reopened one, those its asks ran pinned with. */
|
|
65
|
+
readonly pinned?: readonly TagChoice[];
|
|
66
|
+
};
|
|
67
|
+
/** A tick kept with an object: the ask it came from, that ask's tags, and the ranker's level for it there. */
|
|
68
|
+
export type ObjectTick = {
|
|
69
|
+
readonly id: string;
|
|
70
|
+
readonly ask: string;
|
|
71
|
+
readonly tags: readonly Tag[];
|
|
72
|
+
readonly level: number;
|
|
73
|
+
};
|
|
74
|
+
/** An object that can be reopened, as the page lists it. */
|
|
75
|
+
export type UnfinishedObject = {
|
|
76
|
+
readonly key: string;
|
|
77
|
+
readonly title: string;
|
|
78
|
+
readonly choice?: string | undefined;
|
|
79
|
+
readonly ticked: number;
|
|
80
|
+
};
|
|
81
|
+
/** For sc2-adjutant, may change: where the tray's objects come from and are kept. */
|
|
82
|
+
export type TrayObjects = {
|
|
83
|
+
/** What one is called on the page: "Object". */
|
|
84
|
+
readonly label: string;
|
|
85
|
+
readonly placeholder?: string;
|
|
86
|
+
/** A new one, for the badges' choice; rejects a title it can't take. */
|
|
87
|
+
start(title: string, choice: string | undefined): Promise<TrayObject>;
|
|
88
|
+
/** The ones that can be reopened. */
|
|
89
|
+
unfinished(): Promise<readonly UnfinishedObject[]>;
|
|
90
|
+
reopen(key: string): Promise<TrayObject>;
|
|
91
|
+
/** Keeps its ticks and lines as they are now: on every tick, untick, clear and line edit. */
|
|
92
|
+
save(object: TrayObject): Promise<void>;
|
|
93
|
+
};
|
|
94
|
+
/** A button on the tray that hands its cards to something else, such as one of sc2-adjutant's. */
|
|
95
|
+
export type TrayAction = {
|
|
96
|
+
readonly label: string;
|
|
97
|
+
readonly title?: string;
|
|
98
|
+
readonly inputs?: readonly TrayActionInput[];
|
|
99
|
+
run(context: TrayActionContext): Promise<TrayActionResult>;
|
|
100
|
+
};
|
|
101
|
+
/** The request a finder's own route is asked to answer: false when the route isn't one of its own. */
|
|
102
|
+
export type FinderRoute = (url: URL, request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
|
|
103
|
+
/** What differs between finders: the server asks it for each. */
|
|
104
|
+
export type FinderKind<C extends FinderCard> = {
|
|
105
|
+
/** What /status calls the finder, so a caller can tell one from anything else on a port: `doodad-finder`. */
|
|
106
|
+
readonly name: string;
|
|
107
|
+
/** What a card is, for a refusal that names one: `doodad`. */
|
|
108
|
+
readonly noun: string;
|
|
109
|
+
/** The page. */
|
|
110
|
+
page(): string;
|
|
111
|
+
/** A level's short name, for the cards and the tray. */
|
|
112
|
+
levelName(level: number): string;
|
|
113
|
+
/** Each card's markup for the page, in order, with its tick box; `provided` is the badges' text for a card a choice provides. */
|
|
114
|
+
renderCards(cards: readonly C[], provided: string | undefined): string[];
|
|
115
|
+
/** The tags the ticked cards give, with the mapper's pinned and dropped choices (docs/adr/0001). */
|
|
116
|
+
tags(ticked: readonly C[], choices: TagChoices): ObjectTag[];
|
|
117
|
+
/** What a click on copy puts on the clipboard. */
|
|
118
|
+
readonly copy: CopyText;
|
|
119
|
+
/** GET routes of its own, tried after the kit's; true when it answered. */
|
|
120
|
+
route?: FinderRoute;
|
|
121
|
+
/** Called when the server closes, to let go of what it kept. */
|
|
122
|
+
close?(): void;
|
|
123
|
+
};
|
|
124
|
+
export type FinderServerOptions<C extends FinderCard> = {
|
|
125
|
+
readonly kind: FinderKind<C>;
|
|
126
|
+
readonly finder: {
|
|
127
|
+
narrow(ask: string, options?: NarrowOptions): Promise<Narrowing<C>>;
|
|
128
|
+
readonly cards: ReadonlyMap<string, C>;
|
|
129
|
+
};
|
|
130
|
+
readonly ranker?: Ranker | undefined;
|
|
131
|
+
/** Why there is no ranker: shown on the page. */
|
|
132
|
+
readonly off?: string | undefined;
|
|
133
|
+
/** Where the ranker's key came from, for /status to say: never the key. */
|
|
134
|
+
readonly keySource?: KeySource | undefined;
|
|
135
|
+
/** The session's spend cap. */
|
|
136
|
+
readonly budget?: SpendCap;
|
|
137
|
+
readonly badges?: Badges | undefined;
|
|
138
|
+
readonly trayActions?: readonly TrayAction[];
|
|
139
|
+
/** For sc2-adjutant, may change: objects the tray can be kept for. None by default. */
|
|
140
|
+
readonly objects?: TrayObjects | undefined;
|
|
141
|
+
/** The tick log's file for a choice; no tick log when left out. */
|
|
142
|
+
readonly tickLog?: ((choice: string | undefined) => string) | undefined;
|
|
143
|
+
readonly settings?: FinderSettings;
|
|
144
|
+
/** Where the settings are kept; not written when left out. */
|
|
145
|
+
readonly saveSettings?: (settings: FinderSettings) => Promise<void>;
|
|
146
|
+
readonly timing?: Partial<AskTiming>;
|
|
147
|
+
readonly port?: number;
|
|
148
|
+
/** More for /status to say. */
|
|
149
|
+
readonly status?: Readonly<Record<string, unknown>>;
|
|
150
|
+
/** Lines worth showing the user as the Finder runs, such as a failed ranking. */
|
|
151
|
+
readonly log?: (line: string) => void;
|
|
152
|
+
};
|
|
153
|
+
export type FinderServer = {
|
|
154
|
+
readonly url: string;
|
|
155
|
+
/** US dollars the ranker's calls have cost since the process started, estimated. */
|
|
156
|
+
readonly spend: number;
|
|
157
|
+
close(): Promise<void>;
|
|
158
|
+
};
|
|
159
|
+
/** A failed ask in words, the same on the page and in the log. */
|
|
160
|
+
export declare const failureText: ({ error, narrowed }: {
|
|
161
|
+
readonly error: string;
|
|
162
|
+
readonly narrowed: boolean;
|
|
163
|
+
}) => string;
|
|
164
|
+
/** A tick log's line: the ask, its tags and the ids in the tray ticked from it, in the order ticked. */
|
|
165
|
+
export type TickLogLine = {
|
|
166
|
+
readonly ask: string;
|
|
167
|
+
readonly tags: readonly Tag[];
|
|
168
|
+
readonly ticked: readonly string[];
|
|
169
|
+
readonly object?: string;
|
|
170
|
+
readonly ranker?: RankerName;
|
|
171
|
+
readonly at: string;
|
|
172
|
+
};
|
|
173
|
+
/** An answer that is an error: its status and what the page is told. A finder's own route throws it too. */
|
|
174
|
+
export declare class HttpError extends Error {
|
|
175
|
+
readonly status: number;
|
|
176
|
+
constructor(status: number, message: string);
|
|
177
|
+
}
|
|
178
|
+
export declare function startFinderServer<C extends FinderCard>(options: FinderServerOptions<C>): Promise<FinderServer>;
|