# polaris-hub/polaris architecture

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

- Interactive diagram: https://gitdiagram.com/polaris-hub/polaris
- Repository: https://github.com/polaris-hub/polaris

## Overview

##### Project type and purpose
- This is a Python client library (“polaris-lib”) for AI-based drug-discovery benchmarking.
- It provides both a CLI (`polaris/cli.py`) and a Python API to:
- Download datasets & benchmarks from Polaris Hub
- Load data into standard objects
- Evaluate custom methods against benchmarks
- Submit results back to the Hub

##### High-level architecture from the file structure
- Top-level modules:
- **cli**: parses commands & invokes core API
- **loader**: abstracts how data is pulled locally vs. from Hub
- **dataset**: adapter/factory pattern to build dataset objects, converters (PDB, SDF, Zarr)
- **benchmark** & **competition**: define tasks, splits, metadata
- **evaluate**: metrics, results aggregation, submission helpers
- **hub**: HTTP/OAuth client, external client interface, storage interface
- **mixins/utils**: shared helpers (checksum, formatting, constants)
- Tests validate each module; docs/hosted assets reflect API surface

##### Key insights from README
- Core workflows:
a. `po.load_benchmark(...)` → backend calls to **hub.client** → fetch metadata & raw data
b. `benchmark.get_train_test_split()` → uses **benchmark** internals to create dataset splits
c. Iteration over dataset → uses **loader**, **dataset** objects, converters to produce Python primitives (arrays, pandas, etc.)
d. `benchmark.evaluate(predictions)` → invokes **evaluate** module, metric classes (strategy pattern)
e. `results.upload_to_hub(...)` → back through **hub.external_client** with OAuth

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Entrypoint"]:::ui
        API["Python API Surface"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        subgraph "Dataset Factory & Base"
            Factory["Dataset Factory"]:::service
            Base["Dataset Base"]:::service
        end
        Adapters["Dataset Adapters"]:::service
        subgraph "Dataset Core Classes"
            Core1["_dataset.py"]:::service
            Core2["_dataset_v2.py"]:::service
            Subset["_subset.py"]:::service
        end
        subgraph "Dataset Converters"
            PDB["_pdb Converter"]:::service
            SDF["_sdf Converter"]:::service
            ZarrConv["_zarr Converter"]:::service
        end
        subgraph "Zarr Storage & Checksum"
            ZCk["_checksum.py"]:::service
            ZMem["_memmap.py"]:::service
            ZMan["_manifest.py"]:::service
            ZUtil["_utils.py"]:::service
            ZCodec["codecs.py"]:::service
        end
        subgraph "Benchmark Logic"
            BBase["Base Benchmark"]:::service
            BV2["Benchmark V2"]:::service
            DefTask["Definitions & Task"]:::service
            Splits["Split Logic"]:::service
        end
        Comp["Competition Logic"]:::service
        subgraph "Evaluation Engine"
            EMetric["_metric & Results"]:::service
            Predictions["_predictions.py"]:::service
            Meta["_metadata.py"]:::service
            EUtils["evaluate/utils.py"]:::service
            subgraph "Strategy Pattern Metrics"
                M1["docking_metrics.py"]:::service
                M2["generic_metrics.py"]:::service
            end
        end
    end

    %% Integration Layer
    subgraph "Integration Layer"
        HubClient["Hub HTTP Client"]:::integration
        OAuth["OAuth Module"]:::integration
        ExternalC["External Client"]:::integration
        StorageI["Storage Interface"]:::integration
        Settings["Hub Settings"]:::integration
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Loader["Data Loader"]:::infra
        ExternalHub["Polaris Hub"]:::external
    end

    %% Utility Layer
    subgraph "Utility Layer"
        Mixins["Mixins"]:::util
        Utils["General Utilities"]:::util
    end

    %% Data Flows
    CLI -->|"invoke load_benchmark"| HubClient
    API -->|"invoke load_benchmark"| HubClient
    HubClient -->|"fetch metadata"| ExternalHub
    ExternalHub -->|"return metadata & raw data"| HubClient
    HubClient -->|"provide data"| Factory
    Factory --> Adapters
    Adapters --> Core1
    Adapters --> Core2
    Adapters --> Subset
    Core1 --> PDB
    Core1 --> SDF
    Core1 --> ZarrConv
    ZarrConv --> ZCk
    ZarrConv --> ZMem
    ZarrConv --> ZMan
    ZarrConv --> ZUtil
    ZarrConv --> ZCodec
    BV2 --> DefTask
    DefTask --> Splits
    Factory --> BV2
    Comp --> BV2
    Splits --> Predictions
    Predictions --> EMetric
    EMetric --> M1
    EMetric --> M2
    EMetric --> Meta
    EMetric --> EUtils
    EMetric --> ExternalC
    ExternalC -->|"upload results"| ExternalHub

    %% Click Events
    click CLI "https://github.com/polaris-hub/polaris/blob/main/polaris/cli.py"
    click API "https://github.com/polaris-hub/polaris/blob/main/polaris/__init__.py"
    click Factory "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_factory.py"
    click Base "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_base.py"
    click Adapters "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_adapters.py"
    click Core1 "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_dataset.py"
    click Core2 "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_dataset_v2.py"
    click Subset "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/_subset.py"
    click PDB "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/converters/_pdb.py"
    click SDF "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/converters/_sdf.py"
    click ZarrConv "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/converters/_zarr.py"
    click ZCk "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/zarr/_checksum.py"
    click ZMem "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/zarr/_memmap.py"
    click ZMan "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/zarr/_manifest.py"
    click ZUtil "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/zarr/_utils.py"
    click ZCodec "https://github.com/polaris-hub/polaris/blob/main/polaris/dataset/zarr/codecs.py"
    click BBase "https://github.com/polaris-hub/polaris/blob/main/polaris/benchmark/_base.py"
    click BV2 "https://github.com/polaris-hub/polaris/blob/main/polaris/benchmark/_benchmark_v2.py"
    click DefTask "https://github.com/polaris-hub/polaris/blob/main/polaris/benchmark/_definitions.py"
    click Splits "https://github.com/polaris-hub/polaris/blob/main/polaris/benchmark/_split.py"
    click Comp "https://github.com/polaris-hub/polaris/blob/main/polaris/competition/__init__.py"
    click EMetric "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/_metric.py"
    click Predictions "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/_predictions.py"
    click Meta "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/_metadata.py"
    click M1 "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/metrics/docking_metrics.py"
    click M2 "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/metrics/generic_metrics.py"
    click EUtils "https://github.com/polaris-hub/polaris/blob/main/polaris/evaluate/utils.py"
    click HubClient "https://github.com/polaris-hub/polaris/blob/main/polaris/hub/client.py"
    click OAuth "https://github.com/polaris-hub/polaris/blob/main/polaris/hub/oauth.py"
    click ExternalC "https://github.com/polaris-hub/polaris/blob/main/polaris/hub/external_client.py"
    click StorageI "https://github.com/polaris-hub/polaris/blob/main/polaris/hub/storage.py"
    click Settings "https://github.com/polaris-hub/polaris/blob/main/polaris/hub/settings.py"
    click Loader "https://github.com/polaris-hub/polaris/blob/main/polaris/loader/load.py"
    click Mixins "https://github.com/polaris-hub/polaris/blob/main/polaris/mixins/_checksum.py"
    click Utils "https://github.com/polaris-hub/polaris/blob/main/polaris/utils/constants.py"

    %% Styles
    classDef ui fill:#fdeff9,stroke:#bb3366,stroke-width:2px
    classDef service fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef integration fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef infra fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef util fill:#e0f7fa,stroke:#006064,stroke-width:2px
    classDef external fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 5 5
```
