pi-braid 0.43.6 → 0.43.8
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/CHANGELOG.md +83 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
- package/dist/extensions/core/skills-tool/applicability.js +161 -0
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +31 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +320 -1
- package/dist/extensions/core/skills-tool/index.js +83 -4
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +6 -2
- package/dist/extensions/core/skills-tool/session-records.d.ts +395 -8
- package/dist/extensions/core/skills-tool/session-records.js +645 -5
- package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
- package/dist/extensions/core/skills-tool/skill-families.js +105 -0
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -1
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/applicability.ts +220 -0
- package/src/extensions/core/skills-tool/auto-inject.ts +391 -0
- package/src/extensions/core/skills-tool/index.ts +96 -3
- package/src/extensions/core/skills-tool/loading-guidance.ts +6 -2
- package/src/extensions/core/skills-tool/session-records.ts +932 -5
- package/src/extensions/core/skills-tool/skill-families.ts +112 -0
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Session corpus ask - lexical retrieval over the user-turn index.
|
|
3
|
+
*
|
|
4
|
+
* BM25 over one document per user turn. At this corpus size the lexical model
|
|
5
|
+
* is the cheap, testable choice: no embedding pass to keep current, no vector
|
|
6
|
+
* store to back up, no key to spend on a query, and a score a reader can
|
|
7
|
+
* re-derive by eye from the terms it names. What would earn a vector store is
|
|
8
|
+
* a measured failure: recall@3 below the bar on questions whose answering
|
|
9
|
+
* passage is in the index (the report's falsifier is that measurement).
|
|
10
|
+
*
|
|
11
|
+
* Every hit carries its citation - project, session path, line, timestamp -
|
|
12
|
+
* because the answer is the owner's own words and a reader must be able to
|
|
13
|
+
* check them against the session file. The refusal is a first-class result: a
|
|
14
|
+
* query whose terms appear nowhere in the population says so and names what it
|
|
15
|
+
* searched, rather than returning the least bad rows.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import type { CorpusFreshness, CorpusTurn, LoadedShard } from "./corpus-index.js";
|
|
19
|
+
|
|
20
|
+
/** BM25 term-frequency saturation. */
|
|
21
|
+
export const BM25_K1 = 1.2;
|
|
22
|
+
/** BM25 length normalisation. */
|
|
23
|
+
export const BM25_B = 0.75;
|
|
24
|
+
/** Hits a query returns when the caller names no limit. */
|
|
25
|
+
export const MAX_ASK_HITS = 5;
|
|
26
|
+
/** Characters of a turn the answer prints before it trims. */
|
|
27
|
+
const PASSAGE_CHARS = 360;
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Words that carry no retrieval signal in a question about work. A fixed
|
|
31
|
+
* language table, not a project vocabulary: it holds English function words
|
|
32
|
+
* only, so a query term that names something always survives it.
|
|
33
|
+
*/
|
|
34
|
+
const STOPWORDS = new Set([
|
|
35
|
+
"a",
|
|
36
|
+
"about",
|
|
37
|
+
"after",
|
|
38
|
+
"all",
|
|
39
|
+
"also",
|
|
40
|
+
"am",
|
|
41
|
+
"an",
|
|
42
|
+
"and",
|
|
43
|
+
"any",
|
|
44
|
+
"are",
|
|
45
|
+
"as",
|
|
46
|
+
"at",
|
|
47
|
+
"be",
|
|
48
|
+
"been",
|
|
49
|
+
"before",
|
|
50
|
+
"being",
|
|
51
|
+
"both",
|
|
52
|
+
"but",
|
|
53
|
+
"by",
|
|
54
|
+
"can",
|
|
55
|
+
"could",
|
|
56
|
+
"did",
|
|
57
|
+
"do",
|
|
58
|
+
"does",
|
|
59
|
+
"doing",
|
|
60
|
+
"done",
|
|
61
|
+
"for",
|
|
62
|
+
"from",
|
|
63
|
+
"had",
|
|
64
|
+
"has",
|
|
65
|
+
"have",
|
|
66
|
+
"having",
|
|
67
|
+
"he",
|
|
68
|
+
"her",
|
|
69
|
+
"here",
|
|
70
|
+
"him",
|
|
71
|
+
"his",
|
|
72
|
+
"how",
|
|
73
|
+
"i",
|
|
74
|
+
"if",
|
|
75
|
+
"in",
|
|
76
|
+
"into",
|
|
77
|
+
"is",
|
|
78
|
+
"it",
|
|
79
|
+
"its",
|
|
80
|
+
"just",
|
|
81
|
+
"me",
|
|
82
|
+
"my",
|
|
83
|
+
"no",
|
|
84
|
+
"not",
|
|
85
|
+
"of",
|
|
86
|
+
"on",
|
|
87
|
+
"once",
|
|
88
|
+
"only",
|
|
89
|
+
"or",
|
|
90
|
+
"other",
|
|
91
|
+
"our",
|
|
92
|
+
"out",
|
|
93
|
+
"over",
|
|
94
|
+
"own",
|
|
95
|
+
"same",
|
|
96
|
+
"she",
|
|
97
|
+
"should",
|
|
98
|
+
"so",
|
|
99
|
+
"some",
|
|
100
|
+
"such",
|
|
101
|
+
"than",
|
|
102
|
+
"that",
|
|
103
|
+
"the",
|
|
104
|
+
"their",
|
|
105
|
+
"them",
|
|
106
|
+
"then",
|
|
107
|
+
"there",
|
|
108
|
+
"these",
|
|
109
|
+
"they",
|
|
110
|
+
"this",
|
|
111
|
+
"those",
|
|
112
|
+
"to",
|
|
113
|
+
"too",
|
|
114
|
+
"under",
|
|
115
|
+
"up",
|
|
116
|
+
"us",
|
|
117
|
+
"very",
|
|
118
|
+
"was",
|
|
119
|
+
"we",
|
|
120
|
+
"were",
|
|
121
|
+
"what",
|
|
122
|
+
"when",
|
|
123
|
+
"where",
|
|
124
|
+
"which",
|
|
125
|
+
"while",
|
|
126
|
+
"who",
|
|
127
|
+
"why",
|
|
128
|
+
"will",
|
|
129
|
+
"with",
|
|
130
|
+
"would",
|
|
131
|
+
"you",
|
|
132
|
+
"your",
|
|
133
|
+
]);
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Fold one token to its retrieval stem.
|
|
137
|
+
*
|
|
138
|
+
* Inflected forms of a word are one word for retrieval: a question saying
|
|
139
|
+
* "rendered" must reach a turn saying "renders", and "picks" must reach
|
|
140
|
+
* "pick". The fold is symmetric - the query and the turns pass through the
|
|
141
|
+
* same function - so a fold that is linguistically wrong ("boxes" -> "boxe")
|
|
142
|
+
* is still a fold both sides agree on. The doubled-consonant rule exists for
|
|
143
|
+
* the same reason: "hitting" must reach "hit".
|
|
144
|
+
*/
|
|
145
|
+
function foldToken(token: string): string {
|
|
146
|
+
if (token.length <= 3) return token;
|
|
147
|
+
let stem = token;
|
|
148
|
+
if (stem.endsWith("ies") && stem.length > 4) stem = `${stem.slice(0, -3)}y`;
|
|
149
|
+
else if (stem.endsWith("s") && !stem.endsWith("ss")) stem = stem.slice(0, -1);
|
|
150
|
+
if (stem.endsWith("ing") && stem.length > 5) stem = stem.slice(0, -3);
|
|
151
|
+
else if (stem.endsWith("ed") && stem.length > 4) stem = stem.slice(0, -2);
|
|
152
|
+
const last = stem.at(-1);
|
|
153
|
+
if (/[bdfglmnprt]/.test(last ?? "") && stem.at(-2) === last && stem.length > 3) {
|
|
154
|
+
stem = stem.slice(0, -1);
|
|
155
|
+
}
|
|
156
|
+
return stem;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Words a document is scored on: letter/number runs, lowercased, stemmed.
|
|
161
|
+
*
|
|
162
|
+
* A hyphen separates words: the owner's compound names ("looping-clanker",
|
|
163
|
+
* "anti-crowd") are two words a question may spell either way, and a tokenizer
|
|
164
|
+
* that keeps the compound as one token can never match its own parts.
|
|
165
|
+
*/
|
|
166
|
+
export function tokenizeForIndex(text: string): string[] {
|
|
167
|
+
const raw = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
|
|
168
|
+
const tokens: string[] = [];
|
|
169
|
+
for (const token of raw) {
|
|
170
|
+
if (token.length < 2 && !/\d/.test(token)) continue;
|
|
171
|
+
tokens.push(foldToken(token));
|
|
172
|
+
}
|
|
173
|
+
return tokens;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Query terms: the document tokens minus function words. Duplicates collapse,
|
|
178
|
+
* so a word typed twice scores once.
|
|
179
|
+
*/
|
|
180
|
+
export function askQueryTerms(query: string): string[] {
|
|
181
|
+
const seen = new Set<string>();
|
|
182
|
+
for (const token of tokenizeForIndex(query)) {
|
|
183
|
+
if (STOPWORDS.has(token)) continue;
|
|
184
|
+
seen.add(token);
|
|
185
|
+
}
|
|
186
|
+
return [...seen];
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export interface AskHit {
|
|
190
|
+
turn: CorpusTurn;
|
|
191
|
+
score: number;
|
|
192
|
+
/** Query terms this turn carries. */
|
|
193
|
+
matched: string[];
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export interface AskResult {
|
|
197
|
+
query: string;
|
|
198
|
+
/** Query terms after the function-word filter. */
|
|
199
|
+
terms: string[];
|
|
200
|
+
/** Terms that occur in the searched population. */
|
|
201
|
+
matched_terms: string[];
|
|
202
|
+
/** Terms that occur nowhere in the searched population. */
|
|
203
|
+
unmatched_terms: string[];
|
|
204
|
+
hits: AskHit[];
|
|
205
|
+
/** Whether the index could answer at all (at least one hit). */
|
|
206
|
+
answered: boolean;
|
|
207
|
+
population: {
|
|
208
|
+
turns: number;
|
|
209
|
+
sessions: number;
|
|
210
|
+
projects: string[];
|
|
211
|
+
/** Oldest and newest shard build time in the population. */
|
|
212
|
+
built_oldest: string;
|
|
213
|
+
built_newest: string;
|
|
214
|
+
shards: number;
|
|
215
|
+
};
|
|
216
|
+
freshness: CorpusFreshness;
|
|
217
|
+
filters: { project: string | null; since: string | null };
|
|
218
|
+
/** True when the caller's own session was withheld from the results. */
|
|
219
|
+
self_excluded: boolean;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
export interface AskOptions {
|
|
223
|
+
/** Project label filter; null reads every shard the store loaded. */
|
|
224
|
+
project?: string | null;
|
|
225
|
+
/** Inclusive lower bound on the turn's date (YYYY-MM-DD). */
|
|
226
|
+
since?: string | null;
|
|
227
|
+
limit?: number;
|
|
228
|
+
/** Session file never returned to itself. */
|
|
229
|
+
excludeSession?: string | null;
|
|
230
|
+
freshness: CorpusFreshness;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** BM25 score of one document against the query terms. */
|
|
234
|
+
function scoreDocument(
|
|
235
|
+
termFrequencies: Map<string, number>,
|
|
236
|
+
docLength: number,
|
|
237
|
+
averageLength: number,
|
|
238
|
+
idf: Map<string, number>,
|
|
239
|
+
): { score: number; matched: string[] } {
|
|
240
|
+
const lengthNorm = averageLength > 0 ? 1 - BM25_B + (BM25_B * docLength) / averageLength : 1;
|
|
241
|
+
let score = 0;
|
|
242
|
+
const matched: string[] = [];
|
|
243
|
+
for (const [term, frequency] of termFrequencies) {
|
|
244
|
+
const weight = idf.get(term);
|
|
245
|
+
if (weight === undefined) continue;
|
|
246
|
+
matched.push(term);
|
|
247
|
+
score += (weight * (frequency * (BM25_K1 + 1))) / (frequency + BM25_K1 * lengthNorm);
|
|
248
|
+
}
|
|
249
|
+
return { score, matched };
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Retrieve the turns that answer a question, with citations.
|
|
254
|
+
*
|
|
255
|
+
* The population searched is stated in the result, so a refusal can show what
|
|
256
|
+
* it looked at. `df` and the average document length are computed over the
|
|
257
|
+
* filtered population: an index narrowed by `--project` or `--since` is the
|
|
258
|
+
* corpus the answer claims, not a sample of a larger one it never read.
|
|
259
|
+
*/
|
|
260
|
+
export function askCorpusIndex(shards: LoadedShard[], query: string, opts: AskOptions): AskResult {
|
|
261
|
+
const terms = askQueryTerms(query);
|
|
262
|
+
const allowed = new Set(terms);
|
|
263
|
+
const candidates: CorpusTurn[] = [];
|
|
264
|
+
const projects = new Set<string>();
|
|
265
|
+
const builtAt = new Set<string>();
|
|
266
|
+
for (const shard of shards) {
|
|
267
|
+
projects.add(shard.manifest.project);
|
|
268
|
+
builtAt.add(shard.manifest.built_at);
|
|
269
|
+
for (const turn of shard.turns) {
|
|
270
|
+
if (opts.excludeSession && turn.session === opts.excludeSession) continue;
|
|
271
|
+
if (opts.since && turn.ts.slice(0, 10) < opts.since) continue;
|
|
272
|
+
candidates.push(turn);
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
const sessions = new Set<string>();
|
|
277
|
+
for (const turn of candidates) sessions.add(turn.session);
|
|
278
|
+
|
|
279
|
+
// One pass: term frequencies for the query terms, and the document's length.
|
|
280
|
+
const frequencies: Array<Map<string, number>> = new Array(candidates.length);
|
|
281
|
+
const lengths: number[] = new Array(candidates.length);
|
|
282
|
+
const documentFrequency = new Map<string, number>();
|
|
283
|
+
let totalLength = 0;
|
|
284
|
+
for (let i = 0; i < candidates.length; i++) {
|
|
285
|
+
const tokens = tokenizeForIndex((candidates[i] as CorpusTurn).text);
|
|
286
|
+
lengths[i] = tokens.length;
|
|
287
|
+
totalLength += tokens.length;
|
|
288
|
+
const counts = new Map<string, number>();
|
|
289
|
+
for (const token of tokens) {
|
|
290
|
+
if (!allowed.has(token)) continue;
|
|
291
|
+
counts.set(token, (counts.get(token) ?? 0) + 1);
|
|
292
|
+
}
|
|
293
|
+
frequencies[i] = counts;
|
|
294
|
+
for (const term of counts.keys()) {
|
|
295
|
+
documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
const total = candidates.length;
|
|
300
|
+
const averageLength = total > 0 ? totalLength / total : 0;
|
|
301
|
+
const idf = new Map<string, number>();
|
|
302
|
+
for (const [term, df] of documentFrequency) {
|
|
303
|
+
idf.set(term, Math.log(1 + (total - df + 0.5) / (df + 0.5)));
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const limit = Math.max(1, opts.limit ?? MAX_ASK_HITS);
|
|
307
|
+
const scored: AskHit[] = [];
|
|
308
|
+
for (let i = 0; i < candidates.length; i++) {
|
|
309
|
+
const counts = frequencies[i];
|
|
310
|
+
const turn = candidates[i];
|
|
311
|
+
if (!counts || !turn || counts.size === 0) continue;
|
|
312
|
+
const { score, matched } = scoreDocument(counts, lengths[i] ?? 0, averageLength, idf);
|
|
313
|
+
if (score <= 0) continue;
|
|
314
|
+
scored.push({ turn, score, matched });
|
|
315
|
+
}
|
|
316
|
+
scored.sort(
|
|
317
|
+
(a, b) =>
|
|
318
|
+
b.score - a.score ||
|
|
319
|
+
b.turn.ts.localeCompare(a.turn.ts) ||
|
|
320
|
+
a.turn.session.localeCompare(b.turn.session) ||
|
|
321
|
+
a.turn.line - b.turn.line,
|
|
322
|
+
);
|
|
323
|
+
|
|
324
|
+
const matchedTerms = terms.filter((term) => (documentFrequency.get(term) ?? 0) > 0);
|
|
325
|
+
return {
|
|
326
|
+
query,
|
|
327
|
+
terms,
|
|
328
|
+
matched_terms: matchedTerms,
|
|
329
|
+
unmatched_terms: terms.filter((term) => !matchedTerms.includes(term)),
|
|
330
|
+
hits: scored.slice(0, limit),
|
|
331
|
+
answered: scored.length > 0,
|
|
332
|
+
population: {
|
|
333
|
+
turns: total,
|
|
334
|
+
sessions: sessions.size,
|
|
335
|
+
projects: [...projects].sort(),
|
|
336
|
+
built_oldest: [...builtAt].sort()[0] ?? "",
|
|
337
|
+
built_newest: [...builtAt].sort().at(-1) ?? "",
|
|
338
|
+
shards: shards.length,
|
|
339
|
+
},
|
|
340
|
+
freshness: opts.freshness,
|
|
341
|
+
filters: { project: opts.project ?? null, since: opts.since ?? null },
|
|
342
|
+
self_excluded: Boolean(opts.excludeSession),
|
|
343
|
+
};
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** One passage, trimmed around the best-matching term. */
|
|
347
|
+
function passage(text: string, matched: string[]): string {
|
|
348
|
+
const flat = text.replace(/\s+/g, " ").trim();
|
|
349
|
+
if (flat.length <= PASSAGE_CHARS) return flat;
|
|
350
|
+
const anchor = matched.find((term) => flat.toLowerCase().includes(term)) ?? "";
|
|
351
|
+
const at = anchor ? flat.toLowerCase().indexOf(anchor) : -1;
|
|
352
|
+
if (at < 0) return `${flat.slice(0, PASSAGE_CHARS)}...`;
|
|
353
|
+
const start = Math.max(0, at - Math.floor(PASSAGE_CHARS / 3));
|
|
354
|
+
const end = Math.min(flat.length, start + PASSAGE_CHARS);
|
|
355
|
+
return `${start > 0 ? "..." : ""}${flat.slice(start, end)}${end < flat.length ? "..." : ""}`;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/** Freshness in one phrase, or null when the index is current. */
|
|
359
|
+
function freshnessNote(freshness: CorpusFreshness): string | null {
|
|
360
|
+
const parts: string[] = [];
|
|
361
|
+
if (freshness.changed > 0) parts.push(`${freshness.changed} changed`);
|
|
362
|
+
if (freshness.added > 0) parts.push(`${freshness.added} new`);
|
|
363
|
+
if (freshness.removed > 0) parts.push(`${freshness.removed} gone`);
|
|
364
|
+
if (parts.length === 0) return null;
|
|
365
|
+
const newest = freshness.newest_change ? `, newest ${freshness.newest_change}` : "";
|
|
366
|
+
return `${parts.join(", ")} session file(s) since the build${newest}; rerun the index build for them`;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function number(value: number): string {
|
|
370
|
+
return value.toLocaleString("en-US");
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* Render the answer: cited passages, or a refusal that names the population it
|
|
375
|
+
* searched and the terms it found.
|
|
376
|
+
*/
|
|
377
|
+
export function formatAskResult(result: AskResult): string {
|
|
378
|
+
const population =
|
|
379
|
+
`${number(result.population.turns)} user turns from ` +
|
|
380
|
+
`${number(result.population.sessions)} sessions across ` +
|
|
381
|
+
`${result.population.projects.length} project(s)`;
|
|
382
|
+
const built =
|
|
383
|
+
result.population.built_oldest === result.population.built_newest
|
|
384
|
+
? `built ${result.population.built_newest}`
|
|
385
|
+
: `shards built ${result.population.built_oldest} to ${result.population.built_newest}`;
|
|
386
|
+
const note = freshnessNote(result.freshness);
|
|
387
|
+
const header = [
|
|
388
|
+
`**Ask:** ${result.query}`,
|
|
389
|
+
`Index: ${population}; ${built}.${note ? `\nStaleness: ${note}.` : ""}`,
|
|
390
|
+
result.filters.project || result.filters.since
|
|
391
|
+
? `Filters: project=${result.filters.project ?? "all"}, since=${result.filters.since ?? "none"}`
|
|
392
|
+
: "",
|
|
393
|
+
result.self_excluded ? "Withheld: this session's own turns." : "",
|
|
394
|
+
].filter(Boolean);
|
|
395
|
+
|
|
396
|
+
if (!result.answered) {
|
|
397
|
+
const found =
|
|
398
|
+
result.matched_terms.length > 0
|
|
399
|
+
? `terms found elsewhere in the population: ${result.matched_terms.join(", ")}`
|
|
400
|
+
: "none of the query terms appear in the population";
|
|
401
|
+
const missing =
|
|
402
|
+
result.unmatched_terms.length > 0
|
|
403
|
+
? `terms not found: ${result.unmatched_terms.join(", ")}`
|
|
404
|
+
: "every term was found, but no turn carries them together";
|
|
405
|
+
return [
|
|
406
|
+
...header,
|
|
407
|
+
"",
|
|
408
|
+
"**The index cannot answer this.**",
|
|
409
|
+
`Searched ${population}.`,
|
|
410
|
+
`Result: ${found}; ${missing}.`,
|
|
411
|
+
"Widen the words used, drop the project filter, or rebuild the index if the sessions are newer than the build.",
|
|
412
|
+
].join("\n");
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
const blocks = result.hits.map((hit, index) => {
|
|
416
|
+
const where =
|
|
417
|
+
`**${index + 1}.** ${hit.turn.project} - ${hit.turn.ts} - line ${hit.turn.line}\n` +
|
|
418
|
+
`Session: \`${hit.turn.session}\``;
|
|
419
|
+
return `${where}\n> ${passage(hit.turn.text, hit.matched)}`;
|
|
420
|
+
});
|
|
421
|
+
const lines = [
|
|
422
|
+
...header,
|
|
423
|
+
"",
|
|
424
|
+
`${result.hits.length} turn(s) carry the query, ranked by BM25:`,
|
|
425
|
+
"",
|
|
426
|
+
blocks.join("\n\n"),
|
|
427
|
+
];
|
|
428
|
+
if (result.unmatched_terms.length > 0) {
|
|
429
|
+
lines.push(
|
|
430
|
+
"",
|
|
431
|
+
`Terms found in no turn (the lexical index cannot see them): ${result.unmatched_terms.join(", ")}.`,
|
|
432
|
+
);
|
|
433
|
+
}
|
|
434
|
+
return lines.join("\n");
|
|
435
|
+
}
|