@tangle-network/agent-knowledge 1.3.0 → 1.5.0

package/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*** Add File: /home/drew/worktrees/publish-open-source/modal-inference-blueprint/LICENSE-MIT
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -199,6 +199,66 @@ await runAgentControlLoop({
 })
 ```
 
+## Researcher profile
+
+`@tangle-network/agent-knowledge/profiles` ships a sandbox-SDK
+`AgentProfile` preset for source-grounded research agents. Pairs with
+`runLoop` from `@tangle-network/agent-runtime/loops` — the profile owns
+the prompt + output adapter + validator; the kernel owns iteration,
+concurrency, cost, and trace emission.
+
+```ts
+import { runLoop } from '@tangle-network/agent-runtime/loops'
+import { multiHarnessResearcherFanout } from '@tangle-network/agent-knowledge/profiles'
+
+const research = multiHarnessResearcherFanout({
+  harnesses: ['opencode/zai-coding-plan/glm-5.1', 'claude-code', 'codex'],
+})
+
+const result = await runLoop({
+  driver: research.driver,
+  agentRuns: research.agentRuns,
+  output: research.output,
+  validator: research.validator,
+  task: {
+    question: 'What content does cpg-founder ICP engage with on Twitter?',
+    knowledgeNamespace: 'cust_42',
+    sources: ['twitter', 'web'],
+    maxItems: 20,
+    minConfidence: 0.6,
+  },
+  ctx: { sandboxClient },
+})
+
+if (result.winner?.verdict?.valid) {
+  // result.winner.output.proposedWrites: KnowledgeUpdate[]
+  // The profile does NOT materialize. Decide whether to apply.
+  for (const write of result.winner.output.proposedWrites) {
+    // route through applyKnowledgeWriteBlocks / a KbStore put when ready
+  }
+}
+```
+
+Three invariants are enforced by the validator:
+
+- **Namespace isolation** — every `KnowledgeItem` + `KnowledgeUpdate`
+  must carry `task.knowledgeNamespace`. Cross-tenant writes hard-fail.
+- **Provenance** — every item carries at least one evidence entry.
+- **Citation density** — quotes-with-source / items >= 0.7 by default.
+
+Validator scoring (default; overridable):
+
+```
+score = 0.4 · citation_density
+      + 0.2 · source_diversity
+      + 0.2 · recency_match
+      + 0.2 · gap_coverage
+```
+
+The output preserves agent intelligence — `items`, `citations`,
+`proposedWrites` are typed; `gaps`, `notes`, and any extras the agent
+emitted land in `raw` rather than getting dropped.
+
 ## Pluggable Knowledge Sources
 
 Static knowledge rots. Authorities like Cornell LII, the IRS, and state

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as KnowledgeEventType, f as KnowledgeEvent, g as KnowledgePage, b as KnowledgeGraph, h as KnowledgeLintFinding, i as KnowledgeBaseCandidate, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as SourceRegistry, n as KnowledgeWriteParseResult } from './types-CAeh7Lwb.js';
-export { C as ClaimRef, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-CAeh7Lwb.js';
+import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as KnowledgeEventType, f as KnowledgeEvent, g as KnowledgePage, b as KnowledgeGraph, h as KnowledgeLintFinding, i as KnowledgeWriteBlock, j as KnowledgeClaim, k as KnowledgeRelease, l as SourceRegistry, m as KnowledgeWriteParseResult } from './types-BEDGlXB-.js';
+export { C as ClaimRef, n as KnowledgeBaseCandidate, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-BEDGlXB-.js';
 import { KnowledgeFragment } from './sources/index.js';
 export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from './sources/index.js';
-import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, MultiShotVariant, MultiShotOptimizationConfig, MultiShotRunner, MultiShotScorer, MultiShotMutateAdapter, MultiShotOptimizationResult, AnalystSeverity, AnalystFinding, ReleaseConfidenceScorecard, RunRecord, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
 import { z } from 'zod';
 
 interface SourceAdapterInput {
@@ -471,20 +471,6 @@ declare class FileSystemKbStore extends MemoryKbStore {
 
 declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
 
-type KnowledgeBaseVariant = MultiShotVariant<KnowledgeBaseCandidate>;
-interface KnowledgeOptimizationConfig extends Omit<MultiShotOptimizationConfig<KnowledgeBaseCandidate>, 'runner' | 'scorer' | 'mutateAdapter' | 'target'> {
-    target?: string;
-    runner: MultiShotRunner<KnowledgeBaseCandidate>;
-    scorer: MultiShotScorer<KnowledgeBaseCandidate>;
-    mutateAdapter: MultiShotMutateAdapter<KnowledgeBaseCandidate>;
-}
-declare function runKnowledgeBaseOptimization(config: KnowledgeOptimizationConfig): Promise<MultiShotOptimizationResult<KnowledgeBaseCandidate>>;
-declare function knowledgeVariantFromCandidate(candidate: KnowledgeBaseCandidate, options?: {
-    id?: string;
-    label?: string;
-    generation?: number;
-}): KnowledgeBaseVariant;
-
 interface ApplyWriteBlocksResult {
     written: string[];
     warnings: string[];
@@ -584,11 +570,30 @@ interface KnowledgeReleaseReport {
     candidateRuns: RunRecord[];
     baselineRuns: RunRecord[];
 }
-declare function knowledgeReleaseReportFromOptimization(result: MultiShotOptimizationResult<KnowledgeBaseCandidate>, options?: {
-    runRecords?: RunRecord[];
+/**
+ * Campaign-native release report. The caller (a consumer's KB self-improvement
+ * loop) supplies the candidate/baseline `RunRecord[]` (e.g. via
+ * `campaignToRunRecords`) + optional per-instance `ReleaseTraceEvidence` + the
+ * gate decision; this folds them into a `ReleaseConfidenceScorecard` + a
+ * `KnowledgeRelease`. Decoupled from any optimizer result shape — agent-eval's
+ * legacy multi-shot orchestration (and its `MultiShotOptimizationResult`) was
+ * removed in 0.42; release confidence is computed from records + traces.
+ */
+interface KnowledgeReleaseInput {
+    candidateId: string;
+    baselineId?: string;
+    candidateRuns: RunRecord[];
+    baselineRuns?: RunRecord[];
+    traces?: ReleaseTraceEvidence[];
+    gateDecision?: GateDecision | null;
+    /** True when a held-out split was evaluated (drives the holdout threshold). */
+    hasHoldout?: boolean;
+    /** Candidate is the search-best variant — a promotion precondition. Default true. */
+    promotedIsBest?: boolean;
     createdAt?: string;
     minScore?: number;
-}): KnowledgeReleaseReport;
+}
+declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
 
 interface AddSourceOptions {
     copyIntoRaw?: boolean;
@@ -928,4 +933,4 @@ declare function normalizeLinkTarget(target: string): string;
 declare function isSafeKnowledgePath(path: string, allowedPrefixes?: string[]): boolean;
 declare function parseKnowledgeWriteBlocks(text: string, allowedPrefixes?: string[]): KnowledgeWriteParseResult;
 
-export { type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type D1Adapter, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type KbStore, KnowledgeBaseCandidate, KnowledgeBaseCandidateSchema, type KnowledgeBaseVariant, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, type KnowledgeOptimizationConfig, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReleaseReportFromOptimization, knowledgeVariantFromCandidate, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeBaseOptimization, runKnowledgeResearchLoop, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+export { type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type D1Adapter, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReleaseReport, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeResearchLoop, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };

package/dist/index.js

@@ -615,25 +615,6 @@ function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
 
-// 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
-  };
-}
-
 // src/propose-from-finding.ts
 var KnowledgeProposalParseError = class extends Error {
   constructor(findingId, subject, message) {
@@ -831,50 +812,35 @@ function humanize(slug) {
 // src/release.ts
 import {
   evaluateReleaseConfidence,
-  releaseTraceEvidenceFromMultiShotTrials,
   validateRunRecord
 } from "@tangle-network/agent-eval";
-function knowledgeReleaseReportFromOptimization(result, options = {}) {
-  const trials = result.evolution.generations.flatMap(
-    (generation) => generation.trials
-  );
-  const traceEvidence = releaseTraceEvidenceFromMultiShotTrials(trials);
-  const runRecords = (options.runRecords ?? [
-    ...result.gate?.candidateRuns ?? [],
-    ...result.gate?.baselineRuns ?? []
-  ]).map(validateRunRecord);
+function knowledgeReleaseReport(input) {
+  const baselineRuns = input.baselineRuns ?? [];
+  const runRecords = [...input.candidateRuns, ...baselineRuns].map(validateRunRecord);
   const scorecard = evaluateReleaseConfidence({
     target: "agent-knowledge-base",
-    candidateId: result.promotedVariant.id,
-    baselineId: "baseline",
-    traces: traceEvidence,
+    candidateId: input.candidateId,
+    baselineId: input.baselineId ?? "baseline",
+    traces: input.traces ?? [],
     runs: runRecords,
-    gateDecision: result.gate?.decision ?? null,
+    gateDecision: input.gateDecision ?? null,
     thresholds: {
       requireCorpus: false,
-      requireHoldout: Boolean(result.gate),
-      minHoldoutRuns: result.gate ? 1 : 0,
+      requireHoldout: input.hasHoldout ?? false,
+      minHoldoutRuns: input.hasHoldout ? 1 : 0,
       minSearchRuns: 1,
-      minMeanScore: options.minScore ?? 0.7
+      minMeanScore: input.minScore ?? 0.7
     }
   });
   const release = {
-    id: stableId(
-      "krel",
-      `${result.promotedVariant.id}:${options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}`
-    ),
-    candidateId: result.promotedVariant.id,
-    createdAt: options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-    promoted: scorecard.status !== "fail" && result.promotedVariant.id === result.searchBestVariant.id,
+    id: stableId("krel", `${input.candidateId}:${input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}`),
+    candidateId: input.candidateId,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    promoted: scorecard.status !== "fail" && (input.promotedIsBest ?? true),
     scorecard,
     runRecordIds: runRecords.map((record) => record.runId)
   };
-  return {
-    release,
-    scorecard,
-    candidateRuns: result.gate?.candidateRuns ?? [],
-    baselineRuns: result.gate?.baselineRuns ?? []
-  };
+  return { release, scorecard, candidateRuns: input.candidateRuns, baselineRuns };
 }
 
 // src/research-loop.ts
@@ -1086,8 +1052,7 @@ export {
   inspectKnowledgeIndex,
   isSafeKnowledgePath,
   isScaffoldPath,
-  knowledgeReleaseReportFromOptimization,
-  knowledgeVariantFromCandidate,
+  knowledgeReleaseReport,
   layoutFor,
   lintKnowledgeIndex,
   loadKnowledgePages,
@@ -1101,7 +1066,6 @@ export {
   proposeFromFinding,
   proposeFromFindings,
   reciprocalRankFusion,
-  runKnowledgeBaseOptimization,
   runKnowledgeResearchLoop,
   searchKnowledge,
   sha256,