@tangle-network/agent-knowledge 4.0.0 → 4.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.
Files changed (35) hide show
  1. package/AGENTS.md +32 -18
  2. package/CHANGELOG.md +32 -0
  3. package/README.md +31 -19
  4. package/dist/benchmarks/index.d.ts +51 -3
  5. package/dist/benchmarks/index.js +1 -1
  6. package/dist/{chunk-EUAXSBMH.js → chunk-AKYJG2MR.js} +224 -224
  7. package/dist/chunk-AKYJG2MR.js.map +1 -0
  8. package/dist/{chunk-DW6APRTX.js → chunk-BBCIB4UL.js} +2486 -2457
  9. package/dist/chunk-BBCIB4UL.js.map +1 -0
  10. package/dist/{chunk-UWOTQNBI.js → chunk-CPMLJYA3.js} +1886 -1842
  11. package/dist/chunk-CPMLJYA3.js.map +1 -0
  12. package/dist/{chunk-WCYW2GDA.js → chunk-MYFM6LKH.js} +2 -2
  13. package/dist/chunk-MYFM6LKH.js.map +1 -0
  14. package/dist/cli.js +1 -1
  15. package/dist/index.d.ts +48 -52
  16. package/dist/index.js +2906 -2874
  17. package/dist/index.js.map +1 -1
  18. package/dist/memory/index.d.ts +129 -6
  19. package/dist/memory/index.js +2 -2
  20. package/dist/sources/index.d.ts +17 -33
  21. package/dist/sources/index.js +1 -1
  22. package/dist/{index-Bqg1mBPt.d.ts → types-DP38encz.d.ts} +127 -284
  23. package/docs/eval/investment-material-facts.md +28 -29
  24. package/docs/eval/rag-eval-roadmap.md +6 -5
  25. package/docs/results/adaptive.md +13 -13
  26. package/docs/results/claim-grounding.md +11 -11
  27. package/docs/results/cost-quality.md +4 -4
  28. package/docs/results/investment-thesis.md +56 -56
  29. package/docs/results/research-driving.md +54 -54
  30. package/docs/two-agent-research-ab.md +94 -94
  31. package/package.json +4 -7
  32. package/dist/chunk-DW6APRTX.js.map +0 -1
  33. package/dist/chunk-EUAXSBMH.js.map +0 -1
  34. package/dist/chunk-UWOTQNBI.js.map +0 -1
  35. package/dist/chunk-WCYW2GDA.js.map +0 -1
@@ -49,94 +49,6 @@ function anchorsForText(uri, text) {
49
49
  return anchors;
50
50
  }
51
51
 
52
- // src/wikilinks.ts
53
- var WIKILINK_REGEX = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g;
54
- function extractWikilinks(content) {
55
- const links = [];
56
- const regex = new RegExp(WIKILINK_REGEX.source, "g");
57
- let match;
58
- match = regex.exec(content);
59
- while (match !== null) {
60
- links.push(match[1].trim());
61
- match = regex.exec(content);
62
- }
63
- return [...new Set(links)];
64
- }
65
- function normalizeLinkTarget(target) {
66
- return target.trim().replace(/\.md$/i, "").toLowerCase().replace(/\s+/g, "-");
67
- }
68
-
69
- // src/graph.ts
70
- function buildKnowledgeGraph(pages) {
71
- const byId = /* @__PURE__ */ new Map();
72
- const bySlug = /* @__PURE__ */ new Map();
73
- for (const page of pages) {
74
- byId.set(page.id, page);
75
- bySlug.set(normalizeLinkTarget(page.id), page);
76
- bySlug.set(normalizeLinkTarget(page.title), page);
77
- bySlug.set(normalizeLinkTarget(page.path.split("/").pop().replace(/\.md$/, "")), page);
78
- }
79
- const incoming = /* @__PURE__ */ new Map();
80
- const outgoing = /* @__PURE__ */ new Map();
81
- const edgesByKey = /* @__PURE__ */ new Map();
82
- for (const page of pages) {
83
- outgoing.set(page.id, 0);
84
- incoming.set(page.id, 0);
85
- }
86
- for (const page of pages) {
87
- for (const raw of page.outLinks) {
88
- const target = bySlug.get(normalizeLinkTarget(raw));
89
- if (!target || target.id === page.id) continue;
90
- const key = `${page.id}->${target.id}`;
91
- const edge = edgesByKey.get(key);
92
- if (edge) edge.weight += 1;
93
- else
94
- edgesByKey.set(key, {
95
- source: page.id,
96
- target: target.id,
97
- weight: 1,
98
- reasons: ["wikilink"]
99
- });
100
- outgoing.set(page.id, (outgoing.get(page.id) ?? 0) + 1);
101
- incoming.set(target.id, (incoming.get(target.id) ?? 0) + 1);
102
- }
103
- }
104
- addSourceOverlapEdges(pages, edgesByKey);
105
- const nodes = pages.map((page) => ({
106
- id: page.id,
107
- title: page.title,
108
- path: page.path,
109
- tags: page.tags,
110
- sourceIds: page.sourceIds,
111
- outDegree: outgoing.get(page.id) ?? 0,
112
- inDegree: incoming.get(page.id) ?? 0
113
- }));
114
- return { nodes, edges: [...edgesByKey.values()].sort((a, b) => b.weight - a.weight) };
115
- }
116
- function addSourceOverlapEdges(pages, edges) {
117
- for (let i = 0; i < pages.length; i++) {
118
- for (let j = i + 1; j < pages.length; j++) {
119
- const a = pages[i];
120
- const b = pages[j];
121
- const overlap = a.sourceIds.filter((source) => b.sourceIds.includes(source));
122
- if (overlap.length === 0) continue;
123
- const key = `${a.id}->${b.id}`;
124
- const edge = edges.get(key);
125
- if (edge) {
126
- edge.weight += overlap.length * 0.5;
127
- edge.reasons.push("shared-source");
128
- } else {
129
- edges.set(key, {
130
- source: a.id,
131
- target: b.id,
132
- weight: overlap.length * 0.5,
133
- reasons: ["shared-source"]
134
- });
135
- }
136
- }
137
- }
138
- }
139
-
140
52
  // src/mutation-lock.ts
141
53
  import { AsyncLocalStorage } from "async_hooks";
142
54
  import { mkdir as mkdir2, readFile } from "fs/promises";
@@ -1249,129 +1161,6 @@ function isOdd(value) {
1249
1161
  return value % 2 === 1;
1250
1162
  }
1251
1163
 
1252
- // src/schemas.ts
1253
- import { z as z2 } from "zod";
1254
- var SourceAnchorSchema = z2.object({
1255
- id: z2.string().min(1),
1256
- sourceId: z2.string().min(1),
1257
- label: z2.string().optional(),
1258
- page: z2.number().int().positive().optional(),
1259
- lineStart: z2.number().int().positive().optional(),
1260
- lineEnd: z2.number().int().positive().optional(),
1261
- charStart: z2.number().int().nonnegative().optional(),
1262
- charEnd: z2.number().int().nonnegative().optional(),
1263
- timestampMs: z2.number().nonnegative().optional(),
1264
- metadata: z2.record(z2.string(), z2.unknown()).optional()
1265
- });
1266
- var SourceRecordSchema = z2.object({
1267
- id: z2.string().min(1),
1268
- uri: z2.string().min(1),
1269
- title: z2.string().optional(),
1270
- mediaType: z2.string().optional(),
1271
- contentHash: z2.string().min(16),
1272
- text: z2.string().optional(),
1273
- anchors: z2.array(SourceAnchorSchema).optional(),
1274
- validUntil: z2.iso.datetime().optional(),
1275
- lastVerifiedAt: z2.iso.datetime().optional(),
1276
- metadata: z2.record(z2.string(), z2.unknown()).optional(),
1277
- createdAt: z2.string().min(1)
1278
- });
1279
- var KnowledgePageSchema = z2.object({
1280
- id: z2.string().min(1),
1281
- path: z2.string().min(1),
1282
- title: z2.string().min(1),
1283
- text: z2.string(),
1284
- frontmatter: z2.record(z2.string(), z2.unknown()),
1285
- sourceIds: z2.array(z2.string()),
1286
- tags: z2.array(z2.string()),
1287
- outLinks: z2.array(z2.string())
1288
- });
1289
- var KnowledgeGraphNodeSchema = z2.object({
1290
- id: z2.string(),
1291
- title: z2.string(),
1292
- path: z2.string(),
1293
- tags: z2.array(z2.string()),
1294
- sourceIds: z2.array(z2.string()),
1295
- outDegree: z2.number().int().nonnegative(),
1296
- inDegree: z2.number().int().nonnegative()
1297
- });
1298
- var KnowledgeGraphEdgeSchema = z2.object({
1299
- source: z2.string(),
1300
- target: z2.string(),
1301
- weight: z2.number(),
1302
- reasons: z2.array(z2.string())
1303
- });
1304
- var KnowledgeIndexSchema = z2.object({
1305
- root: z2.string(),
1306
- generatedAt: z2.string(),
1307
- sources: z2.array(SourceRecordSchema),
1308
- pages: z2.array(KnowledgePageSchema),
1309
- graph: z2.object({
1310
- nodes: z2.array(KnowledgeGraphNodeSchema),
1311
- edges: z2.array(KnowledgeGraphEdgeSchema)
1312
- })
1313
- });
1314
- var KnowledgeEventSchema = z2.object({
1315
- id: z2.string().min(1),
1316
- type: z2.enum([
1317
- "source.added",
1318
- "proposal.applied",
1319
- "index.built",
1320
- "lint.run",
1321
- "optimization.run",
1322
- "release.promoted",
1323
- "release.rejected"
1324
- ]),
1325
- createdAt: z2.string().min(1),
1326
- actor: z2.string().optional(),
1327
- target: z2.string().optional(),
1328
- metadata: z2.record(z2.string(), z2.unknown()).optional()
1329
- });
1330
- var KnowledgeBaseCandidateSchema = z2.object({
1331
- id: z2.string().min(1),
1332
- units: z2.array(
1333
- z2.object({
1334
- id: z2.string().min(1),
1335
- title: z2.string().min(1),
1336
- text: z2.string(),
1337
- claims: z2.array(
1338
- z2.object({
1339
- id: z2.string().min(1),
1340
- text: z2.string().min(1),
1341
- refs: z2.array(
1342
- z2.object({
1343
- sourceId: z2.string().min(1),
1344
- anchorId: z2.string().optional(),
1345
- quote: z2.string().optional()
1346
- })
1347
- ),
1348
- confidence: z2.number().min(0).max(1).optional(),
1349
- status: z2.enum(["draft", "active", "superseded", "rejected"]).optional(),
1350
- metadata: z2.record(z2.string(), z2.unknown()).optional()
1351
- })
1352
- ).optional(),
1353
- relations: z2.array(
1354
- z2.object({
1355
- sourceId: z2.string(),
1356
- targetId: z2.string(),
1357
- predicate: z2.string(),
1358
- weight: z2.number().optional(),
1359
- metadata: z2.record(z2.string(), z2.unknown()).optional()
1360
- })
1361
- ).optional(),
1362
- sourceIds: z2.array(z2.string()).optional(),
1363
- tags: z2.array(z2.string()).optional(),
1364
- metadata: z2.record(z2.string(), z2.unknown()).optional(),
1365
- updatedAt: z2.string().optional()
1366
- })
1367
- ),
1368
- retrievalPolicy: z2.string().optional(),
1369
- synthesisPolicy: z2.string().optional(),
1370
- questionPolicy: z2.string().optional(),
1371
- updatePolicy: z2.string().optional(),
1372
- metadata: z2.record(z2.string(), z2.unknown()).optional()
1373
- });
1374
-
1375
1164
  // src/frontmatter.ts
1376
1165
  function parseFrontmatter(content) {
1377
1166
  const normalized = content.replace(/\r\n/g, "\n");
@@ -1434,6 +1223,23 @@ function unquote(value) {
1434
1223
  return value.replace(/^['"]|['"]$/g, "");
1435
1224
  }
1436
1225
 
1226
+ // src/wikilinks.ts
1227
+ var WIKILINK_REGEX = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g;
1228
+ function extractWikilinks(content) {
1229
+ const links = [];
1230
+ const regex = new RegExp(WIKILINK_REGEX.source, "g");
1231
+ let match;
1232
+ match = regex.exec(content);
1233
+ while (match !== null) {
1234
+ links.push(match[1].trim());
1235
+ match = regex.exec(content);
1236
+ }
1237
+ return [...new Set(links)];
1238
+ }
1239
+ function normalizeLinkTarget(target) {
1240
+ return target.trim().replace(/\.md$/i, "").toLowerCase().replace(/\s+/g, "-");
1241
+ }
1242
+
1437
1243
  // src/store.ts
1438
1244
  import { join as join3 } from "path";
1439
1245
  function layoutFor(root) {
@@ -1545,6 +1351,200 @@ function firstHeading(body) {
1545
1351
  return /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
1546
1352
  }
1547
1353
 
1354
+ // src/graph.ts
1355
+ function buildKnowledgeGraph(pages) {
1356
+ const byId = /* @__PURE__ */ new Map();
1357
+ const bySlug = /* @__PURE__ */ new Map();
1358
+ for (const page of pages) {
1359
+ byId.set(page.id, page);
1360
+ bySlug.set(normalizeLinkTarget(page.id), page);
1361
+ bySlug.set(normalizeLinkTarget(page.title), page);
1362
+ bySlug.set(normalizeLinkTarget(page.path.split("/").pop().replace(/\.md$/, "")), page);
1363
+ }
1364
+ const incoming = /* @__PURE__ */ new Map();
1365
+ const outgoing = /* @__PURE__ */ new Map();
1366
+ const edgesByKey = /* @__PURE__ */ new Map();
1367
+ for (const page of pages) {
1368
+ outgoing.set(page.id, 0);
1369
+ incoming.set(page.id, 0);
1370
+ }
1371
+ for (const page of pages) {
1372
+ for (const raw of page.outLinks) {
1373
+ const target = bySlug.get(normalizeLinkTarget(raw));
1374
+ if (!target || target.id === page.id) continue;
1375
+ const key = `${page.id}->${target.id}`;
1376
+ const edge = edgesByKey.get(key);
1377
+ if (edge) edge.weight += 1;
1378
+ else
1379
+ edgesByKey.set(key, {
1380
+ source: page.id,
1381
+ target: target.id,
1382
+ weight: 1,
1383
+ reasons: ["wikilink"]
1384
+ });
1385
+ outgoing.set(page.id, (outgoing.get(page.id) ?? 0) + 1);
1386
+ incoming.set(target.id, (incoming.get(target.id) ?? 0) + 1);
1387
+ }
1388
+ }
1389
+ addSourceOverlapEdges(pages, edgesByKey);
1390
+ const nodes = pages.map((page) => ({
1391
+ id: page.id,
1392
+ title: page.title,
1393
+ path: page.path,
1394
+ tags: page.tags,
1395
+ sourceIds: page.sourceIds,
1396
+ outDegree: outgoing.get(page.id) ?? 0,
1397
+ inDegree: incoming.get(page.id) ?? 0
1398
+ }));
1399
+ return { nodes, edges: [...edgesByKey.values()].sort((a, b) => b.weight - a.weight) };
1400
+ }
1401
+ function addSourceOverlapEdges(pages, edges) {
1402
+ for (let i = 0; i < pages.length; i++) {
1403
+ for (let j = i + 1; j < pages.length; j++) {
1404
+ const a = pages[i];
1405
+ const b = pages[j];
1406
+ const overlap = a.sourceIds.filter((source) => b.sourceIds.includes(source));
1407
+ if (overlap.length === 0) continue;
1408
+ const key = `${a.id}->${b.id}`;
1409
+ const edge = edges.get(key);
1410
+ if (edge) {
1411
+ edge.weight += overlap.length * 0.5;
1412
+ edge.reasons.push("shared-source");
1413
+ } else {
1414
+ edges.set(key, {
1415
+ source: a.id,
1416
+ target: b.id,
1417
+ weight: overlap.length * 0.5,
1418
+ reasons: ["shared-source"]
1419
+ });
1420
+ }
1421
+ }
1422
+ }
1423
+ }
1424
+
1425
+ // src/schemas.ts
1426
+ import { z as z2 } from "zod";
1427
+ var SourceAnchorSchema = z2.object({
1428
+ id: z2.string().min(1),
1429
+ sourceId: z2.string().min(1),
1430
+ label: z2.string().optional(),
1431
+ page: z2.number().int().positive().optional(),
1432
+ lineStart: z2.number().int().positive().optional(),
1433
+ lineEnd: z2.number().int().positive().optional(),
1434
+ charStart: z2.number().int().nonnegative().optional(),
1435
+ charEnd: z2.number().int().nonnegative().optional(),
1436
+ timestampMs: z2.number().nonnegative().optional(),
1437
+ metadata: z2.record(z2.string(), z2.unknown()).optional()
1438
+ });
1439
+ var SourceRecordSchema = z2.object({
1440
+ id: z2.string().min(1),
1441
+ uri: z2.string().min(1),
1442
+ title: z2.string().optional(),
1443
+ mediaType: z2.string().optional(),
1444
+ contentHash: z2.string().min(16),
1445
+ text: z2.string().optional(),
1446
+ anchors: z2.array(SourceAnchorSchema).optional(),
1447
+ validUntil: z2.iso.datetime().optional(),
1448
+ lastVerifiedAt: z2.iso.datetime().optional(),
1449
+ metadata: z2.record(z2.string(), z2.unknown()).optional(),
1450
+ createdAt: z2.string().min(1)
1451
+ });
1452
+ var KnowledgePageSchema = z2.object({
1453
+ id: z2.string().min(1),
1454
+ path: z2.string().min(1),
1455
+ title: z2.string().min(1),
1456
+ text: z2.string(),
1457
+ frontmatter: z2.record(z2.string(), z2.unknown()),
1458
+ sourceIds: z2.array(z2.string()),
1459
+ tags: z2.array(z2.string()),
1460
+ outLinks: z2.array(z2.string())
1461
+ });
1462
+ var KnowledgeGraphNodeSchema = z2.object({
1463
+ id: z2.string(),
1464
+ title: z2.string(),
1465
+ path: z2.string(),
1466
+ tags: z2.array(z2.string()),
1467
+ sourceIds: z2.array(z2.string()),
1468
+ outDegree: z2.number().int().nonnegative(),
1469
+ inDegree: z2.number().int().nonnegative()
1470
+ });
1471
+ var KnowledgeGraphEdgeSchema = z2.object({
1472
+ source: z2.string(),
1473
+ target: z2.string(),
1474
+ weight: z2.number(),
1475
+ reasons: z2.array(z2.string())
1476
+ });
1477
+ var KnowledgeIndexSchema = z2.object({
1478
+ root: z2.string(),
1479
+ generatedAt: z2.string(),
1480
+ sources: z2.array(SourceRecordSchema),
1481
+ pages: z2.array(KnowledgePageSchema),
1482
+ graph: z2.object({
1483
+ nodes: z2.array(KnowledgeGraphNodeSchema),
1484
+ edges: z2.array(KnowledgeGraphEdgeSchema)
1485
+ })
1486
+ });
1487
+ var KnowledgeEventSchema = z2.object({
1488
+ id: z2.string().min(1),
1489
+ type: z2.enum([
1490
+ "source.added",
1491
+ "proposal.applied",
1492
+ "index.built",
1493
+ "lint.run",
1494
+ "optimization.run",
1495
+ "release.promoted",
1496
+ "release.rejected"
1497
+ ]),
1498
+ createdAt: z2.string().min(1),
1499
+ actor: z2.string().optional(),
1500
+ target: z2.string().optional(),
1501
+ metadata: z2.record(z2.string(), z2.unknown()).optional()
1502
+ });
1503
+ var KnowledgeBaseCandidateSchema = z2.object({
1504
+ id: z2.string().min(1),
1505
+ units: z2.array(
1506
+ z2.object({
1507
+ id: z2.string().min(1),
1508
+ title: z2.string().min(1),
1509
+ text: z2.string(),
1510
+ claims: z2.array(
1511
+ z2.object({
1512
+ id: z2.string().min(1),
1513
+ text: z2.string().min(1),
1514
+ refs: z2.array(
1515
+ z2.object({
1516
+ sourceId: z2.string().min(1),
1517
+ anchorId: z2.string().optional(),
1518
+ quote: z2.string().optional()
1519
+ })
1520
+ ),
1521
+ confidence: z2.number().min(0).max(1).optional(),
1522
+ status: z2.enum(["draft", "active", "superseded", "rejected"]).optional(),
1523
+ metadata: z2.record(z2.string(), z2.unknown()).optional()
1524
+ })
1525
+ ).optional(),
1526
+ relations: z2.array(
1527
+ z2.object({
1528
+ sourceId: z2.string(),
1529
+ targetId: z2.string(),
1530
+ predicate: z2.string(),
1531
+ weight: z2.number().optional(),
1532
+ metadata: z2.record(z2.string(), z2.unknown()).optional()
1533
+ })
1534
+ ).optional(),
1535
+ sourceIds: z2.array(z2.string()).optional(),
1536
+ tags: z2.array(z2.string()).optional(),
1537
+ metadata: z2.record(z2.string(), z2.unknown()).optional(),
1538
+ updatedAt: z2.string().optional()
1539
+ })
1540
+ ),
1541
+ retrievalPolicy: z2.string().optional(),
1542
+ synthesisPolicy: z2.string().optional(),
1543
+ questionPolicy: z2.string().optional(),
1544
+ updatePolicy: z2.string().optional(),
1545
+ metadata: z2.record(z2.string(), z2.unknown()).optional()
1546
+ });
1547
+
1548
1548
  // src/sources.ts
1549
1549
  import { lstat as lstat2, readdir as readdir3, readFile as readFile2 } from "fs/promises";
1550
1550
  import { basename as basename2, join as join4, relative as relative2 } from "path";
@@ -2138,31 +2138,31 @@ export {
2138
2138
  finishKnowledgeFileTransaction,
2139
2139
  rollbackKnowledgeFileTransaction,
2140
2140
  assertKnowledgeMutationPath,
2141
- WIKILINK_REGEX,
2142
- extractWikilinks,
2143
- normalizeLinkTarget,
2144
- buildKnowledgeGraph,
2145
2141
  withKnowledgeMutation,
2146
2142
  inspectPendingKnowledgeMutation,
2147
2143
  recoverPendingKnowledgeMutation,
2148
2144
  withKnowledgeRead,
2149
2145
  acquireDurableFileLock,
2150
- SourceAnchorSchema,
2151
- SourceRecordSchema,
2152
- KnowledgePageSchema,
2153
- KnowledgeGraphNodeSchema,
2154
- KnowledgeGraphEdgeSchema,
2155
- KnowledgeIndexSchema,
2156
- KnowledgeEventSchema,
2157
- KnowledgeBaseCandidateSchema,
2158
2146
  parseFrontmatter,
2159
2147
  formatFrontmatter,
2148
+ WIKILINK_REGEX,
2149
+ extractWikilinks,
2150
+ normalizeLinkTarget,
2160
2151
  layoutFor,
2161
2152
  SCAFFOLD_PAGE_BASENAMES,
2162
2153
  isScaffoldPath,
2163
2154
  initKnowledgeBase,
2164
2155
  loadKnowledgePages,
2165
2156
  writeJson,
2157
+ buildKnowledgeGraph,
2158
+ SourceAnchorSchema,
2159
+ SourceRecordSchema,
2160
+ KnowledgePageSchema,
2161
+ KnowledgeGraphNodeSchema,
2162
+ KnowledgeGraphEdgeSchema,
2163
+ KnowledgeIndexSchema,
2164
+ KnowledgeEventSchema,
2165
+ KnowledgeBaseCandidateSchema,
2166
2166
  loadSourceRegistry,
2167
2167
  writeSourceRegistry,
2168
2168
  addSourcePath,
@@ -2180,4 +2180,4 @@ export {
2180
2180
  inspectKnowledgeIndex,
2181
2181
  explainKnowledgeTarget
2182
2182
  };
2183
- //# sourceMappingURL=chunk-EUAXSBMH.js.map
2183
+ //# sourceMappingURL=chunk-AKYJG2MR.js.map