@tangle-network/agent-knowledge 20.0.1 → 22.0.0

package/docs/improvement.md

@@ -0,0 +1,79 @@
+# Improve a live knowledge base
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Improve a live knowledge base
+
+`improveKnowledgeBase` creates an isolated candidate, runs your update callback, measures the candidate, and returns an exact candidate reference.
+It does not overwrite the live knowledge base.
+
+```ts
+import {
+  improveKnowledgeBase,
+  knowledgeImprovementCandidateRef,
+  promoteKnowledgeCandidate,
+} from '@tangle-network/agent-knowledge'
+
+const result = await improveKnowledgeBase({
+  root: './support-kb',
+  goal: 'Answer refund questions using the current policy',
+  implementationRef: 'git:0123456789abcdef0123456789abcdef01234567',
+  runId: 'refund-policy-2026-07',
+  maxCandidates: 3,
+  updateKnowledge: async ({ candidateRoot }) => {
+    await updateCandidate(candidateRoot) // Your code or agent writes only to this copy.
+    return { applied: true, summary: 'Updated refund knowledge' }
+  },
+  evaluate: ({ baselineRoot, candidateRoot }) =>
+    compareOnProductTasks({ baselineRoot, candidateRoot }),
+})
+
+if (result.candidate && result.evaluation?.passed) {
+  const candidate = knowledgeImprovementCandidateRef(result)
+  // Call this only after your application approves the measured candidate.
+  await promoteKnowledgeCandidate({ root: './support-kb', candidate })
+}
+```
+
+`updateCandidate` and `compareOnProductTasks` are application callbacks.
+The update can come from a research agent, a coding agent, a source connector, or deterministic code.
+The comparison must return the product measures that decide whether the change helped.
+
+Use the same `runId` and `implementationRef` to resume an interrupted run.
+Change `implementationRef` whenever callbacks, evaluation policy, models, indexes, or external configuration change.
+Reusing a run ID with a different implementation reference fails before cached work or callbacks run.
+Different run IDs create separate candidate workspaces, so workers can explore in parallel.
+Promotion checks the original base hash and rejects a stale candidate instead of replacing newer work.
+Candidate retries use `evaluateDevelopment` when provided, otherwise they use deterministic validation, readiness, and KB quality checks.
+Diagnosis runs before acquisition and updates, using development data only.
+Its findings and update results remain available to final answer checks and the promotion decision.
+Development evaluation must use only train or selection data.
+The configured `evaluate` callback and final RAG phases run once, on the first candidate that passes those development checks.
+A failed final evaluation ends the run instead of selecting another candidate against final data.
+
+The default evaluator reports only measured dimensions and averages those dimensions with equal weight.
+It omits `answer_quality` without answer evaluation, `promotion_decision` without a promotion decision, and `blocking_readiness` without blocking readiness requirements.
+Default evaluator version `2` records this weighting.
+Declare additional authoritative local state through `stateScope`:
+
+```ts
+const stateScope = { pagesDirectory: 'kb/pages', researchState: true }
+const result = await improveKnowledgeBase({ ...options, stateScope })
+const identity = await hashKnowledgeBase(root, stateScope)
+```
+
+The default scope remains `knowledge/`, `raw/`, and `.agent-knowledge/sources.json`.
+`pagesDirectory` replaces the default page directory for copying, indexing, hashing, and promotion.
+`researchState: true` also includes canonical `.agent-knowledge/claim-ledgers/` records and `.agent-knowledge/events.json`.
+The persisted run binds this scope, and resume rejects a different scope.
+Candidate materialization, selected changes, promotion, and restoration preserve the same declared state.
+Use `normalizeKnowledgeStateScope` when carrying this scope into another contract.
+Indexes, locks, transaction journals, retrieval artifacts, credentials outside declared content directories, and external memory providers remain outside this identity.
+Use the canonical `FileSystemKbStore({ root: candidateRoot })` for research records in update callbacks.
+Callbacks must bind external state separately and must not close over a shared mutable store when evaluating isolated candidates.
+A scoped KB hash does not identify an entire learner with external state.
+
+A candidate can pass structural checks without any task outcome evaluation; the metric notes state this limit.
+`candidate-ready` means the configured checks passed and the candidate remains detached from the live knowledge base.
+
+Candidate promotion currently requires Linux because it relies on Linux directory descriptors for exact file identity.

package/docs/memory.md

@@ -0,0 +1,12 @@
+# Integrate memory systems
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Integrate memory systems
+
+`@tangle-network/agent-knowledge/memory` defines `AgentMemoryAdapter` and adapters for Mem0, Graphiti, and Neo4j Agent Memory.
+The package is not a memory database.
+Install the provider you use, create its client, and pass that client to the adapter.
+
+The memory APIs support scoped reads and writes and isolated branches.
+Compare providers on product tasks with `@tangle-network/agent-eval` before changing production behavior.

package/docs/provenance.md

@@ -0,0 +1,50 @@
+# Prove what the agent saw and used
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Prove what the agent saw and used
+
+A page existing in a knowledge base, a page appearing in retrieval results, and a page influencing a decision are three different facts. The receipt APIs preserve those joins without pretending they prove the page is true or that it improved the outcome.
+
+```ts
+import {
+  createKnowledgeRetrievalReceipt,
+  createKnowledgeUseReceipt,
+  createKnowledgeVisibilitySnapshot,
+  encodeKnowledgeVisibilitySnapshot,
+  KNOWLEDGE_SEARCH_RETRIEVER_ID,
+  knowledgeVisibilityArtifactRef,
+} from '@tangle-network/agent-knowledge'
+
+const visibility = createKnowledgeVisibilitySnapshot(await runStores.loadChain(runId))
+const bytes = encodeKnowledgeVisibilitySnapshot(visibility)
+await artifacts.put('artifact://run/visibility.json', bytes)
+
+const retrieval = createKnowledgeRetrievalReceipt({
+  runId,
+  query: 'prior verifier obstruction',
+  retriever: { id: KNOWLEDGE_SEARCH_RETRIEVER_ID, version: '1.0.0', configDigest },
+  visibility,
+  visibilityArtifact: knowledgeVisibilityArtifactRef({
+    uri: 'artifact://run/visibility.json',
+    bytes,
+  }),
+  results,
+})
+
+const use = createKnowledgeUseReceipt({
+  retrieval,
+  selectedRank: 1,
+  relation: 'extends',
+  consumer: { kind: 'artifact', uri: 'artifact://run/DECISION.md', digest },
+})
+
+console.log(visibility.snapshotDigest, retrieval.receiptDigest, use.receiptDigest)
+```
+
+ELI5: the visibility snapshot is the bookshelf the agent was allowed to see, the retrieval receipt is the exact books search handed back, and the use receipt records which returned book the agent attached to a downstream decision or artifact.
+
+Create the snapshot once per knowledge view and reuse it: the retrieval receipt stores the snapshot's digest, page count, and storage locator, not its pages, so repeated queries over one view do not re-serialize the inventory.
+`verifyKnowledgeRetrievalReceipt` proves the receipt itself; `assertKnowledgeRetrievalMatchesVisibility` and `assertKnowledgeRetrievalMatchesVisibilityArtifact` prove that every returned result occurs in that exact snapshot.
+
+The receipts are content-addressed and mutation-sensitive. They do **not** establish correctness, novelty, compliance, or causal lift; Eval owns those later judgments. Read [knowledge retrieval and use receipts](docs/knowledge-use-receipts.md) for the complete proof boundary, trace attributes, and experiment design.

package/docs/rag-evaluation.md

@@ -0,0 +1,82 @@
+# Evaluate and improve RAG
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Evaluate and improve RAG
+
+Use the narrowest API that matches the job:
+
+| API | What it does |
+|---|---|
+| `runRetrievalImprovementLoop` | Runs one complete `OptimizationMethod` over serialized retrieval configuration. |
+| `runRagOptimization` | Optimizes retrieval and answer behavior as one serialized RAG configuration. |
+| `scoreKnowledgeBaseIndex` | Measures KB structure, citations, source freshness, and configured quality thresholds. |
+| `runRagKnowledgeImprovementLoop` | Connects retrieval tuning, gap diagnosis, source acquisition, KB updates, answer checks, and a promotion decision. |
+| `improveKnowledgeBase` | Adds resumable state, isolated candidates, exact promotion, and conflict detection around that process. |
+
+```ts
+import type {
+  OptimizationMethod,
+} from '@tangle-network/agent-eval/campaign'
+import {
+  runRetrievalImprovementLoop,
+  type RetrievalEvalArtifact,
+  type RetrievalEvalScenario,
+} from '@tangle-network/agent-knowledge'
+
+async function tuneRetrieval(
+  method: OptimizationMethod<RetrievalEvalScenario, RetrievalEvalArtifact>,
+) {
+  return runRetrievalImprovementLoop({
+    executionRef: 'git:0123456789abcdef0123456789abcdef01234567',
+    baseline: { k: 5, reranker: false },
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    retrieve: ({ scenario, config, k }) => search(scenario.query, { ...config, k }),
+    runDir: 'refund-retrieval',
+    expectUsage: 'off', // Local search does not make a billable model call.
+  })
+}
+```
+
+The method receives train and selection cases.
+`agent-eval` keeps final cases out of the search and measures the exact selected configuration on them afterward.
+Every optimization call requires an explicit complete method.
+Create an official method with `gepaOptimizationMethod()` or `skillOptOptimizationMethod()` from `@tangle-network/agent-eval/campaign`, or pass another complete public `OptimizationMethod`.
+Reuse the run directory only with the method's compatible resume mode.
+Use separate run directories to explore branches in parallel.
+Optimizer-specific identity and resume settings stay on the supplied method; this package does not reinterpret them.
+The supplied method owns its engine inputs and resume state.
+`executionRef` owns retrieval, index, judge, model, and external-service identity.
+Use `git:<40 lowercase hex>` or `sha256:<64 lowercase hex>` and change it whenever any candidate execution or scoring behavior changes.
+Each candidate has one canonical serialized identity.
+See the [`agent-eval` method guide](https://github.com/tangle-network/agent-eval/blob/main/docs/campaign-proposers.md) for official GEPA and SkillOpt methods.
+SkillOpt is skill-only; use it here only when the serialized candidate is itself a skill.
+Read reported spend from `result.comparison.totalCost` and upstream source and run identity from `result.comparison.best.provenance`.
+Official external methods must report observed package identity.
+Custom in-process methods have no external package identity, so their behavior must be covered by `executionRef`.
+Treat `accountingComplete: false` as incomplete evidence for activation.
+
+Retrieval, RAG, and serialized-candidate optimization accept Eval's optional `claim` and `finalEvidence` options.
+Use `claim.independentUnit` to group questions from the same source.
+A `new-units` claim requires separate source units for development and final evaluation.
+Results retain scenario scores, source-unit scores, and both observation counts.
+Claim metadata declares the intended scope; it does not authenticate labels or establish certification.
+
+For fresh final evidence, pass a shared durable ledger from `openFinalEvidenceLedger()` in `@tangle-network/agent-eval/experiment`.
+The policy also requires a request ID and the actual evaluator's content digest.
+Eval reserves final units before search and records exposure before measurement.
+Interrupted measurements consume that evidence, and another request cannot restore its freshness.
+See [Eval's integrity guide](https://github.com/tangle-network/agent-eval/blob/main/docs/evaluation-integrity.md) for the full controls and limits.
+
+Retrieval and answer generation remain callbacks.
+This lets the same evaluation code work with local search, vector databases, hybrid search, rerankers, and hosted RAG services.
+Adaptive diagnosis, acquisition, and update callbacks finish before retrieval or RAG final scoring starts.
+Only answer evaluation, the terminal promotion decision, and the returned result can observe selected configurations.
+Answer-quality evidence must name at least two final scenario IDs, immutable dataset and evaluator references, non-empty finite metrics, and observed cost accounting.
+Promotion also requires `answerQualityCostCeiling`.
+
+For evaluator admission, use `auditEvaluator()` from `@tangle-network/agent-eval/meta-eval` with actual judgments of independently verified controls.
+The application must enforce evaluator and auditor separation and retain evidence for the labels.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "20.0.1",
+  "version": "22.0.0",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -38,6 +38,11 @@
       "types": "./dist/benchmarks/index.d.ts",
       "import": "./dist/benchmarks/index.js",
       "default": "./dist/benchmarks/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js",
+      "default": "./dist/search/index.js"
     }
   },
   "bin": {
@@ -67,11 +72,12 @@
     "format": "biome format --write src tests",
     "check:skills": "node scripts/check-skills.mjs",
     "check:path-containment": "node scripts/check-path-containment.mjs",
-    "verify:package": "pnpm run check:version-bump && pnpm run check:skills && pnpm run check:path-containment && pnpm run check:api-surface && publint && attw --pack --profile esm-only . && node scripts/verify-package.mjs",
+    "verify:package": "pnpm run check:version-bump && pnpm run check:skills && pnpm run check:path-containment && pnpm run check:api-surface && publint && attw --pack --profile esm-only . && node scripts/verify-package.mjs && pnpm run verify:search",
     "verify:official-optimizers": "node scripts/verify-official-optimizers.mjs",
     "check:version-bump": "node scripts/check-version-bump.mjs",
     "check:api-surface": "node scripts/check-api-surface.mjs",
-    "api:surface": "node scripts/check-api-surface.mjs --write"
+    "api:surface": "node scripts/check-api-surface.mjs --write",
+    "verify:search": "node scripts/verify-search-entry.mjs"
   },
   "dependencies": {
     "@types/proper-lockfile": "4.1.4",
@@ -79,15 +85,15 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.209.1 <0.212.0",
-    "@tangle-network/agent-interface": "^3.0.0"
+    "@tangle-network/agent-eval": ">=0.213.0 <0.214.0",
+    "@tangle-network/agent-interface": "^5.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.14",
     "@neo4j-labs/agent-memory": "0.5.0",
-    "@tangle-network/agent-eval": "0.211.2",
-    "@tangle-network/agent-interface": "3.0.0",
+    "@tangle-network/agent-eval": "0.213.0",
+    "@tangle-network/agent-interface": "5.0.0",
     "@types/node": "^26.6.2",
     "mem0ai": "3.3.0",
     "oxc-parser": "0.151.0",