retrieval-lens 0.1.0 → 0.1.2
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 +51 -19
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,10 +4,6 @@
|
|
|
4
4
|
|
|
5
5
|
**retrieval-lens** is an MCP server that logs every retrieval step your RAG agent makes — what chunks were retrieved, their scores, sources, and rankings — so you can audit, replay, and diff retrieval runs after the fact.
|
|
6
6
|
|
|
7
|
-
```bash
|
|
8
|
-
npx retrieval-lens
|
|
9
|
-
```
|
|
10
|
-
|
|
11
7
|
---
|
|
12
8
|
|
|
13
9
|
## The Problem
|
|
@@ -18,6 +14,22 @@ retrieval-lens fixes that. Every retrieval run is logged. Nothing is hidden.
|
|
|
18
14
|
|
|
19
15
|
---
|
|
20
16
|
|
|
17
|
+
## Demo
|
|
18
|
+
|
|
19
|
+
When your RAG agent gives a wrong answer, ask retrieval-lens what it saw:
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
await mcp.call("retrieval_diff", {
|
|
23
|
+
run_id_a: "support-bot-before-embedding-refresh",
|
|
24
|
+
run_id_b: "support-bot-after-embedding-refresh",
|
|
25
|
+
match_by: "source"
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
See docs/demo-diff.png for real output from Claude Code.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
21
33
|
## MCP Tools
|
|
22
34
|
|
|
23
35
|
| Tool | What it does |
|
|
@@ -31,17 +43,16 @@ retrieval-lens fixes that. Every retrieval run is logged. Nothing is hidden.
|
|
|
31
43
|
|
|
32
44
|
## Quickstart
|
|
33
45
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
}
|
|
46
|
+
Run retrieval-lens directly with npx:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx retrieval-lens
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Add retrieval-lens to Claude Code with one command:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
claude mcp add retrieval-lens npx retrieval-lens
|
|
45
56
|
```
|
|
46
57
|
|
|
47
58
|
Then call `retrieval_observe` after every retrieval step in your RAG pipeline:
|
|
@@ -60,6 +71,18 @@ await mcp.call("retrieval_observe", {
|
|
|
60
71
|
|
|
61
72
|
---
|
|
62
73
|
|
|
74
|
+
## Adapters
|
|
75
|
+
|
|
76
|
+
### LangChain
|
|
77
|
+
|
|
78
|
+
See examples/langchain-adapter.ts
|
|
79
|
+
|
|
80
|
+
### LlamaIndex
|
|
81
|
+
|
|
82
|
+
See examples/llamaindex-adapter.ts
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
63
86
|
## Why not LangSmith / Langfuse?
|
|
64
87
|
|
|
65
88
|
Those are full observability platforms. retrieval-lens is surgical:
|
|
@@ -75,13 +98,22 @@ Those are full observability platforms. retrieval-lens is surgical:
|
|
|
75
98
|
🚧 Active development. Harness-first build using [harness engineering](https://walkinglabs.github.io/learn-harness-engineering/en/) principles.
|
|
76
99
|
|
|
77
100
|
- [x] F05 — scaffold
|
|
78
|
-
- [
|
|
79
|
-
- [
|
|
80
|
-
- [
|
|
81
|
-
- [
|
|
101
|
+
- [x] F01 — retrieval_observe
|
|
102
|
+
- [x] F02 — retrieval_query
|
|
103
|
+
- [x] F03 — retrieval_diff
|
|
104
|
+
- [x] F04 — retrieval_stats
|
|
82
105
|
|
|
83
106
|
---
|
|
84
107
|
|
|
85
108
|
## License
|
|
86
109
|
|
|
87
110
|
MIT
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Trust Stack
|
|
115
|
+
|
|
116
|
+
retrieval-lens is part of a three-layer trust stack for RAG pipelines:
|
|
117
|
+
- Portcullis — runtime MCP firewall (blocks dangerous tool calls)
|
|
118
|
+
- retrieval-lens — retrieval auditor (logs what the model saw)
|
|
119
|
+
- Dokis — output auditor (verifies claims in generated answers)
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2BpE,wBAAgB,YAAY,IAAI,SAAS,CAmGxC"}
|
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED