@crewhaus/tool-retrieve 0.1.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/package.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "@crewhaus/tool-retrieve",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "Retrieve(query, k?, filter?) tool — composes embedder + vector-store",
6
+ "main": "src/index.ts",
7
+ "types": "src/index.ts",
8
+ "exports": {
9
+ ".": "./src/index.ts"
10
+ },
11
+ "scripts": {
12
+ "test": "bun test src"
13
+ },
14
+ "dependencies": {
15
+ "@crewhaus/embedder": "0.0.0",
16
+ "@crewhaus/errors": "0.0.0",
17
+ "@crewhaus/tool-builder": "0.0.0",
18
+ "@crewhaus/tool-catalog": "0.0.0",
19
+ "@crewhaus/vector-store": "0.0.0",
20
+ "zod": "^3.23.8"
21
+ },
22
+ "license": "Apache-2.0",
23
+ "author": {
24
+ "name": "Max Meier",
25
+ "email": "max@studiomax.io",
26
+ "url": "https://studiomax.io"
27
+ },
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "git+https://github.com/crewhaus/factory.git",
31
+ "directory": "packages/tool-retrieve"
32
+ },
33
+ "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-retrieve#readme",
34
+ "bugs": {
35
+ "url": "https://github.com/crewhaus/factory/issues"
36
+ },
37
+ "publishConfig": {
38
+ "access": "restricted"
39
+ },
40
+ "files": [
41
+ "src",
42
+ "README.md",
43
+ "LICENSE",
44
+ "NOTICE"
45
+ ]
46
+ }
@@ -0,0 +1,104 @@
1
+ import { afterEach, describe, expect, test } from "bun:test";
2
+ import { createEmbedder } from "@crewhaus/embedder";
3
+ import { createVectorStore } from "@crewhaus/vector-store";
4
+ import {
5
+ RetrieveConfigError,
6
+ _resetRetrieveConfig,
7
+ registerRetrieveConfig,
8
+ retrieve,
9
+ } from "./index";
10
+
11
+ afterEach(() => {
12
+ _resetRetrieveConfig();
13
+ });
14
+
15
+ async function seedStore(): Promise<{
16
+ embedder: ReturnType<typeof createEmbedder>;
17
+ vectorStore: ReturnType<typeof createVectorStore>;
18
+ }> {
19
+ const embedder = createEmbedder({ model: "mock/det" });
20
+ const vectorStore = createVectorStore({ backend: "in-memory" });
21
+ const docs = [
22
+ { id: "1", text: "the quick brown fox jumps over the lazy dog" },
23
+ { id: "2", text: "lorem ipsum dolor sit amet" },
24
+ { id: "3", text: "fox in socks on box" },
25
+ ];
26
+ const vectors = await embedder.embed(docs.map((d) => d.text));
27
+ for (let i = 0; i < docs.length; i += 1) {
28
+ const doc = docs[i];
29
+ const vec = vectors[i];
30
+ if (doc === undefined) continue;
31
+ await vectorStore.upsert(doc.id, vec ?? [], { docId: doc.id, text: doc.text });
32
+ }
33
+ return { embedder, vectorStore };
34
+ }
35
+
36
+ describe("Retrieve tool", () => {
37
+ test("flags: readOnly + concurrencySafe", () => {
38
+ expect(retrieve.readOnly).toBe(true);
39
+ expect(retrieve.concurrencySafe).toBe(true);
40
+ expect(retrieve.destructive).toBe(false);
41
+ });
42
+
43
+ test("rejects calls before registerRetrieveConfig", async () => {
44
+ await expect(retrieve.execute({ query: "fox" })).rejects.toBeInstanceOf(RetrieveConfigError);
45
+ });
46
+
47
+ test("returns top-k hits as a numbered list with ids and previews", async () => {
48
+ const { embedder, vectorStore } = await seedStore();
49
+ registerRetrieveConfig({ embedder, vectorStore });
50
+ const out = (await retrieve.execute({ query: "fox", k: 2 })) as string;
51
+ expect(out).toContain("[1]");
52
+ expect(out).toContain("[2]");
53
+ expect(out).toContain("id=");
54
+ expect(out).toContain("score=");
55
+ });
56
+
57
+ test("most relevant doc ranks first (mock embedder cosine sanity)", async () => {
58
+ const { embedder, vectorStore } = await seedStore();
59
+ registerRetrieveConfig({ embedder, vectorStore });
60
+ const out = (await retrieve.execute({ query: "fox jumps lazy dog", k: 1 })) as string;
61
+ // Expect the first-doc (closest match for the fox sentence) to win.
62
+ expect(out).toContain("doc=1");
63
+ });
64
+
65
+ test("filter narrows to matching metadata", async () => {
66
+ const { embedder, vectorStore } = await seedStore();
67
+ // Add a tag.
68
+ const v = (await embedder.embed(["the quick brown fox"]))[0] ?? [];
69
+ await vectorStore.upsert("1", v, { docId: "1", text: "fox doc", tag: "alpha" });
70
+ registerRetrieveConfig({ embedder, vectorStore });
71
+ const out = (await retrieve.execute({
72
+ query: "fox",
73
+ k: 5,
74
+ filter: { tag: "alpha" },
75
+ })) as string;
76
+ expect(out).toContain("doc=1");
77
+ });
78
+
79
+ test("filter injection rejected by vector-store's guard (T8)", async () => {
80
+ const { embedder, vectorStore } = await seedStore();
81
+ registerRetrieveConfig({ embedder, vectorStore });
82
+ await expect(
83
+ retrieve.execute({ query: "fox", filter: { "1=1; DROP TABLE": "x" } }),
84
+ ).rejects.toThrow(/injection probe/);
85
+ });
86
+
87
+ test("default k=5 when no override is given", async () => {
88
+ const { embedder, vectorStore } = await seedStore();
89
+ registerRetrieveConfig({ embedder, vectorStore });
90
+ const out = (await retrieve.execute({ query: "fox" })) as string;
91
+ // Three docs in the store → still works without an explicit k
92
+ expect(out).toContain("[3]");
93
+ });
94
+ });
95
+
96
+ describe("registerRetrieveConfig variants", () => {
97
+ test("can construct embedder + vectorStore from primitives", () => {
98
+ registerRetrieveConfig({
99
+ embedderModel: "mock/det",
100
+ vectorBackend: "in-memory",
101
+ });
102
+ // No throw — config built lazily.
103
+ });
104
+ });
package/src/index.ts ADDED
@@ -0,0 +1,129 @@
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 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?: "in-memory";
43
+ readonly defaultK?: number;
44
+ readonly default_k?: number;
45
+ };
46
+
47
+ let activeConfig: RetrieveConfig | undefined;
48
+
49
+ export function registerRetrieveConfig(input: RetrieveConfigInput): void {
50
+ let embedder = input.embedder;
51
+ if (embedder === undefined && input.embedderModel !== undefined) {
52
+ embedder = createEmbedder({
53
+ model: input.embedderModel,
54
+ ...(input.embedderApiKey !== undefined ? { apiKey: input.embedderApiKey } : {}),
55
+ });
56
+ }
57
+ let vectorStore = input.vectorStore;
58
+ if (vectorStore === undefined) {
59
+ vectorStore = createVectorStore({ backend: input.vectorBackend ?? "in-memory" });
60
+ }
61
+ if (embedder === undefined) {
62
+ throw new RetrieveConfigError(
63
+ "registerRetrieveConfig requires either an `embedder` instance or `embedderModel` string",
64
+ );
65
+ }
66
+ activeConfig = {
67
+ embedder,
68
+ vectorStore,
69
+ ...((input.defaultK ?? input.default_k !== undefined)
70
+ ? { defaultK: input.defaultK ?? input.default_k }
71
+ : {}),
72
+ };
73
+ }
74
+
75
+ export function getRetrieveConfig(): RetrieveConfig | undefined {
76
+ return activeConfig;
77
+ }
78
+
79
+ /** Test-only — clear cached config. */
80
+ export function _resetRetrieveConfig(): void {
81
+ activeConfig = undefined;
82
+ }
83
+
84
+ const retrieveSchema = z.object({
85
+ query: z.string().min(1),
86
+ k: z.number().int().positive().max(50).optional(),
87
+ filter: z.record(z.string(), z.unknown()).optional(),
88
+ });
89
+
90
+ type RetrieveInput = z.infer<typeof retrieveSchema>;
91
+
92
+ function formatHits(
93
+ hits: ReadonlyArray<{ id: string; score: number; metadata?: Readonly<Record<string, unknown>> }>,
94
+ ): string {
95
+ if (hits.length === 0) return "no hits";
96
+ const lines: string[] = [];
97
+ hits.forEach((h, i) => {
98
+ const text = (h.metadata?.["text"] as string | undefined) ?? "";
99
+ const docId = (h.metadata?.["docId"] as string | undefined) ?? "?";
100
+ const preview = text.length > 280 ? `${text.slice(0, 280)}…` : text;
101
+ lines.push(`[${i + 1}] id=${h.id} doc=${docId} score=${h.score.toFixed(4)}\n${preview}`);
102
+ });
103
+ return lines.join("\n\n");
104
+ }
105
+
106
+ export const retrieve: RegisteredTool = buildTool({
107
+ name: "Retrieve",
108
+ description:
109
+ "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.",
110
+ inputSchema: retrieveSchema,
111
+ readOnly: true,
112
+ concurrencySafe: true,
113
+ execute: async (input) => {
114
+ const cfg = activeConfig;
115
+ if (cfg === undefined) {
116
+ throw new RetrieveConfigError(
117
+ "Retrieve tool is unconfigured — call registerRetrieveConfig at boot",
118
+ );
119
+ }
120
+ const inp = input as RetrieveInput;
121
+ const k = inp.k ?? cfg.defaultK ?? 5;
122
+ const [vec] = await cfg.embedder.embed([inp.query]);
123
+ if (vec === undefined) {
124
+ throw new RetrieveConfigError("embedder returned 0 vectors for the query");
125
+ }
126
+ const hits = await cfg.vectorStore.query(vec, k, inp.filter);
127
+ return formatHits(hits);
128
+ },
129
+ });