refactor: move power engines into infx / 将功耗引擎迁入 infx

[adibarra]

Description / 说明

Power processing still lived in utils, requiring infx.results to import legacy scripts. Move both engines into infx.results.power.single_node and infx.results.power.multinode; keep the old scripts as compatibility entrypoints and import the engines directly from fixed-sequence and AgentX adapters.

Share benchmark-window parsing, per-device integration, aggregate replacement, and audit serialization. Keep each telemetry format's validation and failure policy separate. Existing commands, imports, JSON contracts, strict/best-effort behavior, and recipe inputs remain compatible. No new runtime dependencies or installation step.

功耗处理原先仍位于 utils，导致 infx.results 需要反向导入旧脚本。本次将两种引擎迁入 infx.results.power.single_node 和 infx.results.power.multinode，保留旧脚本作为兼容入口，并让固定序列和 AgentX 适配器直接导入包内引擎。

统一基准窗口解析、单设备积分、聚合结果替换和审计序列化，同时保留各遥测格式的校验及失败策略。现有命令、导入路径、JSON 契约、严格模式/尽力处理行为及配方输入保持兼容，无需新增运行时依赖或安装步骤。

Validation / 验证

• Same 274 behavior tests pass on the frozen base and refactor. An additional two tests execute the new package without any legacy scripts or site packages.

• Compared 626 JSON artifacts across 192 cases and 108 CLI calls: identical artifacts, exit codes, stdout, and diagnostics after normalizing checkout/temp paths and moved traceback frames.

• Added 28 cases using existing fixtures and independent expected values: CLI compatibility, missing telemetry, strictness, audit precision, and atomic aggregate/sidecar write failures. Isolated mutations that doubled energy, published before atomic rename, or lost audit precision were all caught.

• Result-processing CI command, run locally: 292 passed in 7.31s.

• Full local suite: 1,251 tests + 207 subtests passed in 14.07s, with four workers.

• 在冻结的基线和重构后代码上运行相同的 274 项行为测试，均通过；另有两项测试在没有旧脚本和 site packages 的环境中执行新包入口。

• 对比 192 个用例产生的 626 份 JSON 产物及 108 次 CLI 调用：归一化检出目录、临时路径和迁移后的 traceback 栈帧后，产物、退出码、标准输出及诊断一致。

• 复用现有夹具，使用独立确定的预期值新增 28 个用例，覆盖 CLI 兼容性、缺失遥测、严格模式、审计精度以及聚合结果/附属文件的原子写入失败。在隔离副本中故意引入能量翻倍、原子重命名前发布和精度丢失，测试均能检出。

• 本地运行结果处理 CI 命令：292 项通过，耗时 7.31 秒。

• 完整本地测试集：四个 worker 下，1,251 项测试及 207 项子测试通过，耗时 14.07 秒。

Scope / 范围

• Internal refactor and synchronized English/Chinese architecture documentation / 内部重构及同步的中英文架构文档
• Tested locally / 已完成本地测试
• Performance changelog: not applicable; no benchmark execution, recipe, or performance changes. / 性能变更日志不适用：未修改基准执行、配方或性能行为。
• Continues the infx package series after refactor: centralize results in infx and speed up tests / 集中结果处理并加速测试 #2940. / 延续 refactor: centralize results in infx and speed up tests / 集中结果处理并加速测试 #2940 之后的 infx 包整理工作。

---

Note

Medium Risk
Large code move touches published benchmark energy metrics and validation sidecars; behavior is intended to be identical but regressions would affect power study gating and aggregate JSON contracts.

Overview
Moves single-node and multinode GPU power validation/aggregation out of utils/aggregate_power*.py into infx.results.power (common.py, single_node, multinode), so result builders no longer depend on legacy utils scripts.

Wires infx.results.fixed_sequence and the AgentX power_adapter to import run, audit helpers, and invalid-fallback payloads from the package (e.g. invalid_validation_payload instead of ad-hoc _validation_payload / _empty_integration).

Keeps utils/aggregate_power.py and utils/aggregate_power_multinode.py as thin compatibility shims (sys.modules[__name__] = single_node|multinode) and documents python -m infx.results.power.single_node|multinode as first-class entrypoints.

Extends tests with subprocess CLI parity (in-repo vs legacy module vs package-only tree), REQUIRE_POWER strictness, and atomic write-failure behavior; updates EN/ZH architecture docs for the new layout.

^{Reviewed by Cursor Bugbot for commit 19e2bf4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[claude]

Claude finished @adibarra's task in 5m 59s —— View job

---

PR Review — refactor: move power engines into infx

• Gather context (diff vs origin/main, repo guidelines)
• Review moved power engines (infx/results/power/) for behavior changes vs legacy scripts
• Review compatibility entrypoints and adapters
• Post findings and summary

LGTM - no blocking issues found

Verified via direct comparison against origin/main:

• infx/results/power/common.py helpers (BenchmarkData, _interpolate_power, _integrate_device, _load_benchmark_data, _write_json_atomic, audit rounding, window payload) are byte-identical to the base implementations in utils/aggregate_power.py; the old multinode script already imported these from the single-node script, so there was one source of truth to move.
• The single_node.py/multinode.py diffs vs the old scripts are pure import rewiring and delegation to that identical shared code — no changes to integration math, validation reason codes, JSON serialization, rounding, or strict/best-effort exit behavior. invalid_validation_payload is a faithful wrapper around the same _validation_payload(benchmark=None, _empty_integration(...)) calls previously inlined in fixed_sequence.py and power_adapter.py.
• The sys.modules[__name__] = <engine> wrapper idiom is supported by CPython (parent package attribute is re-fetched from sys.modules after module exec), so legacy utils.aggregate_power / top-level aggregate_power imports and monkeypatches resolve to the canonical engine module, and CLI exit codes/argv handling are unchanged.
• .github/workflows/test-process-result.yml already triggers on infx/results/**, so the new engine location stays under CI coverage.
• New tests use independently derived expectations (4 GPUs × 350 W × 60 s = 84,000 J; 10,500 J/query) and exercise the real CLI entrypoints, consistent with the repo test-quality policy.

Note: I could not execute the pytest suite locally (command not permitted in this session's allowed tools), so verification above is from static comparison; the test-process-result workflow runs the same suite on this PR.

[claude]

Looks good — this is a faithful, mechanical refactor: the single-node and multinode power engines were moved into infx/results/power/{single_node,multinode}.py with shared helpers (benchmark-window parsing, per-device integration, atomic JSON write, audit-metric rounding) factored into infx/results/power/common.py, and utils/aggregate_power*.py reduced to compatibility shims that alias sys.modules to the new modules. Diffing the moved code against the pre-refactor originals (via git diff -C) confirms no logic changes — only extraction into shared helpers and delegation. infx/results/fixed_sequence.py and utils/agentic/aggregation/power_adapter.py now import the engines directly from infx.results.power, removing the prior reverse-dependency from infx into utils, and utils/test_aggregate_power.py adds coverage for CLI compatibility (legacy script, -m utils.aggregate_power, and the packaged -m infx.results.power.* entrypoints) plus atomic-write-failure and audit-precision cases.

Extended reasoning...

Overview

This PR moves two power-processing engines (utils/aggregate_power.py for single-node GPU telemetry, utils/aggregate_power_multinode.py for multinode srt-slurm DCGM artifacts) into infx/results/power/single_node.py and infx/results/power/multinode.py, extracting genuinely shared logic (benchmark-window loading/validation, per-device trapezoidal power integration, atomic JSON writes, audit-metric rounding, and the patch_power_metrics/with_power_metrics transform) into a new infx/results/power/common.py. The old utils/aggregate_power*.py files become thin compatibility shims that import the new module and do sys.modules[__name__] = <new module>, which correctly preserves both from utils.aggregate_power import X and direct-script-execution behavior. Two consumers (infx/results/fixed_sequence.py, utils/agentic/aggregation/power_adapter.py) were updated to import the engines directly from infx.results.power, eliminating the previous infx → utils reverse dependency described in the PR body. Documentation (docs/architecture.md/_zh.md) was updated to match. infx/results/power.py was renamed (100% similarity, confirmed via git diff -C) to infx/results/power/__init__.py with no content change.

Security risks

None identified. This is a pure internal code-organization refactor of an offline power/energy telemetry post-processing pipeline (reads CSV/JSON artifacts, writes JSON results). No new external inputs, no auth/crypto/permission logic, no network or shell execution introduced. The sys.modules[__name__] = module aliasing pattern in the compat shims is unusual but well-understood — it only affects Python's own import resolution within this repo's process, not any trust boundary.

Level of scrutiny

I diffed the actual moved code against the pre-refactor versions using git diff -C -C (copy detection) rather than trusting the description, and confirmed the multinode engine is 97% similar (only the shared-helper delegation changed) and the single-node engine is 83% similar (helper functions literally cut and pasted into common.py, call sites updated to delegate) — no behavioral hunks beyond that. I also read the new common.py, single_node.py, and the compat shims in full, and checked that infx/results/fixed_sequence.py's import-failure test in utils/test_process_result.py was updated to match the new import path (power.multinode) used internally. This is exactly the kind of change (large line count, but low actual risk, single well-scoped refactor, heavily tested) that warrants approval once verified rather than deferral.

Other factors

The PR author's own validation (274 shared behavior tests, 626 JSON artifact comparisons, 28 new tests including standalone-package execution and induced-fault detection) is consistent with what the diff shows, and the new utils/test_aggregate_power.py includes concrete regression coverage for the compatibility surface (running via legacy script path, -m utils.aggregate_power, and the new -m infx.results.power.single_node/multinode entrypoints, plus atomic-rename-failure and audit-precision-rounding cases). I was not able to execute the test suite myself in this sandbox (test execution is blocked), so approval here rests on manual line-by-line diff verification rather than a live test run, but that verification was thorough enough to have high confidence given the mechanical nature of the change.