trader-portfolio-cg

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Solve the mean-variance optimization

Σ · x = μ

via Conjugate Gradient instead of the legacy Neumann series.

Why CG instead of Neumann (ADR-123 Wedge 8):

Neumann series: ~50 µs at n=256 (legacy
```
npx neural-trader --portfolio optimize
```
)
Conjugate Gradient: ~816 ns at n=256 (this skill)
Measured speedup: 40-60×; parity within 1e-4 on a fixed seed.

The covariance matrix Σ is symmetric positive-definite by construction (it's a Gram matrix on real returns), so CG is provably optimal — it converges in at most n iterations with no preconditioning, and typically far fewer when eigenvalues cluster.

Disable flag: set

RUFLO_NEURAL_TRADER_DISABLE_CG=1

to skip the CG path entirely and fall through to step 4's legacy Neumann route. Useful for A/B validation or when an upstream covariance regression breaks SPD.

Native dispatch flag: set

RUFLO_SUBLINEAR_NATIVE=1

to force the adapter to attempt the native

mcp__ruflo-sublinear__solve

path even when

globalThis

doesn't expose the tool (e.g. when the harness mounts it via a different transport). On any native-dispatch failure the adapter cleanly falls back to the local JS CG and records

method: 'cg-local'

in the artifact metadata — so the regression is auditable.

Steps:

Ensure neural-trader is available:

bash

npm ls neural-trader 2>/dev/null || npm install --ignore-scripts neural-trader

Read the current covariance matrix Σ and expected-return vector μ from neural-trader's portfolio API:

bash

# Primary path (preferred — clean JSON):
npx neural-trader --portfolio current --json
# Fallback paths if the --json flag is unavailable on the installed version:
npx neural-trader --portfolio current  # parse the text output
# OR pull from AgentDB if a prior run stored the matrix there:

text

mcp__claude-flow__memory_search({ query: "covariance matrix current", namespace: "trading-risk", limit: 1 })

The skill expects the response to include

covariance: number[][]

(n × n) and

expectedReturns: number[]

(length n).

Solve Σ · x = μ via the SublinearAdapter (preferred path) when

RUFLO_NEURAL_TRADER_DISABLE_CG

is unset:

import { sublinearAdapter } from '../../src/sublinear-adapter.mjs';
const result = await sublinearAdapter.solveCG(COVARIANCE, EXPECTED_RETURNS, {
  tolerance: 1e-6,
  maxIterations: 200,
});
// result.solution    — optimal weights (number[])
// result.iterations  — CG iterations executed
// result.residual    — final ||A·x − b||₂
// result.latencyMs   — wall-clock latency
// result.method      — 'cg-sublinear-native' | 'cg-local'   <-- READ THIS
// result.solver      — 'sublinear-time-solver@1.7.0' | 'local-js-cg'
// result.degraded    — true if input failed SPD checks (fall back to step 4)

The adapter does the dispatch itself: it probes for

mcp__ruflo-sublinear__solve

globalThis

(and honours

RUFLO_SUBLINEAR_NATIVE=1

as a manual override), routes through the native kernel when reachable, and falls back transparently to the embedded ~50-LOC JS CG when not. The math is identical either way — CG, dense form, n × n SPD covariance. The operator reads

result.method

to know which backend produced the artifact.

The native MCP tool's wire shape (for direct callers who want to bypass the adapter):

text

mcp__ruflo-sublinear__solve({
  matrix: COVARIANCE,
  rhs: EXPECTED_RETURNS,
  algorithm: "cg",
  tolerance: 1e-6,
  maxIterations: 200
})

Output:

{ solution: number[], iterations: number, residual: number }

Fallback (legacy Neumann) — if step 3 reports
```
degraded: true
```
(non-SPD input, non-square matrix, MCP error) OR if
```
RUFLO_NEURAL_TRADER_DISABLE_CG=1
```
:
bash
```
npx neural-trader --portfolio optimize
```
Capture the weights output and tag the artifact metadata with
```
method: 'neumann-fallback'
```
and a
```
reason
```
field.

Store the optimal weights to

trading-risk

namespace with full provenance metadata. Take
method
and
solver
straight from the adapter's result so the operator can verify which backend ran:

text

mcp__claude-flow__memory_store({
  key: "portfolio-weights-PORTFOLIO_ID-TIMESTAMP",
  namespace: "trading-risk",
  value: JSON.stringify({
    weights: result.solution,           // number[] from step 3 (or weights from step 4 fallback)
    method: result.method,              // 'cg-sublinear-native' | 'cg-local' | 'neumann-fallback'
    solver: result.solver,              // 'sublinear-time-solver@1.7.0' | 'local-js-cg' | 'neural-trader-cli'
    iterations: result.iterations,
    residual: result.residual,
    latencyMs: result.latencyMs,
    capturedAt: NEW_DATE_ISO,
    reason: FALLBACK_REASON || null
  })
})

The

trading-risk

namespace is canonical (ADR-126 Phase 1; the five-namespace alignment). Long-lived — no TTL — because portfolio weights are the audit trail Phase 4 will Ed25519-sign.

Cross-check against historical patterns (optional but recommended):
text
```
mcp__claude-flow__agentdb_pattern-search({
  query: "portfolio weights Sharpe regime:CURRENT_REGIME",
  namespace: "trading-risk"
})
```
If the new weights differ by more than 30% in any single asset from the historical median, flag for human review before applying. This is a guard-rail, not a hard block.

Acceptance criteria (ADR-126 Phase 3):

Latency < 1 ms on n = 256 covariance (local JS CG); native path target 40-60× faster (816 ns native vs 50 µs Neumann per sublinear-time-solver@1.7.0).
Parity with legacy Neumann within
```
||cg − neumann||_∞ < 1e-4
```
on a fixed seed.
Fallback path engages cleanly when native MCP unavailable / covariance non-SPD.

Artifact metadata distinguishes

cg-sublinear-native

cg-local

, and

neumann-fallback

Refs:

ADR-126 Phase 3 (this skill's authoring ADR)
ADR-123 §162 Row 8 (Wedge 8 speedup claim)
ADR-123 §262-289 (the SublinearAdapter contract)

plugins/ruflo-neural-trader/src/sublinear-adapter.ts

(the adapter)

plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.ts

(the measured numbers)

使用共轭梯度（Conjugate Gradient，简称CG）替代传统Neumann级数来求解均值-方差优化问题

Σ · x = μ

。

为何选择CG而非Neumann（ADR-123第8项）：

Neumann级数：n=256时约50微秒（传统
```
npx neural-trader --portfolio optimize
```
命令）
共轭梯度：n=256时约816纳秒（本技能实现）
实测提速：40-60倍；固定随机种子下结果误差在1e-4以内。

协方差矩阵Σ本质上是对称正定（symmetric positive-definite，简称SPD）的（它是基于实际收益率的Gram矩阵），因此CG算法具有可证明的最优性——无需预条件即可在最多n次迭代内收敛，当特征值聚类时通常迭代次数会少得多。

禁用标志：设置

RUFLO_NEURAL_TRADER_DISABLE_CG=1

可完全跳过CG路径，转而使用步骤4中的传统Neumann方法。适用于A/B验证或上游协方差回归导致SPD属性失效的场景。

原生调度标志：设置

RUFLO_SUBLINEAR_NATIVE=1

可强制适配器尝试调用原生

mcp__ruflo-sublinear__solve

路径，即使

globalThis

未暴露该工具（例如当测试套件通过其他传输方式挂载它时）。若原生调度失败，适配器会平稳回退到本地JS实现的CG算法，并在产物元数据中记录

method: 'cg-local'

——因此回归情况可被审计。

步骤：

确保neural-trader可用：

bash

npm ls neural-trader 2>/dev/null || npm install --ignore-scripts neural-trader

从neural-trader的投资组合API读取当前协方差矩阵Σ和预期收益向量μ：

bash

# Primary path (preferred — clean JSON):
npx neural-trader --portfolio current --json
# Fallback paths if the --json flag is unavailable on the installed version:
npx neural-trader --portfolio current  # parse the text output
# OR pull from AgentDB if a prior run stored the matrix there:

text

mcp__claude-flow__memory_search({ query: "covariance matrix current", namespace: "trading-risk", limit: 1 })

该技能要求响应包含

covariance: number[][]

（n×n矩阵）和

expectedReturns: number[]

（长度为n的向量）。

当未设置
RUFLO_NEURAL_TRADER_DISABLE_CG
时，通过SublinearAdapter求解Σ · x = μ（首选路径）：

import { sublinearAdapter } from '../../src/sublinear-adapter.mjs';
const result = await sublinearAdapter.solveCG(COVARIANCE, EXPECTED_RETURNS, {
  tolerance: 1e-6,
  maxIterations: 200,
});
// result.solution    — 最优权重（number[]）
// result.iterations  — 执行的CG迭代次数
// result.residual    — 最终的||A·x − b||₂值
// result.latencyMs   — 实际耗时（毫秒）
// result.method      — 'cg-sublinear-native' | 'cg-local'   <-- 请关注此字段
// result.solver      — 'sublinear-time-solver@1.7.0' | 'local-js-cg'
// result.degraded    — 若输入未通过SPD检查则为true（回退到步骤4）

适配器会自动处理调度：它会探测

globalThis

上的

mcp__ruflo-sublinear__solve

（并将

RUFLO_SUBLINEAR_NATIVE=1

作为手动覆盖选项），当可访问时路由到原生内核，否则透明回退到内嵌的约50行代码的JS版CG算法。两种方式的数学逻辑完全一致——均为CG算法、稠密矩阵形式、n×n的SPD协方差矩阵。操作人员可通过

result.method

了解产物由哪个后端生成。

原生MCP工具的调用格式（供想要绕过适配器的直接调用者使用）：

text

mcp__ruflo-sublinear__solve({
  matrix: COVARIANCE,
  rhs: EXPECTED_RETURNS,
  algorithm: "cg",
  tolerance: 1e-6,
  maxIterations: 200
})

输出：

{ solution: number[], iterations: number, residual: number }

回退方案（传统Neumann方法） — 若步骤3返回
```
degraded: true
```
（输入非SPD、非方阵、MCP错误）或设置了
```
RUFLO_NEURAL_TRADER_DISABLE_CG=1
```
：
bash
```
npx neural-trader --portfolio optimize
```
捕获输出的权重，并在产物元数据中标记
```
method: 'neumann-fallback'
```
和
```
reason
```
字段。

将最优权重存储到
trading-risk
命名空间，并附带完整来源元数据。直接从适配器结果中获取
method
和
solver
，以便操作人员验证使用的后端：

text

mcp__claude-flow__memory_store({
  key: "portfolio-weights-PORTFOLIO_ID-TIMESTAMP",
  namespace: "trading-risk",
  value: JSON.stringify({
    weights: result.solution,           // number[] from step 3 (or weights from step 4 fallback)
    method: result.method,              // 'cg-sublinear-native' | 'cg-local' | 'neumann-fallback'
    solver: result.solver,              // 'sublinear-time-solver@1.7.0' | 'local-js-cg' | 'neural-trader-cli'
    iterations: result.iterations,
    residual: result.residual,
    latencyMs: result.latencyMs,
    capturedAt: NEW_DATE_ISO,
    reason: FALLBACK_REASON || null
  })
})

trading-risk

命名空间是标准规范（ADR-126第一阶段；五命名空间对齐）。长期存储——无TTL（生存时间）——因为投资组合权重是第四阶段将使用Ed25519签名的审计追踪数据。

与历史模式交叉校验（可选但推荐）：
text
```
mcp__claude-flow__agentdb_pattern-search({
  query: "portfolio weights Sharpe regime:CURRENT_REGIME",
  namespace: "trading-risk"
})
```
若新权重中任意单一资产与历史中位数差异超过30%，则在应用前标记为需人工审核。这是一个防护措施，而非硬性阻止。

验收标准（ADR-126第三阶段）：

n=256的协方差矩阵下，本地JS版CG耗时<1毫秒；原生路径目标提速40-60倍（根据sublinear-time-solver@1.7.0的数据，原生耗时816纳秒vs Neumann耗时50微秒）。
固定随机种子下，与传统Neumann方法的结果误差满足
```
||cg − neumann||_∞ < 1e-4
```
。
当原生MCP不可用/协方差矩阵非SPD时，回退路径可平稳触发。
产物元数据可区分
```
cg-sublinear-native
```
、
```
cg-local
```
和
```
neumann-fallback
```
三种方式。

参考资料：

ADR-126第三阶段（本技能的编写规范）
ADR-123第162行第8项（Wedge 8提速声明）
ADR-123第262-289节（SublinearAdapter契约）

plugins/ruflo-neural-trader/src/sublinear-adapter.ts

（适配器代码）

plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.ts

（性能测试数据）