trader-explain

trading-analysis

SignedAttributionArtifact

• 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__ruflo-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).

1. Retrieve the signal from the canonical

   trading-signals

   namespace (ADR-126 Phase 1 + Phase 2 lifecycle):
   text

   mcp__claude-flow__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:
   bash

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

   The expected output shape:
   ts

   {
     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__ruflo-sublinear__page-rank-entry

   is registered:
   text

   mcp__ruflo-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/ruflo-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:
     ts

     {
       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. RUFLO_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/ruflo-neural-trader/src/signed-attribution.mjs

     .
   • If NEITHER path resolves: log

     "[WARN] ruflo-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):
   text

   mcp__claude-flow__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

import { verifyAttributionArtifact } from 'plugins/ruflo-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;
}

• 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.

• 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/ruflo-neural-trader/src/signed-attribution.ts

  (the typed contract)

• plugins/ruflo-neural-trader/src/signed-attribution.mjs

  (the runtime mirror)

• scripts/smoke-neural-trader-feature-attribution.mjs

  (the regression smoke)