@tangle-network/agent-knowledge 0.1.0

package/dist/index.js

@@ -0,0 +1,219 @@
+import {
+  WIKILINK_REGEX,
+  addSourcePath,
+  applyKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocksFile,
+  buildKnowledgeGraph,
+  buildKnowledgeIndex,
+  explainKnowledgeTarget,
+  extractWikilinks,
+  formatFrontmatter,
+  initKnowledgeBase,
+  inspectKnowledgeIndex,
+  isSafeKnowledgePath,
+  layoutFor,
+  lintKnowledgeIndex,
+  loadKnowledgePages,
+  loadSourceRegistry,
+  mediaTypeFor,
+  normalizeLinkTarget,
+  parseFrontmatter,
+  parseKnowledgeWriteBlocks,
+  reciprocalRankFusion,
+  searchKnowledge,
+  sha256,
+  slugify,
+  sourceRegistryPath,
+  stableId,
+  textSourceAdapter,
+  tokenizeQuery,
+  writeJson,
+  writeKnowledgeIndex,
+  writeSourceRegistry
+} from "./chunk-XDXIBHPS.js";
+
+// src/chunking.ts
+var DEFAULT_OPTIONS = {
+  targetChars: 1e3,
+  maxChars: 1500,
+  minChars: 160,
+  overlapChars: 180
+};
+function chunkMarkdown(content, options) {
+  const opts = normalizeOptions({ ...DEFAULT_OPTIONS, ...options ?? {} });
+  const { body, bodyOffset } = stripFrontmatter(content);
+  if (body.trim() === "") return [];
+  const sections = splitSections(body, bodyOffset);
+  const chunks = [];
+  for (const section of sections) {
+    for (const part of chunkText(section.text, opts)) {
+      const start = section.start + part.start;
+      chunks.push({
+        index: chunks.length,
+        text: part.text,
+        headingPath: section.headingPath,
+        charStart: start,
+        charEnd: start + part.text.length,
+        oversized: part.text.length > opts.maxChars
+      });
+    }
+  }
+  return chunks;
+}
+function stripFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) return { body: normalized, bodyOffset: 0 };
+  const match = /^---\n[\s\S]*?\n---\s*\n?/.exec(normalized);
+  if (!match) return { body: normalized, bodyOffset: 0 };
+  return { body: normalized.slice(match[0].length), bodyOffset: match[0].length };
+}
+function normalizeOptions(opts) {
+  if (opts.maxChars < opts.targetChars) opts.maxChars = opts.targetChars;
+  if (opts.overlapChars >= opts.targetChars) opts.overlapChars = Math.floor(opts.targetChars / 2);
+  return opts;
+}
+function splitSections(body, bodyOffset) {
+  const lines = body.split("\n");
+  const sections = [];
+  const headings = {};
+  let current = { lines: [], start: bodyOffset, headingPath: "" };
+  let cursor = bodyOffset;
+  let fence = null;
+  const flush = () => {
+    const text = current.lines.join("\n");
+    if (text.trim() !== "") sections.push({ text, start: current.start, headingPath: current.headingPath });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineLen = line.length + (i < lines.length - 1 ? 1 : 0);
+    const fenceMatch = /^(`{3,}|~{3,})/.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      fence = fence === null ? marker : line.startsWith(fence) ? null : fence;
+      current.lines.push(line);
+      cursor += lineLen;
+      continue;
+    }
+    const heading = fence === null ? /^(#{1,6})\s+(.+?)\s*$/.exec(line) : null;
+    if (heading) {
+      flush();
+      const level = heading[1].length;
+      headings[level] = heading[2].trim();
+      for (let next = level + 1; next <= 6; next++) delete headings[next];
+      current = {
+        lines: [line],
+        start: cursor,
+        headingPath: Object.entries(headings).sort(([a], [b]) => Number(a) - Number(b)).map(([levelText, title]) => `${"#".repeat(Number(levelText))} ${title}`).join(" > ")
+      };
+      cursor += lineLen;
+      continue;
+    }
+    current.lines.push(line);
+    cursor += lineLen;
+  }
+  flush();
+  return sections;
+}
+function chunkText(text, opts) {
+  if (text.length <= opts.targetChars) return [{ text, start: 0 }];
+  const atoms = splitAtoms(text);
+  const chunks = [];
+  let buffer = "";
+  let bufferStart = 0;
+  for (const atom of atoms) {
+    if (buffer === "") bufferStart = atom.start;
+    if (buffer.length > 0 && buffer.length + atom.text.length > opts.targetChars) {
+      chunks.push({ text: buffer.trimEnd(), start: bufferStart });
+      const overlap = buffer.slice(Math.max(0, buffer.length - opts.overlapChars));
+      buffer = overlap + atom.text;
+      bufferStart = Math.max(bufferStart, atom.start - overlap.length);
+    } else {
+      buffer += atom.text;
+    }
+  }
+  if (buffer.trim() !== "") chunks.push({ text: buffer.trimEnd(), start: bufferStart });
+  return mergeTinyChunks(chunks, opts);
+}
+function splitAtoms(text) {
+  const parts = [];
+  const paragraphs = text.split(/(\n\s*\n)/);
+  let cursor = 0;
+  for (let i = 0; i < paragraphs.length; i += 2) {
+    const paragraph = (paragraphs[i] ?? "") + (paragraphs[i + 1] ?? "");
+    if (paragraph === "") continue;
+    parts.push({ text: paragraph, start: cursor });
+    cursor += paragraph.length;
+  }
+  return parts;
+}
+function mergeTinyChunks(chunks, opts) {
+  const out = [];
+  for (const chunk of chunks) {
+    const prev = out[out.length - 1];
+    if (prev && chunk.text.length < opts.minChars && prev.text.length + chunk.text.length <= opts.maxChars) {
+      prev.text = `${prev.text}
+
+${chunk.text}`;
+    } else {
+      out.push({ ...chunk });
+    }
+  }
+  return out;
+}
+
+// src/optimization.ts
+import {
+  runMultiShotOptimization
+} from "@tangle-network/agent-eval";
+async function runKnowledgeBaseOptimization(config) {
+  return runMultiShotOptimization({
+    ...config,
+    target: config.target ?? "agent-knowledge-base"
+  });
+}
+function knowledgeVariantFromCandidate(candidate, options = {}) {
+  return {
+    id: options.id ?? candidate.id,
+    label: options.label ?? candidate.id,
+    generation: options.generation ?? 0,
+    payload: candidate
+  };
+}
+export {
+  WIKILINK_REGEX,
+  addSourcePath,
+  applyKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocksFile,
+  buildKnowledgeGraph,
+  buildKnowledgeIndex,
+  chunkMarkdown,
+  explainKnowledgeTarget,
+  extractWikilinks,
+  formatFrontmatter,
+  initKnowledgeBase,
+  inspectKnowledgeIndex,
+  isSafeKnowledgePath,
+  knowledgeVariantFromCandidate,
+  layoutFor,
+  lintKnowledgeIndex,
+  loadKnowledgePages,
+  loadSourceRegistry,
+  mediaTypeFor,
+  normalizeLinkTarget,
+  parseFrontmatter,
+  parseKnowledgeWriteBlocks,
+  reciprocalRankFusion,
+  runKnowledgeBaseOptimization,
+  searchKnowledge,
+  sha256,
+  slugify,
+  sourceRegistryPath,
+  stableId,
+  stripFrontmatter,
+  textSourceAdapter,
+  tokenizeQuery,
+  writeJson,
+  writeKnowledgeIndex,
+  writeSourceRegistry
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chunking.ts","../src/optimization.ts"],"sourcesContent":["export interface ChunkingOptions {\n  targetChars: number\n  maxChars: number\n  minChars: number\n  overlapChars: number\n}\n\nexport interface KnowledgeChunk {\n  index: number\n  text: string\n  headingPath: string\n  charStart: number\n  charEnd: number\n  oversized: boolean\n}\n\nconst DEFAULT_OPTIONS: ChunkingOptions = {\n  targetChars: 1000,\n  maxChars: 1500,\n  minChars: 160,\n  overlapChars: 180,\n}\n\nexport function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[] {\n  const opts = normalizeOptions({ ...DEFAULT_OPTIONS, ...(options ?? {}) })\n  const { body, bodyOffset } = stripFrontmatter(content)\n  if (body.trim() === '') return []\n\n  const sections = splitSections(body, bodyOffset)\n  const chunks: KnowledgeChunk[] = []\n  for (const section of sections) {\n    for (const part of chunkText(section.text, opts)) {\n      const start = section.start + part.start\n      chunks.push({\n        index: chunks.length,\n        text: part.text,\n        headingPath: section.headingPath,\n        charStart: start,\n        charEnd: start + part.text.length,\n        oversized: part.text.length > opts.maxChars,\n      })\n    }\n  }\n  return chunks\n}\n\nexport function stripFrontmatter(content: string): { body: string; bodyOffset: number } {\n  const normalized = content.replace(/\\r\\n/g, '\\n')\n  if (!normalized.startsWith('---\\n')) return { body: normalized, bodyOffset: 0 }\n  const match = /^---\\n[\\s\\S]*?\\n---\\s*\\n?/.exec(normalized)\n  if (!match) return { body: normalized, bodyOffset: 0 }\n  return { body: normalized.slice(match[0].length), bodyOffset: match[0].length }\n}\n\nfunction normalizeOptions(opts: ChunkingOptions): ChunkingOptions {\n  if (opts.maxChars < opts.targetChars) opts.maxChars = opts.targetChars\n  if (opts.overlapChars >= opts.targetChars) opts.overlapChars = Math.floor(opts.targetChars / 2)\n  return opts\n}\n\ninterface Section {\n  text: string\n  start: number\n  headingPath: string\n}\n\nfunction splitSections(body: string, bodyOffset: number): Section[] {\n  const lines = body.split('\\n')\n  const sections: Section[] = []\n  const headings: Record<number, string> = {}\n  let current: { lines: string[]; start: number; headingPath: string } = { lines: [], start: bodyOffset, headingPath: '' }\n  let cursor = bodyOffset\n  let fence: string | null = null\n\n  const flush = () => {\n    const text = current.lines.join('\\n')\n    if (text.trim() !== '') sections.push({ text, start: current.start, headingPath: current.headingPath })\n  }\n\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i]!\n    const lineLen = line.length + (i < lines.length - 1 ? 1 : 0)\n    const fenceMatch = /^(`{3,}|~{3,})/.exec(line)\n    if (fenceMatch) {\n      const marker = fenceMatch[1]!\n      fence = fence === null ? marker : line.startsWith(fence) ? null : fence\n      current.lines.push(line)\n      cursor += lineLen\n      continue\n    }\n    const heading = fence === null ? /^(#{1,6})\\s+(.+?)\\s*$/.exec(line) : null\n    if (heading) {\n      flush()\n      const level = heading[1]!.length\n      headings[level] = heading[2]!.trim()\n      for (let next = level + 1; next <= 6; next++) delete headings[next]\n      current = {\n        lines: [line],\n        start: cursor,\n        headingPath: Object.entries(headings)\n          .sort(([a], [b]) => Number(a) - Number(b))\n          .map(([levelText, title]) => `${'#'.repeat(Number(levelText))} ${title}`)\n          .join(' > '),\n      }\n      cursor += lineLen\n      continue\n    }\n    current.lines.push(line)\n    cursor += lineLen\n  }\n  flush()\n  return sections\n}\n\nfunction chunkText(text: string, opts: ChunkingOptions): Array<{ text: string; start: number }> {\n  if (text.length <= opts.targetChars) return [{ text, start: 0 }]\n  const atoms = splitAtoms(text)\n  const chunks: Array<{ text: string; start: number }> = []\n  let buffer = ''\n  let bufferStart = 0\n  for (const atom of atoms) {\n    if (buffer === '') bufferStart = atom.start\n    if (buffer.length > 0 && buffer.length + atom.text.length > opts.targetChars) {\n      chunks.push({ text: buffer.trimEnd(), start: bufferStart })\n      const overlap = buffer.slice(Math.max(0, buffer.length - opts.overlapChars))\n      buffer = overlap + atom.text\n      bufferStart = Math.max(bufferStart, atom.start - overlap.length)\n    } else {\n      buffer += atom.text\n    }\n  }\n  if (buffer.trim() !== '') chunks.push({ text: buffer.trimEnd(), start: bufferStart })\n  return mergeTinyChunks(chunks, opts)\n}\n\nfunction splitAtoms(text: string): Array<{ text: string; start: number }> {\n  const parts: Array<{ text: string; start: number }> = []\n  const paragraphs = text.split(/(\\n\\s*\\n)/)\n  let cursor = 0\n  for (let i = 0; i < paragraphs.length; i += 2) {\n    const paragraph = (paragraphs[i] ?? '') + (paragraphs[i + 1] ?? '')\n    if (paragraph === '') continue\n    parts.push({ text: paragraph, start: cursor })\n    cursor += paragraph.length\n  }\n  return parts\n}\n\nfunction mergeTinyChunks(chunks: Array<{ text: string; start: number }>, opts: ChunkingOptions): Array<{ text: string; start: number }> {\n  const out: Array<{ text: string; start: number }> = []\n  for (const chunk of chunks) {\n    const prev = out[out.length - 1]\n    if (prev && chunk.text.length < opts.minChars && prev.text.length + chunk.text.length <= opts.maxChars) {\n      prev.text = `${prev.text}\\n\\n${chunk.text}`\n    } else {\n      out.push({ ...chunk })\n    }\n  }\n  return out\n}\n","import {\n  runMultiShotOptimization,\n  type MultiShotMutateAdapter,\n  type MultiShotOptimizationConfig,\n  type MultiShotOptimizationResult,\n  type MultiShotRunner,\n  type MultiShotScorer,\n  type MultiShotVariant,\n} from '@tangle-network/agent-eval'\nimport type { KnowledgeBaseCandidate } from './types'\n\nexport type KnowledgeBaseVariant = MultiShotVariant<KnowledgeBaseCandidate>\n\nexport interface KnowledgeOptimizationConfig\n  extends Omit<\n    MultiShotOptimizationConfig<KnowledgeBaseCandidate>,\n    'runner' | 'scorer' | 'mutateAdapter' | 'target'\n  > {\n  target?: string\n  runner: MultiShotRunner<KnowledgeBaseCandidate>\n  scorer: MultiShotScorer<KnowledgeBaseCandidate>\n  mutateAdapter: MultiShotMutateAdapter<KnowledgeBaseCandidate>\n}\n\nexport async function runKnowledgeBaseOptimization(\n  config: KnowledgeOptimizationConfig,\n): Promise<MultiShotOptimizationResult<KnowledgeBaseCandidate>> {\n  return runMultiShotOptimization<KnowledgeBaseCandidate>({\n    ...config,\n    target: config.target ?? 'agent-knowledge-base',\n  })\n}\n\nexport function knowledgeVariantFromCandidate(\n  candidate: KnowledgeBaseCandidate,\n  options: { id?: string; label?: string; generation?: number } = {},\n): KnowledgeBaseVariant {\n  return {\n    id: options.id ?? candidate.id,\n    label: options.label ?? candidate.id,\n    generation: options.generation ?? 0,\n    payload: candidate,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types-C1FBNRIN.d.ts

@@ -0,0 +1,135 @@
+type KnowledgeId = string;
+interface SourceAnchor {
+    id: string;
+    sourceId: string;
+    label?: string;
+    page?: number;
+    lineStart?: number;
+    lineEnd?: number;
+    charStart?: number;
+    charEnd?: number;
+    timestampMs?: number;
+    metadata?: Record<string, unknown>;
+}
+interface SourceRecord {
+    id: KnowledgeId;
+    uri: string;
+    title?: string;
+    mediaType?: string;
+    contentHash: string;
+    text?: string;
+    anchors?: SourceAnchor[];
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+interface SourceRegistry {
+    generatedAt: string;
+    sources: SourceRecord[];
+}
+interface ClaimRef {
+    sourceId: string;
+    anchorId?: string;
+    quote?: string;
+}
+interface KnowledgeClaim {
+    id: KnowledgeId;
+    text: string;
+    refs: ClaimRef[];
+    confidence?: number;
+    status?: 'draft' | 'active' | 'superseded' | 'rejected';
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeRelation {
+    sourceId: KnowledgeId;
+    targetId: KnowledgeId;
+    predicate: string;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeUnit {
+    id: KnowledgeId;
+    title: string;
+    text: string;
+    claims?: KnowledgeClaim[];
+    relations?: KnowledgeRelation[];
+    sourceIds?: string[];
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    updatedAt?: string;
+}
+interface KnowledgePage {
+    id: KnowledgeId;
+    path: string;
+    title: string;
+    text: string;
+    frontmatter: Record<string, unknown>;
+    sourceIds: string[];
+    tags: string[];
+    outLinks: string[];
+}
+interface KnowledgeGraphNode {
+    id: KnowledgeId;
+    title: string;
+    path: string;
+    tags: string[];
+    sourceIds: string[];
+    outDegree: number;
+    inDegree: number;
+}
+interface KnowledgeGraphEdge {
+    source: KnowledgeId;
+    target: KnowledgeId;
+    weight: number;
+    reasons: string[];
+}
+interface KnowledgeGraph {
+    nodes: KnowledgeGraphNode[];
+    edges: KnowledgeGraphEdge[];
+}
+interface KnowledgeIndex {
+    root: string;
+    generatedAt: string;
+    sources: SourceRecord[];
+    pages: KnowledgePage[];
+    graph: KnowledgeGraph;
+}
+interface KnowledgeSearchResult {
+    page: KnowledgePage;
+    score: number;
+    rank: number;
+    snippet: string;
+    reasons: string[];
+}
+interface KnowledgeLintFinding {
+    type: 'broken-link' | 'orphan' | 'no-outlinks' | 'uncited-claim' | 'missing-source' | 'duplicate-title';
+    severity: 'info' | 'warning' | 'error';
+    page?: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgePolicy {
+    id: string;
+    description?: string;
+    requiredCitationRate?: number;
+    allowedPathPrefixes?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeBaseCandidate {
+    id: KnowledgeId;
+    units: KnowledgeUnit[];
+    retrievalPolicy?: string;
+    synthesisPolicy?: string;
+    questionPolicy?: string;
+    updatePolicy?: string;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeWriteBlock {
+    path: string;
+    content: string;
+}
+interface KnowledgeWriteParseResult {
+    blocks: KnowledgeWriteBlock[];
+    warnings: string[];
+}
+
+export type { ClaimRef as C, KnowledgeGraphEdge as K, SourceRecord as S, KnowledgeGraphNode as a, KnowledgeGraph as b, KnowledgeWriteParseResult as c, KnowledgePage as d, SourceRegistry as e, KnowledgeIndex as f, KnowledgeSearchResult as g, KnowledgeLintFinding as h, KnowledgeBaseCandidate as i, KnowledgeClaim as j, KnowledgeId as k, KnowledgePolicy as l, KnowledgeRelation as m, KnowledgeUnit as n, KnowledgeWriteBlock as o, SourceAnchor as p };

package/dist/viz/index.d.ts

@@ -0,0 +1,37 @@
+import { K as KnowledgeGraphEdge, a as KnowledgeGraphNode, b as KnowledgeGraph } from '../types-C1FBNRIN.js';
+
+interface KnowledgeVizNode extends KnowledgeGraphNode {
+    degree: number;
+    community: number;
+}
+interface KnowledgeVizEdge extends KnowledgeGraphEdge {
+    id: string;
+}
+interface KnowledgeCommunity {
+    id: number;
+    nodeIds: string[];
+    topTitles: string[];
+    cohesion: number;
+}
+interface KnowledgeVizGraph {
+    nodes: KnowledgeVizNode[];
+    edges: KnowledgeVizEdge[];
+    communities: KnowledgeCommunity[];
+}
+interface KnowledgeGap {
+    type: 'isolated-node' | 'sparse-community' | 'bridge-node';
+    title: string;
+    nodeIds: string[];
+    suggestion: string;
+}
+interface SurprisingConnection {
+    source: KnowledgeVizNode;
+    target: KnowledgeVizNode;
+    score: number;
+    reasons: string[];
+}
+declare function toKnowledgeVizGraph(graph: KnowledgeGraph): KnowledgeVizGraph;
+declare function detectKnowledgeGaps(graph: KnowledgeVizGraph, limit?: number): KnowledgeGap[];
+declare function findSurprisingConnections(graph: KnowledgeVizGraph, limit?: number): SurprisingConnection[];
+
+export { type KnowledgeCommunity, type KnowledgeGap, type KnowledgeVizEdge, type KnowledgeVizGraph, type KnowledgeVizNode, type SurprisingConnection, detectKnowledgeGaps, findSurprisingConnections, toKnowledgeVizGraph };

package/dist/viz/index.js

@@ -0,0 +1,11 @@
+import {
+  detectKnowledgeGaps,
+  findSurprisingConnections,
+  toKnowledgeVizGraph
+} from "../chunk-TXNYP4WI.js";
+export {
+  detectKnowledgeGaps,
+  findSurprisingConnections,
+  toKnowledgeVizGraph
+};
+//# sourceMappingURL=index.js.map

package/dist/viz/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/architecture.md

@@ -0,0 +1,52 @@
+# Architecture
+
+`@tangle-network/agent-knowledge` is a domain-agnostic knowledge growth layer for agents.
+
+It does not try to be a vector database, a RAG framework, or a product-specific wiki. It owns the small set of primitives every serious agent knowledge system needs:
+
+- immutable source records
+- generated knowledge pages and units
+- claims with source references
+- deterministic indexing, graph construction, search, and lint
+- safe LLM write proposals
+- eval-gated optimization through `@tangle-network/agent-eval`
+- visualization DTOs under the `/viz` subpath
+
+## Boundaries
+
+`agent-eval` owns traces, ASI, multi-shot optimization, run records, and promotion gates.
+
+`agent-knowledge` owns sources, claims, pages, graph/search/lint, and knowledge base candidates. It calls `agent-eval` instead of reimplementing evaluation.
+
+Product apps own domain policies, source adapters, task corpora, and promotion decisions.
+
+## Runtime Loop
+
+1. Normalize sources into immutable source records.
+2. Generate staged knowledge write proposals.
+3. Parse write proposals through the safe write protocol.
+4. Validate paths, citations, links, and schema.
+5. Index generated knowledge pages.
+6. Search and graph-lint the knowledge base.
+7. Evaluate candidate KB variants with `runKnowledgeBaseOptimization`.
+8. Promote only variants that pass downstream gates.
+
+## CLI
+
+The CLI is intentionally fast and local:
+
+```bash
+agent-knowledge init
+agent-knowledge source-add ./source.md
+agent-knowledge sources
+agent-knowledge apply-write-blocks ./proposal.txt
+agent-knowledge index
+agent-knowledge search "query"
+agent-knowledge inspect
+agent-knowledge explain knowledge/concepts/example.md
+agent-knowledge graph
+agent-knowledge lint
+agent-knowledge viz
+```
+
+It does not call an LLM. It operates over markdown and cached JSON indexes so fleet jobs and dev containers can use it cheaply.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tangle-network/agent-knowledge",
+  "version": "0.1.0",
+  "description": "Source-grounded, eval-gated knowledge growth primitives for agents.",
+  "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangle-network/agent-knowledge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tangle-network/agent-knowledge/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./viz": {
+      "types": "./dist/viz/index.d.ts",
+      "import": "./dist/viz/index.js",
+      "default": "./dist/viz/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "agent-knowledge": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepare": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tangle-network/agent-eval": "^0.19.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "packageManager": "pnpm@10.28.0"
+}