# ribesstefano/protac-splitter architecture

> Architecture diagram of the GitHub repository ribesstefano/protac-splitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ribesstefano/protac-splitter
- Repository: https://github.com/ribesstefano/protac-splitter

## Overview

PROTAC-Splitter accepts PROTAC SMILES and returns E3-ligand, linker, and POI-warhead predictions. Its central API supports heuristic, graph/XGBoost, Transformer, and adaptive QC-gated strategies; CLI, HTTP, and Gradio interfaces expose that workflow. Related product capabilities include dataset curation and synthetic-data generation, graph/model training, prediction repair, plausibility evaluation, and visualization. Edges follow the excerpted code, SOURCE INDEX references, or README; unsampled subsystem links are omitted where their caller is not evidenced.

Main entry points: [`protac_splitter/protac_splitter.py`](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/protac_splitter.py) (Split orchestrator), [`protac_splitter/graphs/splitting_algorithms.py`](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/splitting_algorithms.py) (Heuristic splitter), [`protac_splitter/graphs/edge_classifier.py`](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/edge_classifier.py) (Graph classifier), [`protac_splitter/data/curation/curation.py`](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/curation.py) (Dataset curation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_python["Python API<br/>[__init__.py]"]
  node_cli["Command line<br/>[cli.py]"]
  node_http["HTTP service<br/>[app.py]"]
  node_gradio["Gradio app"]
end

subgraph group_inference["Splitting and inference"]
  node_orchestrator["Split orchestrator<br/>[protac_splitter.py]"]
  node_heuristic["Heuristic splitter"]
  node_graphmodel["Graph classifier<br/>[edge_classifier.py]"]
  node_features["Graph features<br/>[edge_features.py]"]
  node_clustering["Ligand clustering<br/>[clustering.py]"]
  node_transformer["Transformer inference<br/>[model_utils.py]"]
end

subgraph group_chemistry["Chemistry and quality"]
  node_chem["Chemoinformatics"]
  node_repair["Prediction repair"]
  node_evaluation["Split evaluation<br/>[evaluation.py]"]
  node_display["Molecule display<br/>[display_utils.py]"]
end

subgraph group_data["Dataset workflows"]
  node_curation["Dataset curation<br/>[curation.py]"]
  node_extraction["Substructure extraction"]
  node_adjustments["Bond adjustments"]
  node_generation["Data generation<br/>[generation.py]"]
  node_functional["Functional groups"]
end

subgraph group_models["Model development"]
  node_llmdata["LLM data prep<br/>[data_utils.py]"]
  node_training["LLM training<br/>[training.py]"]
  node_llmeval["LLM evaluation<br/>[evaluation.py]"]
end

node_user(("SMILES user"))
node_modelhub[("Hugging Face Hub")]

node_user -->|"submits SMILES"| node_python
node_user -->|"submits SMILES"| node_cli
node_user -->|"sends requests"| node_http
node_user -->|"submits SMILES"| node_gradio
node_cli -->|"calls"| node_orchestrator
node_http -->|"calls"| node_orchestrator
node_gradio -->|"calls"| node_orchestrator
node_python -->|"exposes"| node_orchestrator
node_orchestrator -->|"dispatches"| node_heuristic
node_orchestrator -->|"dispatches"| node_graphmodel
node_orchestrator -->|"dispatches"| node_transformer
node_orchestrator -->|"repairs predictions"| node_repair
node_orchestrator -->|"scores candidates"| node_evaluation
node_heuristic -->|"uses classifier"| node_graphmodel
node_graphmodel -->|"builds features"| node_features
node_heuristic -->|"uses representatives"| node_clustering
node_heuristic -->|"adjusts fragments"| node_adjustments
node_orchestrator -->|"uses utilities"| node_chem
node_repair -->|"uses extraction"| node_extraction
node_curation -->|"extracts substructures"| node_extraction
node_curation -->|"adjusts bonds"| node_adjustments
node_generation -->|"checks outputs"| node_evaluation
node_generation -->|"uses groups"| node_functional
node_training -->|"prepares data"| node_llmdata
node_training -->|"evaluates model"| node_llmeval
node_transformer -.->|"loads pretrained model"| node_modelhub
node_graphmodel -->|"downloads classifier"| node_modelhub

click node_python "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/__init__.py"
click node_cli "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/cli.py"
click node_http "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/serve/app.py"
click node_gradio "https://github.com/ribesstefano/protac-splitter/blob/main/scripts/protac_splitter_app.py"
click node_orchestrator "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/protac_splitter.py"
click node_heuristic "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/splitting_algorithms.py"
click node_graphmodel "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/edge_classifier.py"
click node_features "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/edge_features.py"
click node_clustering "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/clustering.py"
click node_transformer "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/model_utils.py"
click node_chem "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/chemoinformatics.py"
click node_repair "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/fixing_functions.py"
click node_evaluation "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/evaluation.py"
click node_display "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/display_utils.py"
click node_curation "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/curation.py"
click node_extraction "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/substructure_extraction.py"
click node_adjustments "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/bond_adjustments.py"
click node_generation "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/generation/generation.py"
click node_functional "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/generation/functional_groups.py"
click node_llmdata "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/data_utils.py"
click node_training "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/training.py"
click node_llmeval "https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/evaluation.py"

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_python,node_cli,node_http,node_gradio,node_user toneBlue
class node_orchestrator,node_heuristic,node_graphmodel,node_features,node_clustering,node_transformer,node_modelhub toneAmber
class node_chem,node_repair,node_evaluation,node_display toneMint
class node_curation,node_extraction,node_adjustments,node_generation,node_functional toneRose
class node_llmdata,node_training,node_llmeval toneIndigo
```

## Components

### User interfaces

- [Python API](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/__init__.py): `protac_splitter/__init__.py`
- [Command line](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/cli.py): `protac_splitter/cli.py`
- [HTTP service](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/serve/app.py): `protac_splitter/serve/app.py`
- [Gradio app](https://github.com/ribesstefano/protac-splitter/blob/main/scripts/protac_splitter_app.py): `scripts/protac_splitter_app.py`

### Splitting and inference

- [Split orchestrator](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/protac_splitter.py): `protac_splitter/protac_splitter.py`
- [Heuristic splitter](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/splitting_algorithms.py): `protac_splitter/graphs/splitting_algorithms.py`
- [Graph classifier](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/edge_classifier.py): `protac_splitter/graphs/edge_classifier.py`
- [Graph features](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/edge_features.py): `protac_splitter/graphs/edge_features.py`
- [Ligand clustering](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/graphs/clustering.py): `protac_splitter/graphs/clustering.py`
- [Transformer inference](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/model_utils.py): `protac_splitter/llms/model_utils.py`

### Chemistry and quality

- [Chemoinformatics](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/chemoinformatics.py): `protac_splitter/chemoinformatics.py`
- [Prediction repair](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/fixing_functions.py): `protac_splitter/fixing_functions.py`
- [Split evaluation](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/evaluation.py): `protac_splitter/evaluation.py`
- [Molecule display](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/display_utils.py): `protac_splitter/display_utils.py`

### Dataset workflows

- [Dataset curation](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/curation.py): `protac_splitter/data/curation/curation.py`
- [Substructure extraction](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/substructure_extraction.py): `protac_splitter/data/curation/substructure_extraction.py`
- [Bond adjustments](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/curation/bond_adjustments.py): `protac_splitter/data/curation/bond_adjustments.py`
- [Data generation](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/generation/generation.py): `protac_splitter/data/generation/generation.py`
- [Functional groups](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/data/generation/functional_groups.py): `protac_splitter/data/generation/functional_groups.py`

### Model development

- [LLM data prep](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/data_utils.py): `protac_splitter/llms/data_utils.py`
- [LLM training](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/training.py): `protac_splitter/llms/training.py`
- [LLM evaluation](https://github.com/ribesstefano/protac-splitter/blob/main/protac_splitter/llms/evaluation.py): `protac_splitter/llms/evaluation.py`

### Other components

- **SMILES user**
- **Hugging Face Hub**

## Connections

- SMILES user → Python API: submits SMILES (evidence: `README.md`)
- SMILES user → Command line: submits SMILES (evidence: `README.md`)
- SMILES user → HTTP service: sends requests (evidence: `protac_splitter/serve/app.py`)
- SMILES user → Gradio app: submits SMILES (evidence: `README.md`)
- Command line → Split orchestrator: calls (evidence: `protac_splitter/cli.py`)
- HTTP service → Split orchestrator: calls (evidence: `protac_splitter/serve/app.py`)
- Gradio app → Split orchestrator: calls (evidence: `scripts/protac_splitter_app.py`)
- Python API → Split orchestrator: exposes (evidence: `README.md`)
- Split orchestrator → Heuristic splitter: dispatches (evidence: `protac_splitter/protac_splitter.py`)
- Split orchestrator → Graph classifier: dispatches (evidence: `protac_splitter/protac_splitter.py`)
- Split orchestrator → Transformer inference: dispatches (evidence: `protac_splitter/protac_splitter.py`)
- Split orchestrator → Prediction repair: repairs predictions (evidence: `protac_splitter/protac_splitter.py`)
- Split orchestrator → Split evaluation: scores candidates (evidence: `protac_splitter/protac_splitter.py`)
- Heuristic splitter → Graph classifier: uses classifier (evidence: `protac_splitter/graphs/splitting_algorithms.py`)
- Graph classifier → Graph features: builds features (evidence: `protac_splitter/graphs/edge_classifier.py`)
- Heuristic splitter → Ligand clustering: uses representatives (evidence: `protac_splitter/graphs/splitting_algorithms.py`)
- Heuristic splitter → Bond adjustments: adjusts fragments (evidence: `protac_splitter/graphs/splitting_algorithms.py`)
- Split orchestrator → Chemoinformatics: uses utilities (evidence: `protac_splitter/protac_splitter.py`)
- Prediction repair → Substructure extraction: uses extraction (evidence: `protac_splitter/fixing_functions.py`)
- Dataset curation → Substructure extraction: extracts substructures (evidence: `protac_splitter/data/curation/curation.py`)
- Dataset curation → Bond adjustments: adjusts bonds (evidence: `protac_splitter/data/curation/curation.py`)
- Data generation → Split evaluation: checks outputs (evidence: `protac_splitter/data/generation/generation.py`)
- Data generation → Functional groups: uses groups (evidence: `protac_splitter/data/generation/__init__.py`)
- LLM training → LLM data prep: prepares data (evidence: `protac_splitter/llms/training.py`)
- LLM training → LLM evaluation: evaluates model (evidence: `protac_splitter/llms/training.py`)
- Transformer inference → Hugging Face Hub: loads pretrained model (evidence: `README.md`)
- Graph classifier → Hugging Face Hub: downloads classifier (evidence: `README.md`)
