Metadata-Version: 2.5
Name: ezscreen
Version: 1.17.1
Summary: GPU-accelerated virtual screening CLI — powered by Kaggle GPUs
Project-URL: Repository, https://github.com/ChandraguptSharma07/SwiftScreen
Project-URL: Issues, https://github.com/ChandraguptSharma07/SwiftScreen/issues
License: Apache-2.0
License-File: LICENSE
Keywords: cheminformatics,drug-discovery,kaggle,molecular-docking,virtual-screening
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: cryptography>=43.0.0
Requires-Dist: gemmi>=0.6.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: kaggle>=2.2.2
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: meeko>=0.5.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pdbfixer>=1.9.0
Requires-Dist: py3dmol>=2.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rdkit>=2024.3.1
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: textual<1.0.0,>=0.86.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: analysis
Requires-Dist: mdanalysis>=2.7.0; extra == 'analysis'
Requires-Dist: posebusters>=0.3.0; extra == 'analysis'
Requires-Dist: prolif>=2.0.0; extra == 'analysis'
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: hatchling>=1.24.0; extra == 'dev'
Requires-Dist: pandas>=2.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.15.10; extra == 'dev'
Provides-Extra: enumerate
Requires-Dist: gypsum-dl>=1.3.0; extra == 'enumerate'
Provides-Extra: prep
Requires-Dist: pdb2pqr>=3.7.1; extra == 'prep'
Requires-Dist: propka>=3.5.1; extra == 'prep'
Description-Content-Type: text/markdown

# ezscreen

**Kaggle-backed virtual screening orchestration for resource-limited labs.**

`ezscreen` is a CLI/TUI workflow for preparing receptors and ligands, running docking on Kaggle or local backends, and collecting review artifacts. It lowers the operational barrier to virtual screening, but it does not replace scientific judgment about receptor quality, pocket choice, protonation, or docking-score interpretation.

## Prerequisites

- Python 3.11+
- A [Kaggle account](https://www.kaggle.com/) with GPU quota and an API token (`kaggle.json`)
- *(Optional)* NVIDIA NIM API key for Stage 2 validation with DiffDock-L

## Installation

```bash
pip install ezscreen
```

### Optional: scrubber for enhanced ligand prep

[forlilab/scrubber](https://github.com/forlilab/scrubber) provides tautomer enumeration and pH-driven protonation. Not on PyPI — install separately:

```bash
pip install git+https://github.com/forlilab/scrubber.git
```

Without it, `ezscreen` falls back to RDKit-only preparation, so the core docking path still works but ligand-state handling is less comprehensive.

## Setup

```bash
ezscreen auth
```

Prompts for your Kaggle `kaggle.json` path and optionally an NVIDIA NIM API key.

## Quickstart — TUI

Launch the full-screen interface:

```bash
ezscreen
```

This opens the home dashboard. From there:

- Press `r` to open the Run Wizard (5-step guided docking pipeline)
- Press `s` to open the Status Monitor (live run tracking)
- Press `?` for the full keybindings reference

### Run Wizard walkthrough

1. **Receptor** — enter a PDB ID (downloaded automatically from RCSB) or a local `.pdb` path. Select chains.
2. **Binding site** — choose from co-crystal ligand, residue list, P2Rank prediction, or blind whole-protein.
3. **Ligand library** — path to a `.smi`, `.smiles`, or `.sdf` file.
4. **Options** — toggle ADMET pre-filter and set search depth (Fast / Balanced / Thorough).
5. **Summary + submit** — review all parameters including box coordinates, then submit to Kaggle.

Results appear in the TUI Results screen when the run completes; they should be reviewed as docking hypotheses, not treated as validated screening conclusions on their own.

## Quickstart — CLI

```bash
ezscreen auth          # set up credentials once
ezscreen run           # guided CLI wizard
ezscreen status        # track running jobs
ezscreen view <run_id> # show results table and open 3D viewer
```

See `examples/1hsg_quickstart.md` for a walkthrough against HIV-1 protease.

## Commands

| Command | Description |
|---|---|
| `ezscreen` | Launch full-screen TUI (default when no subcommand given) |
| `ezscreen auth` | Configure Kaggle and NIM credentials |
| `ezscreen status` | List all runs with status (auto-refreshes) |
| `ezscreen view <run_id>` | Show results table and open 3D viewer |
| `ezscreen admet <file>` | Standalone ADMET filtering on any SDF or SMILES file |
| `ezscreen validate <receptor> <hits>` | Stage 2 re-docking via NVIDIA NIM DiffDock-L |
| `ezscreen clean <run_id>` | Delete Kaggle dataset and kernel artifacts |

## Features

- **Full-screen TUI** — Textual-based interface with dashboard, run wizard, live status monitor, and results viewer
- **UniDock GPU docking** — builds UniDock from source on Kaggle to match the installed CUDA toolkit
- **Tiered binding site detection** — co-crystal, residue Cα box, P2Rank top-3, or blind fallback
- **ADMET filtering** — Lipinski, Veber, PAINS, Brenk toxicophores applied locally before submitting to reduce wasted GPU time
- **Compound identity** — results include the original name and SMILES alongside docking scores
- **Artifact filtering** — unphysical scores (below −15 kcal/mol) removed automatically
- **Resilient download** — exponential backoff retry; local score recovery from PDBQTs if download fails
- **Browser-based viewers** - pose, interaction, and report pages for manual review
- **DiffDock-L follow-up** - NVIDIA NIM integration for an additional pose-confidence check on selected hits
- **Checkpoint resume** — SQLite-backed run state; interrupted runs can be resumed mid-shard
- **Desktop notifications** — optional toast on run completion via plyer

## Screenshots

![Home Dashboard](docs/screenshots/Home_Dashboard.png)

![Status Monitor](docs/screenshots/Status_Monitor.png)

![Results Viewer](docs/screenshots/Result_Viewer.png)

## License

Apache-2.0
