architecture-extractor 0.27.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. architecture_extractor-0.27.0/LICENSE +21 -0
  2. architecture_extractor-0.27.0/PKG-INFO +87 -0
  3. architecture_extractor-0.27.0/README.md +66 -0
  4. architecture_extractor-0.27.0/pyproject.toml +29 -0
  5. architecture_extractor-0.27.0/setup.cfg +4 -0
  6. architecture_extractor-0.27.0/src/ae/__init__.py +3 -0
  7. architecture_extractor-0.27.0/src/ae/cli.py +90 -0
  8. architecture_extractor-0.27.0/src/ae/presenter/__init__.py +3 -0
  9. architecture_extractor-0.27.0/src/ae/presenter/api.py +157 -0
  10. architecture_extractor-0.27.0/src/ae/presenter/efficientnet_hierarchy.py +50 -0
  11. architecture_extractor-0.27.0/src/ae/presenter/flow.py +212 -0
  12. architecture_extractor-0.27.0/src/ae/presenter/flow_layout.py +171 -0
  13. architecture_extractor-0.27.0/src/ae/presenter/health.py +73 -0
  14. architecture_extractor-0.27.0/src/ae/presenter/instance_flow.py +135 -0
  15. architecture_extractor-0.27.0/src/ae/presenter/instance_hierarchy.py +188 -0
  16. architecture_extractor-0.27.0/src/ae/presenter/layout.py +155 -0
  17. architecture_extractor-0.27.0/src/ae/presenter/mobilenetv3_hierarchy.py +81 -0
  18. architecture_extractor-0.27.0/src/ae/presenter/projection.py +240 -0
  19. architecture_extractor-0.27.0/src/ae/presenter/reader.py +41 -0
  20. architecture_extractor-0.27.0/src/ae/presenter/render.py +185 -0
  21. architecture_extractor-0.27.0/src/ae/presenter/semantic.py +129 -0
  22. architecture_extractor-0.27.0/src/ae/presenter/themes/__init__.py +4 -0
  23. architecture_extractor-0.27.0/src/ae/presenter/themes/scientific_latex.py +49 -0
  24. architecture_extractor-0.27.0/src/ae/presenter/vgg16_hierarchy.py +53 -0
  25. architecture_extractor-0.27.0/src/ae/presenter/web_viewer.py +281 -0
  26. architecture_extractor-0.27.0/src/ae/sae/__init__.py +4 -0
  27. architecture_extractor-0.27.0/src/ae/sae/analysis/__init__.py +0 -0
  28. architecture_extractor-0.27.0/src/ae/sae/analysis/analyzer.py +366 -0
  29. architecture_extractor-0.27.0/src/ae/sae/analysis/composite_shapes.py +320 -0
  30. architecture_extractor-0.27.0/src/ae/sae/analysis/configuration.py +79 -0
  31. architecture_extractor-0.27.0/src/ae/sae/analysis/container_specialization.py +341 -0
  32. architecture_extractor-0.27.0/src/ae/sae/analysis/dataflow.py +258 -0
  33. architecture_extractor-0.27.0/src/ae/sae/analysis/dense_instance_forward.py +205 -0
  34. architecture_extractor-0.27.0/src/ae/sae/analysis/efficientnet_b0_instance_forward.py +276 -0
  35. architecture_extractor-0.27.0/src/ae/sae/analysis/factory_specialization.py +298 -0
  36. architecture_extractor-0.27.0/src/ae/sae/analysis/forward_flow.py +275 -0
  37. architecture_extractor-0.27.0/src/ae/sae/analysis/instance_forward.py +518 -0
  38. architecture_extractor-0.27.0/src/ae/sae/analysis/interprocedural.py +191 -0
  39. architecture_extractor-0.27.0/src/ae/sae/analysis/mobilenetv3_instance_forward.py +324 -0
  40. architecture_extractor-0.27.0/src/ae/sae/analysis/nested_shapes.py +87 -0
  41. architecture_extractor-0.27.0/src/ae/sae/analysis/pytorch_static.py +154 -0
  42. architecture_extractor-0.27.0/src/ae/sae/analysis/scopes.py +49 -0
  43. architecture_extractor-0.27.0/src/ae/sae/analysis/symbolic_shapes.py +152 -0
  44. architecture_extractor-0.27.0/src/ae/sae/analysis/unet_instance_forward.py +358 -0
  45. architecture_extractor-0.27.0/src/ae/sae/analysis/vgg16_instance_forward.py +168 -0
  46. architecture_extractor-0.27.0/src/ae/sae/analysis/vit_instance_forward.py +330 -0
  47. architecture_extractor-0.27.0/src/ae/sae/api.py +266 -0
  48. architecture_extractor-0.27.0/src/ae/sae/indexing/__init__.py +0 -0
  49. architecture_extractor-0.27.0/src/ae/sae/indexing/inherited_forward.py +127 -0
  50. architecture_extractor-0.27.0/src/ae/sae/indexing/model_index.py +370 -0
  51. architecture_extractor-0.27.0/src/ae/sae/indexing/nested_templates.py +103 -0
  52. architecture_extractor-0.27.0/src/ae/sae/inventory/__init__.py +0 -0
  53. architecture_extractor-0.27.0/src/ae/sae/inventory/walker.py +86 -0
  54. architecture_extractor-0.27.0/src/ae/sae/ir/__init__.py +0 -0
  55. architecture_extractor-0.27.0/src/ae/sae/ir/canonical.py +19 -0
  56. architecture_extractor-0.27.0/src/ae/sae/ir/models.py +34 -0
  57. architecture_extractor-0.27.0/src/ae/sae/ir/validator.py +63 -0
  58. architecture_extractor-0.27.0/src/ae/sae/linking/__init__.py +0 -0
  59. architecture_extractor-0.27.0/src/ae/sae/linking/project.py +380 -0
  60. architecture_extractor-0.27.0/src/ae/sae/output/__init__.py +0 -0
  61. architecture_extractor-0.27.0/src/ae/sae/output/bundle.py +21 -0
  62. architecture_extractor-0.27.0/src/ae/sae/parsing/__init__.py +0 -0
  63. architecture_extractor-0.27.0/src/ae/sae/parsing/python_parser.py +35 -0
  64. architecture_extractor-0.27.0/src/ae/sae/parsing/source_spans.py +54 -0
  65. architecture_extractor-0.27.0/src/ae/sae/settings.py +18 -0
  66. architecture_extractor-0.27.0/src/ae/verification/__init__.py +1 -0
  67. architecture_extractor-0.27.0/src/ae/verification/fx_correspondence.py +142 -0
  68. architecture_extractor-0.27.0/src/ae/verification/instance_correspondence.py +235 -0
  69. architecture_extractor-0.27.0/src/ae/verification/runtime_reference.py +186 -0
  70. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/PKG-INFO +87 -0
  71. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/SOURCES.txt +106 -0
  72. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/dependency_links.txt +1 -0
  73. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/entry_points.txt +2 -0
  74. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/requires.txt +12 -0
  75. architecture_extractor-0.27.0/src/architecture_extractor.egg-info/top_level.txt +1 -0
  76. architecture_extractor-0.27.0/tests/test_architecture_diversity.py +83 -0
  77. architecture_extractor-0.27.0/tests/test_collection_provenance_v09.py +193 -0
  78. architecture_extractor-0.27.0/tests/test_composite_shapes_v013.py +174 -0
  79. architecture_extractor-0.27.0/tests/test_container_specialization_v012.py +161 -0
  80. architecture_extractor-0.27.0/tests/test_dataflow.py +49 -0
  81. architecture_extractor-0.27.0/tests/test_factory_specialization.py +114 -0
  82. architecture_extractor-0.27.0/tests/test_flow_v06.py +105 -0
  83. architecture_extractor-0.27.0/tests/test_forward_flow.py +149 -0
  84. architecture_extractor-0.27.0/tests/test_full_densenet121_v018.py +79 -0
  85. architecture_extractor-0.27.0/tests/test_full_efficientnet_b0_v024.py +99 -0
  86. architecture_extractor-0.27.0/tests/test_full_mobilenetv3_small_v022.py +168 -0
  87. architecture_extractor-0.27.0/tests/test_full_resnet50_v017.py +52 -0
  88. architecture_extractor-0.27.0/tests/test_full_unet_resnet34_v019.py +130 -0
  89. architecture_extractor-0.27.0/tests/test_full_vgg16_v023.py +113 -0
  90. architecture_extractor-0.27.0/tests/test_full_vit_tiny_v020.py +196 -0
  91. architecture_extractor-0.27.0/tests/test_fx_correspondence_v014.py +94 -0
  92. architecture_extractor-0.27.0/tests/test_instance_correspondence_v015.py +167 -0
  93. architecture_extractor-0.27.0/tests/test_instance_forward_v016.py +83 -0
  94. architecture_extractor-0.27.0/tests/test_interprocedural_v08.py +187 -0
  95. architecture_extractor-0.27.0/tests/test_mvp_architecture.py +122 -0
  96. architecture_extractor-0.27.0/tests/test_nested_forward_v011.py +155 -0
  97. architecture_extractor-0.27.0/tests/test_nested_shapes_v014.py +204 -0
  98. architecture_extractor-0.27.0/tests/test_phase2_research_v025.py +46 -0
  99. architecture_extractor-0.27.0/tests/test_phase3_viewer_v026.py +74 -0
  100. architecture_extractor-0.27.0/tests/test_presenter.py +172 -0
  101. architecture_extractor-0.27.0/tests/test_project_linking.py +111 -0
  102. architecture_extractor-0.27.0/tests/test_pytorch_semantics.py +66 -0
  103. architecture_extractor-0.27.0/tests/test_realworld_completeness_gate.py +51 -0
  104. architecture_extractor-0.27.0/tests/test_research_integration.py +42 -0
  105. architecture_extractor-0.27.0/tests/test_sae.py +207 -0
  106. architecture_extractor-0.27.0/tests/test_scientific_theme.py +88 -0
  107. architecture_extractor-0.27.0/tests/test_v027_generalization_runtime.py +124 -0
  108. architecture_extractor-0.27.0/tests/test_verification_phase.py +64 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MAGG contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,87 @@
1
+ Metadata-Version: 2.4
2
+ Name: architecture-extractor
3
+ Version: 0.27.0
4
+ Summary: Static Python/PyTorch architecture extraction and vector diagrams
5
+ Author: AE contributors
6
+ License-Expression: MIT
7
+ Keywords: pytorch,static-analysis,architecture,intermediate-representation
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: PyYAML<7,>=6.0
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest>=8; extra == "dev"
14
+ Requires-Dist: jsonschema>=4; extra == "dev"
15
+ Requires-Dist: reportlab>=4; extra == "dev"
16
+ Provides-Extra: render
17
+ Requires-Dist: reportlab>=4; extra == "render"
18
+ Provides-Extra: runtime
19
+ Requires-Dist: torch<3,>=2.4; extra == "runtime"
20
+ Dynamic: license-file
21
+
22
+ # Architecture Extractor (AE)
23
+
24
+ Static Python/PyTorch architecture extraction and vector diagrams. Models are not imported or executed.
25
+
26
+ ## Install
27
+
28
+ ```bash
29
+ pip install -e '.[dev,render]'
30
+ ```
31
+
32
+ ## Commands
33
+
34
+ ```bash
35
+ ae extract examples/cnn_residual_mvp --entrypoint model:CNN --output ae-bundle
36
+ ae validate ae-bundle
37
+ ae inspect ae-bundle
38
+ ae present ae-bundle --view structure --level operation --format all --output figures
39
+ ```
40
+
41
+ ## Output
42
+
43
+ SAE: source-backed IR, model index, source snapshots, hashes and unresolved records. Presenter: SVG, PDF, TikZ and health/provenance manifests.
44
+
45
+ Static factory specialization: ResNet block configuration; supported fixed-count nested containers (including DenseNet factory stages). Counts are conditional construction blueprints, not runtime tensor paths.
46
+
47
+ Nested shape propagation, FX source-site audit, and [instance-aware FX verification](docs/instance-fx-v0.15.md).
48
+
49
+ Bounded full forward expansion for the verified default ResNet18 and ResNet50 factories:
50
+
51
+ ```bash
52
+ ae extract path/to/torchvision/models --entrypoint resnet:resnet18 --input-shape 1,3,64,64 --output ae-bundle
53
+ ae present ae-bundle --view instance --level operation --format all --output figures
54
+ ```
55
+
56
+ The static instance graph is conditional on the input and source proof. [Scope and independent gate](docs/instance-forward-v0.16.md).
57
+
58
+ ## Tests
59
+
60
+ ```bash
61
+ python -m pytest -q
62
+ python scripts/verify_container_specialization.py
63
+ ```
64
+
65
+ See docs/limitations.md and docs/container-specialization-v0.12.md.
66
+
67
+ ResNet50 Bottleneck support: [independent stage gate](docs/instance-forward-v0.17.md).
68
+
69
+ DenseNet121 (TorchVision 0.25.0 default factory): bounded, source-verified instance forward graph with complete feature-list concatenation dependencies for the audited input shapes. See [v0.18 scope and independent verification](docs/instance-forward-v0.18.md). Other variants and modified source remain unsupported.
70
+
71
+ SMP 0.6.0 U-Net/ResNet34 bounded, source-proven instance graph and external FX/hooks validation: [v0.19](docs/instance-forward-v0.19.md). Non-Tensor shape metadata is labeled separately; its nodes do not have Tensor shapes.
72
+
73
+ timm ViT-Tiny (1.0.22): bounded 12-block source-only instance-forward expansion with explicit `--attention-mode fused|unfused` and independent FX/hooks validation. See [v0.20](docs/instance-forward-v0.20.md). Other ViTs and modified sources remain unsupported.
74
+
75
+ Presenter v0.21: source-backed hierarchical instance views for the exact pinned ViT-Tiny reference. `ae present ae-bundle --view instance --level overview|block|operation` and `--level operation --focus blocks.0`. Overview/block group operation and edge provenance without modifying the underlying instance graph; the detail view remains 1:1. [Scope and evidence policy](docs/instance-hierarchy-v0.21.md).
76
+
77
+ MobileNetV3 Small: audited TorchVision 0.25.0 default `mobilenet_v3_small(weights=None)` source-only full forward extraction for 64/128/224 square RGB inputs. Independent FX, ShapeProp, runtime hooks, ordered edges and manifest checks; 159 operations / 173 dependencies. Original-source-only `overview`, `block` and `operation` views, with `--focus features.4`. [Scope and limitations](docs/instance-forward-v0.22.md). Arbitrary variants are unsupported.
78
+
79
+ VGG16 source-only (v0.23) default torchvision 0.25.0: verified 42 operations / 41 ordered dependencies / 39 leaf calls. Two-level source-evidenced overview/block/operation visualizations and stage focus. See docs/instance-forward-v0.23.md.
80
+
81
+ EfficientNet-B0 source-only (v0.24): audited TorchVision 0.25.0 default model, 251 FX operations / 275 ordered dependencies, 214 leaf modules, 16 SE gates and 9 residual additions. Supports source-proven overview/block/operation/focus views for four audited input shapes. See [scope and independent verification](docs/instance-forward-v0.24.md).
82
+
83
+ Research generalization v0.25: source-only audits on exact pinned AWN and Chessformer CF-ACT/CF-CAH repositories (no claimed runtime equivalence), plus independent FX/torchview/torchviz/VisualTorch comparison. [Scope, scripts and evidence policy](docs/phase2-research-benchmark.md).
84
+
85
+ Offline interactive viewer v0.26 (Architecture / Block / Operation, zoom/pan, source-proven drill-down, no browser networking): `ae viewer BUNDLE --view instance --output viewer`, then open `viewer/index.html`. For general sources use `--view structure` or `--view nested`; unsupported full instance paths remain blocked. [Clean installation and release gate](docs/public-release-v026.md).
86
+
87
+ AE v0.27 adds generic source-category colors and default auto-selecting offline hierarchies with source-identity search/drill-down. **The default extractor still does not import or execute the target.** For deliberately trusted projects, `ae runtime-audit SOURCE --factory module:build --input-shape 1,3,64,64 --allow-execute --output audit` generates an independent PyTorch FX/hooks reference; this executes user code and does not establish AE-to-runtime equivalence. [v0.27 scope](docs/v027-generalization.md).
@@ -0,0 +1,66 @@
1
+ # Architecture Extractor (AE)
2
+
3
+ Static Python/PyTorch architecture extraction and vector diagrams. Models are not imported or executed.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pip install -e '.[dev,render]'
9
+ ```
10
+
11
+ ## Commands
12
+
13
+ ```bash
14
+ ae extract examples/cnn_residual_mvp --entrypoint model:CNN --output ae-bundle
15
+ ae validate ae-bundle
16
+ ae inspect ae-bundle
17
+ ae present ae-bundle --view structure --level operation --format all --output figures
18
+ ```
19
+
20
+ ## Output
21
+
22
+ SAE: source-backed IR, model index, source snapshots, hashes and unresolved records. Presenter: SVG, PDF, TikZ and health/provenance manifests.
23
+
24
+ Static factory specialization: ResNet block configuration; supported fixed-count nested containers (including DenseNet factory stages). Counts are conditional construction blueprints, not runtime tensor paths.
25
+
26
+ Nested shape propagation, FX source-site audit, and [instance-aware FX verification](docs/instance-fx-v0.15.md).
27
+
28
+ Bounded full forward expansion for the verified default ResNet18 and ResNet50 factories:
29
+
30
+ ```bash
31
+ ae extract path/to/torchvision/models --entrypoint resnet:resnet18 --input-shape 1,3,64,64 --output ae-bundle
32
+ ae present ae-bundle --view instance --level operation --format all --output figures
33
+ ```
34
+
35
+ The static instance graph is conditional on the input and source proof. [Scope and independent gate](docs/instance-forward-v0.16.md).
36
+
37
+ ## Tests
38
+
39
+ ```bash
40
+ python -m pytest -q
41
+ python scripts/verify_container_specialization.py
42
+ ```
43
+
44
+ See docs/limitations.md and docs/container-specialization-v0.12.md.
45
+
46
+ ResNet50 Bottleneck support: [independent stage gate](docs/instance-forward-v0.17.md).
47
+
48
+ DenseNet121 (TorchVision 0.25.0 default factory): bounded, source-verified instance forward graph with complete feature-list concatenation dependencies for the audited input shapes. See [v0.18 scope and independent verification](docs/instance-forward-v0.18.md). Other variants and modified source remain unsupported.
49
+
50
+ SMP 0.6.0 U-Net/ResNet34 bounded, source-proven instance graph and external FX/hooks validation: [v0.19](docs/instance-forward-v0.19.md). Non-Tensor shape metadata is labeled separately; its nodes do not have Tensor shapes.
51
+
52
+ timm ViT-Tiny (1.0.22): bounded 12-block source-only instance-forward expansion with explicit `--attention-mode fused|unfused` and independent FX/hooks validation. See [v0.20](docs/instance-forward-v0.20.md). Other ViTs and modified sources remain unsupported.
53
+
54
+ Presenter v0.21: source-backed hierarchical instance views for the exact pinned ViT-Tiny reference. `ae present ae-bundle --view instance --level overview|block|operation` and `--level operation --focus blocks.0`. Overview/block group operation and edge provenance without modifying the underlying instance graph; the detail view remains 1:1. [Scope and evidence policy](docs/instance-hierarchy-v0.21.md).
55
+
56
+ MobileNetV3 Small: audited TorchVision 0.25.0 default `mobilenet_v3_small(weights=None)` source-only full forward extraction for 64/128/224 square RGB inputs. Independent FX, ShapeProp, runtime hooks, ordered edges and manifest checks; 159 operations / 173 dependencies. Original-source-only `overview`, `block` and `operation` views, with `--focus features.4`. [Scope and limitations](docs/instance-forward-v0.22.md). Arbitrary variants are unsupported.
57
+
58
+ VGG16 source-only (v0.23) default torchvision 0.25.0: verified 42 operations / 41 ordered dependencies / 39 leaf calls. Two-level source-evidenced overview/block/operation visualizations and stage focus. See docs/instance-forward-v0.23.md.
59
+
60
+ EfficientNet-B0 source-only (v0.24): audited TorchVision 0.25.0 default model, 251 FX operations / 275 ordered dependencies, 214 leaf modules, 16 SE gates and 9 residual additions. Supports source-proven overview/block/operation/focus views for four audited input shapes. See [scope and independent verification](docs/instance-forward-v0.24.md).
61
+
62
+ Research generalization v0.25: source-only audits on exact pinned AWN and Chessformer CF-ACT/CF-CAH repositories (no claimed runtime equivalence), plus independent FX/torchview/torchviz/VisualTorch comparison. [Scope, scripts and evidence policy](docs/phase2-research-benchmark.md).
63
+
64
+ Offline interactive viewer v0.26 (Architecture / Block / Operation, zoom/pan, source-proven drill-down, no browser networking): `ae viewer BUNDLE --view instance --output viewer`, then open `viewer/index.html`. For general sources use `--view structure` or `--view nested`; unsupported full instance paths remain blocked. [Clean installation and release gate](docs/public-release-v026.md).
65
+
66
+ AE v0.27 adds generic source-category colors and default auto-selecting offline hierarchies with source-identity search/drill-down. **The default extractor still does not import or execute the target.** For deliberately trusted projects, `ae runtime-audit SOURCE --factory module:build --input-shape 1,3,64,64 --allow-execute --output audit` generates an independent PyTorch FX/hooks reference; this executes user code and does not establish AE-to-runtime equivalence. [v0.27 scope](docs/v027-generalization.md).
@@ -0,0 +1,29 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "architecture-extractor"
7
+ version = "0.27.0"
8
+ description = "Static Python/PyTorch architecture extraction and vector diagrams"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ authors = [{name = "AE contributors"}]
12
+ license = "MIT"
13
+ keywords = ["pytorch", "static-analysis", "architecture", "intermediate-representation"]
14
+ dependencies = ["PyYAML>=6.0,<7"]
15
+
16
+ [project.optional-dependencies]
17
+ dev = ["pytest>=8", "jsonschema>=4", "reportlab>=4"]
18
+ render = ["reportlab>=4"]
19
+ runtime = ["torch>=2.4,<3"]
20
+
21
+ [project.scripts]
22
+ ae = "ae.cli:main"
23
+
24
+ [tool.setuptools.packages.find]
25
+ where = ["src"]
26
+
27
+ [tool.pytest.ini_options]
28
+ testpaths = ["tests"]
29
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Architecture Extractor (AE)."""
2
+
3
+ __version__ = "0.27.0"
@@ -0,0 +1,90 @@
1
+ """Command-line entry point for the static extractor."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ import sys
7
+
8
+ from .sae.api import extract, inspect_bundle, validate_bundle
9
+ from .presenter import present
10
+ from .presenter.web_viewer import build_viewer
11
+ from .verification.runtime_reference import runtime_audit
12
+
13
+
14
+ def build_parser() -> argparse.ArgumentParser:
15
+ parser = argparse.ArgumentParser(prog="ae", description="AE: static source-grounded model architecture extraction")
16
+ commands = parser.add_subparsers(dest="command", required=True)
17
+ extraction = commands.add_parser("extract", help="Extract from source without importing or executing it")
18
+ extraction.add_argument("source", help="Source repository directory")
19
+ extraction.add_argument("--output", "-o", required=True, help="Output IR bundle directory")
20
+ extraction.add_argument("--entrypoint", help="Optional class/factory identifier (metadata hint, not executed)")
21
+ extraction.add_argument("--input-shape", help="Concrete input dimensions, e.g. 1,3,64,64")
22
+ extraction.add_argument("--attention-mode", choices=["fused", "unfused"],
23
+ help="Explicit ViT-Tiny attention implementation branch")
24
+ extraction.add_argument("--max-files", type=int, default=2000)
25
+ extraction.add_argument("--max-file-bytes", type=int, default=2_000_000)
26
+ for command in ("validate", "inspect"):
27
+ p = commands.add_parser(command)
28
+ p.add_argument("bundle", help="IR bundle directory or architecture.ir.json")
29
+ presenter = commands.add_parser("present", help="Draw a static architecture from a validated SAE bundle")
30
+ presenter.add_argument("bundle", help="Existing SAE extraction bundle directory")
31
+ presenter.add_argument("--output", "-o", required=True, help="Target diagram directory")
32
+ presenter.add_argument("--view", choices=["structure", "flow", "nested", "instance"], default="structure")
33
+ presenter.add_argument("--level", choices=["overview", "block", "operation"], default="block")
34
+ presenter.add_argument("--mode", choices=["exploration", "publication"], default="exploration")
35
+ presenter.add_argument("--format", choices=["svg", "pdf", "tikz", "all"], default="svg")
36
+ presenter.add_argument("--focus", help="Focus a module in flow/nested or a proven instance stage such as blocks.0")
37
+ presenter.add_argument("--theme", choices=["scientific-latex", "legacy"], default="scientific-latex")
38
+ presenter.add_argument("--allow-partial", action="store_true", help="Allow clearly labeled partial publication export")
39
+ viewer = commands.add_parser('viewer', help='Build a self-contained offline HTML viewer from a validated bundle')
40
+ viewer.add_argument('bundle', help='Existing SAE extraction bundle directory')
41
+ viewer.add_argument('--output', '-o', required=True, help='Output directory containing index.html')
42
+ viewer.add_argument('--view', choices=['auto','instance','nested','flow','structure'], default='auto')
43
+ viewer.add_argument('--title', default='Architecture Extractor')
44
+ runtime = commands.add_parser('runtime-audit', help='OPT-IN: execute trusted PyTorch model as independent FX/runtime reference')
45
+ runtime.add_argument('source', help='Trusted Python source directory. Executed: review first.')
46
+ runtime.add_argument('--factory', required=True, help='module:zero_arg_factory returning torch.nn.Module')
47
+ runtime.add_argument('--input-shape', required=True, action='append', help='Repeated positional synthetic input shape, e.g. 1,3,64,64')
48
+ runtime.add_argument('--input-dtype', action='append', help='Repeated input dtype: float32,int64,etc; defaults float32')
49
+ runtime.add_argument('--output', '-o', required=True, help='Reference JSON output directory')
50
+ runtime.add_argument('--allow-execute', action='store_true', help='Explicit approval to import/execute target model; NOT a sandbox')
51
+ runtime.add_argument('--max-nodes', type=int, default=20000)
52
+ return parser
53
+
54
+
55
+ def main(argv: list[str] | None = None) -> int:
56
+ args = build_parser().parse_args(argv)
57
+ try:
58
+ if args.command == "extract":
59
+ result = extract(args.source, args.output, entrypoint=args.entrypoint,
60
+ max_files=args.max_files, max_file_bytes=args.max_file_bytes,
61
+ input_shape=tuple(map(int, args.input_shape.split(","))) if args.input_shape else None,
62
+ attention_mode=args.attention_mode)
63
+ elif args.command == "validate":
64
+ result = validate_bundle(args.bundle)
65
+ elif args.command == 'runtime-audit':
66
+ shapes = [tuple(int(x) for x in item.split(',')) for item in args.input_shape]
67
+ result = runtime_audit(source_root=args.source, factory=args.factory,
68
+ input_shapes=shapes, input_dtypes=args.input_dtype,
69
+ output=args.output, allow_execute=args.allow_execute,
70
+ max_nodes=args.max_nodes)
71
+ elif args.command == 'viewer':
72
+ result = build_viewer(args.bundle, args.output, view=args.view, title=args.title)
73
+ elif args.command == "present":
74
+ result = present(args.bundle, args.output, level=args.level, mode=args.mode,
75
+ format=args.format, allow_partial=args.allow_partial, view=args.view, focus=args.focus, theme=args.theme)
76
+ else:
77
+ result = inspect_bundle(args.bundle)
78
+ print(json.dumps(result, sort_keys=True, indent=2, ensure_ascii=False))
79
+ if args.command == 'viewer':
80
+ return 0 if result['rendered_levels'] else 2
81
+ if args.command == 'runtime-audit':
82
+ return 0 if result['status'] == 'traced' else 2
83
+ return 0 if args.command != "present" or result["render_allowed"] else 2
84
+ except (ValueError, OSError, json.JSONDecodeError) as exc:
85
+ print(f"ae: {type(exc).__name__}: {exc}", file=sys.stderr)
86
+ return 1
87
+
88
+
89
+ if __name__ == "__main__":
90
+ raise SystemExit(main())
@@ -0,0 +1,3 @@
1
+ """Monochrome scientific architecture Presenter; consumes validated SAE data."""
2
+ from .api import present
3
+ __all__ = ['present']
@@ -0,0 +1,157 @@
1
+ """One-stage Presenter API: verified bundle -> provenance-backed scientific outputs."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from ae.sae.ir.canonical import canonical_bytes, sha256
9
+ from .reader import load_bundle
10
+ from .projection import project
11
+ from .flow import project_flow, project_nested_flow
12
+ from .instance_flow import project_instance_forward, make_instance_scene
13
+ from .flow_layout import make_flow_scene
14
+ from .health import evaluate
15
+ from .layout import make_scene
16
+ from .render import svg, pdf, tikz
17
+ from .themes import select_theme
18
+
19
+
20
+ FORMATS={'svg': ('svg',), 'pdf': ('pdf',), 'tikz': ('tex',),
21
+ 'all': ('svg','pdf','tex')}
22
+
23
+
24
+ def present(bundle_path: str | Path, output: str | Path, *, level: str = 'block',
25
+ mode: str = 'exploration', format: str = 'svg',
26
+ allow_partial: bool = False, view: str = 'structure',
27
+ focus: str | None = None, theme: str = 'scientific-latex') -> dict[str, Any]:
28
+ """Do not render on invalid bundles or without sufficient evidence.
29
+
30
+ Always write the health and manifest JSON; diagrams are absent if blocked
31
+ or withheld by publication policy.
32
+ """
33
+ style = select_theme(theme)
34
+ if view not in ('structure','flow','nested','instance'):
35
+ raise ValueError(f'Invalid view: {view}')
36
+ if focus and view not in ('flow', 'nested', 'instance'):
37
+ raise ValueError('--focus currently supports flow, nested and instance views only')
38
+ if level not in ('overview','block','operation'):
39
+ raise ValueError(f'Invalid level: {level}')
40
+ if mode not in ('exploration','publication'):
41
+ raise ValueError(f'Invalid mode: {mode}')
42
+ if format not in FORMATS:
43
+ raise ValueError(f'Invalid format: {format}')
44
+ if allow_partial and mode != 'publication':
45
+ raise ValueError('--allow-partial applies to publication mode only')
46
+ output_dir=Path(output)
47
+ output_dir.mkdir(parents=True,exist_ok=True)
48
+ # No stale figures should survive a failed or subsequently blocked invocation.
49
+ for ext in ('svg','pdf','tex'):
50
+ (output_dir/f'architecture.{ext}').unlink(missing_ok=True)
51
+ bundle=None; graph=None; problem=None
52
+ try:
53
+ bundle=load_bundle(bundle_path)
54
+ graph=(project_instance_forward(bundle,level,focus=focus) if view=='instance' else
55
+ project_flow(bundle,level,focus=focus) if view=='flow' else
56
+ project_nested_flow(bundle,level,focus=focus) if view=='nested' else
57
+ project(bundle,level))
58
+ except (OSError,ValueError,KeyError,TypeError,json.JSONDecodeError) as exc:
59
+ problem=f'{type(exc).__name__}: {exc}'
60
+ health=evaluate(bundle,graph,mode=mode,level=level,input_error=problem)
61
+ if view=='instance':
62
+ health['scope']='Bounded source-proven forward for explicit input shape; external execution check is separate'
63
+ if view in ('flow', 'nested'):
64
+ health['scope']='Source-backed static forward dependencies, supported call summaries and conditional type-level shapes; runtime behavior unverified'
65
+ health['view']=view
66
+ health['focus']=focus
67
+ allowed=health['status'] != 'blocked' and (mode=='exploration' or
68
+ health['status']=='complete' or allow_partial)
69
+ health['render_allowed']=allowed
70
+ health['publication_gate']='withheld_partial' if health['status']=='partial' and mode=='publication' and not allow_partial else 'ok'
71
+ if bundle is not None:
72
+ input_hashes=bundle.metadata.get('artifact_sha256',{})
73
+ else:
74
+ input_hashes={}
75
+ manifest={'schema_version':'1.0','style_version':style['name'],
76
+ 'mode':mode,'level':level,'view':view,'focus':focus,'entrypoint':bundle.ir.get('entrypoint') if bundle else None,
77
+ 'input_artifact_hashes':input_hashes,'status':health['status'],
78
+ 'rendered':allowed,'visual_elements':{},'visual_links':{},
79
+ 'omitted_indexed_ir_ids':[],'output_sha256':{}}
80
+ if graph is not None:
81
+ # Source-backed parent-child membership is used for drill-down;
82
+ # membership never asserts concrete runtime tensor dependencies.
83
+ elements = {n['id']: n for n in graph['nodes']}
84
+ memberships = {nid: set(n['ir_node_ids']) for nid, n in elements.items()}
85
+ for n in graph['nodes']:
86
+ parent = n.get('parent_id')
87
+ visited = {n['id']}
88
+ while parent in elements and parent not in visited:
89
+ memberships[parent].update(n['ir_node_ids'])
90
+ visited.add(parent)
91
+ parent = elements[parent].get('parent_id')
92
+ if view == 'structure' and level != 'operation' and bundle is not None:
93
+ # A grouped source node can carry exact declared-operation
94
+ # membership from the *full* source-only Operation projection.
95
+ # Stable visual IDs identify the same constructor path at
96
+ # every zoom level; this is NOT runtime topology or execution.
97
+ full = project(bundle, 'operation')
98
+ full_nodes = {n['id']: n for n in full['nodes']}
99
+ full_members = {nid: set(n['ir_node_ids']) for nid, n in full_nodes.items()}
100
+ for deep in full['nodes']:
101
+ parent = deep.get('parent_id')
102
+ visited = {deep['id']}
103
+ while parent in full_nodes and parent not in visited:
104
+ full_members[parent].update(deep['ir_node_ids'])
105
+ visited.add(parent)
106
+ parent = full_nodes[parent].get('parent_id')
107
+ for vid in memberships:
108
+ if vid in full_members:
109
+ memberships[vid].update(full_members[vid])
110
+ if view=='instance':
111
+ manifest['input_shape']=graph.get('input_shape')
112
+ manifest['instance_artifact']='instance-forward.json'
113
+ manifest['collapsed_instance_edge_ids']=graph.get('collapsed_instance_edge_ids', [])
114
+ manifest['omitted_instance_node_ids']=graph.get('omitted_instance_node_ids', [])
115
+ manifest['omitted_instance_edge_ids']=graph.get('omitted_instance_edge_ids', [])
116
+ manifest['visual_elements']={n['id']:{'kind':n['kind'],
117
+ 'label':n['label'], 'shape':n.get('shape'),
118
+ 'evidence':n.get('evidence','source-backed'),
119
+ 'member_ir_node_ids': sorted(memberships[n['id']]),
120
+ 'ir_node_ids':n['ir_node_ids'],'ir_edge_ids':n['ir_edge_ids'],
121
+ 'source_refs':n['source_refs'],
122
+ **({'semantic_category':n['semantic_category']}
123
+ if 'semantic_category' in n else {})}
124
+ for n in graph['nodes']}
125
+ manifest['visual_links']={e['id']:{'relation_kind':e['relation_kind'],
126
+ 'ir_edge_ids':e['ir_edge_ids'],'source_refs':e['source_refs'],
127
+ **({'instance_edge_id':e['instance_edge_id']} if 'instance_edge_id' in e else {})}
128
+ for e in graph['links']}
129
+ if bundle:
130
+ indexed=set()
131
+ for m in bundle.model_index.get('modules',[]):
132
+ if m['definition_id'] not in {x for n in graph['nodes'] for x in n['ir_node_ids']}:
133
+ continue
134
+ indexed.update(m.get('forward_relation_ids',[]))
135
+ indexed.update(c['call_site_id'] for c in m['forward_calls'])
136
+ indexed.update(op['operation_site_id'] for op in m['forward_operations'])
137
+ mapped={z for n in graph['nodes'] for z in n['ir_node_ids']}
138
+ mapped|={z for e in graph['links'] for z in e['ir_edge_ids']}
139
+ manifest['omitted_indexed_ir_ids']=[{'id':i,'reason':'hidden_by_selected_view_or_unsupported_projection'}
140
+ for i in sorted(indexed-mapped)]
141
+ if allowed:
142
+ scene=(make_instance_scene if view=='instance' else make_flow_scene if view in ('flow','nested') else make_scene)(
143
+ graph, status=health['status'],
144
+ entrypoint=(f"{health['entrypoint']} / {focus}"
145
+ if focus and focus != (health['entrypoint'] or '').split(':')[-1]
146
+ else health['entrypoint']))
147
+ scene['style'] = style
148
+ exporters={'svg':svg,'pdf':pdf,'tex':tikz}
149
+ for extension in FORMATS[format]:
150
+ content=exporters[extension](scene)
151
+ (output_dir/f'architecture.{extension}').write_bytes(content)
152
+ manifest['output_sha256'][f'architecture.{extension}']=sha256(content)
153
+ (output_dir/'presentation-health.json').write_bytes(canonical_bytes(health))
154
+ (output_dir/'presentation-manifest.json').write_bytes(canonical_bytes(manifest))
155
+ return {'status':health['status'],'render_allowed':allowed,'mode':mode,'level':level,'view':view,'focus':focus,'theme':theme,
156
+ 'formats':list(FORMATS[format]) if allowed else [],
157
+ 'issues':len(health['issues']),'output':str(output_dir)}
@@ -0,0 +1,50 @@
1
+ """Evidence-preserving two-level presentation for audited EfficientNet-B0."""
2
+ from __future__ import annotations
3
+ from .instance_hierarchy import _focus,_summary,_unsupported
4
+
5
+
6
+ def project_efficientnet_hierarchy(graph:dict, *, level:str,focus:str|None,
7
+ source_scope:str)->dict:
8
+ if source_scope!="pinned_torchvision_0_25_0_efficientnet_b0":
9
+ return _unsupported(level,"Requires pinned TorchVision 0.25.0 EfficientNet-B0")
10
+ stages=[];current="input"
11
+ for n in graph["nodes"]:
12
+ target=n["target"]
13
+ if n["op"]=="placeholder":
14
+ current="input"
15
+ elif target.startswith("features."):
16
+ pieces=target.split(".")
17
+ if len(pieces)>2 and pieces[1].isdigit():
18
+ index=int(pieces[1])
19
+ if not 0<=index<=8:
20
+ return _unsupported(level,"Unexpected EfficientNet feature target")
21
+ current=f"features.{index}"
22
+ elif target=="avgpool" or target=="flatten" or target.startswith("classifier."):
23
+ current="classifier"
24
+ elif n["op"]=="output":
25
+ current="output"
26
+ # Functional SE, StochasticDepth, and residual add remain within their
27
+ # previously source-proven feature stage.
28
+ stages.append(current)
29
+ expected={"input","classifier","output"}|{f"features.{i}" for i in range(9)}
30
+ if set(stages)!=expected:
31
+ return _unsupported(level,"Incomplete source-evidenced EfficientNet stages")
32
+ if focus:
33
+ if level!="operation":
34
+ return _unsupported(level,"Only operation focus is supported")
35
+ return _focus(graph,stages,focus)
36
+ if level=="operation":return graph
37
+ if level not in ("overview","block"):
38
+ return _unsupported(level,"Unknown EfficientNet display level")
39
+ transformed=["backbone" if level=="overview" and s in {
40
+ f"features.{i}" for i in range(1,8)} else s for s in stages]
41
+ labels={"input":"RGB Input","features.0":"Stem Conv-BN-SiLU",
42
+ "backbone":"EfficientNet-B0 MBConv Backbone",
43
+ "features.8":"Final Conv-BN-SiLU",
44
+ "classifier":"Global Pool / Classifier","output":"Output",
45
+ **{f"features.{i}":f"MBConv Stage {i}" for i in range(1,8)}}
46
+ result=_summary(graph,transformed,level,model_key="torchvision-efficientnet-b0",
47
+ labels_override=labels,fallback_prefix="EfficientNet ")
48
+ if len(result["nodes"])!=(6 if level=="overview" else 12):
49
+ return _unsupported(level,"Unexpected EfficientNet grouping")
50
+ return result