# probabl-ai/skore architecture

> Architecture diagram of the GitHub repository probabl-ai/skore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/probabl-ai/skore
- Repository: https://github.com/probabl-ai/skore

## Overview

##### Main Components
- Library Core: The heart of the project is within the “skore/src/skore” directory. This core has multiple submodules:
– Configuration and Exception Handling (e.g., _config, exceptions)
– Externals: Adapters for integrating with Pandas, scikit-learn, etc.
– Persistence: Including “persistence/item”, “persistence/repository”, and “persistence/storage” modules. These manage saving various data objects (charts, models, arrays, etc.) and offer different storage mechanisms (disk caching, in-memory storage).
– Sklearn Integrations: Modules under “skore/sklearn” (such as _base, _comparison, _cross_validation, _estimator, _plot, and train_test_split) that extend scikit-learn’s functionalities by offering diagnostic warnings, enhanced metrics, and plotting utilities.
– Project Management: The “skore/project” module that provides a simple API to store and retrieve artifacts (e.g., project.put and project.get).
– Utilities: Common helper functions spread throughout “skore/utils”.

- Testing & Examples: There is an extensive test suite (“skore/tests/unit” and “skore/tests/functional”) which emphasizes test-driven development, and the examples directory demonstrates how to use the library for various ML and reporting scenarios.

- CI/CD & DevOps: Presence of GitHub Actions workflows, pre-commit configurations, and CI scripts (in “skore/ci”) indicate a robust automated pipeline for linting, testing, and documentation (using Sphinx).

- Documentation: The “docs” and “sphinx” directories handle documentation building and deployment. Sphinx-specific configurations and templates exist to render user documentation and API references.

##### Out the Relationships and Interactions
- The core library functions as the central processing engine. It interacts with external libraries like scikit-learn (for model inputs, training, and validations) and Pandas/NumPy for data handling.
- The Persistence Layer interacts with the core evaluation components by storing and retrieving various report objects and data artifacts.
- The sklearn extension modules produce reports and warnings that are orchestrated by the EstimatorReport and CrossValidationReport features.
- The Project Management component sits on top of the persistence capability to allow users to easily save and later access their results.
- CI/CD pipelines and tests ensure the robustness and maintainability of all these components.
- The documentation layer (built with Sphinx) ties together usage examples, API reference details, and guides for new users.

##### Architectural Patterns and Design Principles
- The modular separation of concerns is clear: each major functionality (evaluation, persistence, sklearn integration, project management, utilities) is isolated into submodules.
- The design leverages the dependency inversion principle – the high-level components (like project and estimator reporting) rely on lower-level services (like persistence or external library integrations) that can potentially be swapped or extended.
- Extensive use of unit and functional tests attests to a design that emphasizes maintainability and reliability.
- CI/CD and documentation automation are integral parts of the development process.

##### Relevant Technologies and Tools
- Programming Language: Python (supporting versions 3.9 through 3.12).
- Core External Libraries: Scikit-learn, Pandas, NumPy, matplotlib, plotly, altair, etc.
- Documentation: Sphinx.
- Testing: Pytest (implied by the tests structure), along with CI pipelines via GitHub Actions.
- DevOps: GitHub Actions and Dependabot for dependency management.

##### Detail and Clarity
- Component (even those with submodules) are clearly represented to capture the intricacies of the design.
- Don’t shy away from splitting the architecture into multiple layers if needed – the goal is to capture as many essential architectural elements as possible for the principal software engineer’s review.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DS("Data Scientist"):::external

    subgraph "Core Library"
        LC("Core Engine"):::core
        CONF("Configuration"):::core
        EXCEP("Exception Handling"):::core
        EXT("Externals"):::core
        subgraph "Persistence"
            PI("Persistence Items"):::persistence
            PR("Persistence Repository"):::persistence
            PS("Persistence Storage"):::persistence
        end
        subgraph "Sklearn Integrations"
            SK("Sklearn Integrations"):::integration
            TTS("Train/Test Split/Diagnostics"):::integration
        end
        PM("Project Management"):::core
        UTIL("Utilities"):::core
    end

    subgraph "Supporting Infrastructure"
        TS("Testing Suite"):::infra
        EXMP("Examples"):::infra
        subgraph "CI/CD"
            GHA("GitHub Actions"):::infra
            CI("CI Scripts"):::infra
        end
        subgraph "Documentation"
            DOC("Documentation"):::infra
            SPHX("Sphinx Configurations"):::infra
        end
    end

    subgraph "External Dependencies"
        SKLT("scikit-learn"):::external
        PND("Pandas/NumPy"):::external
    end

    %% Relationships between Data Scientist and Core Library
    DS -->|"calls"| LC

    %% Core Library internal structure
    LC -->|"includes"| CONF
    LC -->|"includes"| EXCEP
    LC -->|"integrates"| EXT
    LC -->|"manages"| PM
    LC -->|"utilizes"| UTIL
    LC -->|"extends"| SK

    %% Sklearn Integrations details
    SK -->|"executes"| TTS
    SK -->|"stores"| PI
    SK -->|"stores"| PR
    SK -->|"reports via"| PM

    %% Externals integration with external dependencies
    EXT -->|"adapts"| SKLT
    EXT -->|"adapts"| PND

    %% Supporting Infrastructure feedback
    TS -->|"tests"| LC
    GHA -->|"builds"| LC
    CI -->|"builds"| LC
    DOC -->|"documents"| LC
    SPHX -->|"formats"| LC
    EXMP -->|"demonstrates"| LC

    %% Click Events for Core Library components
    click LC "https://github.com/probabl-ai/skore/tree/main/skore/src/skore"
    click CONF "https://github.com/probabl-ai/skore/blob/main/skore/src/skore/_config.py"
    click EXCEP "https://github.com/probabl-ai/skore/blob/main/skore/src/skore/exceptions.py"
    click EXT "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/externals"
    click PI "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/persistence/item"
    click PR "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/persistence/repository"
    click PS "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/persistence/storage"
    click SK "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/sklearn"
    click TTS "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/sklearn/train_test_split"
    click PM "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/project"
    click UTIL "https://github.com/probabl-ai/skore/tree/main/skore/src/skore/utils"

    %% Click Events for Supporting Infrastructure components
    click TS "https://github.com/probabl-ai/skore/tree/main/skore/tests"
    click EXMP "https://github.com/probabl-ai/skore/tree/main/examples"
    click GHA "https://github.com/probabl-ai/skore/blob/main/.github"
    click CI "https://github.com/probabl-ai/skore/tree/main/skore/ci"
    click DOC "https://github.com/probabl-ai/skore/tree/main/docs"
    click SPHX "https://github.com/probabl-ai/skore/tree/main/sphinx"

    %% Class definitions for styling
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef persistence fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef infra fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
