Apolo MVP v1

Apolo es un flujo de trabajo bioinformatico para descubrimiento asistido por IA y docking molecular. Esta carpeta corresponde a una version final, documentada y lista para GitHub del MVP ya probado en el workspace local.

La prioridad de esta distribucion es dejar una base publica, reproducible y trazable sin subir artefactos gigantes o temporales que compliquen el push a GitHub.

Highlights

• flujo end-to-end de cribado virtual asistido por IA y docking molecular
• biblioteca botanica priorizada de Ecuador y Amazonia
• 6 targets terapeuticos consolidados
• 193 ligandos retenidos desde una entrada inicial de 500
• 1158 pares evaluados por screening AI
• 20 pares finales dockeados con docking_status=success
• corridas de referencia incluidas para 20260401 y 20260405

Alcance del MVP

Este MVP incluye:

• repositorio de targets curados y preparados para docking
• repositorio de ligandos botanicos curados
• cribado DTI masivo con modelo XGBoost y embeddings ESM-2
• docking batch con AutoDock Vina
• validacion por redocking gate
• clustering de poses y ranking ejecutivo
• documentacion operativa y configuraciones usadas en corridas validadas

No intenta ser una refactorizacion profunda. La meta sigue siendo estabilidad, ejecucion repetible y facilidad de handoff.

Flujo oficial

1. scripts/target_repository.py Descarga, limpia y prepara targets; separa receptor y ligando co-cristal y genera PDBQT y pocket.
2. scripts/ligand_repository.py Resuelve compuestos desde fuentes curadas, deduplica y genera la biblioteca consolidada de ligandos.
3. scripts/dti_predictor.py Ejecuta el cribado DTI masivo y exporta ai_docking_manifest.csv.
4. scripts/docking_pipeline.py Ejecuta docking batch sobre el manifiesto, con redocking gate y clustering de poses.

Wrappers historicos incluidos por compatibilidad:

• scripts/06_ai_massive_screening.py -> delega a dti_predictor.py
• scripts/vina_orchestrator.py -> delega a docking_pipeline.py

Que incluye esta version para GitHub

• vina.exe en la raiz del proyecto
• data/models/apolo_dti_xgboost_v3.json
• data/models/apolo_model_metadata.json
• data/models/facebook_esm2_t33_650M_UR50D/ con archivos de configuracion y tokenizer
• data/targets/ y data/ligands/ con activos preparados para pruebas
• data/results/dti_screening/dti_full_20260401/
• data/results/dti_screening/dti_193ligands_6targets_20260405/
• data/docking/results_v20260401/
• data/docking/results_v20260405/

Que se excluyo deliberadamente

• venv/, .venv/, logs y caches temporales
• data/models/facebook_esm2_t33_650M_UR50D/model.safetensors

El peso principal del modelo ESM-2 no se incluye porque supera ampliamente los limites practicos de GitHub. Esta version queda publicable; para reejecutar el screening DTI puedes:

• descargar el modelo localmente y apuntarlo con --esm-model-path
• o dejar que transformers lo resuelva desde Hugging Face si el entorno tiene acceso de red y cache local

Consulta docs/INSTALLATION.md y data/models/facebook_esm2_t33_650M_UR50D/APOLO_SETUP.md.

Corridas de referencia

Corrida historica 20260401

• data/results/dti_screening/dti_full_20260401/
• data/docking/results_v20260401/docking_top_hits_clustered_20260401/
• redocking gate paso para P15056 y P27487
• el docking batch completo termino con 10/10 pares exitosos

Campana ejecutiva 20260405

• data/results/dti_screening/dti_193ligands_6targets_20260405/
• data/docking/results_v20260405/docking_193ligands_6targets_20260405/
• resumen ejecutivo: data/docking/results_v20260405/docking_193ligands_6targets_20260405/EXECUTIVE_SUMMARY_20260405.md
• screening AI: 1158 pares evaluados, 28 seleccionados para docking
• redocking gate: 4 targets pass, 2 fail
• docking final: 20 pares finales, todos con docking_status=success

Inicio rapido

Consulta la guia completa en docs/QUICKSTART.md. El resumen minimo es:

python -m venv venv
.\venv\Scripts\python.exe -m pip install --upgrade pip
.\venv\Scripts\pip.exe install -r requirements.txt
.\venv\Scripts\python.exe scripts\target_repository.py --help
.\venv\Scripts\python.exe scripts\ligand_repository.py --help
.\venv\Scripts\python.exe scripts\dti_predictor.py --help
.\venv\Scripts\python.exe scripts\main_batch_run.py --help

Si ya descargaste el modelo ESM-2 local:

.\venv\Scripts\python.exe scripts\dti_predictor.py `
  --esm-model-path data\models\facebook_esm2_t33_650M_UR50D `
  --help

Documentacion

• docs/ARCHITECTURE.md
• docs/INSTALLATION.md
• docs/QUICKSTART.md
• docs/PIPELINE.md
• docs/INPUTS_OUTPUTS.md
• docs/RUNBOOK.md
• docs/TROUBLESHOOTING.md
• docs/REFERENCE_RUNS.md

Estructura

apolo_mvp_v1/
├── config/
├── data/
├── docs/
├── env/
├── scripts/
├── src/
├── tests/
├── requirements.txt
├── vina.exe
└── README.md

Recomendacion de uso

Usa esta carpeta como base publica del proyecto y conserva el workspace original como historico de desarrollo y experimentacion.