Metadata-Version: 2.4
Name: pkanet-cloud
Version: 0.8.0
Summary: Tautomer-aware microstate ranking · HH scoring · PubChem pKa evidence · pH-adjusted 3D structures
Project-URL: Homepage, https://github.com/nyelidl/pKaNET_Cloud
Project-URL: Documentation, https://github.com/nyelidl/pKaNET_Cloud#readme
Project-URL: Bug Tracker, https://github.com/nyelidl/pKaNET_Cloud/issues
Project-URL: DFDD Project, https://github.com/nyelidl/DFDD
Author-email: Kowit Hengphasatporn <kowith@ccs.tsukuba.ac.jp>
License: MIT License
        
        Copyright (c) 2026 Kowit Hengphasatporn
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cheminformatics,drug-design,molecular-docking,pKa,protonation,rdkit,tautomer
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.9
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 :: Chemistry
Requires-Python: >=3.9
Requires-Dist: rdkit>=2022.03
Requires-Dist: requests>=2.28
Provides-Extra: all
Requires-Dist: dimorphite-dl>=1.3; extra == 'all'
Requires-Dist: pandas>=1.5; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: propka>=3.5; extra == 'all'
Requires-Dist: streamlit>=1.32; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.1; extra == 'dev'
Requires-Dist: dimorphite-dl>=1.3; extra == 'dev'
Requires-Dist: pandas>=1.5; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: dimorphite
Requires-Dist: dimorphite-dl>=1.3; extra == 'dimorphite'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Provides-Extra: pkasolver
Requires-Dist: pkasolver>=0.1; extra == 'pkasolver'
Provides-Extra: propka
Requires-Dist: propka>=3.5; extra == 'propka'
Provides-Extra: recommended
Requires-Dist: dimorphite-dl>=1.3; extra == 'recommended'
Requires-Dist: pandas>=1.5; extra == 'recommended'
Provides-Extra: web
Requires-Dist: pillow>=10.0; extra == 'web'
Requires-Dist: streamlit>=1.32; extra == 'web'
Description-Content-Type: text/markdown

# pKaNET Cloud+

[![PyPI](https://img.shields.io/pypi/v/pkanet-cloud)](https://pypi.org/project/pkanet-cloud/)
[![Python](https://img.shields.io/pypi/pyversions/pkanet-cloud)](https://pypi.org/project/pkanet-cloud/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Tautomer-aware microstate ranking · Henderson–Hasselbalch scoring ·
PubChem pKa evidence · pH-adjusted 3D structures**

Part of the [DFDD Project](https://github.com/nyelidl/DFDD).

---

## Features

- **Tautomer enumeration** with SMARTS-based plausibility scoring
- **Dimorphite-DL** protonation state enumeration over a pH window
- **Henderson–Hasselbalch** 5-layer microstate scoring
- **PubChem experimental pKa** evidence to guide state selection
- **ETKDGv3 + MMFF** 3D minimization for the top microstates
- Optional ML backends: **pkasolver**, **propka**, **unipka CLI**
- **CLI** (`pkanet`) and **Python API**
- **Streamlit** web UI (optional)

---

## Installation

```bash
# Minimal (RDKit + requests only — heuristic mode)
pip install pkanet-cloud

# Recommended (adds Dimorphite-DL and pandas)
pip install "pkanet-cloud[recommended]"

# Full (adds propka and Streamlit web UI)
pip install "pkanet-cloud[all]"
```

> **RDKit note:** `rdkit` is listed as a dependency but PyPI's `rdkit` wheel
> requires Python ≥ 3.9 on 64-bit platforms. If your environment uses a
> conda-managed RDKit, install without deps:
> ```bash
> pip install pkanet-cloud --no-deps
> pip install requests dimorphite-dl pandas   # then add these manually
> ```

---

## CLI

After installation a `pkanet` command is available:

```bash
# Single SMILES
pkanet --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" --ph 7.4

# Compound name  (PubChem auto-lookup)
pkanet --name "baicalein" --ph 7.4 --out-dir ./results

# SMILES file  (one SMILES [name] per line)
pkanet --smi-file ligands.smi --formats PDB MOL2 --top-n 3

# Ligand file  (.pdb / .mol2 / .sdf)
pkanet --file ligand.pdb --no-pubchem --keep-stereo

# Fast heuristic charge only  (no 3D, sub-millisecond)
pkanet --smiles "NCC(=O)O" --fast
pkanet --smi-file library.smi --fast --quiet   # TSV output
```

### All CLI flags

| Flag | Default | Description |
|---|---|---|
| `--ph` | 7.4 | Target pH |
| `--out-dir` | `./pkanet_out` | Output directory |
| `--out-name` | `ligand` | Base name for output files |
| `--formats PDB MOL2 SDF` | PDB | 3D output format(s) |
| `--ph-window` | 1.0 | Dimorphite-DL pH window |
| `--max-tautomers` | 8 | Max tautomers to enumerate |
| `--top-n` | 5 | Top N microstates to rank |
| `--top-k-3d` | 3 | Write 3D for top-k microstates |
| `--keep-stereo` | off | Skip R/S stereoisomer enumeration |
| `--no-pubchem` | off | Disable PubChem pKa lookup |
| `--fast` | off | Heuristic charge only (no 3D) |
| `--json-out FILE` | — | Write full results as JSON |
| `--quiet` | off | TSV output, no banner |

---

## Python API

```python
from pkanet import predict_charge, heuristic_net_charge, batch_predict_charges

# Auto mode: fast for unambiguous sites, full pipeline for borderline pKa
charge, mode = predict_charge("NCC(=O)O", ph=7.4)
print(charge, mode)   # 0  'full'

# Sub-millisecond heuristic estimate
charge = heuristic_net_charge("CC(=O)OC1=CC=CC=C1C(=O)O", ph=7.4)
print(charge)         # -1

# Batch prediction → pandas DataFrame
df = batch_predict_charges(
    ["NCC(=O)O", "CC(N)C(=O)O", "c1ccccc1O"],
    ph=7.4,
    mode="auto",
)
print(df[["name", "predicted_charge", "is_zwitterion"]])
```

### Full pipeline

```python
from pkanet.core import run_job

result = run_job(
    input_type    = "SMILES",
    smiles_text   = "CC(=O)OC1=CC=CC=C1C(=O)O",
    uploaded_bytes = None,
    uploaded_name  = None,
    target_pH     = 7.4,
    output_name   = "aspirin",
    out_dir       = "./output",
    output_formats = ["PDB"],
    use_pubchem   = True,
)

top = result["results"][0]
print(top["selected_microstate_smiles"])
print(top["formal_charge"])
print(top["minimized_pdb"])
```

---

## pKa backends (auto-selected by priority)

| Priority | Backend | Install |
|---|---|---|
| 1 | **pkasolver** (GNN) | `pip install pkasolver` |
| 2 | **propka** (semi-empirical) | `pip install "pkanet-cloud[propka]"` |
| 3 | **unipka CLI** | system install |
| 4 | **heuristic SMARTS table** | built-in, always available |

---

## Citation

If you use pKaNET Cloud+ in your research, please cite:

```
Hengphasatporn K. et al. DFDD / Anyone Can Dock. JCIM (2026).
Ropp PJ et al. Dimorphite-DL. J Cheminform (2019).
```

---

## License

MIT © Kowit Hengphasatporn — [kowith@ccs.tsukuba.ac.jp](mailto:kowith@ccs.tsukuba.ac.jp)
