trader-explain

Explain a trading signal by building a feature-contribution graph and running single-entry forward-push PageRank from the signal output node. Top-K ranked features are returned as a markdown table AND persisted to trading-analysis as a SignedAttributionArtifact (ADR-126 Phase 6).

Why this skill matters:

• EU AI Act + SEC Reg-AI guidance require interpretable model output for any algorithmic trading system that touches retail capital. This is the regulator-grade attribution path the rest of the substrate has been waiting for.
• The same call site picks up the full native-WASM PageRank from mcp__swarmdo-sublinear__page-rank-entry once that tool is registered in the runtime — until then, the local power-iteration kernel ships in signed-attribution.mjs and produces the same ordering (seeded mulberry32).

Steps:

1. Retrieve the signal from the canonical trading-signals namespace (ADR-126 Phase 1 + Phase 2 lifecycle):

   mcp__swarmdo__memory_retrieve({
     key: "SIGNAL_ID",
     namespace: "trading-signals"
   })
   

   The signal entry includes modelId, prediction, and the feature vector at the time of inference.

2. Extract per-feature contribution scores from the model:

   npx neural-trader --predict --signal "$SIGNAL_ID" --explain --json
   

   The expected output shape:

   {
     features: Array<{ name: string; contribution: number }>;
     // for Transformers, also includes per-head attention co-occurrence:
     attention?: Array<{ head: string; cooccur: Array<[number, number, number]> }>;
   }
   

   Fallback path — if --explain is not shipped on the installed neural-trader build (older versions; the flag was scoped for a follow-up upstream PR), the skill degrades to a deterministic feature-importance heuristic over the signal's input vector: contribution_i = |input_i - μ_i| / σ_i (z-score magnitude). This is a known proxy — not as faithful as attention/SHAP — and the resulting artifact is tagged attribution_method: "input-zscore-fallback" so downstream consumers can filter it out for regulator filings. Document the fallback path in the resulting markdown summary so the agent surfaces it to the user.

3. Build the feature-contribution graph:

   • Nodes: one node per feature + one source node __signal_output__ for the prediction.
   • Edges: outgoing edges from __signal_output__ to each feature node, weighted by contribution_i. When attention co-occurrence data is available, also add edges between feature nodes weighted by cooccur — this is what makes the PageRank single-entry rather than degenerating to plain top-K.
   • Source: __signal_output__ (index 0 by convention so the smoke can assert reproducibility).

4. Run single-entry PageRank — preferred path when mcp__swarmdo-sublinear__page-rank-entry is registered:

   mcp__swarmdo-sublinear__page-rank-entry({
     nodes: GRAPH_NODES,
     edges: GRAPH_EDGES,
     sourceIndex: 0,
     damping: 0.85,
     maxIterations: 100,
     tolerance: 1e-8,
     seed: 42
   })
   

   The local fallback (localSingleEntryPageRank in plugins/swarmdo-neural-trader/src/signed-attribution.mjs) runs ~30 LOC of seeded power-iteration when the MCP tool is not available — same math, same result up to floating-point tolerance, same ordering for the same seed (the Phase 6 smoke asserts this).

5. Build the top-K AttributionFeature[] via topKFeatures(graph, scores, k=10, excludeIndex=0) — excludes the source node from the ranked output. Ties broken by node index (lower index wins) so the ranking is deterministic.

6. Sign the artifact (reuses the Phase 4 signing primitives — same Ed25519 + canonicalization):

   • Build the SignedAttributionArtifact body:

     {
       signalId: SIGNAL_ID,
       modelId: SIGNAL.modelId,
       features: TOP_K_FEATURES,             // from step 5
       graphMetadata: {
         nodeCount: GRAPH.nodes.length,
         edgeCount: COUNT_EDGES,
         pageRankIterations: PR_RESULT.iterations,
         seed: SEED                          // load-bearing for reproducibility
       },
       generatedAt: NEW_DATE_ISO
     }
     

   • Resolve the witness signing key — same lookup order as Phase 4:
     1. SWARMDO_WITNESS_KEY_PATH env var — JSON file with { "privateKey": "<hex>" }.
     2. verification/witness-key.json (the ADR-103 default path).
   • If a key resolves: signAttributionArtifact(body, privateKeyHex) from plugins/swarmdo-neural-trader/src/signed-attribution.mjs.
   • If NEITHER path resolves: log "[WARN] swarmdo-neural-trader: no witness signing key found — storing attribution artifact in UNSIGNED degraded mode. Regulator filings will reject UNSIGNED artifacts." and store the body unsigned. NEVER silently fall back.

7. Store the (possibly signed) artifact to the canonical trading-analysis namespace (ADR-126 Phase 1):

   mcp__swarmdo__memory_store({
     key: "attribution-SIGNAL_ID-TIMESTAMP",
     namespace: "trading-analysis",
     value: JSON.stringify(signedArtifact)
   })
   

   The trading-analysis namespace is the canonical home for model-analysis output (regime classifications, technical-indicator summaries, model-training results — and now attribution rankings). Long-lived — no TTL — because the audit trail is the deliverable.

8. Return the markdown summary to the agent. Suggested format:

   ## Feature attribution for signal `SIGNAL_ID` (model: MODEL_ID)
   
   | Rank | Feature | Score |
   |------|---------|-------|
   | 1    | NAME    | 0.42  |
   | 2    | NAME    | 0.18  |
   | …    | …       | …     |
   
   - PageRank iterations: N
   - Graph: nodeCount nodes, edgeCount edges
   - Seed: 42 (reproducible — same seed → same ordering)
   - Path: mcp | local
   - Signature: ed25519:abcd… (or UNSIGNED — degraded warning above)
   

Verification

Downstream consumers verify the artifact before any regulator-facing report or paper→live promotion:

import { verifyAttributionArtifact } from 'plugins/swarmdo-neural-trader/src/signed-attribution.mjs';

const ok = await verifyAttributionArtifact(artifact, trustedPublicKey);
if (!ok) {
  // [ERROR] attribution verification failed — refuse to publish.
  // Pin to trustedPublicKey from project config; do NOT trust the
  // artifact.witnessPublicKey field (CWE-347 / #1922 — attacker-controllable).
  return;
}

Acceptance criteria (ADR-126 Phase 6):

• trader-explain <signalId> returns a ranked feature list whose top-3 features overlap the model's attention argmax (when --explain available; documented tolerance).
• Reproducibility: two runs with the same signalId + same --seed produce byte-identical rank ordering (asserted by scripts/smoke-neural-trader-feature-attribution.mjs).
• Signed artifact verifies under the trusted pubkey; tampering any feature score or graphMetadata.seed invalidates the signature.
• Fallback paths engage cleanly: when MCP unavailable, local kernel runs; when --explain flag missing, z-score heuristic runs and the artifact is tagged.

Refs:

• ADR-126 Phase 6 (this skill's authoring ADR)
• ADR-126 Phase 4 (the signing scheme this reuses)
• ADR-123 (single-entry PageRank substrate; the same family that Phase 3 leverages for portfolio CG)
• plugins/swarmdo-neural-trader/src/signed-attribution.ts (the typed contract)
• plugins/swarmdo-neural-trader/src/signed-attribution.mjs (the runtime mirror)
• scripts/smoke-neural-trader-feature-attribution.mjs (the regression smoke)