How youcef3939/aletheia works
1. Repository role
- This is a Python explainable-AI framework centered on image model inference + attribution + visualization + metrics.
- The architecture is intentionally modular: the dashboard is separate from the inference/explanation pipeline, which is separate from the model, explainer, and metrics layers.
2. Top-level control flow
- The main user flow is: input image/sample → model prediction → explanation generation → metric computation → visualization/reporting.
- That flow is implemented twice: once for interactive use in the Streamlit dashboard, and once as a reusable programmatic entrypoint through pipeline.py.
3. Dashboard boundary
- dashboard/app.py is the presentation layer.
- It likely handles user interaction, sample selection/upload, display of predictions, and rendering of heatmaps/metrics.
- Importantly, it should depend on the central pipeline rather than directly coupling to model or explainer internals.
4. Orchestration layer
- pipeline.py is the central orchestrator and the best place to draw the “system spine” in an architecture diagram.
- It coordinates loading a model, running inference, selecting an explainer, computing metrics, and preparing visual outputs for either the dashboard or external callers.
5. Model subsystem
- models/model_loader.py encapsulates model loading and inference.
- This is the boundary between the framework and the underlying deep learning model, likely a PyTorch model based on the README and Captum integration.
- This layer should be treated as swappable: the framework is designed so different model weights/architectures can be plugged in without changing the rest of the stack.
6. Explanation subsystem
- explainers/captum_explainers.py contains the attribution methods built on Captum.
- This is where raw model inputs/gradients are turned into saliency or attribution maps.
- In the diagram, this sits downstream of inference and upstream of visualization/metrics.
7. Metrics subsystem
- metrics/xai_metrics.py computes explanation-quality metrics such as faithfulness/sensitivity-style evaluations mentioned in the README.
- This layer consumes the model outputs and explanation artifacts, so it forms a separate analytical boundary from the explainer itself.
- It is useful to show metrics as parallel to visualization, not embedded inside the UI.
8. Visualization subsystem
- utils/viz.py is responsible for converting numeric outputs and attribution tensors into human-readable images, overlays, or plots.
- It is the final presentation transform before results are shown in the dashboard or exported.
- For architecture purposes, this is the bridge between analytic outputs and end-user interpretation.
9. Cross-cutting concerns
- utils/logger.py provides logging for traceability and auditability.
- config.py holds global settings such as paths, model/explainer selection, and runtime parameters.
- These are cross-cutting support modules used by multiple layers rather than standalone subsystems.
10. Extensibility model
- The repository is designed around replaceable components:
- swap the model in models/
- add attribution methods in explainers/
- add evaluation methods in metrics/
- adjust display logic in utils/viz.py
- That means the key architectural boundary is the pipeline interface, not the dashboard itself.
11. Runtime and packaging
- This is a Python project with a Streamlit frontend and ML/XAI dependencies listed in requirements.txt.
- The runtime is therefore a local or server-side Python process that serves the dashboard and performs inference/explanation in-process, rather than calling out to external services.
12. What to emphasize in a diagram
- Show one central pipeline feeding both:
- the dashboard UI, and
- the programmatic API path.
- Around that core, show four main internal subsystems: model loading/inference, Captum explainers, XAI metrics, and visualization, with config and logger as shared support components.
Main entry points: pipeline.py Pipeline · xai_metrics.py Metrics · captum_explainers.py Explainers · config.py Config
Components 8
Presentation
Interactive user-facing dashboard
- Dashboard · Interactive interface for loading samples, showing predictions, and rendering explanation outputs
dashboard/app.py
Orchestration
Central runtime flow and API entrypoint
- Pipeline · Coordinates the end-to-end image inference, attribution, metrics, and output preparation flow
pipeline.py
XAI Core
Model, explanation, metrics, and visualization subsystems
- Model Loader · Loads the underlying model and runs prediction/inference
models/model_loader.py - Explainers · Captum-based explainers that turn model behavior into saliency or attribution maps
explainers/captum_explainers.py - Metrics · Computes explanation-quality metrics such as faithfulness and sensitivity-style scores
metrics/xai_metrics.py - Visualization · Converts numeric outputs and attribution tensors into plots, overlays, and human-readable artifacts
utils/viz.py
Connections 17
- Dashboard → Pipeline: uses · Dashboard delegates execution to the central pipeline rather than calling internals directly
- Pipeline → Model Loader: loads/infers · Pipeline loads the model and performs prediction
- Pipeline → Explainers: explains · Pipeline selects and runs attribution methods
- Pipeline → Metrics: evaluates · Pipeline computes explanation metrics from model outputs and attribution artifacts
- Pipeline → Visualization: renders · Pipeline prepares visual outputs for display or export
- Pipeline → Config: reads · Pipeline uses shared configuration for runtime behavior
- Pipeline → Logger: logs · Pipeline emits execution logs for traceability
- Explainers → Model Loader: depends on · Attribution methods operate on the loaded model and its gradients/outputs
- Metrics → Model Loader: consumes · Metrics use model predictions and related signals
- Metrics → Explainers: consumes · Metrics evaluate the generated explanation artifacts
- Visualization → Explainers: formats · Visualization turns attribution tensors into displayable artifacts
- Visualization → Metrics: formats · Visualization can present metric outputs in reports or UI
- Dashboard → Visualization: displays · Dashboard renders plots, overlays, and results produced by the visualization layer
- Config → Model Loader: configures · Settings influence model selection and load behavior
- Config → Explainers: configures · Settings influence explainer selection and runtime parameters
- Config → Metrics: configures · Settings influence metric selection and thresholds
- Logger → Dashboard: shared · Dashboard participates in the shared logging boundary