@cogitator-ai/rag 0.3.5 → 0.4.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/README.md +11 -0
- package/dist/rerankers/index.d.ts +1 -1
- package/dist/rerankers/index.d.ts.map +1 -1
- package/dist/rerankers/index.js +1 -1
- package/dist/rerankers/index.js.map +1 -1
- package/dist/rerankers/llm-reranker.d.ts +27 -0
- package/dist/rerankers/llm-reranker.d.ts.map +1 -1
- package/dist/rerankers/llm-reranker.js +33 -5
- package/dist/rerankers/llm-reranker.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -307,6 +307,17 @@ const pipeline = new RAGPipelineBuilder()
|
|
|
307
307
|
.build();
|
|
308
308
|
```
|
|
309
309
|
|
|
310
|
+
When the model's answer holds no ranking (a reasoning model that spent its token budget on reasoning returns empty content, for example) or `generateFn` throws, the reranker keeps the retrieval order and logs a warning. Pass `onError` to observe that fallback, or `strict: true` to make `rerank()` throw an `LLMRerankError` (with the raw answer in `response` and the original error in `cause`):
|
|
311
|
+
|
|
312
|
+
```typescript
|
|
313
|
+
const observed = new LLMReranker({
|
|
314
|
+
generateFn: (prompt) => llm.generate(prompt),
|
|
315
|
+
onError: (error, { query, response }) => logger.warn({ query, response }, error.message),
|
|
316
|
+
});
|
|
317
|
+
|
|
318
|
+
const strict = new LLMReranker({ generateFn: (prompt) => llm.generate(prompt), strict: true });
|
|
319
|
+
```
|
|
320
|
+
|
|
310
321
|
### Cohere Reranker
|
|
311
322
|
|
|
312
323
|
Uses the Cohere Rerank API (rerank-v3.5 by default).
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export { LLMReranker, type LLMRerankerConfig } from './llm-reranker.js';
|
|
1
|
+
export { LLMReranker, LLMRerankError, type LLMRerankerConfig, type LLMRerankFailureContext, } from './llm-reranker.js';
|
|
2
2
|
export { CohereReranker, type CohereRerankerConfig } from './cohere-reranker.js';
|
|
3
3
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
|
package/dist/rerankers/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,cAAc,GAGf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAA6B,MAAM,sBAAsB,CAAC"}
|
|
@@ -1,9 +1,36 @@
|
|
|
1
1
|
import type { Reranker, RetrievalResult } from '@cogitator-ai/types';
|
|
2
|
+
/** What the reranker was doing when it failed. */
|
|
3
|
+
export interface LLMRerankFailureContext {
|
|
4
|
+
query: string;
|
|
5
|
+
/** The model's raw answer, or undefined when `generateFn` itself failed. */
|
|
6
|
+
response?: string;
|
|
7
|
+
}
|
|
2
8
|
export interface LLMRerankerConfig {
|
|
3
9
|
generateFn: (prompt: string) => Promise<string>;
|
|
10
|
+
/**
|
|
11
|
+
* Called when the model's answer cannot be turned into a ranking, or `generateFn` fails. The
|
|
12
|
+
* reranker then returns the results in retrieval order (unless `strict` is set) and does not
|
|
13
|
+
* log to the console.
|
|
14
|
+
*/
|
|
15
|
+
onError?: (error: LLMRerankError, context: LLMRerankFailureContext) => void;
|
|
16
|
+
/** Throw an `LLMRerankError` instead of falling back to the retrieval order. Defaults to false. */
|
|
17
|
+
strict?: boolean;
|
|
18
|
+
}
|
|
19
|
+
/** Reranking failed: the model gave no usable ranking, or `generateFn` threw (see `cause`). */
|
|
20
|
+
export declare class LLMRerankError extends Error {
|
|
21
|
+
/** The model's raw answer, when there was one. */
|
|
22
|
+
readonly response?: string | undefined;
|
|
23
|
+
readonly name = "LLMRerankError";
|
|
24
|
+
constructor(message: string,
|
|
25
|
+
/** The model's raw answer, when there was one. */
|
|
26
|
+
response?: string | undefined, options?: {
|
|
27
|
+
cause?: unknown;
|
|
28
|
+
});
|
|
4
29
|
}
|
|
5
30
|
export declare class LLMReranker implements Reranker {
|
|
6
31
|
private readonly generateFn;
|
|
32
|
+
private readonly onError?;
|
|
33
|
+
private readonly strict;
|
|
7
34
|
constructor(config: LLMRerankerConfig);
|
|
8
35
|
rerank(query: string, results: RetrievalResult[], topN?: number): Promise<RetrievalResult[]>;
|
|
9
36
|
private buildPrompt;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"llm-reranker.d.ts","sourceRoot":"","sources":["../../src/rerankers/llm-reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"llm-reranker.d.ts","sourceRoot":"","sources":["../../src/rerankers/llm-reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAErE,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC5E,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,+FAA+F;AAC/F,qBAAa,cAAe,SAAQ,KAAK;IAKrC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM;IAL5B,SAAkB,IAAI,oBAAoB;gBAGxC,OAAO,EAAE,MAAM;IACf,kDAAkD;IACzC,QAAQ,CAAC,EAAE,MAAM,YAAA,EAC1B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAID,qBAAa,WAAY,YAAW,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,MAAM,EAAE,iBAAiB;IAM/B,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,EAAE,EAC1B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,EAAE,CAAC;IA0C7B,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,WAAW;CAqCpB"}
|
|
@@ -1,15 +1,30 @@
|
|
|
1
|
+
/** Reranking failed: the model gave no usable ranking, or `generateFn` threw (see `cause`). */
|
|
2
|
+
export class LLMRerankError extends Error {
|
|
3
|
+
response;
|
|
4
|
+
name = 'LLMRerankError';
|
|
5
|
+
constructor(message,
|
|
6
|
+
/** The model's raw answer, when there was one. */
|
|
7
|
+
response, options) {
|
|
8
|
+
super(message, options);
|
|
9
|
+
this.response = response;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
1
12
|
const MAX_DOCUMENTS_IN_PROMPT = 50;
|
|
2
13
|
export class LLMReranker {
|
|
3
14
|
generateFn;
|
|
15
|
+
onError;
|
|
16
|
+
strict;
|
|
4
17
|
constructor(config) {
|
|
5
18
|
this.generateFn = config.generateFn;
|
|
19
|
+
this.onError = config.onError;
|
|
20
|
+
this.strict = config.strict ?? false;
|
|
6
21
|
}
|
|
7
22
|
async rerank(query, results, topN) {
|
|
8
23
|
if (results.length === 0)
|
|
9
24
|
return [];
|
|
25
|
+
let response;
|
|
10
26
|
try {
|
|
11
|
-
|
|
12
|
-
const response = await this.generateFn(prompt);
|
|
27
|
+
response = await this.generateFn(this.buildPrompt(query, results));
|
|
13
28
|
const scores = this.parseScores(response, results.length);
|
|
14
29
|
const scored = results.map((result, i) => {
|
|
15
30
|
const entry = scores.find((s) => s.index === i);
|
|
@@ -23,7 +38,17 @@ export class LLMReranker {
|
|
|
23
38
|
return topN ? reranked.slice(0, topN) : reranked;
|
|
24
39
|
}
|
|
25
40
|
catch (error) {
|
|
26
|
-
|
|
41
|
+
const failure = error instanceof LLMRerankError
|
|
42
|
+
? error
|
|
43
|
+
: new LLMRerankError(`${response === undefined ? 'generateFn failed' : 'Reranking failed'}: ${error instanceof Error ? error.message : String(error)}`, response, { cause: error });
|
|
44
|
+
if (this.strict)
|
|
45
|
+
throw failure;
|
|
46
|
+
if (this.onError) {
|
|
47
|
+
this.onError(failure, { query, response });
|
|
48
|
+
}
|
|
49
|
+
else {
|
|
50
|
+
console.warn('[LLMReranker] Reranking failed, returning original order:', failure);
|
|
51
|
+
}
|
|
27
52
|
const fallback = [...results];
|
|
28
53
|
return topN ? fallback.slice(0, topN) : fallback;
|
|
29
54
|
}
|
|
@@ -42,9 +67,12 @@ export class LLMReranker {
|
|
|
42
67
|
].join('\n');
|
|
43
68
|
}
|
|
44
69
|
parseScores(response, count) {
|
|
70
|
+
if (typeof response !== 'string' || response.trim() === '') {
|
|
71
|
+
throw new LLMRerankError('The model returned an empty response (a reasoning model may have spent its token budget on reasoning)', response);
|
|
72
|
+
}
|
|
45
73
|
const candidates = response.match(/\[[\s\S]*?\]/g);
|
|
46
74
|
if (!candidates)
|
|
47
|
-
throw new
|
|
75
|
+
throw new LLMRerankError('No JSON array found in the response', response);
|
|
48
76
|
for (let i = candidates.length - 1; i >= 0; i--) {
|
|
49
77
|
try {
|
|
50
78
|
const parsed = JSON.parse(candidates[i]);
|
|
@@ -63,7 +91,7 @@ export class LLMReranker {
|
|
|
63
91
|
continue;
|
|
64
92
|
}
|
|
65
93
|
}
|
|
66
|
-
throw new
|
|
94
|
+
throw new LLMRerankError('No JSON array of { index, score } objects found in the response', response);
|
|
67
95
|
}
|
|
68
96
|
}
|
|
69
97
|
//# sourceMappingURL=llm-reranker.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"llm-reranker.js","sourceRoot":"","sources":["../../src/rerankers/llm-reranker.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"llm-reranker.js","sourceRoot":"","sources":["../../src/rerankers/llm-reranker.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cogitator-ai/rag",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Retrieval Augmented Generation for Cogitator AI agents",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -18,12 +18,12 @@
|
|
|
18
18
|
"node": ">=22.12.0"
|
|
19
19
|
},
|
|
20
20
|
"dependencies": {
|
|
21
|
-
"@cogitator-ai/types": "0.
|
|
21
|
+
"@cogitator-ai/types": "0.30.0",
|
|
22
22
|
"nanoid": "^6.0.1",
|
|
23
23
|
"zod": "^4.6.5"
|
|
24
24
|
},
|
|
25
25
|
"peerDependencies": {
|
|
26
|
-
"@cogitator-ai/memory": ">=0.11.
|
|
26
|
+
"@cogitator-ai/memory": ">=0.11.1"
|
|
27
27
|
},
|
|
28
28
|
"peerDependenciesMeta": {
|
|
29
29
|
"@cogitator-ai/memory": {
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"pdf-parse": "^2.4.5"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
|
-
"@cogitator-ai/memory": "0.11.
|
|
39
|
+
"@cogitator-ai/memory": "0.11.1",
|
|
40
40
|
"@types/papaparse": "^5.3.15",
|
|
41
41
|
"typescript": "^6.0.3",
|
|
42
42
|
"vitest": "^5.0.3"
|