# ross-sec/fractal_attention_analysis architecture

> Architecture diagram of the GitHub repository ross-sec/fractal_attention_analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ross-sec/fractal_attention_analysis
- Repository: https://github.com/ross-sec/fractal_attention_analysis

## Overview

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.

Main entry points: [`src/fractal_attention_analysis/core.py`](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/core.py) (Core), [`src/fractal_attention_analysis/__init__.py`](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/__init__.py) (fractal_attention_analysis), [`src/fractal_attention_analysis/metrics.py`](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/metrics.py) (Metrics), [`pyproject.toml`](https://github.com/ross-sec/fractal_attention_analysis/blob/main/pyproject.toml) (Build config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_pkg["fractal_attention_analysis<br/>package facade<br/>[__init__.py]"]
  node_core["Core<br/>orchestrator<br/>[core.py]"]
  node_fractal["Fractal math<br/>numerics<br/>[fractal.py]"]
  node_metrics["Metrics<br/>scoring<br/>[metrics.py]"]
  node_viz["Visualization<br/>plotting<br/>[visualization.py]"]
  node_utils["Utils<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>command entrypoints<br/>[cli.py]"]
  node_basic["Basic usage<br/>example<br/>[basic_usage.py]"]
  node_advanced["Advanced analysis<br/>example"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_setupdocs["Setup guide<br/>docs"]
end

subgraph group_ops["Project Ops"]
  node_tests_fractal["Fractal tests<br/>test suite<br/>[test_fractal.py]"]
  node_tests_metrics["Metrics tests<br/>test suite<br/>[test_metrics.py]"]
  node_pyproject["Build config<br/>packaging<br/>[pyproject.toml]"]
  node_workflows["CI/CD<br/>automation<br/>[ci.yml]"]
  node_publish["Publish flow<br/>automation<br/>[publish.yml]"]
  node_pythonpublish["Py publish<br/>automation<br/>[python-publish.yml]"]
end

node_pkg -->|"exposes"| node_core
node_pkg -->|"exposes"| node_fractal
node_pkg -->|"exposes"| node_metrics
node_pkg -->|"exposes"| node_viz
node_core -->|"calls"| node_fractal
node_core -->|"computes"| node_metrics
node_core -->|"uses"| node_utils
node_metrics -->|"uses"| node_utils
node_viz -->|"uses"| node_utils
node_cli -->|"wraps"| node_core
node_basic -->|"demonstrates"| node_core
node_advanced -->|"demonstrates"| node_core
node_advanced -->|"demonstrates"| node_viz
node_readme -->|"documents"| node_pkg
node_readme -->|"documents"| node_cli
node_setupdocs -->|"supports"| node_pyproject
node_tests_fractal -->|"verifies"| node_fractal
node_tests_metrics -->|"verifies"| node_metrics
node_workflows -->|"builds"| node_pyproject
node_publish -->|"releases"| node_pyproject
node_pythonpublish -->|"releases"| node_pyproject

click node_pkg "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/__init__.py"
click node_core "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/core.py"
click node_fractal "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/fractal.py"
click node_metrics "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/metrics.py"
click node_viz "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/visualization.py"
click node_utils "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/utils.py"
click node_cli "https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/cli.py"
click node_basic "https://github.com/ross-sec/fractal_attention_analysis/blob/main/examples/basic_usage.py"
click node_advanced "https://github.com/ross-sec/fractal_attention_analysis/blob/main/examples/advanced_analysis.py"
click node_readme "https://github.com/ross-sec/fractal_attention_analysis/blob/main/README.md"
click node_setupdocs "https://github.com/ross-sec/fractal_attention_analysis/blob/main/docs/SETUP_INSTRUCTIONS.md"
click node_tests_fractal "https://github.com/ross-sec/fractal_attention_analysis/blob/main/tests/test_fractal.py"
click node_tests_metrics "https://github.com/ross-sec/fractal_attention_analysis/blob/main/tests/test_metrics.py"
click node_pyproject "https://github.com/ross-sec/fractal_attention_analysis/blob/main/pyproject.toml"
click node_workflows "https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/ci.yml"
click node_publish "https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/publish.yml"
click node_pythonpublish "https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/python-publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pkg,node_core,node_fractal,node_metrics,node_viz,node_utils toneBlue
class node_cli,node_basic,node_advanced,node_readme,node_setupdocs toneAmber
class node_tests_fractal,node_tests_metrics,node_pyproject,node_workflows,node_publish,node_pythonpublish toneMint
```

## Components

### Library

Installable analysis package under src/

- [fractal_attention_analysis](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/__init__.py): package facade · Public package surface exported to users · `src/fractal_attention_analysis/__init__.py`
- [Core](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/core.py): orchestrator · Coordinates model loading, attention extraction, and analysis assembly · `src/fractal_attention_analysis/core.py`
- [Fractal math](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/fractal.py): numerics · Fractal dimension and attention transforms · `src/fractal_attention_analysis/fractal.py`
- [Metrics](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/metrics.py): scoring · Attention summaries and interpretability scores · `src/fractal_attention_analysis/metrics.py`
- [Visualization](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/visualization.py): plotting · Renders attention matrices and comparisons · `src/fractal_attention_analysis/visualization.py`
- [Utils](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/utils.py): shared helpers · Common tensor, device, and export helpers · `src/fractal_attention_analysis/utils.py`

### Interfaces

Public entrypoints, examples, and documentation

- [CLI](https://github.com/ross-sec/fractal_attention_analysis/blob/main/src/fractal_attention_analysis/cli.py): command entrypoints · Command-line analysis and comparison wrapper · `src/fractal_attention_analysis/cli.py`
- [Basic usage](https://github.com/ross-sec/fractal_attention_analysis/blob/main/examples/basic_usage.py): example · Simple single-input analysis walkthrough · `examples/basic_usage.py`
- [Advanced analysis](https://github.com/ross-sec/fractal_attention_analysis/blob/main/examples/advanced_analysis.py): example · Batch analysis, comparison, and export flows · `examples/advanced_analysis.py`
- [README](https://github.com/ross-sec/fractal_attention_analysis/blob/main/README.md): docs · Primary user-facing overview and usage guide · `README.md`
- [Setup guide](https://github.com/ross-sec/fractal_attention_analysis/blob/main/docs/SETUP_INSTRUCTIONS.md): docs · Environment and installation instructions · `docs/SETUP_INSTRUCTIONS.md`

### Project Ops

Packaging, testing, and release automation

- [Fractal tests](https://github.com/ross-sec/fractal_attention_analysis/blob/main/tests/test_fractal.py): test suite · Coverage for fractal transformation logic · `tests/test_fractal.py`
- [Metrics tests](https://github.com/ross-sec/fractal_attention_analysis/blob/main/tests/test_metrics.py): test suite · Coverage for attention metrics and scoring · `tests/test_metrics.py`
- [Build config](https://github.com/ross-sec/fractal_attention_analysis/blob/main/pyproject.toml): packaging · Project metadata and build configuration · `pyproject.toml`
- [CI/CD](https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/ci.yml): automation · Test and publish workflows · `.github/workflows/ci.yml`
- [Publish flow](https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/publish.yml): automation · Release publishing workflow · `.github/workflows/publish.yml`
- [Py publish](https://github.com/ross-sec/fractal_attention_analysis/blob/main/.github/workflows/python-publish.yml): automation · Python package publish workflow · `.github/workflows/python-publish.yml`

## Connections

- fractal_attention_analysis → Core: exposes · Package facade presents the main analyzer
- fractal_attention_analysis → Fractal math: exposes · Exports transform and fractal primitives
- fractal_attention_analysis → Metrics: exposes · Exports metrics API
- fractal_attention_analysis → Visualization: exposes · Exports visualization API
- Core → Fractal math: calls · Core delegates mathematical transforms and dimension estimation
- Core → Metrics: computes · Core assembles score outputs from metrics
- Core → Utils: uses · Core relies on shared helpers for data and device handling
- Metrics → Utils: uses · Metrics reuses helper functions for tensor handling
- Visualization → Utils: uses · Visualization may share formatting/export helpers
- CLI → Core: wraps · CLI invokes the same analyzer used by Python callers
- Basic usage → Core: demonstrates · Shows the standard analysis flow
- Advanced analysis → Core: demonstrates · Shows extended analysis and comparison flows
- Advanced analysis → Visualization: demonstrates · Shows plotting and inspection outputs
- README → fractal_attention_analysis: documents · README describes the public API
- README → CLI: documents · README documents command-line usage
- Setup guide → Build config: supports · Setup instructions align with project configuration
- Fractal tests → Fractal math: verifies · Tests the numerical fractal subsystem
- Metrics tests → Metrics: verifies · Tests the metrics subsystem
- CI/CD → Build config: builds · CI runs the configured package build and test flow
- Publish flow → Build config: releases · Publish workflow uses project packaging metadata
- Py publish → Build config: releases · Python publish workflow uses project packaging metadata