@tangle-network/traces 0.9.19 → 0.10.0

package/README.md

@@ -147,7 +147,7 @@ traces upload   --since 24h                        # upload last day to the Inte
 | `--dir <path>` | `improve`: write the full artifact pack to this directory |
 | `--otlp <path>` | OTLP artifact path (also evidence provenance / dry-run upload preview) |
 | `--format <kind>` | File `analyze`, `export`, or `stream`: `auto`, `policy-evidence`, `sandbox-events`, `openinference`, `intelligence-spans`, or `chat-trajectory` |
-| `--llm` / `--budget <usd>` | Enable agentic analysts (needs `OPENAI_API_KEY`) / cap their spend |
+| `--llm` / `--budget <usd>` | Enable agentic analysts (needs `TANGLE_API_KEY` + Python with `agent-eval-rpc[dspy]`) / cap their spend |
 | `--config <path>` | `analyze` / `investigate` / `improve` / `stream`: load BYO analysts, live analysts, and external analyzers |
 | `--interval <s>` / `--window <m>` | `watch` / live `stream`: poll seconds (default 5) / active-session window minutes (default 30) |
 | `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
@@ -373,7 +373,10 @@ traces upload --since 24h --dry-run --redactor "my-pii-scrubber"
 In the SDK these are the `ExternalAnalyzer` and `Redactor` interfaces (`haloAnalyzer`, `hodoscopeAnalyzer`, `commandAnalyzer`, `commandRedactor`, `applyRedactor`, `runExternalAnalyzers`).
 See [`examples/external-engines.ts`](./examples/external-engines.ts).
 
-> For the built-in agentic analysts (`--llm`), set `OPENAI_API_KEY`, or point at any OpenAI-compatible gateway with `OPENAI_BASE_URL` (e.g. an internal router) to use a non-OpenAI key.
+> The built-in agentic analysts (`--llm`) run on the Tangle router by default: set `TANGLE_API_KEY`.
+> `OPENAI_API_KEY` alone targets OpenAI instead, and `OPENAI_BASE_URL` overrides the endpoint for any other OpenAI-compatible gateway.
+> `--llm` also needs a Python interpreter with `agent-eval-rpc[dspy]` installed, because agent-eval's model-backed analysts run through the DSPy RLM engine out of process; set `TRACES_PYTHON` to choose the interpreter.
+> Every deterministic command — `list`, `analyze` without `--llm`, `convert`, `index`, `inspect`, `export`, `evidence`, `stream`, `watch`, `analyze --supervisor-run-dir` — needs neither a key nor Python.
 
 ## Agent skills
 

package/dist/{chunk-WCJVRJD5.js → chunk-7BQ2CVEA.js}

@@ -8973,13 +8973,12 @@ async function analyzeSpans(spans, opts = {}) {
   const detRegistry = opts.registry ?? buildDefaultAnalystRegistry({ registry: { log: opts.log } });
   const result = await detRegistry.run(runId, { traceStore: detStore }, { signal: opts.signal });
   opts.signal?.throwIfAborted();
-  if (opts.ai || opts.agenticRegistry) {
+  if (opts.engine || opts.agenticRegistry) {
     const agStore = new OtlpFileTraceStore({ path: otlpPath, maxFileBytes: GENERATED_TRACE_FILE_CEILING });
     await agStore.ensureIndexed();
     const agRegistry = opts.agenticRegistry ?? buildDefaultAnalystRegistry({
-      ai: opts.ai,
-      model: opts.model,
-      kinds: opts.agenticKinds,
+      engine: opts.engine,
+      ...opts.agenticKinds ? { definitions: opts.agenticKinds } : {},
       includeBehavioral: false,
       registry: { log: opts.log }
     });
@@ -9973,9 +9972,9 @@ async function runTraceInvestigation(opts) {
   ]);
   opts.signal?.throwIfAborted();
   const deterministic = deterministicFindings(pipelines, reactions, adoption, opts.spans);
-  const agenticRoute = opts.ai && !opts.agenticRegistry ? planTraceAgenticRoute(pipelines, reactions) : void 0;
+  const agenticRoute = opts.engine && !opts.agenticRegistry ? planTraceAgenticRoute(pipelines, reactions) : void 0;
   const analysis = await analyzeSpans(opts.spans, {
-    ai: opts.ai,
+    engine: opts.engine,
     model: opts.model,
     budgetUsd: opts.budgetUsd,
     registry: opts.registry,
@@ -10025,8 +10024,7 @@ async function runTraceStoreInvestigation(opts) {
   opts.signal?.throwIfAborted();
   const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
   const registry = opts.registry ?? buildDefaultAnalystRegistry2({
-    ai: opts.ai,
-    model: opts.model,
+    ...opts.engine ? { engine: opts.engine } : {},
     registry: { log: opts.log }
   });
   const runId = opts.runId ?? `traces-store-investigation-${Date.parse(generatedAt) || Date.now()}`;

package/dist/cli.js

@@ -44,7 +44,7 @@ import {
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-WCJVRJD5.js";
+} from "./chunk-7BQ2CVEA.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
@@ -58,8 +58,9 @@ import {
   renderSupervisorRunMarkdown,
   rollupSupervisorRuns
 } from "@tangle-network/agent-eval/supervisor-run";
-import { createAnalystAi } from "@tangle-network/agent-eval/analyst";
+import { createDspyRlmTraceEngine } from "@tangle-network/agent-eval/analyst";
 var DEFAULT_ANALYST_MODEL = "gpt-5-mini";
+var TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
 function packageVersion() {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
@@ -346,15 +347,23 @@ async function resolveSelectedSession(args) {
     `session ID "${args.session}" is ambiguous across ${matches.length} files; select one harness or pass its explicit session path`
   );
 }
-async function buildAxService(model) {
-  const apiKey = process.env.OPENAI_API_KEY;
+function buildAnalysisEngine(model) {
+  const tangleKey = process.env.TANGLE_API_KEY;
+  const openAiKey = process.env.OPENAI_API_KEY;
+  const apiKey = tangleKey || openAiKey;
   if (!apiKey) {
     throw new Error(
-      "--llm needs OPENAI_API_KEY: an OpenAI key, or a router/gateway key with OPENAI_BASE_URL set to an OpenAI-compatible endpoint (e.g. the Tangle router). Deterministic analysis needs no key."
+      "--llm needs a model key: TANGLE_API_KEY for the Tangle router (the default endpoint), or OPENAI_API_KEY for OpenAI. Set OPENAI_BASE_URL to target any other OpenAI-compatible gateway. Deterministic analysis needs no key."
     );
   }
-  const apiURL = process.env.OPENAI_BASE_URL || void 0;
-  return createAnalystAi({ apiKey, baseUrl: apiURL, model });
+  const baseUrl = process.env.OPENAI_BASE_URL || (tangleKey ? TANGLE_ROUTER_BASE_URL : "https://api.openai.com/v1");
+  const python = process.env.TRACES_PYTHON;
+  return createDspyRlmTraceEngine({
+    apiKey,
+    baseUrl,
+    model,
+    ...python ? { runner: { command: python } } : {}
+  });
 }
 async function cmdList(args) {
   const groups = await discover({ ...args, last: args.last || 20 });
@@ -702,7 +711,7 @@ async function investigate(args, options = {}) {
   if (spans.length === 0) throw new Error("no spans found for the given selection");
   const config = args.config !== void 0 || options.loadDefaultConfig !== false ? await loadTracesConfig(args.config) : void 0;
   const analystModel = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
-  const ai = args.llm ? await buildAxService(analystModel) : void 0;
+  const engine = args.llm ? buildAnalysisEngine(analystModel) : void 0;
   return runTraceInvestigation(mergeTracesConfig({
     spans,
     harness,
@@ -710,7 +719,7 @@ async function investigate(args, options = {}) {
     workflow,
     cwds,
     minLoopOccurrences: args.minLoop,
-    ai,
+    engine,
     model: args.llm ? analystModel : args.model,
     budgetUsd: args.budget,
     otlpOutPath: args.otlp,
@@ -725,7 +734,7 @@ async function cmdImprove(args) {
   if (spans.length === 0) throw new Error("no spans found for the given selection");
   const config = await loadTracesConfig(args.config);
   const analystModel = args.model ?? process.env.TRACES_ANALYST_MODEL ?? DEFAULT_ANALYST_MODEL;
-  const ai = args.llm ? await buildAxService(analystModel) : void 0;
+  const engine = args.llm ? buildAnalysisEngine(analystModel) : void 0;
   const result = await runTraceImprovement({
     ...mergeTracesConfig({
       spans,
@@ -734,7 +743,7 @@ async function cmdImprove(args) {
       workflow,
       cwds,
       minLoopOccurrences: args.minLoop,
-      ai,
+      engine,
       model: args.llm ? analystModel : args.model,
       budgetUsd: args.budget,
       otlpOutPath: args.otlp,
@@ -1039,7 +1048,10 @@ Options:
   --replay, --once stream: scan once and exit (default for positional input / --session)
   --no-spans       stream: omit per-span pulse events
   --no-findings    stream: omit semantic live-finding events
-  --llm            Enable agentic RLM analysts (needs OPENAI_API_KEY / OPENAI_BASE_URL)
+  --llm            Enable agentic RLM analysts. Runs on the Tangle router by
+                   default (TANGLE_API_KEY); OPENAI_API_KEY alone targets OpenAI,
+                   OPENAI_BASE_URL overrides the endpoint. Needs Python with
+                   agent-eval-rpc[dspy] (TRACES_PYTHON selects the interpreter).
   --model <id>     Model for --llm, HALO, and Hodoscope (default for --llm: ${DEFAULT_ANALYST_MODEL})
   --config <path>  investigate/improve/stream: JS config with analysts, liveAnalysts, or external analyzers
   --budget <usd>   USD cap for agentic analysts

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
 import { StuckLoopReport, FailureClusterReport } from '@tangle-network/agent-eval/pipelines';
-import { TraceAnalystKindSpec, AnalystRegistry, AnalystFinding, buildDefaultAnalystRegistry, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
+import { TraceAnalystDefinition, TraceAnalysisEngine, AnalystRegistry, AnalystFinding, buildDefaultAnalystRegistry, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
-import { AxAIService } from '@ax-llm/ax';
 import { ExecutionReport } from '@tangle-network/agent-eval/contract';
 import { TraceAnalysisStore, RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
 export { DEFAULT_REDACTION_RULES, ErrorCluster, RedactionReport, RedactionRule, TraceAnalysisStore, redactString, redactValue } from '@tangle-network/agent-eval/traces';
@@ -1154,7 +1153,7 @@ interface TraceAgenticRoute {
  */
 declare function planTraceAgenticRoute(pipelines: PipelineReport, reactions: ReactionReport): TraceAgenticRoute;
 /** Resolve a route into the maintained agent-eval kind specifications. */
-declare function traceAgenticKinds(route: TraceAgenticRoute): readonly TraceAnalystKindSpec[];
+declare function traceAgenticKinds(route: TraceAgenticRoute): readonly TraceAnalystDefinition[];
 
 /**
  * Project normalized `OtlpSpan[]` onto agent-eval's runtime trace store.
@@ -1190,8 +1189,12 @@ declare function toRuntimeStore(spans: readonly OtlpSpan[]): Promise<RuntimeTrac
  */
 
 interface AnalyzeOptions {
-    /** Ax service enabling the agentic RLM kinds. Omit → deterministic only. */
-    ai?: AxAIService;
+    /**
+     * Recursive analysis engine enabling the agentic analyst kinds. Omit →
+     * deterministic only. The engine's id, version, and model become the
+     * exact-run identity of every analyst it executes.
+     */
+    engine?: TraceAnalysisEngine;
     model?: string;
     /** USD cap across agentic analysts. */
     budgetUsd?: number;
@@ -1206,7 +1209,7 @@ interface AnalyzeOptions {
      * deterministic pass and receives its compact findings as prior context. */
     agenticRegistry?: AnalystRegistry;
     /** Select a subset of agent-eval's maintained trace analyst kinds. */
-    agenticKinds?: readonly TraceAnalystKindSpec[];
+    agenticKinds?: readonly TraceAnalystDefinition[];
     /** Compact deterministic findings that agents receive before reading spans. */
     agenticPriorFindings?: readonly AnalystFinding[];
     /** Where to write the OTLP-JSONL artifact. Defaults to a temp file. */
@@ -1827,7 +1830,7 @@ interface TraceInvestigationOptions {
     readonly workflow?: SessionWorkflowSummary;
     readonly cwds?: readonly string[];
     readonly minLoopOccurrences?: number;
-    readonly ai?: AxAIService;
+    readonly engine?: TraceAnalysisEngine;
     readonly model?: string;
     readonly budgetUsd?: number;
     readonly registry?: AnalystRegistry;
@@ -1897,7 +1900,7 @@ interface BuildTraceFindingPacketOptions {
 interface TraceStoreInvestigationOptions {
     readonly traceStore: TraceAnalysisStore;
     readonly registry?: AnalystRegistry;
-    readonly ai?: AxAIService;
+    readonly engine?: TraceAnalysisEngine;
     readonly model?: string;
     readonly budgetUsd?: number;
     readonly runId?: string;

package/dist/index.js

@@ -131,7 +131,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceImprovementArtifacts
-} from "./chunk-WCJVRJD5.js";
+} from "./chunk-7BQ2CVEA.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.9.19",
+  "version": "0.10.0",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -47,8 +47,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ax-llm/ax": "^23.0.6",
-    "@tangle-network/agent-eval": "0.137.0"
+    "@tangle-network/agent-eval": "0.139.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",