@crewhaus/tool-retrieve 0.1.4 → 0.1.5
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/dist/index.d.ts +54 -0
- package/dist/index.js +100 -0
- package/package.json +13 -10
- package/src/index.test.ts +0 -151
- package/src/index.ts +0 -146
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Catalog R12 `tool-retrieve` — `Retrieve(query, k?, filter?)` agent tool.
|
|
3
|
+
*
|
|
4
|
+
* Embeds the query via the configured embedder, queries the vector
|
|
5
|
+
* store for top-k hits, and returns a numbered list with citations
|
|
6
|
+
* the model can read (`[1] (id=…) text…`).
|
|
7
|
+
*
|
|
8
|
+
* Configuration is registered at boot via
|
|
9
|
+
* `registerRetrieveConfig({ embedder, vectorStore, defaultK? })` so
|
|
10
|
+
* the codegen layer can wire the tool with whichever backends the
|
|
11
|
+
* spec declares.
|
|
12
|
+
*
|
|
13
|
+
* Layer R12. Pairs with `embedder`, `vector-store`, `pipeline-engine`,
|
|
14
|
+
* `target-pipeline`.
|
|
15
|
+
*/
|
|
16
|
+
import { type Embedder } from "@crewhaus/embedder";
|
|
17
|
+
import { CrewhausError } from "@crewhaus/errors";
|
|
18
|
+
import type { RegisteredTool } from "@crewhaus/tool-catalog";
|
|
19
|
+
import { type VectorBackendId, type VectorStore } from "@crewhaus/vector-store";
|
|
20
|
+
export declare class RetrieveConfigError extends CrewhausError {
|
|
21
|
+
readonly name = "RetrieveConfigError";
|
|
22
|
+
constructor(message: string, cause?: unknown);
|
|
23
|
+
}
|
|
24
|
+
export type RetrieveConfig = {
|
|
25
|
+
readonly embedder: Embedder;
|
|
26
|
+
readonly vectorStore: VectorStore;
|
|
27
|
+
readonly defaultK?: number;
|
|
28
|
+
};
|
|
29
|
+
export type RetrieveConfigInput = {
|
|
30
|
+
readonly embedder?: Embedder;
|
|
31
|
+
readonly embedderModel?: string;
|
|
32
|
+
readonly embedderApiKey?: string;
|
|
33
|
+
readonly vectorStore?: VectorStore;
|
|
34
|
+
readonly vectorBackend?: VectorBackendId;
|
|
35
|
+
/**
|
|
36
|
+
* Connection config for the chosen `vectorBackend`, consulted only when no
|
|
37
|
+
* `vectorStore` instance is supplied. Mirrors the pipeline spec's
|
|
38
|
+
* `retrieve.{url,collection,apiKey}`. The HTTP backends
|
|
39
|
+
* (qdrant/pinecone/weaviate) require `url` + `collection`; lance reads
|
|
40
|
+
* `url` as its on-disk index path. `apiKey` here is the vector store's,
|
|
41
|
+
* distinct from `embedderApiKey`. (At runtime the caller passes the
|
|
42
|
+
* resolved secret — there is no bundle to keep it out of.)
|
|
43
|
+
*/
|
|
44
|
+
readonly url?: string;
|
|
45
|
+
readonly collection?: string;
|
|
46
|
+
readonly apiKey?: string;
|
|
47
|
+
readonly defaultK?: number;
|
|
48
|
+
readonly default_k?: number;
|
|
49
|
+
};
|
|
50
|
+
export declare function registerRetrieveConfig(input: RetrieveConfigInput): void;
|
|
51
|
+
export declare function getRetrieveConfig(): RetrieveConfig | undefined;
|
|
52
|
+
/** Test-only — clear cached config. */
|
|
53
|
+
export declare function _resetRetrieveConfig(): void;
|
|
54
|
+
export declare const retrieve: RegisteredTool;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Catalog R12 `tool-retrieve` — `Retrieve(query, k?, filter?)` agent tool.
|
|
3
|
+
*
|
|
4
|
+
* Embeds the query via the configured embedder, queries the vector
|
|
5
|
+
* store for top-k hits, and returns a numbered list with citations
|
|
6
|
+
* the model can read (`[1] (id=…) text…`).
|
|
7
|
+
*
|
|
8
|
+
* Configuration is registered at boot via
|
|
9
|
+
* `registerRetrieveConfig({ embedder, vectorStore, defaultK? })` so
|
|
10
|
+
* the codegen layer can wire the tool with whichever backends the
|
|
11
|
+
* spec declares.
|
|
12
|
+
*
|
|
13
|
+
* Layer R12. Pairs with `embedder`, `vector-store`, `pipeline-engine`,
|
|
14
|
+
* `target-pipeline`.
|
|
15
|
+
*/
|
|
16
|
+
import { createEmbedder } from "@crewhaus/embedder";
|
|
17
|
+
import { CrewhausError } from "@crewhaus/errors";
|
|
18
|
+
import { buildTool } from "@crewhaus/tool-builder";
|
|
19
|
+
import { createVectorStore } from "@crewhaus/vector-store";
|
|
20
|
+
import { z } from "zod";
|
|
21
|
+
export class RetrieveConfigError extends CrewhausError {
|
|
22
|
+
name = "RetrieveConfigError";
|
|
23
|
+
constructor(message, cause) {
|
|
24
|
+
super("config", message, cause);
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
let activeConfig;
|
|
28
|
+
export function registerRetrieveConfig(input) {
|
|
29
|
+
let embedder = input.embedder;
|
|
30
|
+
if (embedder === undefined && input.embedderModel !== undefined) {
|
|
31
|
+
embedder = createEmbedder({
|
|
32
|
+
model: input.embedderModel,
|
|
33
|
+
...(input.embedderApiKey !== undefined ? { apiKey: input.embedderApiKey } : {}),
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
let vectorStore = input.vectorStore;
|
|
37
|
+
if (vectorStore === undefined) {
|
|
38
|
+
vectorStore = createVectorStore({
|
|
39
|
+
backend: input.vectorBackend ?? "in-memory",
|
|
40
|
+
...(input.url !== undefined ? { url: input.url } : {}),
|
|
41
|
+
...(input.apiKey !== undefined ? { apiKey: input.apiKey } : {}),
|
|
42
|
+
...(input.collection !== undefined ? { collection: input.collection } : {}),
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
if (embedder === undefined) {
|
|
46
|
+
throw new RetrieveConfigError("registerRetrieveConfig requires either an `embedder` instance or `embedderModel` string");
|
|
47
|
+
}
|
|
48
|
+
activeConfig = {
|
|
49
|
+
embedder,
|
|
50
|
+
vectorStore,
|
|
51
|
+
...((input.defaultK ?? input.default_k !== undefined)
|
|
52
|
+
? { defaultK: input.defaultK ?? input.default_k }
|
|
53
|
+
: {}),
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
export function getRetrieveConfig() {
|
|
57
|
+
return activeConfig;
|
|
58
|
+
}
|
|
59
|
+
/** Test-only — clear cached config. */
|
|
60
|
+
export function _resetRetrieveConfig() {
|
|
61
|
+
activeConfig = undefined;
|
|
62
|
+
}
|
|
63
|
+
const retrieveSchema = z.object({
|
|
64
|
+
query: z.string().min(1),
|
|
65
|
+
k: z.number().int().positive().max(50).optional(),
|
|
66
|
+
filter: z.record(z.string(), z.unknown()).optional(),
|
|
67
|
+
});
|
|
68
|
+
function formatHits(hits) {
|
|
69
|
+
if (hits.length === 0)
|
|
70
|
+
return "no hits";
|
|
71
|
+
const lines = [];
|
|
72
|
+
hits.forEach((h, i) => {
|
|
73
|
+
const text = h.metadata?.["text"] ?? "";
|
|
74
|
+
const docId = h.metadata?.["docId"] ?? "?";
|
|
75
|
+
const preview = text.length > 280 ? `${text.slice(0, 280)}…` : text;
|
|
76
|
+
lines.push(`[${i + 1}] id=${h.id} doc=${docId} score=${h.score.toFixed(4)}\n${preview}`);
|
|
77
|
+
});
|
|
78
|
+
return lines.join("\n\n");
|
|
79
|
+
}
|
|
80
|
+
export const retrieve = buildTool({
|
|
81
|
+
name: "Retrieve",
|
|
82
|
+
description: "Retrieve top-k chunks from the configured vector store for a natural-language query. Pass `query` (required), optional `k` (default 5), and optional `filter` (metadata predicates). Returns a numbered list of hits with citations.",
|
|
83
|
+
inputSchema: retrieveSchema,
|
|
84
|
+
readOnly: true,
|
|
85
|
+
concurrencySafe: true,
|
|
86
|
+
execute: async (input) => {
|
|
87
|
+
const cfg = activeConfig;
|
|
88
|
+
if (cfg === undefined) {
|
|
89
|
+
throw new RetrieveConfigError("Retrieve tool is unconfigured — call registerRetrieveConfig at boot");
|
|
90
|
+
}
|
|
91
|
+
const inp = input;
|
|
92
|
+
const k = inp.k ?? cfg.defaultK ?? 5;
|
|
93
|
+
const [vec] = await cfg.embedder.embed([inp.query]);
|
|
94
|
+
if (vec === undefined) {
|
|
95
|
+
throw new RetrieveConfigError("embedder returned 0 vectors for the query");
|
|
96
|
+
}
|
|
97
|
+
const hits = await cfg.vectorStore.query(vec, k, inp.filter);
|
|
98
|
+
return formatHits(hits);
|
|
99
|
+
},
|
|
100
|
+
});
|
package/package.json
CHANGED
|
@@ -1,22 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-retrieve",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Retrieve(query, k?, filter?) tool — composes embedder + vector-store",
|
|
6
|
-
"main": "
|
|
7
|
-
"types": "
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
8
|
"exports": {
|
|
9
|
-
".":
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
10
13
|
},
|
|
11
14
|
"scripts": {
|
|
12
15
|
"test": "bun test src"
|
|
13
16
|
},
|
|
14
17
|
"dependencies": {
|
|
15
|
-
"@crewhaus/embedder": "0.1.
|
|
16
|
-
"@crewhaus/errors": "0.1.
|
|
17
|
-
"@crewhaus/tool-builder": "0.1.
|
|
18
|
-
"@crewhaus/tool-catalog": "0.1.
|
|
19
|
-
"@crewhaus/vector-store": "0.1.
|
|
18
|
+
"@crewhaus/embedder": "0.1.5",
|
|
19
|
+
"@crewhaus/errors": "0.1.5",
|
|
20
|
+
"@crewhaus/tool-builder": "0.1.5",
|
|
21
|
+
"@crewhaus/tool-catalog": "0.1.5",
|
|
22
|
+
"@crewhaus/vector-store": "0.1.5",
|
|
20
23
|
"zod": "^3.23.8"
|
|
21
24
|
},
|
|
22
25
|
"license": "Apache-2.0",
|
|
@@ -37,5 +40,5 @@
|
|
|
37
40
|
"publishConfig": {
|
|
38
41
|
"access": "public"
|
|
39
42
|
},
|
|
40
|
-
"files": ["
|
|
43
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"]
|
|
41
44
|
}
|
package/src/index.test.ts
DELETED
|
@@ -1,151 +0,0 @@
|
|
|
1
|
-
import { afterEach, describe, expect, test } from "bun:test";
|
|
2
|
-
import { mkdtempSync, rmSync } from "node:fs";
|
|
3
|
-
import { tmpdir } from "node:os";
|
|
4
|
-
import { join } from "node:path";
|
|
5
|
-
import { createEmbedder } from "@crewhaus/embedder";
|
|
6
|
-
import { createVectorStore } from "@crewhaus/vector-store";
|
|
7
|
-
import {
|
|
8
|
-
RetrieveConfigError,
|
|
9
|
-
_resetRetrieveConfig,
|
|
10
|
-
getRetrieveConfig,
|
|
11
|
-
registerRetrieveConfig,
|
|
12
|
-
retrieve,
|
|
13
|
-
} from "./index";
|
|
14
|
-
|
|
15
|
-
afterEach(() => {
|
|
16
|
-
_resetRetrieveConfig();
|
|
17
|
-
});
|
|
18
|
-
|
|
19
|
-
async function seedStore(): Promise<{
|
|
20
|
-
embedder: ReturnType<typeof createEmbedder>;
|
|
21
|
-
vectorStore: ReturnType<typeof createVectorStore>;
|
|
22
|
-
}> {
|
|
23
|
-
const embedder = createEmbedder({ model: "mock/det" });
|
|
24
|
-
const vectorStore = createVectorStore({ backend: "in-memory" });
|
|
25
|
-
const docs = [
|
|
26
|
-
{ id: "1", text: "the quick brown fox jumps over the lazy dog" },
|
|
27
|
-
{ id: "2", text: "lorem ipsum dolor sit amet" },
|
|
28
|
-
{ id: "3", text: "fox in socks on box" },
|
|
29
|
-
];
|
|
30
|
-
const vectors = await embedder.embed(docs.map((d) => d.text));
|
|
31
|
-
for (let i = 0; i < docs.length; i += 1) {
|
|
32
|
-
const doc = docs[i];
|
|
33
|
-
const vec = vectors[i];
|
|
34
|
-
if (doc === undefined) continue;
|
|
35
|
-
await vectorStore.upsert(doc.id, vec ?? [], { docId: doc.id, text: doc.text });
|
|
36
|
-
}
|
|
37
|
-
return { embedder, vectorStore };
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
describe("Retrieve tool", () => {
|
|
41
|
-
test("flags: readOnly + concurrencySafe", () => {
|
|
42
|
-
expect(retrieve.readOnly).toBe(true);
|
|
43
|
-
expect(retrieve.concurrencySafe).toBe(true);
|
|
44
|
-
expect(retrieve.destructive).toBe(false);
|
|
45
|
-
});
|
|
46
|
-
|
|
47
|
-
test("rejects calls before registerRetrieveConfig", async () => {
|
|
48
|
-
await expect(retrieve.execute({ query: "fox" })).rejects.toBeInstanceOf(RetrieveConfigError);
|
|
49
|
-
});
|
|
50
|
-
|
|
51
|
-
test("returns top-k hits as a numbered list with ids and previews", async () => {
|
|
52
|
-
const { embedder, vectorStore } = await seedStore();
|
|
53
|
-
registerRetrieveConfig({ embedder, vectorStore });
|
|
54
|
-
const out = (await retrieve.execute({ query: "fox", k: 2 })) as string;
|
|
55
|
-
expect(out).toContain("[1]");
|
|
56
|
-
expect(out).toContain("[2]");
|
|
57
|
-
expect(out).toContain("id=");
|
|
58
|
-
expect(out).toContain("score=");
|
|
59
|
-
});
|
|
60
|
-
|
|
61
|
-
test("most relevant doc ranks first (mock embedder cosine sanity)", async () => {
|
|
62
|
-
const { embedder, vectorStore } = await seedStore();
|
|
63
|
-
registerRetrieveConfig({ embedder, vectorStore });
|
|
64
|
-
const out = (await retrieve.execute({ query: "fox jumps lazy dog", k: 1 })) as string;
|
|
65
|
-
// Expect the first-doc (closest match for the fox sentence) to win.
|
|
66
|
-
expect(out).toContain("doc=1");
|
|
67
|
-
});
|
|
68
|
-
|
|
69
|
-
test("filter narrows to matching metadata", async () => {
|
|
70
|
-
const { embedder, vectorStore } = await seedStore();
|
|
71
|
-
// Add a tag.
|
|
72
|
-
const v = (await embedder.embed(["the quick brown fox"]))[0] ?? [];
|
|
73
|
-
await vectorStore.upsert("1", v, { docId: "1", text: "fox doc", tag: "alpha" });
|
|
74
|
-
registerRetrieveConfig({ embedder, vectorStore });
|
|
75
|
-
const out = (await retrieve.execute({
|
|
76
|
-
query: "fox",
|
|
77
|
-
k: 5,
|
|
78
|
-
filter: { tag: "alpha" },
|
|
79
|
-
})) as string;
|
|
80
|
-
expect(out).toContain("doc=1");
|
|
81
|
-
});
|
|
82
|
-
|
|
83
|
-
test("filter injection rejected by vector-store's guard (T8)", async () => {
|
|
84
|
-
const { embedder, vectorStore } = await seedStore();
|
|
85
|
-
registerRetrieveConfig({ embedder, vectorStore });
|
|
86
|
-
await expect(
|
|
87
|
-
retrieve.execute({ query: "fox", filter: { "1=1; DROP TABLE": "x" } }),
|
|
88
|
-
).rejects.toThrow(/injection probe/);
|
|
89
|
-
});
|
|
90
|
-
|
|
91
|
-
test("default k=5 when no override is given", async () => {
|
|
92
|
-
const { embedder, vectorStore } = await seedStore();
|
|
93
|
-
registerRetrieveConfig({ embedder, vectorStore });
|
|
94
|
-
const out = (await retrieve.execute({ query: "fox" })) as string;
|
|
95
|
-
// Three docs in the store → still works without an explicit k
|
|
96
|
-
expect(out).toContain("[3]");
|
|
97
|
-
});
|
|
98
|
-
});
|
|
99
|
-
|
|
100
|
-
describe("registerRetrieveConfig variants", () => {
|
|
101
|
-
test("can construct embedder + vectorStore from primitives", () => {
|
|
102
|
-
registerRetrieveConfig({
|
|
103
|
-
embedderModel: "mock/det",
|
|
104
|
-
vectorBackend: "in-memory",
|
|
105
|
-
});
|
|
106
|
-
// No throw — config built lazily.
|
|
107
|
-
});
|
|
108
|
-
|
|
109
|
-
test("constructs a lance store from vectorBackend + url (on-disk index path)", () => {
|
|
110
|
-
// Pass an explicit temp path so the test never writes the default
|
|
111
|
-
// `.crewhaus/vectors/lance` dir into the working tree.
|
|
112
|
-
const dir = mkdtempSync(join(tmpdir(), "crewhaus-retrieve-lance-"));
|
|
113
|
-
try {
|
|
114
|
-
registerRetrieveConfig({ embedderModel: "mock/det", vectorBackend: "lance", url: dir });
|
|
115
|
-
expect(getRetrieveConfig()?.vectorStore.backend).toBe("lance");
|
|
116
|
-
} finally {
|
|
117
|
-
rmSync(dir, { recursive: true, force: true });
|
|
118
|
-
}
|
|
119
|
-
});
|
|
120
|
-
|
|
121
|
-
test("constructs an http (qdrant) store from vectorBackend + url + collection + apiKey", () => {
|
|
122
|
-
registerRetrieveConfig({
|
|
123
|
-
embedderModel: "mock/det",
|
|
124
|
-
vectorBackend: "qdrant",
|
|
125
|
-
url: "https://qdrant.example",
|
|
126
|
-
collection: "docs",
|
|
127
|
-
apiKey: "test-key",
|
|
128
|
-
});
|
|
129
|
-
expect(getRetrieveConfig()?.vectorStore.backend).toBe("qdrant");
|
|
130
|
-
});
|
|
131
|
-
|
|
132
|
-
test("an http backend missing url throws (config reaches the factory guard)", () => {
|
|
133
|
-
expect(() =>
|
|
134
|
-
registerRetrieveConfig({
|
|
135
|
-
embedderModel: "mock/det",
|
|
136
|
-
vectorBackend: "qdrant",
|
|
137
|
-
collection: "docs",
|
|
138
|
-
}),
|
|
139
|
-
).toThrow(/requires url/);
|
|
140
|
-
});
|
|
141
|
-
|
|
142
|
-
test("an http backend missing collection throws", () => {
|
|
143
|
-
expect(() =>
|
|
144
|
-
registerRetrieveConfig({
|
|
145
|
-
embedderModel: "mock/det",
|
|
146
|
-
vectorBackend: "weaviate",
|
|
147
|
-
url: "https://weaviate.example",
|
|
148
|
-
}),
|
|
149
|
-
).toThrow(/requires collection/);
|
|
150
|
-
});
|
|
151
|
-
});
|
package/src/index.ts
DELETED
|
@@ -1,146 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Catalog R12 `tool-retrieve` — `Retrieve(query, k?, filter?)` agent tool.
|
|
3
|
-
*
|
|
4
|
-
* Embeds the query via the configured embedder, queries the vector
|
|
5
|
-
* store for top-k hits, and returns a numbered list with citations
|
|
6
|
-
* the model can read (`[1] (id=…) text…`).
|
|
7
|
-
*
|
|
8
|
-
* Configuration is registered at boot via
|
|
9
|
-
* `registerRetrieveConfig({ embedder, vectorStore, defaultK? })` so
|
|
10
|
-
* the codegen layer can wire the tool with whichever backends the
|
|
11
|
-
* spec declares.
|
|
12
|
-
*
|
|
13
|
-
* Layer R12. Pairs with `embedder`, `vector-store`, `pipeline-engine`,
|
|
14
|
-
* `target-pipeline`.
|
|
15
|
-
*/
|
|
16
|
-
|
|
17
|
-
import { type Embedder, createEmbedder } from "@crewhaus/embedder";
|
|
18
|
-
import { CrewhausError } from "@crewhaus/errors";
|
|
19
|
-
import { buildTool } from "@crewhaus/tool-builder";
|
|
20
|
-
import type { RegisteredTool } from "@crewhaus/tool-catalog";
|
|
21
|
-
import { type VectorBackendId, type VectorStore, createVectorStore } from "@crewhaus/vector-store";
|
|
22
|
-
import { z } from "zod";
|
|
23
|
-
|
|
24
|
-
export class RetrieveConfigError extends CrewhausError {
|
|
25
|
-
override readonly name = "RetrieveConfigError";
|
|
26
|
-
constructor(message: string, cause?: unknown) {
|
|
27
|
-
super("config", message, cause);
|
|
28
|
-
}
|
|
29
|
-
}
|
|
30
|
-
|
|
31
|
-
export type RetrieveConfig = {
|
|
32
|
-
readonly embedder: Embedder;
|
|
33
|
-
readonly vectorStore: VectorStore;
|
|
34
|
-
readonly defaultK?: number;
|
|
35
|
-
};
|
|
36
|
-
|
|
37
|
-
export type RetrieveConfigInput = {
|
|
38
|
-
readonly embedder?: Embedder;
|
|
39
|
-
readonly embedderModel?: string;
|
|
40
|
-
readonly embedderApiKey?: string;
|
|
41
|
-
readonly vectorStore?: VectorStore;
|
|
42
|
-
readonly vectorBackend?: VectorBackendId;
|
|
43
|
-
/**
|
|
44
|
-
* Connection config for the chosen `vectorBackend`, consulted only when no
|
|
45
|
-
* `vectorStore` instance is supplied. Mirrors the pipeline spec's
|
|
46
|
-
* `retrieve.{url,collection,apiKey}`. The HTTP backends
|
|
47
|
-
* (qdrant/pinecone/weaviate) require `url` + `collection`; lance reads
|
|
48
|
-
* `url` as its on-disk index path. `apiKey` here is the vector store's,
|
|
49
|
-
* distinct from `embedderApiKey`. (At runtime the caller passes the
|
|
50
|
-
* resolved secret — there is no bundle to keep it out of.)
|
|
51
|
-
*/
|
|
52
|
-
readonly url?: string;
|
|
53
|
-
readonly collection?: string;
|
|
54
|
-
readonly apiKey?: string;
|
|
55
|
-
readonly defaultK?: number;
|
|
56
|
-
readonly default_k?: number;
|
|
57
|
-
};
|
|
58
|
-
|
|
59
|
-
let activeConfig: RetrieveConfig | undefined;
|
|
60
|
-
|
|
61
|
-
export function registerRetrieveConfig(input: RetrieveConfigInput): void {
|
|
62
|
-
let embedder = input.embedder;
|
|
63
|
-
if (embedder === undefined && input.embedderModel !== undefined) {
|
|
64
|
-
embedder = createEmbedder({
|
|
65
|
-
model: input.embedderModel,
|
|
66
|
-
...(input.embedderApiKey !== undefined ? { apiKey: input.embedderApiKey } : {}),
|
|
67
|
-
});
|
|
68
|
-
}
|
|
69
|
-
let vectorStore = input.vectorStore;
|
|
70
|
-
if (vectorStore === undefined) {
|
|
71
|
-
vectorStore = createVectorStore({
|
|
72
|
-
backend: input.vectorBackend ?? "in-memory",
|
|
73
|
-
...(input.url !== undefined ? { url: input.url } : {}),
|
|
74
|
-
...(input.apiKey !== undefined ? { apiKey: input.apiKey } : {}),
|
|
75
|
-
...(input.collection !== undefined ? { collection: input.collection } : {}),
|
|
76
|
-
});
|
|
77
|
-
}
|
|
78
|
-
if (embedder === undefined) {
|
|
79
|
-
throw new RetrieveConfigError(
|
|
80
|
-
"registerRetrieveConfig requires either an `embedder` instance or `embedderModel` string",
|
|
81
|
-
);
|
|
82
|
-
}
|
|
83
|
-
activeConfig = {
|
|
84
|
-
embedder,
|
|
85
|
-
vectorStore,
|
|
86
|
-
...((input.defaultK ?? input.default_k !== undefined)
|
|
87
|
-
? { defaultK: input.defaultK ?? input.default_k }
|
|
88
|
-
: {}),
|
|
89
|
-
};
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
export function getRetrieveConfig(): RetrieveConfig | undefined {
|
|
93
|
-
return activeConfig;
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/** Test-only — clear cached config. */
|
|
97
|
-
export function _resetRetrieveConfig(): void {
|
|
98
|
-
activeConfig = undefined;
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
const retrieveSchema = z.object({
|
|
102
|
-
query: z.string().min(1),
|
|
103
|
-
k: z.number().int().positive().max(50).optional(),
|
|
104
|
-
filter: z.record(z.string(), z.unknown()).optional(),
|
|
105
|
-
});
|
|
106
|
-
|
|
107
|
-
type RetrieveInput = z.infer<typeof retrieveSchema>;
|
|
108
|
-
|
|
109
|
-
function formatHits(
|
|
110
|
-
hits: ReadonlyArray<{ id: string; score: number; metadata?: Readonly<Record<string, unknown>> }>,
|
|
111
|
-
): string {
|
|
112
|
-
if (hits.length === 0) return "no hits";
|
|
113
|
-
const lines: string[] = [];
|
|
114
|
-
hits.forEach((h, i) => {
|
|
115
|
-
const text = (h.metadata?.["text"] as string | undefined) ?? "";
|
|
116
|
-
const docId = (h.metadata?.["docId"] as string | undefined) ?? "?";
|
|
117
|
-
const preview = text.length > 280 ? `${text.slice(0, 280)}…` : text;
|
|
118
|
-
lines.push(`[${i + 1}] id=${h.id} doc=${docId} score=${h.score.toFixed(4)}\n${preview}`);
|
|
119
|
-
});
|
|
120
|
-
return lines.join("\n\n");
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
export const retrieve: RegisteredTool = buildTool({
|
|
124
|
-
name: "Retrieve",
|
|
125
|
-
description:
|
|
126
|
-
"Retrieve top-k chunks from the configured vector store for a natural-language query. Pass `query` (required), optional `k` (default 5), and optional `filter` (metadata predicates). Returns a numbered list of hits with citations.",
|
|
127
|
-
inputSchema: retrieveSchema,
|
|
128
|
-
readOnly: true,
|
|
129
|
-
concurrencySafe: true,
|
|
130
|
-
execute: async (input) => {
|
|
131
|
-
const cfg = activeConfig;
|
|
132
|
-
if (cfg === undefined) {
|
|
133
|
-
throw new RetrieveConfigError(
|
|
134
|
-
"Retrieve tool is unconfigured — call registerRetrieveConfig at boot",
|
|
135
|
-
);
|
|
136
|
-
}
|
|
137
|
-
const inp = input as RetrieveInput;
|
|
138
|
-
const k = inp.k ?? cfg.defaultK ?? 5;
|
|
139
|
-
const [vec] = await cfg.embedder.embed([inp.query]);
|
|
140
|
-
if (vec === undefined) {
|
|
141
|
-
throw new RetrieveConfigError("embedder returned 0 vectors for the query");
|
|
142
|
-
}
|
|
143
|
-
const hits = await cfg.vectorStore.query(vec, k, inp.filter);
|
|
144
|
-
return formatHits(hits);
|
|
145
|
-
},
|
|
146
|
-
});
|