@xtatistix/rag-wiki 0.1.12 → 0.1.13
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 +103 -199
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +35 -6
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +6 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,120 +1,105 @@
|
|
|
1
|
-
# rag-wiki
|
|
1
|
+
# @xtatistix/rag-wiki
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Yapılandırılmış bir wiki üzerinden çalışan, kaynak gösterebilen, kapsam dışı soruları reddedebilen hafif bir RAG sistemi.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Ham belge chunk'ları yerine markdown sayfalardan oluşan derlenmiş bir wiki tutar. Sorular bu wikiye dayanarak yanıtlanır. Sistem emin olmadığında söyler — tahmin yürütmez.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Node.js ve **tarayıcı** ortamlarında çalışır.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Kurulum
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
```bash
|
|
14
|
+
npm install @xtatistix/rag-wiki
|
|
15
|
+
```
|
|
14
16
|
|
|
15
|
-
|
|
16
|
-
- **Guideline** — `{projectId}/guideline.md`. Tells the LLM what's in scope, what tone to use, and what to never answer. The gate that makes the system trustworthy.
|
|
17
|
-
- **Index** — `index.md`. A catalogue of all wiki pages with one-line summaries. The LLM reads this first on every query to find relevant pages. `ingest()` keeps it up to date automatically.
|
|
17
|
+
OpenAI API anahtarı gerektirir.
|
|
18
18
|
|
|
19
19
|
---
|
|
20
20
|
|
|
21
|
-
##
|
|
21
|
+
## Nasıl Çalışır
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
Üç katman:
|
|
24
|
+
|
|
25
|
+
- **Wiki** — `{projectId}/wiki/` altındaki markdown sayfalar. `ingest()` ile eklenir veya elle yazılır.
|
|
26
|
+
- **Index** — `index.md`. Tüm wiki sayfalarının tek satırlık özetlerini içeren katalog. `ingest()` her çağrıda otomatik günceller.
|
|
27
|
+
- **Guideline** — `{projectId}/guideline.md`. LLM'e neyi yanıtlayıp neyi reddedeceğini söyleyen kural dosyası. İsteğe bağlıdır.
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
`ask()` çağrısında:
|
|
30
|
+
1. `index.md` okunur, soruyla ilgili sayfalar seçilir
|
|
31
|
+
2. Seçilen sayfaların içeriği yüklenir
|
|
32
|
+
3. Guideline varsa eklenir
|
|
33
|
+
4. Hepsi LLM'e gönderilir
|
|
34
|
+
5. LLM ya yanıtlar (kaynak göstererek) ya da reddeder
|
|
35
|
+
6. Sonuç `{projectId}/log.md`'ye kaydedilir
|
|
28
36
|
|
|
29
37
|
---
|
|
30
38
|
|
|
31
|
-
##
|
|
39
|
+
## Hızlı Başlangıç — Node.js
|
|
32
40
|
|
|
33
41
|
```ts
|
|
34
|
-
import { createRagWiki } from "rag-wiki";
|
|
42
|
+
import { createRagWiki } from "@xtatistix/rag-wiki";
|
|
35
43
|
|
|
36
44
|
const wiki = createRagWiki({
|
|
37
|
-
projectId: "
|
|
38
|
-
openaiApiKey: "sk-...", //
|
|
39
|
-
// rawPath defaults to "./raw"
|
|
45
|
+
projectId: "destek",
|
|
46
|
+
openaiApiKey: "sk-...", // ya da OPENAI_API_KEY env değişkeni
|
|
40
47
|
});
|
|
41
48
|
|
|
42
|
-
|
|
49
|
+
// Sayfa ekle
|
|
50
|
+
await wiki.ingest("İade Politikası", "## Genel Bakış\nTüm ürünler 30 gün içinde iade edilebilir...");
|
|
51
|
+
|
|
52
|
+
// Soru sor
|
|
53
|
+
const result = await wiki.ask("Ürünümü nasıl iade ederim?");
|
|
43
54
|
|
|
44
55
|
if (result.answered) {
|
|
45
56
|
console.log(result.answer);
|
|
46
|
-
console.log("
|
|
57
|
+
console.log("Kaynaklar:", result.sources?.map((s) => s.summary));
|
|
47
58
|
} else {
|
|
48
|
-
console.log("Escalated:", result.escalationReason);
|
|
49
59
|
console.log(result.escalationMessage);
|
|
50
60
|
}
|
|
51
61
|
```
|
|
52
62
|
|
|
53
63
|
---
|
|
54
64
|
|
|
55
|
-
##
|
|
65
|
+
## Hızlı Başlangıç — Tarayıcı (PresignedAdapter)
|
|
56
66
|
|
|
57
|
-
|
|
67
|
+
S3 gibi bir depolama servisini presigned URL'lerle kullanmak için:
|
|
58
68
|
|
|
59
69
|
```ts
|
|
60
|
-
import { createRagWiki,
|
|
70
|
+
import { createRagWiki, PresignedAdapter } from "@xtatistix/rag-wiki/dist/browser";
|
|
61
71
|
|
|
62
72
|
const wiki = createRagWiki({
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
adapter: new
|
|
66
|
-
|
|
73
|
+
openaiApiKey: "sk-...",
|
|
74
|
+
model: "gpt-4o",
|
|
75
|
+
adapter: new PresignedAdapter({
|
|
76
|
+
getReadUrl: (path) =>
|
|
77
|
+
fetch(`/api/presigned/read?path=${path}`).then((r) => r.json()).then((r) => r.url),
|
|
78
|
+
getWriteUrl: (path) =>
|
|
79
|
+
fetch("/api/presigned/write", {
|
|
80
|
+
method: "POST",
|
|
81
|
+
body: JSON.stringify({ path }),
|
|
82
|
+
}).then((r) => r.json()).then((r) => r.url),
|
|
67
83
|
}),
|
|
68
84
|
});
|
|
69
85
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
**Frontend project setup:**
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
public/
|
|
77
|
-
└── raw/
|
|
78
|
-
├── index.md
|
|
79
|
-
└── my-project/
|
|
80
|
-
├── guideline.md
|
|
81
|
-
└── wiki/
|
|
82
|
-
├── return-policy.md
|
|
83
|
-
└── shipping.md
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
Put your wiki files under `public/raw/` and they will be fetched at runtime. `ingest()` writes go to `localStorage` — they persist across page reloads but are local to the browser.
|
|
87
|
-
|
|
88
|
-
> **Note:** Never put your OpenAI API key in frontend code that ships to production. For production, proxy the OpenAI call through your own backend.
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## Directory structure
|
|
93
|
-
|
|
94
|
-
```
|
|
95
|
-
{rawPath or public/raw}/
|
|
96
|
-
├── index.md ← auto-managed by ingest(), do not edit manually
|
|
97
|
-
└── {projectId}/
|
|
98
|
-
├── guideline.md ← you write this once, edit as needed
|
|
99
|
-
├── log.md ← auto-written after every ask()
|
|
100
|
-
└── wiki/
|
|
101
|
-
├── return-policy.md ← written by ingest("Return Policy", ...)
|
|
102
|
-
└── shipping.md ← written by ingest("Shipping", ...)
|
|
86
|
+
await wiki.ingest("Rapor Başlığı", raporIcerigi, { projectId: "proje-42" });
|
|
87
|
+
const result = await wiki.ask("Bu raporu yorumlar mısın?", { projectId: "proje-42" });
|
|
103
88
|
```
|
|
104
89
|
|
|
105
90
|
---
|
|
106
91
|
|
|
107
92
|
## API
|
|
108
93
|
|
|
109
|
-
### `createRagWiki(config)`
|
|
94
|
+
### `createRagWiki(config)`
|
|
110
95
|
|
|
111
96
|
```ts
|
|
112
97
|
const wiki = createRagWiki({
|
|
113
|
-
projectId: "
|
|
114
|
-
openaiApiKey: "sk-...",
|
|
115
|
-
model: "gpt-4o",
|
|
116
|
-
rawPath: "./data",
|
|
117
|
-
adapter: customAdapter,
|
|
98
|
+
projectId: "proje-id", // varsayılan proje — her çağrıda override edilebilir
|
|
99
|
+
openaiApiKey: "sk-...", // tarayıcıda zorunlu, Node'da env'den okunabilir
|
|
100
|
+
model: "gpt-4o", // varsayılan: "gpt-4o-mini"
|
|
101
|
+
rawPath: "./data", // Node only, varsayılan: "./raw"
|
|
102
|
+
adapter: customAdapter, // LocalAdapter, BrowserAdapter, PresignedAdapter veya custom
|
|
118
103
|
});
|
|
119
104
|
```
|
|
120
105
|
|
|
@@ -122,195 +107,114 @@ const wiki = createRagWiki({
|
|
|
122
107
|
|
|
123
108
|
### `wiki.ingest(title, content, options?)`
|
|
124
109
|
|
|
125
|
-
|
|
110
|
+
Wiki'ye sayfa ekler, `index.md`'yi günceller. Aynı başlıkla tekrar çağrılırsa sayfa güncellenir.
|
|
126
111
|
|
|
127
112
|
```ts
|
|
128
|
-
|
|
129
|
-
"Return Policy",
|
|
130
|
-
`## Overview\nAll items can be returned within 30 days of purchase...`
|
|
131
|
-
);
|
|
132
|
-
// → "acme-support/wiki/return-policy.md"
|
|
133
|
-
|
|
134
|
-
// override project per-call
|
|
135
|
-
await wiki.ingest("Shipping", "...", { projectId: "logistics" });
|
|
136
|
-
```
|
|
113
|
+
await wiki.ingest("İade Politikası", "30 gün iade garantisi...");
|
|
137
114
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
115
|
+
// Farklı proje için
|
|
116
|
+
await wiki.ingest("Kargo Bilgisi", "...", { projectId: "lojistik" });
|
|
117
|
+
```
|
|
141
118
|
|
|
142
|
-
|
|
119
|
+
- `title` dosya adına dönüştürülür: `"İade Politikası"` → `iade-politikas.md`
|
|
120
|
+
- İçerik `#` başlığıyla başlamıyorsa otomatik eklenir
|
|
143
121
|
|
|
144
122
|
---
|
|
145
123
|
|
|
146
124
|
### `wiki.ask(question, options?)`
|
|
147
125
|
|
|
148
|
-
Queries the wiki and returns a `QueryResult`.
|
|
149
|
-
|
|
150
126
|
```ts
|
|
151
|
-
const result = await wiki.ask("
|
|
152
|
-
|
|
153
|
-
// override project per-call
|
|
154
|
-
const result = await wiki.ask("How do I return an item?", { projectId: "legal" });
|
|
127
|
+
const result = await wiki.ask("Nasıl iade yaparım?");
|
|
128
|
+
const result = await wiki.ask("Sözleşme maddeleri?", { projectId: "hukuk" });
|
|
155
129
|
```
|
|
156
130
|
|
|
157
|
-
Internally:
|
|
158
|
-
1. Reads `index.md` to find relevant pages
|
|
159
|
-
2. Loads matching page content
|
|
160
|
-
3. Reads `{projectId}/guideline.md` if it exists
|
|
161
|
-
4. Sends pages + guideline to the LLM
|
|
162
|
-
5. The LLM either answers (with sources) or escalates
|
|
163
|
-
6. Appends an entry to `{projectId}/log.md`
|
|
164
|
-
|
|
165
131
|
**`QueryResult`**
|
|
166
132
|
|
|
167
133
|
```ts
|
|
168
134
|
interface QueryResult {
|
|
169
135
|
answered: boolean;
|
|
170
|
-
|
|
171
|
-
// present when answered = true
|
|
172
136
|
answer?: string;
|
|
173
137
|
sources?: { path: string; summary: string }[];
|
|
174
|
-
|
|
175
|
-
// present when answered = false
|
|
176
138
|
escalationReason?: "out_of_scope" | "insufficient_sources" | "guideline_violation" | "no_index";
|
|
177
139
|
escalationMessage?: string;
|
|
178
140
|
}
|
|
179
141
|
```
|
|
180
142
|
|
|
181
|
-
```ts
|
|
182
|
-
if (result.answered) {
|
|
183
|
-
console.log(result.answer);
|
|
184
|
-
console.log(result.sources);
|
|
185
|
-
// [{ path: "acme-support/wiki/return-policy.md", summary: "..." }]
|
|
186
|
-
} else {
|
|
187
|
-
switch (result.escalationReason) {
|
|
188
|
-
case "out_of_scope": // question outside guideline scope
|
|
189
|
-
case "insufficient_sources": // wiki doesn't have enough info
|
|
190
|
-
case "guideline_violation": // hit a hard rule (e.g. medical advice)
|
|
191
|
-
case "no_index": // no wiki pages exist yet
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
```
|
|
195
|
-
|
|
196
143
|
---
|
|
197
144
|
|
|
198
|
-
##
|
|
199
|
-
|
|
200
|
-
The guideline is what turns a generic chatbot into a disciplined domain assistant. Create `{projectId}/guideline.md`:
|
|
201
|
-
|
|
202
|
-
```markdown
|
|
203
|
-
# Guideline — acme-support
|
|
145
|
+
## Adaptörler
|
|
204
146
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
147
|
+
| Adaptör | Ortam | Okuma | Yazma |
|
|
148
|
+
|---|---|---|---|
|
|
149
|
+
| `LocalAdapter` | Node.js | Dosya sistemi | Dosya sistemi |
|
|
150
|
+
| `BrowserAdapter` | Tarayıcı | `fetch()` (public/) | `localStorage` |
|
|
151
|
+
| `PresignedAdapter` | Tarayıcı | Presigned URL (S3 vb.) | Presigned URL (S3 vb.) |
|
|
152
|
+
| Custom | Her ikisi | Senin backend'in | Senin backend'in |
|
|
208
153
|
|
|
209
|
-
|
|
210
|
-
- Friendly and concise
|
|
211
|
-
- Always cite the source page
|
|
212
|
-
|
|
213
|
-
## Hard rules (never answer)
|
|
214
|
-
- Legal advice
|
|
215
|
-
- Medical advice
|
|
216
|
-
- Personally identifiable customer data
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
If no guideline file exists, the system still works — it just has no domain restrictions.
|
|
220
|
-
|
|
221
|
-
---
|
|
222
|
-
|
|
223
|
-
## Adapters
|
|
224
|
-
|
|
225
|
-
### `LocalAdapter` (Node.js default)
|
|
226
|
-
|
|
227
|
-
Reads and writes from the local filesystem. Used automatically when no `adapter` is provided.
|
|
154
|
+
### Custom Adaptör
|
|
228
155
|
|
|
229
156
|
```ts
|
|
230
|
-
import {
|
|
231
|
-
|
|
232
|
-
const wiki = createRagWiki({
|
|
233
|
-
projectId: "my-project",
|
|
234
|
-
adapter: new LocalAdapter("./raw"), // explicit, same as default
|
|
235
|
-
});
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
### `BrowserAdapter`
|
|
239
|
-
|
|
240
|
-
Reads via `fetch()` from a public URL base, writes to `localStorage`.
|
|
241
|
-
|
|
242
|
-
```ts
|
|
243
|
-
import { BrowserAdapter, createRagWiki } from "rag-wiki";
|
|
244
|
-
|
|
245
|
-
const wiki = createRagWiki({
|
|
246
|
-
projectId: "my-project",
|
|
247
|
-
openaiApiKey: "sk-...",
|
|
248
|
-
adapter: new BrowserAdapter({
|
|
249
|
-
publicBase: "/raw", // default: "/raw"
|
|
250
|
-
storagePrefix: "rag-wiki:", // default: "rag-wiki:"
|
|
251
|
-
}),
|
|
252
|
-
});
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### Custom adapter
|
|
256
|
-
|
|
257
|
-
Implement `RagWikiAdapter` to plug in any backend (S3, Supabase, etc.):
|
|
258
|
-
|
|
259
|
-
```ts
|
|
260
|
-
import { RagWikiAdapter, createRagWiki } from "rag-wiki";
|
|
157
|
+
import { RagWikiAdapter } from "@xtatistix/rag-wiki";
|
|
261
158
|
|
|
262
159
|
const myAdapter: RagWikiAdapter = {
|
|
263
160
|
async read(path: string): Promise<string | null> { ... },
|
|
264
161
|
async write(path: string, content: string): Promise<void> { ... },
|
|
265
162
|
async list(prefix: string): Promise<string[]> { ... },
|
|
266
163
|
};
|
|
267
|
-
|
|
268
|
-
const wiki = createRagWiki({ projectId: "my-project", adapter: myAdapter });
|
|
269
164
|
```
|
|
270
165
|
|
|
271
166
|
---
|
|
272
167
|
|
|
273
|
-
##
|
|
168
|
+
## Çoklu Proje
|
|
274
169
|
|
|
275
|
-
|
|
170
|
+
Her `projectId` tamamen izoledir — kendi wiki'si, kılavuzu ve logu vardır.
|
|
276
171
|
|
|
277
172
|
```ts
|
|
278
|
-
const wiki = createRagWiki({ adapter }); //
|
|
173
|
+
const wiki = createRagWiki({ adapter }); // varsayılan projectId yok
|
|
279
174
|
|
|
280
|
-
await wiki.ask("
|
|
281
|
-
await wiki.ask("
|
|
282
|
-
await wiki.ingest("New Policy", "...", { projectId: "support" });
|
|
175
|
+
await wiki.ask("İade politikası?", { projectId: "destek" });
|
|
176
|
+
await wiki.ask("Sözleşme maddeleri?", { projectId: "hukuk" });
|
|
283
177
|
```
|
|
284
178
|
|
|
285
|
-
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Guideline Dosyası
|
|
286
182
|
|
|
287
|
-
|
|
288
|
-
|
|
183
|
+
Sistemi disiplinli bir domain asistanına dönüştürür. `{projectId}/guideline.md` oluştur:
|
|
184
|
+
|
|
185
|
+
```markdown
|
|
186
|
+
# Kılavuz — destek
|
|
187
|
+
|
|
188
|
+
## Kapsam
|
|
189
|
+
Bu wiki yalnızca ürün iadesi, kargo ve hesap sorunlarını yanıtlar.
|
|
190
|
+
Rakip ürünler veya genel alışveriş tavsiyeleri kapsam dışıdır.
|
|
289
191
|
|
|
290
|
-
|
|
291
|
-
|
|
192
|
+
## Kesinlikle yanıtlama
|
|
193
|
+
- Hukuki tavsiye
|
|
194
|
+
- Tıbbi tavsiye
|
|
195
|
+
- Kişisel müşteri verileri
|
|
292
196
|
```
|
|
293
197
|
|
|
294
|
-
|
|
198
|
+
Guideline dosyası yoksa sistem çalışmaya devam eder, sadece domain kısıtlaması olmaz.
|
|
295
199
|
|
|
296
200
|
---
|
|
297
201
|
|
|
298
|
-
##
|
|
299
|
-
|
|
300
|
-
Every `ask()` call appends an entry to `{projectId}/log.md`:
|
|
202
|
+
## Dizin Yapısı
|
|
301
203
|
|
|
302
204
|
```
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
205
|
+
raw/
|
|
206
|
+
├── index.md ← ingest() tarafından otomatik yönetilir
|
|
207
|
+
└── {projectId}/
|
|
208
|
+
├── guideline.md ← isteğe bağlı kural dosyası
|
|
209
|
+
├── log.md ← ask() çağrılarının otomatik logu
|
|
210
|
+
└── wiki/
|
|
211
|
+
├── iade-politikasi.md
|
|
212
|
+
└── kargo-bilgisi.md
|
|
307
213
|
```
|
|
308
214
|
|
|
309
215
|
---
|
|
310
216
|
|
|
311
|
-
## TypeScript
|
|
312
|
-
|
|
313
|
-
All public types are exported:
|
|
217
|
+
## TypeScript Tipleri
|
|
314
218
|
|
|
315
219
|
```ts
|
|
316
220
|
import type {
|
|
@@ -320,5 +224,5 @@ import type {
|
|
|
320
224
|
WikiPage,
|
|
321
225
|
WikiIndex,
|
|
322
226
|
EscalationReason,
|
|
323
|
-
} from "rag-wiki";
|
|
227
|
+
} from "@xtatistix/rag-wiki";
|
|
324
228
|
```
|
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":"AAIA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAkB,MAAM,SAAS,CAAC;AAGrE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAIjB,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAkB;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAkB,MAAM,SAAS,CAAC;AAGrE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAIjB,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAkB;IAEpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;gBAEvC,MAAM,EAAE,aAAa;IAsBjC,OAAO,CAAC,gBAAgB;IAUxB;;;;;;OAMG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,MAAM,CAAC;IAKlB;;;;;;OAMG;IACG,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC,WAAW,CAAC;CAmDxB;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE5D"}
|
package/dist/index.js
CHANGED
|
@@ -17,6 +17,7 @@ Object.defineProperty(exports, "PresignedAdapter", { enumerable: true, get: func
|
|
|
17
17
|
class RagWiki {
|
|
18
18
|
constructor(config) {
|
|
19
19
|
this.defaultProjectId = config.projectId;
|
|
20
|
+
this.globalProjectId = config.globalProjectId;
|
|
20
21
|
this.adapter = config.adapter ?? new local_1.LocalAdapter(config.rawPath ?? "./raw");
|
|
21
22
|
this.reader = new wiki_reader_1.WikiReader(this.adapter);
|
|
22
23
|
this.ingester = new ingest_1.IngestEngine(this.adapter);
|
|
@@ -56,12 +57,40 @@ class RagWiki {
|
|
|
56
57
|
*/
|
|
57
58
|
async ask(question, options) {
|
|
58
59
|
const id = this.resolveProjectId(options?.projectId);
|
|
59
|
-
const index = await
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
60
|
+
const [index, guideline] = await Promise.all([
|
|
61
|
+
this.reader.loadIndex(id),
|
|
62
|
+
this.reader.loadGuideline(id),
|
|
63
|
+
]);
|
|
64
|
+
let allPages = index.pages;
|
|
65
|
+
let mergedGuideline = guideline;
|
|
66
|
+
if (this.globalProjectId !== undefined && this.globalProjectId !== id) {
|
|
67
|
+
const [globalIndex, globalGuideline] = await Promise.all([
|
|
68
|
+
this.reader.loadIndex(this.globalProjectId),
|
|
69
|
+
this.reader.loadGuideline(this.globalProjectId),
|
|
70
|
+
]);
|
|
71
|
+
// Merge global pages, avoiding duplicates by path
|
|
72
|
+
const existingPaths = new Set(index.pages.map((p) => p.path));
|
|
73
|
+
const newGlobalPages = globalIndex.pages.filter((p) => !existingPaths.has(p.path));
|
|
74
|
+
allPages = [...index.pages, ...newGlobalPages];
|
|
75
|
+
if (globalGuideline) {
|
|
76
|
+
mergedGuideline = mergedGuideline
|
|
77
|
+
? `${mergedGuideline}\n\n---\n\n${globalGuideline}`
|
|
78
|
+
: globalGuideline;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
const selectedPaths = await this.engine.selectPages(question, allPages);
|
|
82
|
+
const paths = selectedPaths.length > 0 ? selectedPaths : allPages.map((p) => p.path);
|
|
83
|
+
// Load pages from the correct index (project or global)
|
|
84
|
+
const projectPaths = paths.filter((p) => index.pages.some((ip) => ip.path === p));
|
|
85
|
+
const globalPaths = paths.filter((p) => !index.pages.some((ip) => ip.path === p));
|
|
86
|
+
const [projectPages, globalPages] = await Promise.all([
|
|
87
|
+
this.reader.loadPages(index, projectPaths),
|
|
88
|
+
this.globalProjectId !== undefined && globalPaths.length > 0
|
|
89
|
+
? this.reader.loadPages(await this.reader.loadIndex(this.globalProjectId), globalPaths)
|
|
90
|
+
: Promise.resolve([]),
|
|
91
|
+
]);
|
|
92
|
+
const pages = [...projectPages, ...globalPages];
|
|
93
|
+
const result = await this.engine.query(question, pages, mergedGuideline, id);
|
|
65
94
|
this.logger.appendQuery(id, question, result).catch(() => { });
|
|
66
95
|
return result;
|
|
67
96
|
}
|
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/dist/types.d.ts
CHANGED
|
@@ -28,6 +28,12 @@ export interface RagWikiConfig {
|
|
|
28
28
|
* Resolved relative to process.cwd() if not absolute.
|
|
29
29
|
*/
|
|
30
30
|
rawPath?: string;
|
|
31
|
+
/**
|
|
32
|
+
* Project ID for shared/global knowledge pages (e.g. reporting guidelines,
|
|
33
|
+
* phrase banks). These pages are merged into every ask() call regardless of
|
|
34
|
+
* the per-call projectId, so they are always available as context.
|
|
35
|
+
*/
|
|
36
|
+
globalProjectId?: string | number;
|
|
31
37
|
}
|
|
32
38
|
export interface WikiPage {
|
|
33
39
|
/** Relative path within the project wiki (e.g. "wiki/concept-rag.md") */
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3C,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD,0DAA0D;IAC1D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACzC;AAID,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3C,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD,0DAA0D;IAC1D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACzC;AAID,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAID,MAAM,WAAW,QAAQ;IACvB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,uCAAuC;IACvC,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAID,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,sBAAsB,GACtB,qBAAqB,GACrB,UAAU,CAAC;AAEf,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAElB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IAErB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}
|