@framers/agentos-ext-citation-check 0.0.0-stage → 0.1.1

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/LICENSE +98 -0
  2. package/README.md +167 -2
  3. package/dist/bin.d.ts +10 -0
  4. package/dist/bin.d.ts.map +1 -0
  5. package/dist/bin.js +11 -0
  6. package/dist/bin.js.map +1 -0
  7. package/dist/cli.d.ts +36 -0
  8. package/dist/cli.d.ts.map +1 -0
  9. package/dist/cli.js +145 -0
  10. package/dist/cli.js.map +1 -0
  11. package/dist/embeddings.d.ts +54 -0
  12. package/dist/embeddings.d.ts.map +1 -0
  13. package/dist/embeddings.js +52 -0
  14. package/dist/embeddings.js.map +1 -0
  15. package/dist/index.d.ts +55 -0
  16. package/dist/index.d.ts.map +1 -0
  17. package/dist/index.js +63 -0
  18. package/dist/index.js.map +1 -0
  19. package/dist/match.d.ts +44 -0
  20. package/dist/match.d.ts.map +1 -0
  21. package/dist/match.js +108 -0
  22. package/dist/match.js.map +1 -0
  23. package/dist/page.d.ts +105 -0
  24. package/dist/page.d.ts.map +1 -0
  25. package/dist/page.js +400 -0
  26. package/dist/page.js.map +1 -0
  27. package/dist/parse.d.ts +36 -0
  28. package/dist/parse.d.ts.map +1 -0
  29. package/dist/parse.js +314 -0
  30. package/dist/parse.js.map +1 -0
  31. package/dist/report.d.ts +28 -0
  32. package/dist/report.d.ts.map +1 -0
  33. package/dist/report.js +128 -0
  34. package/dist/report.js.map +1 -0
  35. package/dist/runner.d.ts +89 -0
  36. package/dist/runner.d.ts.map +1 -0
  37. package/dist/runner.js +298 -0
  38. package/dist/runner.js.map +1 -0
  39. package/dist/tools/citationVerify.d.ts +59 -0
  40. package/dist/tools/citationVerify.d.ts.map +1 -0
  41. package/dist/tools/citationVerify.js +98 -0
  42. package/dist/tools/citationVerify.js.map +1 -0
  43. package/dist/types.d.ts +150 -0
  44. package/dist/types.d.ts.map +1 -0
  45. package/dist/types.js +20 -0
  46. package/dist/types.js.map +1 -0
  47. package/manifest.json +66 -0
  48. package/package.json +79 -3
package/dist/parse.js ADDED
@@ -0,0 +1,314 @@
1
+ /**
2
+ * @file parse.ts
3
+ * @description The cited claims of a document, with the line each starts on. Markdown: each quotation ("…", “…” or
4
+ * „…“) and the first http or https address after it in its sentence, whether in parentheses (`(https://…, read 1 Mar
5
+ * 2026)`), in a markdown link, between angle brackets or bare, on the same line or a later line of the paragraph;
6
+ * several quotations waiting in a sentence share the address that follows them. A quotation of four words or more that
7
+ * no address follows before its sentence ends is uncited; a shorter one is a term or a title and is passed over.
8
+ * Fenced code, code spans and escaped quotation marks hold no claim. JSON: an array of `{ claim, url, exact }`.
9
+ *
10
+ * @module agentos/extensions/research/citation-check/parse
11
+ */
12
+ import { collapse, stopEndsSentence, words } from '@framers/agentos-ext-grounding-guard/values';
13
+ /** A document the parser cannot read: a JSON entry that is no claim, an address that is not http or https. */
14
+ export class CitationInputError extends Error {
15
+ /** @param message - What is wrong, and where. */
16
+ constructor(message) {
17
+ super(message);
18
+ this.name = 'CitationInputError';
19
+ }
20
+ }
21
+ /** The fewest words an uncited quotation needs to count as a claim. */
22
+ const UNCITED_MIN_WORDS = 4;
23
+ /** The marks that open a quotation, each with the marks that close it. */
24
+ const CLOSERS = { '"': '"', '“': '”', '„': '“”' };
25
+ /** A fence that opens or closes a code block: three or more backticks or tildes. */
26
+ const FENCE = /^ {0,3}(`{3,}|~{3,})/u;
27
+ /** Lines that start a unit of their own: a heading, a list item, a table row. */
28
+ const STARTS_UNIT = /^\s*(?:#{1,6}(?:\s|$)|[-*+]\s|\d{1,9}[.)]\s|\|)/u;
29
+ /** Lines that end their unit too: a heading and a table row. */
30
+ const ALONE = /^\s*(?:#{1,6}(?:\s|$)|\|)/u;
31
+ /** A thematic break. */
32
+ const RULE = /^\s*(?:[-*_]\s*){3,}$/u;
33
+ /** A block quotation's marker. */
34
+ const QUOTE_MARKER = /^ {0,3}>/u;
35
+ /** What ends an address in prose: white space, angle brackets, quotation marks, a backtick. */
36
+ const ADDRESS_END = /[\s<>"“”„`]/u;
37
+ /** Punctuation that ends a sentence or a markdown span after an address, not the address itself. */
38
+ const TRAILING = /[.,;:!?'*_~]/u;
39
+ /** Whether a string is an absolute http or https address with a host. */
40
+ export function isHttpUrl(value) {
41
+ try {
42
+ const url = new URL(value);
43
+ return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== '';
44
+ }
45
+ catch {
46
+ return false;
47
+ }
48
+ }
49
+ /** The units of a markdown document, each a paragraph, a list item, a heading, a table row or a block quotation's paragraph. */
50
+ function units(text) {
51
+ const out = [];
52
+ let unit = [];
53
+ let fence = null;
54
+ let quoted = false;
55
+ const close = () => {
56
+ if (unit.length > 0)
57
+ out.push(unit);
58
+ unit = [];
59
+ };
60
+ text.split(/\r\n|\r|\n/u).forEach((raw, index) => {
61
+ const line = index + 1;
62
+ if (fence !== null) {
63
+ const closing = FENCE.exec(raw);
64
+ if (closing && closing[1][0] === fence.char && closing[1].length >= fence.length && raw.trim() === closing[1])
65
+ fence = null;
66
+ return;
67
+ }
68
+ const opening = FENCE.exec(raw);
69
+ if (opening) {
70
+ close();
71
+ fence = { char: opening[1][0] ?? '`', length: opening[1].length };
72
+ return;
73
+ }
74
+ const inQuote = QUOTE_MARKER.test(raw);
75
+ if (inQuote !== quoted) {
76
+ close();
77
+ quoted = inQuote;
78
+ }
79
+ const content = inQuote ? raw.replace(/^(?: {0,3}> ?)+/u, '') : raw;
80
+ if (content.trim() === '') {
81
+ close();
82
+ return;
83
+ }
84
+ if (STARTS_UNIT.test(content) || RULE.test(content))
85
+ close();
86
+ unit.push({ line, text: content });
87
+ if (ALONE.test(content) || RULE.test(content))
88
+ close();
89
+ });
90
+ close();
91
+ return out;
92
+ }
93
+ /** Where the quotation opened before `from` closes, skipping escaped marks; -1 when it does not close in the unit. */
94
+ function closingMark(text, from, closers) {
95
+ for (let at = from; at < text.length; at += 1) {
96
+ const char = text[at] ?? '';
97
+ if (char === '\\') {
98
+ at += 1;
99
+ continue;
100
+ }
101
+ if (closers.includes(char))
102
+ return at;
103
+ }
104
+ return -1;
105
+ }
106
+ /** A quotation's words: escapes and the markdown marks for bold and code removed, white space collapsed. */
107
+ function cleanQuotation(raw) {
108
+ return collapse(raw.replace(/\\(.)/gu, '$1').replace(/\*\*|__|`/gu, ''));
109
+ }
110
+ /** How many times a character stands in a string. */
111
+ function count(text, char) {
112
+ return text.split(char).length - 1;
113
+ }
114
+ /**
115
+ * The address that starts at `start`: up to white space, an angle bracket or a quotation mark, without the punctuation
116
+ * after it and without a closing bracket it did not open, so `(https://host/Page_(a), read …)` gives
117
+ * `https://host/Page_(a)`.
118
+ */
119
+ function addressAt(text, start) {
120
+ let end = start;
121
+ while (end < text.length && !ADDRESS_END.test(text[end] ?? ''))
122
+ end += 1;
123
+ let url = text.slice(start, end);
124
+ for (;;) {
125
+ const last = url.at(-1) ?? '';
126
+ if (TRAILING.test(last))
127
+ url = url.slice(0, -1);
128
+ else if (last === ')' && count(url, '(') < count(url, ')'))
129
+ url = url.slice(0, -1);
130
+ else if (last === ']' && count(url, '[') < count(url, ']'))
131
+ url = url.slice(0, -1);
132
+ else
133
+ return url;
134
+ }
135
+ }
136
+ /** The claims of one unit, appended to `out` in the order they stand. */
137
+ function scanUnit(unit, out) {
138
+ let text = '';
139
+ const starts = [];
140
+ for (const part of unit) {
141
+ starts.push(text.length);
142
+ text += `${part.text}\n`;
143
+ }
144
+ const lineAt = (offset) => {
145
+ let index = starts.length - 1;
146
+ while (index > 0 && (starts[index] ?? 0) > offset)
147
+ index -= 1;
148
+ return unit[index]?.line ?? 1;
149
+ };
150
+ let waiting = [];
151
+ const settle = () => {
152
+ for (const quote of waiting) {
153
+ if (words(quote.claim).length >= UNCITED_MIN_WORDS)
154
+ out.push({ line: quote.line, claim: quote.claim, url: null, exact: true });
155
+ }
156
+ waiting = [];
157
+ };
158
+ // Brackets and parentheses the scan is inside: a stop there (`et al.`, `vol. 2.`) does not end the sentence.
159
+ let depth = 0;
160
+ let index = 0;
161
+ while (index < text.length) {
162
+ const char = text[index] ?? '';
163
+ if (char === '\\') {
164
+ index += 2;
165
+ continue;
166
+ }
167
+ if (char === '`') {
168
+ const run = /^`+/u.exec(text.slice(index))?.[0] ?? '`';
169
+ const end = text.indexOf(run, index + run.length);
170
+ index = end === -1 ? index + run.length : end + run.length;
171
+ continue;
172
+ }
173
+ const closers = CLOSERS[char];
174
+ if (closers !== undefined) {
175
+ const end = closingMark(text, index + 1, closers);
176
+ if (end === -1) {
177
+ index += 1;
178
+ continue;
179
+ }
180
+ const claim = cleanQuotation(text.slice(index + 1, end));
181
+ if (words(claim).length > 0)
182
+ waiting.push({ line: lineAt(index), claim });
183
+ index = end + 1;
184
+ continue;
185
+ }
186
+ if (/^https?:\/\//iu.test(text.slice(index, index + 8))) {
187
+ const url = addressAt(text, index);
188
+ if (isHttpUrl(url)) {
189
+ for (const quote of waiting)
190
+ out.push({ line: quote.line, claim: quote.claim, url, exact: true });
191
+ waiting = [];
192
+ }
193
+ index += Math.max(url.length, 1);
194
+ continue;
195
+ }
196
+ if (char === '(' || char === '[') {
197
+ depth += 1;
198
+ }
199
+ else if (char === ')' || char === ']') {
200
+ depth = Math.max(0, depth - 1);
201
+ }
202
+ else if (char === '.' || char === '!' || char === '?') {
203
+ let end = index;
204
+ while (end < text.length && '.!?'.includes(text[end] ?? ''))
205
+ end += 1;
206
+ if (depth === 0 && (end === text.length || /\s/u.test(text[end] ?? '')) && stopEndsSentence(text, index, end))
207
+ settle();
208
+ index = end;
209
+ continue;
210
+ }
211
+ index += 1;
212
+ }
213
+ settle();
214
+ }
215
+ /** The claims of a markdown document. */
216
+ function parseMarkdown(text) {
217
+ const out = [];
218
+ for (const unit of units(text))
219
+ scanUnit(unit, out);
220
+ return out;
221
+ }
222
+ /** The line each top-level entry of a JSON array starts on, read from the text the array was parsed from. */
223
+ function entryLines(text) {
224
+ const lines = [];
225
+ let line = 1;
226
+ let depth = 0;
227
+ let inString = false;
228
+ let escaped = false;
229
+ let expecting = false;
230
+ for (const char of text) {
231
+ if (char === '\n')
232
+ line += 1;
233
+ if (inString) {
234
+ if (escaped)
235
+ escaped = false;
236
+ else if (char === '\\')
237
+ escaped = true;
238
+ else if (char === '"')
239
+ inString = false;
240
+ continue;
241
+ }
242
+ if (depth === 1 && expecting && !/\s/u.test(char) && char !== ']') {
243
+ lines.push(line);
244
+ expecting = false;
245
+ }
246
+ if (char === '"')
247
+ inString = true;
248
+ else if (char === '[' || char === '{') {
249
+ depth += 1;
250
+ if (depth === 1)
251
+ expecting = true;
252
+ }
253
+ else if (char === ']' || char === '}')
254
+ depth -= 1;
255
+ else if (char === ',' && depth === 1)
256
+ expecting = true;
257
+ }
258
+ return lines;
259
+ }
260
+ /** The claims of a parsed JSON document. */
261
+ function parseJson(text, value) {
262
+ if (!Array.isArray(value))
263
+ throw new CitationInputError('a JSON document of claims must be an array of { "claim", "url", "exact" } objects');
264
+ const lines = entryLines(text);
265
+ return value.map((entry, index) => {
266
+ const line = lines[index] ?? 1;
267
+ const where = `entry ${index + 1} (line ${line})`;
268
+ if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
269
+ throw new CitationInputError(`${where} is not an object`);
270
+ const { claim, url, exact } = entry;
271
+ if (typeof claim !== 'string' || collapse(claim) === '')
272
+ throw new CitationInputError(`${where} has no claim`);
273
+ if (url !== undefined && url !== null && typeof url !== 'string')
274
+ throw new CitationInputError(`${where}: url must be a string`);
275
+ if (exact !== undefined && typeof exact !== 'boolean')
276
+ throw new CitationInputError(`${where}: exact must be true or false`);
277
+ const address = typeof url === 'string' ? url.trim() : '';
278
+ if (address !== '' && !isHttpUrl(address))
279
+ throw new CitationInputError(`${where}: url is not an http or https address`);
280
+ return { line, claim: collapse(claim), url: address === '' ? null : address, exact: exact ?? true };
281
+ });
282
+ }
283
+ /**
284
+ * The cited claims of a document, in the order they stand, each with its line.
285
+ *
286
+ * @param text - Markdown, or a JSON array of `{ "claim": string, "url"?: string, "exact"?: boolean }`; an entry with no
287
+ * `url`, or an empty one, is uncited, and `exact` is true when left out.
288
+ * @param options - `format`: `auto` (the default) reads a document that is a JSON array as JSON and any other as
289
+ * markdown.
290
+ * @returns The claims; one with no address has `url: null`.
291
+ * @throws {CitationInputError} For a JSON document that is not an array of claims, or that `format: 'json'` names and
292
+ * that is not JSON.
293
+ */
294
+ export function parseCitedClaims(text, options = {}) {
295
+ const format = options.format ?? 'auto';
296
+ if (format !== 'auto' && format !== 'markdown' && format !== 'json') {
297
+ throw new CitationInputError(`unknown format ${JSON.stringify(format)}: use auto, markdown or json`);
298
+ }
299
+ const source = text.replace(/^\uFEFF/u, '');
300
+ if (format === 'json' || (format === 'auto' && source.trimStart().startsWith('['))) {
301
+ let value;
302
+ try {
303
+ value = JSON.parse(source);
304
+ }
305
+ catch (error) {
306
+ if (format === 'json')
307
+ throw new CitationInputError(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
308
+ return parseMarkdown(source);
309
+ }
310
+ return parseJson(source, value);
311
+ }
312
+ return parseMarkdown(source);
313
+ }
314
+ //# sourceMappingURL=parse.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @file report.ts
3
+ * @description What a reader does with a report: whether it fails, and the markdown a document's "Citation check log"
4
+ * section holds: a line on how the claims were checked, the counts and the result, a table of the claims with what
5
+ * each page says, and the nearest sentences for each claim not found.
6
+ *
7
+ * @module agentos/extensions/research/citation-check/report
8
+ */
9
+ import { type CitationReport, type CitationVerdict } from './types.js';
10
+ /** The verdicts that fail a check: a claim the page contradicts, does not hold, or does not come near, and a page not read. */
11
+ export declare const FAILING_VERDICTS: readonly CitationVerdict[];
12
+ /** What a reader asks of a report. */
13
+ export interface CitationReportOptions {
14
+ /** Count a claim whose page could not be fetched or read as no failure. */
15
+ allowUnreachable?: boolean;
16
+ }
17
+ /**
18
+ * Whether a report fails: a claim is `contradicted`, `not_found` or `unverifiable`, or, unless `allowUnreachable`, its
19
+ * page was `unreachable` or `unreadable`. `exact`, `supported`, `weak` and `uncited` claims never fail it.
20
+ */
21
+ export declare function citationReportFails(report: CitationReport, options?: CitationReportOptions): boolean;
22
+ /**
23
+ * The markdown for a document's "Citation check log" section: the date and how the claims were checked, the counts and
24
+ * whether the check passes, a table with each claim's line, verdict, address and what its page says, and the nearest
25
+ * sentences for each claim not found. It carries no heading, so it goes under the section's own.
26
+ */
27
+ export declare function renderCitationLog(report: CitationReport, options?: CitationReportOptions): string;
28
+ //# sourceMappingURL=report.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAyC,KAAK,cAAc,EAAE,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAE/H,+HAA+H;AAC/H,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAA+E,CAAC;AAKvI,sCAAsC;AACtC,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAExG;AA+ED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CA+BrG"}
package/dist/report.js ADDED
@@ -0,0 +1,128 @@
1
+ /**
2
+ * @file report.ts
3
+ * @description What a reader does with a report: whether it fails, and the markdown a document's "Citation check log"
4
+ * section holds: a line on how the claims were checked, the counts and the result, a table of the claims with what
5
+ * each page says, and the nearest sentences for each claim not found.
6
+ *
7
+ * @module agentos/extensions/research/citation-check/report
8
+ */
9
+ import { CITATION_VERDICTS } from './types.js';
10
+ /** The verdicts that fail a check: a claim the page contradicts, does not hold, or does not come near, and a page not read. */
11
+ export const FAILING_VERDICTS = ['contradicted', 'not_found', 'unverifiable', 'unreachable', 'unreadable'];
12
+ /** The verdicts of a page that was not read, which `allowUnreachable` does not count. */
13
+ const PAGE_VERDICTS = new Set(['unreachable', 'unreadable']);
14
+ /**
15
+ * Whether a report fails: a claim is `contradicted`, `not_found` or `unverifiable`, or, unless `allowUnreachable`, its
16
+ * page was `unreachable` or `unreadable`. `exact`, `supported`, `weak` and `uncited` claims never fail it.
17
+ */
18
+ export function citationReportFails(report, options = {}) {
19
+ return report.checks.some((check) => FAILING_VERDICTS.includes(check.verdict) && !(options.allowUnreachable === true && PAGE_VERDICTS.has(check.verdict)));
20
+ }
21
+ /** The longest a cell of the table runs, in characters. */
22
+ const CELL_MAX = 240;
23
+ /** Text for a table cell: one line, its pipes escaped, held to {@link CELL_MAX} characters. */
24
+ function cell(text) {
25
+ const line = text.replace(/\s+/gu, ' ').trim();
26
+ const held = line.length <= CELL_MAX ? line : `${line.slice(0, CELL_MAX - 1).trimEnd()}…`;
27
+ return held.replace(/\|/gu, '\\|');
28
+ }
29
+ /** An address as a markdown autolink, with the characters that would end it encoded. */
30
+ function link(url) {
31
+ return `<${url.replace(/\|/gu, '%7C').replace(/>/gu, '%3E').replace(/\s/gu, '%20')}>`;
32
+ }
33
+ /** A verdict as the log writes it. */
34
+ function label(verdict) {
35
+ return verdict === 'not_found' ? 'not found' : verdict;
36
+ }
37
+ /** A score with two decimals. */
38
+ function score(value) {
39
+ return value.toFixed(2);
40
+ }
41
+ /** Why a page was not read, in words. */
42
+ function problem(page) {
43
+ if (!page)
44
+ return '';
45
+ switch (page.failure) {
46
+ case 'status':
47
+ return `HTTP ${page.status ?? ''}`.trim();
48
+ case 'timeout':
49
+ return 'no answer by the deadline';
50
+ case 'network':
51
+ return page.detail === null ? 'no connection' : `no connection (${page.detail})`;
52
+ case 'refused':
53
+ return `refused by the egress policy (${page.detail ?? 'refused'})`;
54
+ case 'redirects':
55
+ return 'too many redirects';
56
+ case 'too_large':
57
+ return 'larger than the size cap';
58
+ case 'pdf':
59
+ return 'a PDF, which this check does not read';
60
+ case 'binary':
61
+ return page.detail === null ? 'not text' : `not text (${page.detail})`;
62
+ case 'no_text':
63
+ return 'no text on the page';
64
+ default:
65
+ return '';
66
+ }
67
+ }
68
+ /** What the page says for a check: the passage, its score, or why the page was not read. */
69
+ function evidence(check) {
70
+ switch (check.verdict) {
71
+ case 'exact':
72
+ return check.passage ?? '';
73
+ case 'supported':
74
+ case 'weak':
75
+ case 'unverifiable':
76
+ case 'contradicted':
77
+ return check.passage === null ? `(${score(check.score ?? 0)}) no sentence near it` : `(${score(check.score ?? 0)}) ${check.passage}`;
78
+ case 'not_found':
79
+ return check.passage === null ? 'no sentence shares a word with it' : `nearest (${score(check.score ?? 0)}): ${check.passage}`;
80
+ case 'unreachable':
81
+ case 'unreadable':
82
+ return problem(check.page);
83
+ default:
84
+ return '';
85
+ }
86
+ }
87
+ /** A count with its noun, singular or plural. */
88
+ function counted(count, noun) {
89
+ return `${count} ${noun}${count === 1 ? '' : 's'}`;
90
+ }
91
+ /**
92
+ * The markdown for a document's "Citation check log" section: the date and how the claims were checked, the counts and
93
+ * whether the check passes, a table with each claim's line, verdict, address and what its page says, and the nearest
94
+ * sentences for each claim not found. It carries no heading, so it goes under the section's own.
95
+ */
96
+ export function renderCitationLog(report, options = {}) {
97
+ const { summary } = report;
98
+ const how = report.grading === 'embedding'
99
+ ? "each claim's words were looked for on its page, and AgentOS's CitationVerifier graded the claims not found there against the page's sentences by embedding similarity"
100
+ : "each claim's words were looked for on its page, and each claim not found there is shown with the page's sentences nearest it by shared words";
101
+ const verdicts = CITATION_VERDICTS.filter((verdict) => summary.counts[verdict] > 0).map((verdict) => `${summary.counts[verdict]} ${label(verdict)}`);
102
+ const lines = [
103
+ `Checked ${counted(summary.claims, 'claim')} against ${counted(summary.pages, 'page')} on ${report.checkedAt}: ${how}.`,
104
+ `Verdicts: ${verdicts.length === 0 ? 'none' : verdicts.join(', ')}. Result: ${citationReportFails(report, options) ? 'fails' : 'passes'}.`,
105
+ ];
106
+ if (report.checks.length > 0) {
107
+ lines.push('', '| Line | Verdict | Claim | Source | What the page says |', '| --- | --- | --- | --- | --- |');
108
+ for (const check of report.checks) {
109
+ lines.push(`| ${check.line} | ${label(check.verdict)} | ${cell(check.claim)} | ${check.url === null ? 'none' : link(check.url)} | ${cell(evidence(check))} |`);
110
+ }
111
+ }
112
+ const notFound = report.checks.filter((check) => check.verdict === 'not_found' && check.nearest.length > 0);
113
+ if (notFound.length > 0) {
114
+ lines.push('', 'Nearest passages for the claims not found:', '');
115
+ for (const check of notFound) {
116
+ lines.push(`- Line ${check.line}, "${cell(check.claim)}":`);
117
+ check.nearest.forEach((passage, index) => lines.push(` ${index + 1}. (${score(passage.score)}) ${cell(passage.text)}`));
118
+ }
119
+ }
120
+ const notes = report.checks.filter((check) => check.note !== null);
121
+ if (notes.length > 0) {
122
+ lines.push('', 'Notes:', '');
123
+ for (const check of notes)
124
+ lines.push(`- Line ${check.line}: ${cell(check.note ?? '')}`);
125
+ }
126
+ return `${lines.join('\n')}\n`;
127
+ }
128
+ //# sourceMappingURL=report.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,89 @@
1
+ /**
2
+ * @file runner.ts
3
+ * @description The check itself. Each distinct page a document cites is read once, a few at a time. Classical first:
4
+ * a claim whose words stand on its page is `exact`, with the sentence they stand in. A claim that is not is graded by
5
+ * AgentOS's `CitationVerifier` against the page's sentences when the caller gives an embedding function (an NLI
6
+ * function, when given too, turning a `supported` claim the page contradicts into `contradicted`), and is `not_found`
7
+ * otherwise, with the sentences nearest it by shared words. Nothing that costs money is called unless the caller
8
+ * passes it in; no search service is called at all.
9
+ *
10
+ * @module agentos/extensions/research/citation-check/runner
11
+ */
12
+ import { type EgressProfile, type PageScraper } from './page.js';
13
+ import { type CitedClaimFormat } from './parse.js';
14
+ import { type CitationLogger, type CitationReport, type CitedClaim, type EmbedFn, type NliFn } from './types.js';
15
+ /** How a check runs. Every option has a default; none calls a paid service unless it is passed in. */
16
+ export interface CitationCheckOptions {
17
+ /**
18
+ * The `fetch` pages are requested with; the global one when left out. Pass one that applies your egress rules when
19
+ * the documents come from people you do not trust. Not with `egress`.
20
+ */
21
+ fetch?: typeof globalThis.fetch;
22
+ /**
23
+ * Read pages through AgentOS's checked egress (`@framers/agentos/safety/egress`, from 0.13.120) with this policy
24
+ * instead of `fetch`: `hosted` reaches public https addresses on port 443 alone, `local` any address.
25
+ */
26
+ egress?: EgressProfile;
27
+ /**
28
+ * The retry for a page that failed in a way a browser may mend: the web scraper pack's `WebScraperService` (`true`),
29
+ * another scraper, or none (`false`). On by default only when neither `fetch` nor `egress` is given, since the
30
+ * scraper's requests do not go through them.
31
+ */
32
+ fallback?: boolean | PageScraper;
33
+ /** The deadline of one page's request, in milliseconds; 15,000 when left out. */
34
+ timeoutMs?: number;
35
+ /** The most bytes read of one page; 5,000,000 when left out. */
36
+ maxBytes?: number;
37
+ /** The most characters of text kept of one page; 300,000 when left out. */
38
+ textBudget?: number;
39
+ /** How many pages are read at once; 4 when left out. */
40
+ concurrency?: number;
41
+ /** The most distinct pages one check reads; 100 when left out. More is a {@link CitationInputError}. */
42
+ maxPages?: number;
43
+ /** The User-Agent sent; a browser's, generated by the web scraper pack, when left out. */
44
+ userAgent?: string;
45
+ /** The batch embedding function `CitationVerifier` grades with; with none, a claim not found word for word is `not_found`. */
46
+ embedFn?: EmbedFn;
47
+ /** `CitationVerifier`'s similarity for `supported`; its own default (0.6) when left out. */
48
+ supportThreshold?: number;
49
+ /** `CitationVerifier`'s similarity under which a claim is `unverifiable`; its own default (0.3) when left out. */
50
+ unverifiableThreshold?: number;
51
+ /** The NLI function `CitationVerifier` turns a contradicted `supported` claim with, such as grounding-guard's `createNliFunction()`. */
52
+ nliFn?: NliFn;
53
+ /** The most sentences of one page graded by embeddings, in page order; 2,000 when left out. */
54
+ maxPassages?: number;
55
+ /** How many nearest sentences a `not_found` claim shows; 3 when left out. */
56
+ nearest?: number;
57
+ /** Where the check writes its events. */
58
+ logger?: CitationLogger;
59
+ /** The caller's cancellation: the check stops and throws its reason. */
60
+ signal?: AbortSignal;
61
+ /** The clock of `checkedAt` and of each page's `readAt`; `Date.now` when left out. */
62
+ now?: () => number;
63
+ }
64
+ /** Settings the check cannot run with. */
65
+ export declare class CitationSetupError extends Error {
66
+ /** @param message - What is wrong. */
67
+ constructor(message: string);
68
+ }
69
+ /**
70
+ * Checks each cited claim against the page it cites, and reports the verdicts, the pages and a summary.
71
+ *
72
+ * @param claims - The claims, as {@link parseCitedClaims} gives them.
73
+ * @param options - How to run; see {@link CitationCheckOptions}.
74
+ * @returns The report: one check per claim in the claims' order, one status per distinct page.
75
+ * @throws {CitationInputError} For a claim whose address is not http or https, or more distinct pages than `maxPages`.
76
+ * @throws {CitationSetupError} For options out of range, or `egress` with an AgentOS that has no checked egress.
77
+ * @throws The caller's cancellation reason, when `signal` aborts.
78
+ */
79
+ export declare function checkCitations(claims: readonly CitedClaim[], options?: CitationCheckOptions): Promise<CitationReport>;
80
+ /**
81
+ * Parses a document's cited claims and checks them: {@link parseCitedClaims}, then {@link checkCitations}.
82
+ *
83
+ * @param text - Markdown, or a JSON array of claims.
84
+ * @param options - The check's options, and `format` for the parser.
85
+ */
86
+ export declare function checkCitationDocument(text: string, options?: CitationCheckOptions & {
87
+ format?: CitedClaimFormat;
88
+ }): Promise<CitationReport>;
89
+ //# sourceMappingURL=runner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAgE,KAAK,aAAa,EAAiB,KAAK,WAAW,EAAkB,MAAM,WAAW,CAAC;AAC9J,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAyC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAwB,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAmB,MAAM,YAAY,CAAC;AAE/L,sGAAsG;AACtG,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACjC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wGAAwG;IACxG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8HAA8H;IAC9H,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kHAAkH;IAClH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,wIAAwI;IACxI,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,sCAAsC;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAwKD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoG/H;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAoB,GAAG;IAAE,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAGrJ"}