v0.3.3 — Graph-layer architecture review: model/renderer split, correctness + perf fixes, issue #1

Large architecture-review pass over the alphaDeesp graph layer: correctness
fixes, performance work, two deep revisions, the interactive-viewer
decomposition, and the fix for the multigraph Dijkstra-weight bug (#1).

Backward-compatible: all public import paths are unchanged
(from alphaDeesp.core.graphsAndPaths import ... still works). 418 unit tests
pass without grid2op; changes were cross-checked by adversarial multi-agent
verification. The grid2op integration suites and the new capacity-weighted
routing mode still want validation on reference grids in CI.

Bug fixes

• Multigraph Dijkstra weight in the null-flow path search (#1). On the overflow MultiDiGraph, networkx passes a callable weight the {key: attr} parallel-edge view, so _compute_sssp_paths' attr.get("capacity", 0) read 0 — routing was hop-cost-only. The weight is now precomputed as an edge attribute (string-weight Dijkstra) with a capacity_weighted switch: False (default) reproduces the historical behaviour bit-identical ("bless"); True enables capacity-weighted routing with correct min-parallel capacity and (u,v)/(u,v,key) promoted matching ("fix"). Threaded through add_relevant_null_flow_lines[_all_paths] so downstream callers can opt in without patching.
• shortest_paths.py: removed a dead branch; made promoted-edge matching multigraph-correct (was silently weighting every parallel edge as 0).
• OverFlowGraph.__init__ no longer mutates the caller's DataFrame (copies it); rename_nodes clarified (behaviour unchanged).
• Structured_Overload_Distribution_Graph.get_dispatch_edges_nodes guards the empty-loops case (no more TypeError on a grid with no loop paths).
• to_DiGraph defaults a missing edge capacity to 0.0 (was 1.0), which no longer skews rank_red_loops' min-cut.

Deep revisions

• OverFlowGraph model/renderer split: new OverflowGraphRenderer owns all Graphviz presentation; OverFlowGraph keeps the semantic model. New edge_roles.py (edge_role_of, EDGE_ROLE_*, OverFlowGraph.edge_role) is the single authority mapping an edge's base colour to a role — no consumer parses colour strings; highlight_significant_line_loading records an authoritative base_color.
• AlphaDeesp explicit pipeline: ranking moved to run(); AlphaDeesp(..., auto_run=True) (default) preserves previous behaviour, auto_run=False builds without side effects.
• Lazy Structured_Overload_Distribution_Graph: colour views, red_loops and hubs are functools.cached_property computed from a construction-time snapshot — behaviour-identical and order-independent.

Performance

• delete_color_edges accepts a colour or an iterable of colours (single graph copy); derived views built in single passes.
• sort_hubs and the initial-inflow lookup vectorised (were per-hub / per-edge iterrows scans).
• simulation.create_df vectorised (400-case differential fuzz pins equivalence).
• Null-flow Dijkstra uses a precomputed string weight instead of a per-edge Python callable.

Maintainability & docs

• core/interactive_html.py (976 LOC) split into the core/interactive_html/ package (8 focused modules) with CSS/JS/HTML externalised under assets/ and reassembled byte-exactly at runtime (shipped via package_data).
• find_loops / consolidation path enumeration gained opt-in cutoffs (default None = unbounded = original behaviour).
• New Architecture guide + autodoc API reference (docs/ARCHITECTURE.rst, docs/API.rst); docs/CODE_REVIEW.md (full review + downstream-impact analysis on Expert_op4grid_recommender); CLAUDE.md refreshed.

Tests

New suites: test_edge_roles, test_overflow_renderer, test_simulation_create_df, test_null_flow_weighting, test_graph_consolidation, test_elements, test_simulation_helpers, test_alphadeesp_combinations; expanded test_graphs_package, test_overflow_graph, test_alphadeesp_unit, test_shortest_paths, test_interactive_html, test_topo_applicator.

Full changelog: v0.3.2.post4...v0.3.3