Metadata-Version: 2.4
Name: fractalml
Version: 1.0.0
Summary: FRACTAL: Framework for Representation-guided Atomic ConsTruction & ALignment - A protein structure prediction system
Author: Aayan Mishra
License: MIT
Project-URL: Homepage, https://github.com/Aayan-Mishra/FractalGPT
Project-URL: Repository, https://github.com/Aayan-Mishra/FractalGPT
Project-URL: Documentation, https://github.com/Aayan-Mishra/FractalGPT#readme
Project-URL: Issues, https://github.com/Aayan-Mishra/FractalGPT/issues
Keywords: protein,folding,structure-prediction,bioinformatics,deep-learning,esm,alphafold
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: certifi>=2024.0.0
Requires-Dist: torch>=2.1
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.5
Requires-Dist: PyYAML>=6.0
Provides-Extra: esm
Requires-Dist: fair-esm>=2.0.0; extra == "esm"
Provides-Extra: train
Requires-Dist: tqdm>=4.66; extra == "train"
Provides-Extra: data
Requires-Dist: requests>=2.31; extra == "data"
Requires-Dist: tqdm>=4.66; extra == "data"
Requires-Dist: gemmi>=0.6.6; extra == "data"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Provides-Extra: webui
Requires-Dist: fastapi>=0.110; extra == "webui"
Requires-Dist: uvicorn[standard]>=0.27; extra == "webui"
Requires-Dist: python-multipart>=0.0.9; extra == "webui"
Requires-Dist: pyngrok>=7.0; extra == "webui"

# FRACTAL

**FRACTAL (Framework for Representation-guided Atomic ConsTruction & ALignment)** is a research-grade protein folding *system* inspired by AlphaFold-style pipelines and modern protein language models (ESM-2).

Philosophy:

- Intelligence predicts **structured geometric constraints** (distance distributions, contacts, torsions, confidence)
- Deterministic code enforces **geometry + physics-inspired priors**

This repository intentionally does **not** predict raw XYZ coordinates from the neural network.

## Recent Updates (AlphaFold-Style Enhancements)

**New capabilities:**
- ✅ **Validation loop** with automatic model selection
- ✅ **Checkpointing** with training state resumption
- ✅ **Learning rate scheduling** (ReduceLROnPlateau)
- ✅ **Early stopping** based on validation loss
- ✅ **Evaluation metrics**: RMSD, TM-score, GDT-TS, contact accuracy
- ✅ **Enhanced training** with better logging and error handling

## Repository layout

- `src/fractal/models/` : ESM-2 backbone wrappers + lightweight constraint heads
- `src/fractal/data/` : dataset formats + preprocessing utilities
- `src/fractal/geometry/` : deterministic folding/assembly engine
- `src/fractal/training/` : trainers, losses, configs (with validation & checkpointing)
- `src/fractal/inference/` : FASTA → constraints pipeline
- `src/fractal/evaluation/` : **NEW** - RMSD, TM-score, GDT-TS metrics
- `scripts/` : CLI-adjacent utilities (preprocess/train/eval/infer)
- `configs/` : YAML configs
- `tests/` : unit tests (geometry + model components)

## Quickstart

Create an environment and install:

- Minimal install: `pip install -e .`
- With ESM support: `pip install -e '.[esm]'`
- With tests: `pip install -e '.[test]'`

Run CLI help:

```bash
fractal --help
```

## Training with Validation

The new training pipeline supports:
- Automatic validation during training
- Best model selection based on validation loss
- Learning rate reduction on plateau
- Early stopping to prevent overfitting
- Checkpoint management (keeps last N checkpoints)

**Train from scratch:**
```bash
python scripts/train.py configs/train.yaml
```

**Resume from checkpoint:**
```bash
python scripts/train.py configs/train.yaml --resume checkpoints/best
```

**Config options** (see `configs/train.yaml`):
```yaml
trainer:
  epochs: 50
  validate_every_n_epochs: 1
  save_every_n_epochs: 5
  keep_last_n_checkpoints: 3
  use_lr_scheduler: true
  early_stopping_patience: 15
```

## Evaluation

Evaluate a trained model:
```bash
python scripts/eval.py checkpoints/best data/processed/test_manifest.jsonl -o results.json
```

Metrics computed:
- Distance prediction accuracy (bin classification)
- Contact prediction accuracy (binary classification)
- Torsion angle error (degrees)
- Structure quality (when ground truth available):
  - RMSD (Cα atoms)
  - TM-score
  - GDT-TS

## Next Steps to Reach AlphaFold Performance

1. **Scale dataset**: Download 10K+ PDB structures using `scripts/download_rcsb.py`
2. **Add MSA features**: Integrate evolutionary information via MMseqs2/HMMER
3. **Implement structure module**: Replace simple optimization with learned refinement
4. **Add template features**: Use homologous structure templates
5. **Distributed training**: Scale to multi-GPU with PyTorch DDP

> Note: the current implementation focuses on a correct modular system skeleton with proper training infrastructure. Dataset preprocessing/training loops are research-grade and ready for expansion.
