# biomedsciai/biomed-multi-alignment architecture

> Architecture diagram of the GitHub repository biomedsciai/biomed-multi-alignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biomedsciai/biomed-multi-alignment
- Repository: https://github.com/biomedsciai/biomed-multi-alignment

## Overview

##### Project type and purpose
- This is an open-source Python library and CLI tool (“biomed-multi-alignment” / MAMMAL) providing a biomedical multi-modal foundation model.
- It supports fine-tuning and inference on tasks spanning proteins, small molecules (SMILES), single-cell gene expression, etc.
- It bundles core code (model definition, tasks, losses, schedulers, metrics), example pipelines (data modules, config files, example scripts), and CI/workflows for packaging and publication.

##### File structure
- Top-level directories/files
– .github/workflows: CI for testing, publishing, cloning badge
– CLONE.md, CONTRIBUTING.md, LICENSE.txt, README.md, pyproject.toml, .pre-commit-config.yaml → project metadata, packaging, code style
– tutorials/: Jupyter notebooks for “beginner” and “advanced” guides
- Core module “mammal/”
– mammal/model.py, task.py, losses.py, lr_schedulers.py, metrics.py, lora.py, keys.py → core abstractions
– mammal/main_finetune.py → CLI entry for training & evaluation pipelines
– mammal/examples/… → task-specific example subpackages, each with config.yaml, pl_data_module.py (PyTorch Lightning DataModule), task.py, main_infer.py, data/
– tests under mammal/examples/tests
- Configuration & examples
– pyproject.toml defines packaging
– Each example has a Hydra/YAML config, enabling dynamic protocol for different biomedical tasks
- External integrations
– Modular tokenizer from an external “fuse” library
– HuggingFace model hub (pre-trained weights)
– PyTorch Lightning for training loops
– Hydra for configuration

##### README for additional insights
- Describes MAMMAL’s architecture: aligned multi-modal tokens, prompt syntax
- Shows usage patterns: load pre-trained model + tokenizer, build prompt, run generate()
- Fine-tuning commands via main_finetune.py
- Emphasizes extensibility: adding new tasks via tutorials

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Configuration & CLI Layer
  subgraph "Configuration & CLI Layer"
    direction TB
    Config["Hydra Configs"]:::core
    FTCLI["main_finetune.py"]:::core
    InferCLI["main_infer.py"]:::core
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    DataModule["DataModule (PyTorch Lightning)"]:::core
    RawData["Raw Datasets"]:::core
  end

  %% Core Library
  subgraph "Core Library"
    direction TB
    Model["Model Module"]:::core
    Task["Task Abstraction"]:::core
    Loss["Loss Functions"]:::core
    Scheduler["LR Schedulers"]:::core
    Metrics["Evaluation Metrics"]:::core
    LoRA["LoRA Adapter"]:::core
    Keys["Key Definitions"]:::core
  end

  %% Example Task Plugins
  subgraph "Example Task Plugins" 
    direction TB
    subgraph Carcinogenicity
      direction TB
      CarcConfig["config.yaml"]:::plugin
      CarcData["pl_data_module.py"]:::plugin
      CarcInfer["main_infer.py"]:::plugin
      CarcData --> CarcInfer
      CarcConfig --> CarcData
    end
    subgraph DTI_BindingDB
      direction TB
      DTIConfig["config.yaml"]:::plugin
      DTIData["pl_data_module.py"]:::plugin
      DTIInfer["main_infer.py"]:::plugin
      DTIConfig --> DTIData
      DTIData --> DTIInfer
    end
    subgraph Protein_Solubility
      direction TB
      ProtConfig["config.yaml"]:::plugin
      ProtData["pl_data_module.py"]:::plugin
      ProtInfer["main_infer.py"]:::plugin
      ProtConfig --> ProtData
      ProtData --> ProtInfer
    end
    subgraph scRNA_Cell_Type
      direction TB
      scConfig["config.yaml"]:::plugin
      scData["pl_data_module.py"]:::plugin
      scInfer["scRNA_infer.py"]:::plugin
      scConfig --> scData
      scData --> scInfer
    end
    subgraph MolNet
      direction TB
      MolInfer["molnet_infer.py"]:::plugin
    end
    subgraph TCR_Epitope
      direction TB
      TCRInfer["main_infer.py"]:::plugin
    end
  end

  %% External Services & Dependencies
  subgraph "External Services & Dependencies"
    direction TB
    HFHub["HuggingFace Hub"]:::external
    Tokenizer["fuse Tokenizer"]:::external
    PyTorch["PyTorch / Lightning"]:::external
    Hydra["Hydra"]:::external
  end

  %% CI/CD & Packaging
  subgraph "CI/CD & Packaging"
    direction TB
    Workflows["GitHub Actions Workflows"]:::ci
    PreCommit["pre-commit hooks"]:::ci
    Packaging["pyproject.toml"]:::ci
  end

  %% Tutorials
  Tutorials["Tutorials (Jupyter Notebooks)"]:::plugin

  %% Connections
  Config -->|provides settings| DataModule
  FTCLI -->|uses config| Config
  InferCLI -->|uses config| Config
  DataModule -->|loads| RawData
  DataModule -->|yields batches| Task
  Task -->|executes| Model
  Model -->|computes logits| Loss
  Loss -->|updates| Scheduler
  Model -->|provides metrics input| Metrics
  Model -->|applies adapters| LoRA
  Task -->|defines prompts| Keys

  %% External interactions
  Model -->|from_pretrained| HFHub
  Model -->|tokenize inputs| Tokenizer
  DataModule -->|data transforms| PyTorch
  Config -->|managed by| Hydra

  %% Inference flow
  InferCLI -->|loads checkpoint| Model
  InferCLI -->|uses tokenizer| Tokenizer
  InferCLI -->|generates| Metrics

  %% Example plugin pipeline
  CarcInfer -->|runs inference through| Model
  DTIInfer -->|runs inference through| Model
  ProtInfer -->|runs inference through| Model
  scInfer -->|runs inference through| Model
  MolInfer -->|runs inference through| Model
  TCRInfer -->|runs inference through| Model

  %% CI/CD pipeline
  Workflows -->|on push executes tests & publish| Packaging
  Workflows -->|runs| PreCommit

  %% Tutorials connection
  Tutorials -->|guide extension via| Config
  Tutorials -->|demonstrate usage of| FTCLI

  %% Click Events
  click Model "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/model.py"
  click Task "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/task.py"
  click Loss "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/losses.py"
  click Scheduler "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/lr_schedulers.py"
  click Metrics "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/metrics.py"
  click LoRA "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/lora.py"
  click Keys "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/keys.py"
  click FTCLI "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/main_finetune.py"
  click CarcConfig "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/carcinogenicity/config.yaml"
  click DTIConfig "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/dti_bindingdb_kd/config.yaml"
  click ProtConfig "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/protein_solubility/config.yaml"
  click scConfig "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/scrna_cell_type/config.yaml"
  click CarcInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/carcinogenicity/main_infer.py"
  click DTIInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/dti_bindingdb_kd/main_infer.py"
  click ProtInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/protein_solubility/main_infer.py"
  click scInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/scrna_cell_type/scRNA_infer.py"
  click MolInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/molnet/molnet_infer.py"
  click TCRInfer "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/tcr_epitope_binding/main_infer.py"
  click CarcData "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/carcinogenicity/pl_data_module.py"
  click DTIData "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/dti_bindingdb_kd/pl_data_module.py"
  click ProtData "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/protein_solubility/pl_data_module.py"
  click scData "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/mammal/examples/scrna_cell_type/pl_data_module.py"
  click Workflows "https://github.com/biomedsciai/biomed-multi-alignment/tree/main/.github/workflows"
  click PreCommit "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/.pre-commit-config.yaml"
  click Packaging "https://github.com/biomedsciai/biomed-multi-alignment/blob/main/pyproject.toml"

  %% Styles
  classDef core fill:#cce5ff,stroke:#004085,color:#004085
  classDef plugin fill:#d4edda,stroke:#155724,color:#155724
  classDef external fill:#fff3cd,stroke:#856404,color:#856404
  classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5
```
