ross-sec/fractal_attention_analysis

1. Repository shape

This is a Python package laid out in the src/ pattern. The installable library lives in src/fractal_attention_analysis, with tests, examples, docs, and GitHub Actions workflows around it.

2. Primary purpose

The package analyzes transformer attention patterns through a fractal-geometry lens. The central input is text plus a HuggingFace model name; the central output is an analysis result built from attention matrices, fractal measurements, and derived interpretability metrics.

3. Core orchestration layer

core.py is the main coordination layer and is the most likely home of FractalAttentionAnalyzer. It appears to own the end-to-end flow: load model, run inference, extract attention, select layer/head, call the mathematical routines, and assemble results.

4. Model and attention boundary

The architecture depends on external transformer models rather than training its own model. HuggingFace Transformers and GPU/CUDA support matter here because the analyzer must load arbitrary model IDs, manage device placement, and handle attention extraction efficiently.

5. Fractal mathematics subsystem

fractal.py is the numerical core for the project’s distinctive methods: fractal dimension estimation, golden-ratio-based transforms, and interpolation-style transformations. This layer operates directly on attention matrices and is the main “analysis math” boundary.

6. Metrics subsystem

metrics.py computes standard and custom attention summaries such as entropy, sparsity, concentration, and composite interpretability scores. It likely consumes the raw or transformed attention matrix and may also incorporate the computed fractal dimension as an input to aggregate scoring.

7. Visualization subsystem

visualization.py is the reporting/inspection layer, using matplotlib-style plots to render attention matrices and comparisons between original and transformed attention. This is a downstream consumer of analysis outputs rather than part of the computation itself.

8. Utility and shared helpers

utils.py likely contains shared plumbing used across the package: tensor handling, array conversion, device helpers, validation, file export helpers, or token formatting. This module is a support boundary that keeps the core/math/visualization code from duplicating low-level logic.

9. Public API surface

__init__.py defines what the package exposes to users, and the README shows the intended public objects: FractalAttentionAnalyzer, FractalTransforms, AttentionMetrics, and AttentionVisualizer. That suggests the repository is organized as a small façade over separate computation, metrics, and visualization components.

10. CLI boundary

cli.py provides the command-line entry points such as faa-analyze and faa-compare. It wraps the same core analyzer used by Python callers, so the CLI is a thin presentation layer over the library rather than a separate execution engine.

11. Examples and usage paths

examples/basic_usage.py and examples/advanced_analysis.py show the expected usage modes: single-text analysis, batch analysis, model comparison, and export/visualization flows. These files are useful for diagramming the “happy path” from input text to results.

12. Testing strategy

The test suite is focused on computational correctness, with dedicated tests for fractal logic and metrics (test_fractal.py, test_metrics.py). That indicates the most important correctness boundaries are the math routines, not the CLI or packaging.

13. Packaging and release pipeline

pyproject.toml, requirements.txt, and MANIFEST.in define the Python package build/install shape. The GitHub Actions workflows (ci.yml, publish.yml, python-publish.yml) suggest automated testing and publishing to package indexes as part of the repo’s delivery flow.

14. Documentation and setup

README.md and docs/SETUP_INSTRUCTIONS.md define onboarding and operational usage, while CHANGELOG.md and CONTRIBUTING.md support release management and contributor workflow. These are non-runtime but important for understanding how the project is maintained and consumed.