From 39212aaf816bb59f1f7d3b3560b77acc1d00c01f Mon Sep 17 00:00:00 2001 From: Antoine Date: Sat, 21 Feb 2026 08:00:14 +0000 Subject: [PATCH] auto: daily sync --- war-room-codex-analysis.md | 194 ++++++++++++++++++++++++++++++++++ war-room-migration-plan.md | 206 +++++++++++++++++++++++++++++++++++++ 2 files changed, 400 insertions(+) create mode 100644 war-room-codex-analysis.md create mode 100644 war-room-migration-plan.md diff --git a/war-room-codex-analysis.md b/war-room-codex-analysis.md new file mode 100644 index 00000000..114c6147 --- /dev/null +++ b/war-room-codex-analysis.md @@ -0,0 +1,194 @@ +# War-Room Codex Analysis (Code-Level Reality) + +Date: 2026-02-20 +Scope: Static + runtime checks starting from `atomizer.py` and `optimization_engine/run_optimization.py`. + +## 1) Entry Point Reality + +### A. `atomizer.py` is runnable +- Verified: `python3 atomizer.py --help` exits `0`. +- Top-level imports are valid. +- Command handlers branch into two very different worlds: + - **Atomizer UX path**: `intake`, `gate`, `finalize`. + - **Legacy study-script launcher**: `neural-optimize` shells into per-study `studies//run_optimization.py`. + +### B. `optimization_engine/run_optimization.py` is currently broken at import time +- Verified: `python3 optimization_engine/run_optimization.py --help` exits `1`. +- Failure: + - `optimization_engine/run_optimization.py:39` + - imports `optimization_engine.future.llm_optimization_runner` + - which imports `optimization_engine.extractor_orchestrator` at `optimization_engine/future/llm_optimization_runner.py:26` + - but only `optimization_engine/future/extractor_orchestrator.py` exists. +- Result: this entrypoint never reaches argument parsing. + +## 2) Import Chains and Dependency Graph + +## 2.1 Atomizer chain (actual reachable modules) + +```mermaid +graph TD + A[atomizer.py] + A --> TL[optimization_engine.config.template_loader] + A --> AT[optimization_engine.processors.surrogates.auto_trainer] + A --> SV[optimization_engine.validators.study_validator] + A --> IN[optimization_engine.intake] + A --> VG[optimization_engine.validation] + A --> HR[optimization_engine.reporting.html_report] + + SV --> CV[validators.config_validator] + SV --> MV[validators.model_validator] + SV --> RV[validators.results_validator] +``` + +Key behavior: +- `neural-optimize` does **not** call a central engine runner; it executes `studies//run_optimization.py` via subprocess. +- This makes runtime behavior depend on many heterogeneous study scripts. + +## 2.2 Unified runner chain (intended, but broken) + +```mermaid +graph TD + R[optimization_engine/run_optimization.py] + R --> WA[future.llm_workflow_analyzer] + R --> LR[future.llm_optimization_runner] + R --> NXU[nx.updater] + R --> NXS[nx.solver] + R --> CR[core.runner] + + LR --> HM[plugins.hook_manager] + LR -.broken import.-> EO[optimization_engine.extractor_orchestrator (missing)] + LR -.broken import.-> IC[optimization_engine.inline_code_generator (missing)] + LR -.broken import.-> HG[optimization_engine.hook_generator (missing)] +``` + +Observations: +- `OptimizationRunner` is imported in `optimization_engine/run_optimization.py:40` but not used. +- Manual mode is scaffolding and exits (`optimization_engine/run_optimization.py:286-320`). + +## 3) Tight vs Loose Coupling + +### Tight coupling (high-risk refactor areas) +- `atomizer.py` to repository layout (`studies//run_optimization.py`) and command shelling. +- `core/runner.py` to config schema and exact extractor return shape (`result[metric_name]`). +- Validation gate and intake to specific extractor functions and NX solver assumptions. +- Template loader to incorrect engine-relative paths and missing module names. + +### Loose coupling (good seams) +- Hook function interface (`dict -> optional dict`) is flexible. +- Extractor call abstraction (`name -> callable`) in runners can be standardized. +- Lazy imports in `atomizer.py` for intake/gate/finalize reduce startup coupling. + +## 4) Circular Dependencies + +Detected import cycles are limited and not the main blocker: +- `optimization_engine.extractors -> optimization_engine.extractors.extract_zernike_figure -> optimization_engine.extractors` +- `optimization_engine.model_discovery -> optimization_engine.model_discovery` (package self-cycle artifact) + +Main instability is from **missing/incorrect module paths**, not classic circular imports. + +## 5) Dead Code / Orphan Findings + +## 5.1 `optimization_engine/future/` (what is actually wired) + +Direct non-test references: +- `llm_workflow_analyzer.py`: referenced by `optimization_engine/run_optimization.py`. +- `llm_optimization_runner.py`: referenced by `optimization_engine/run_optimization.py` and some study scripts. +- `report_generator.py`: referenced by dashboard backend route. + +Mostly test/deprecation only: +- `research_agent.py`, `step_classifier.py`, `targeted_research_planner.py`, `workflow_decomposer.py`, `pynastran_research_agent.py`. + +Practically dead due broken imports: +- `future/extractor_orchestrator.py`, `future/inline_code_generator.py`, `future/hook_generator.py` are intended runtime pieces, but callers import them using missing top-level paths. + +## 5.2 Extractors (used vs orphaned) + +Clearly used in runtime paths: +- `extract_displacement.py`, `extract_von_mises_stress.py`, `bdf_mass_extractor.py` +- via validation/intake/wizard/base runner. + +Used mainly by studies/tools/dashboard: +- `extract_frequency.py`, `extract_mass_from_expression.py`, `extract_zernike*.py`, `op2_extractor.py`, `stiffness_calculator.py`. + +Likely orphaned (no non-test references found): +- `field_data_extractor.py` +- `zernike_helpers.py` + +Low-usage / isolated: +- `extract_stress_field_2d.py` (single tools reference) +- `extract_zernike_surface.py` (single study script reference) + +## 5.3 Orphaned module references (hard breaks) + +- Missing module imports in code: + - `optimization_engine.extractor_orchestrator` (missing) + - `optimization_engine.inline_code_generator` (missing) + - `optimization_engine.hook_generator` (missing) + - `optimization_engine.study_runner` (missing) + +Evidence: +- `optimization_engine/future/llm_optimization_runner.py:26-28` +- `optimization_engine/config/setup_wizard.py:26-27` +- generated script template in `optimization_engine/config/template_loader.py:216` + +## 6) Hooks/Plugins: Wired vs Scaffolding + +There are **two distinct hook concepts**: + +1. `optimization_engine/plugins/*`: +- lifecycle hook framework (`pre_solve`, `post_solve`, etc.) used by runners. + +2. `optimization_engine/hooks/*`: +- NX Open CAD/CAE API wrappers (not plugin lifecycle hooks). + +### What is actually wired +- `core/runner.py` executes hook points across trial lifecycle. +- `future/llm_optimization_runner.py` also executes lifecycle hooks. + +### Why most plugins are not actually loaded +- Wrong plugin directory resolution: + - `core/runner.py:76` uses `Path(__file__).parent / 'plugins'` -> `optimization_engine/core/plugins` (does not exist). + - `future/llm_optimization_runner.py:140` uses `optimization_engine/future/plugins` (does not exist). + - `config/setup_wizard.py:426` same issue (`optimization_engine/config/plugins`). +- Real plugin directory is `optimization_engine/plugins/`. + +### Additional plugin scaffolding mismatches +- Hook point enum uses `custom_objective` (`plugins/hooks.py:24`) but directory present is `plugins/custom_objectives/` (plural). +- `safety_factor_constraint.py` defines `register_hooks` but returns `[hook]` without calling `hook_manager.register_hook(...)` (`plugins/post_calculation/safety_factor_constraint.py:88-90`), so loader does not register it. + +Net: hook execution calls exist, but effective loaded-hook count is often zero. + +## 7) Data Flow Through Actual Code + +## 7.1 `atomizer.py` main flows + +1. `neural-optimize`: +- validate study via `validators.study_validator` +- inspect training state via `AutoTrainer` +- subprocess into `studies//run_optimization.py` +- optional post-run retraining + +2. `intake`: +- `IntakeProcessor` populates context, introspection, baseline + +3. `gate`: +- `ValidationGate` validates spec + optional test trials + extractor probes + +4. `finalize`: +- `HTMLReportGenerator` builds report + +## 7.2 `optimization_engine/run_optimization.py` intended flow + +- Parse args -> validate `prt/sim` +- `--llm`: analyze request -> setup updater/solver closures -> `LLMOptimizationRunner` -> Optuna loop +- `--config`: currently stub that exits + +Actual current behavior: import-time crash before step 1. + +## 8) High-Risk Inconsistencies Blocking Migration + +- Broken import namespace split between `future/*` and expected top-level modules. +- Template system points to wrong template/study roots and generates scripts importing missing `study_runner`. +- Hook framework looks complete but plugin discovery paths are wrong in all main call sites. +- `atomizer` delegates execution to many inconsistent study-local scripts, preventing predictable architecture. + diff --git a/war-room-migration-plan.md b/war-room-migration-plan.md new file mode 100644 index 00000000..dbd95d1e --- /dev/null +++ b/war-room-migration-plan.md @@ -0,0 +1,206 @@ +# War-Room Migration Plan (Prioritized, Code-Level) + +Date: 2026-02-20 +Goal: Stabilize entrypoints and create a coherent, testable architecture from the current code reality. + +## Phase 0 - Stop The Bleeding (P0, 1-2 days) +Risk: High if skipped, Low implementation risk + +Moves: +- Fix broken module import paths in runtime code: + - `optimization_engine/future/llm_optimization_runner.py` + - `optimization_engine/config/setup_wizard.py` +- Make `optimization_engine/run_optimization.py` importable/executable. +- Fix plugin directory resolution in all loaders: + - `core/runner.py` + - `future/llm_optimization_runner.py` + - `config/setup_wizard.py` + +Interface changes: +- None to user CLI shape. +- Internal module paths become explicit (`optimization_engine.future.*` or extracted to a new stable package). + +Dependency order: +1. Fix import paths. +2. Fix plugin discovery path. +3. Add smoke tests for `atomizer.py --help` and `optimization_engine/run_optimization.py --help`. + +Concrete refactor steps: +1. Replace missing imports with real module paths: + - `optimization_engine.extractor_orchestrator` -> `optimization_engine.future.extractor_orchestrator` + - `optimization_engine.inline_code_generator` -> `optimization_engine.future.inline_code_generator` + - `optimization_engine.hook_generator` -> `optimization_engine.future.hook_generator` +2. In hook loaders, resolve plugin root to `optimization_engine/plugins` (shared constant helper). +3. Add assertion/telemetry when no hooks are loaded to avoid silent no-op behavior. + +## Phase 1 - Entrypoint Contract Unification (P0, 2-4 days) +Risk: Medium + +Moves: +- Define a single canonical optimization runner API used by both: + - `atomizer.py` workflows + - `optimization_engine/run_optimization.py` +- Remove dead import (`OptimizationRunner`) from unified runner unless actually used. +- Implement manual mode or explicitly remove it behind feature flag. + +Interface changes: +- Introduce a stable internal entry function, e.g. `optimization_engine.app.run(spec)`. +- Keep CLI flags backward-compatible in this phase. + +Dependency order: +1. Stabilize Phase 0. +2. Create adapter layer from old study scripts to new runner API. +3. Route `run_optimization.py` through this API. + +Concrete refactor steps: +1. Create `optimization_engine/app/runner_service.py` with: + - config parsing + - model update/solve/extract loop + - hook execution +2. Convert `run_optimization.py` to thin CLI adapter. +3. Add compatibility wrapper for existing study scripts. + +## Phase 2 - Study Script Decoupling (P1, 1-2 weeks) +Risk: High (behavioral) + +Moves: +- Stop subprocess dependence on arbitrary `studies//run_optimization.py` from `atomizer.py`. +- Replace with deterministic “load study spec + run canonical engine”. + +Interface changes: +- `atomizer neural-optimize --study X` resolves study metadata and calls canonical engine directly. +- Study-local scripts become optional wrappers, not required runtime dependency. + +Dependency order: +1. Canonical runner available (Phase 1). +2. Study resolver module. +3. Migrate one or two representative studies first (UAV + M1 mirror). + +Concrete refactor steps: +1. Implement study resolver for `1_setup/optimization_config.json` and/or `atomizer_spec.json`. +2. Add `atomizer` path for direct in-process execution. +3. Keep fallback to legacy script for unmigrated studies with explicit warning. + +## Phase 3 - Hooks/Plugins Hardening (P1, 3-5 days) +Risk: Medium + +Moves: +- Consolidate lifecycle hook system (`plugins`) and clarify that NX Open wrappers (`hooks`) are separate. +- Fix mismatches: + - `custom_objective` hook point vs `custom_objectives` folder naming. + - broken plugin registration patterns (e.g. return list without registering). + +Interface changes: +- Standard plugin authoring contract: + - `register_hooks(hook_manager) -> None` + - must call `hook_manager.register_hook(...)` + +Dependency order: +1. Shared plugin root helper. +2. Plugin validation lint. +3. Hook contract docs + tests. + +Concrete refactor steps: +1. Add plugin linter test to fail on non-registered plugins. +2. Normalize folder naming to enum values. +3. Add runtime summary printout for loaded/active hooks at each hook point. + +## Phase 4 - Extractor Surface Rationalization (P1, 1 week) +Risk: Medium + +Moves: +- Classify extractors into tiers: + - Tier A (active runtime): displacement/stress/mass/frequency basics + - Tier B (domain-specific): zernike, optical, special studies + - Tier C (candidate deprecate): no references (`field_data_extractor.py`, `zernike_helpers.py`) +- Move tier C to `archive/` or mark deprecated. + +Interface changes: +- New extractor registry metadata: status (`active`, `experimental`, `deprecated`). + +Dependency order: +1. Build reference report snapshot. +2. Mark deprecated modules. +3. Remove only after one release cycle. + +Concrete refactor steps: +1. Add machine-readable registry file for extractors. +2. Enforce registration for runtime-eligible extractors. +3. Update callers to consume registry, not free-form imports. + +## Phase 5 - Template/Study Generation Repair (P1, 2-4 days) +Risk: Medium + +Moves: +- Fix template loader roots and generated script imports. +- Current issues: + - templates resolve to `optimization_engine/templates` instead of repo `templates/` JSON set. + - studies root points to missing `optimization_engine/studies`. + - generated scripts import missing `optimization_engine.study_runner`. + +Interface changes: +- `atomizer create-study` should generate runnable study directly against canonical runner API. + +Dependency order: +1. Canonical runner available (Phase 1). +2. Replace generated script template. +3. Add integration test for create+validate flow. + +Concrete refactor steps: +1. Correct template/study root resolution to repo-level paths. +2. Replace `study_runner` import with canonical service call. +3. Validate generated study with `atomizer validate` in CI smoke test. + +## Phase 6 - Future Folder Re-homing (P2, 1 week) +Risk: Low/Medium + +Moves: +- Split `optimization_engine/future/` into: + - `experimental/` (not production-wired) + - `runtime/` (production-wired) +- Remove deprecation aliases from `optimization_engine/__init__.py` that point to non-runtime pieces unless intentionally supported. + +Interface changes: +- Explicit import policy: production code cannot import `experimental` without feature flag. + +Dependency order: +1. Tag modules by runtime usage. +2. Move files and add shims. +3. Remove shims after transition window. + +Concrete refactor steps: +1. Create `optimization_engine/experimental/`. +2. Move low-usage research modules. +3. Keep only proven runtime modules in primary namespace. + +## Phase 7 - Verification and Guardrails (P0 ongoing) +Risk: High if omitted + +Moves: +- Add CI checks that would have caught current breakage: + - import smoke for both entrypoints + - plugin load count assertions + - create-study runnable check + +Concrete refactor steps: +1. Add tests: + - `test_entrypoint_imports.py` + - `test_plugin_discovery_paths.py` + - `test_template_loader_paths.py` +2. Add static scan that fails on unresolved `optimization_engine.` imports. +3. Add architecture decision record (ADR) for canonical runner + plugin model. + +## Dependency-Critical Ordering Summary +1. Phase 0 (import/plugin path fixes) +2. Phase 1 (canonical runner contract) +3. Phase 2 and 5 (atomizer/study generation migration) +4. Phase 3 (hooks hardening) +5. Phase 4 and 6 (extractor/future rationalization) +6. Phase 7 continuously + +## Quick Wins (do immediately) +1. Fix `run_optimization.py` import crash. +2. Fix all three plugin loader paths. +3. Remove or wire `OptimizationRunner` import in unified runner. +4. Fix `template_loader` roots and `study_runner` reference. +