Metadata-Version: 2.4
Name: hiwosy-bio
Version: 0.1.0
Summary: The bioisostere trust layer — score a molecular swap with full evidence.
Author: Ljubisa Kovach
License: MIT
Project-URL: Homepage, https://github.com/Hiwosy/hiwosy-bio
Project-URL: Documentation, https://github.com/Hiwosy/hiwosy-bio#readme
Project-URL: Issues, https://github.com/Hiwosy/hiwosy-bio/issues
Project-URL: Source, https://github.com/Hiwosy/hiwosy-bio
Keywords: cheminformatics,bioisostere,medicinal-chemistry,drug-discovery,rdkit,mmpdb,chembl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-DATA.md
Requires-Dist: rdkit>=2023.9.1
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Hiwosy BIO — the bioisostere trust layer

> *Paste a molecule and a proposed swap.
> Get a defensible confidence score and the full evidence trail in five seconds.*

Hiwosy BIO is the trust layer for bioisosteric replacements. Not a discovery
engine. Not a recommender. Not a generator. **A scorer.**

A medicinal chemist who is about to commit six weeks of bench time to
synthesizing an analog wants one question answered, fast: *"Is this swap
supported by the public data — and how strongly?"*

That is the only question Hiwosy BIO answers. It does so with:

- A 0.0–1.0 **confidence score** decomposed into 9 transparent factors.
- The **full evidence trail**: every matched molecular pair from ChEMBL
  that supports or refutes the swap, broken down by target class.
- **Off-target divergence** detection (the Vioxx-style safety flag).
- **Liability annotations** for known-problematic functional groups.
- **Synthetic accessibility** scoring on the proposed analog.
- **Novelty classification** (KNOWN / SEMI-NOVEL / NOVEL).
- **Patent landscape** — stubbed in v1, hookable to SureChEMBL.

---

## Positioning vs. the rest of the world

| Tool | What it does | Why a chemist still needs Hiwosy BIO |
|---|---|---|
| SwissBioisostere (free DB) | Lookup table | No confidence, no breakdown, no context |
| BIOSTER (paid catalogue) | Curated list | Static, no quantitative confidence |
| Schrödinger Bioisostere Search | Embedded in Maestro | Black box, no factor decomposition |
| MMPDB (open-source) | Raw MMP extraction | Low-level, no scoring |
| Generative ML (REINVENT, MMPT-RAG) | Generate analogs | No traceability — can't tell you *why* |
| SureChEMBL | Patent search | No scientific support score |

Hiwosy BIO is the **single** tool you run *before* committing to synthesis.
Show it to your PI. Show it to a regulator. Show it to a patent attorney.
Every confidence number traces back to the underlying compound pairs.
**No black boxes. No vibes. Always show your work.**

---

## Quick start

```bash
pip install -r requirements.txt

python -m hiwosy_bio.cli score \
  --mol "CC(C)Cc1ccc(C(C)C(=O)O)cc1" \
  --swap "carboxylic_acid:tetrazole" \
  --target-class "cyclooxygenase"
```

Or in Python:

```python
from hiwosy_bio import ConfidenceEngine

engine = ConfidenceEngine.default()
report = engine.score(
    smiles="CC(C)Cc1ccc(C(C)C(=O)O)cc1",     # ibuprofen
    swap=("carboxylic_acid", "tetrazole"),
    target_class="cyclooxygenase",
)
print(report.render())
```

---

## What the output looks like

```
─────────────────────────────────────────────────────
INPUT
  Molecule       : CC(C)Cc1ccc(C(C)C(=O)O)cc1
  Proposed swap  : carboxylic_acid → tetrazole
  Context        : target_class = cyclooxygenase
─────────────────────────────────────────────────────
CONFIDENCE     : 0.79  (HIGH — would synthesise)
CLASSIFICATION : KNOWN
─────────────────────────────────────────────────────
Evidence: 142 matched pairs
  ├── 38   from same target class (cyclooxygenase)
  ├── 87   from related targets
  └── 17   from unrelated targets

9-Factor breakdown:
  F1 Observations         0.91   142 pairs ≥ threshold
  F2 Target diversity     0.84   54 distinct targets
  F3 Activity quality     0.72   geomean ratio 1.3x
  F4 Scaffold diversity   0.78   29 distinct Murcko scaffolds
  F5 Consistency          0.81   variance 0.18
  F6 Fragment Tanimoto    0.65
  F7 Δ Property dist      0.84   ΔPSA +12, ΔlogP -0.3
  F8 Δ LLE                0.71   avg -0.2
  F9 Size match           0.92   ΔMW +12 Da

Liability flags:
  ⚠ tetrazole adds an ionizable acidic moiety (pKa ~4.9)
  ⚠ tetrazole may alter HSA binding profile

Off-target divergence : uniform ✓ (CV log-ratio 0.18)
Synthetic accessibility: 3.2 (moderate)
Novelty               : KNOWN

Patent landscape (SureChEMBL stub):
  ⓘ patent backend not configured

Top supporting MMP examples:
  CHEMBL3801 ↔ CHEMBL3802  COX-1  ratio=1.10x
  CHEMBL5621 ↔ CHEMBL5622  PTGS2  ratio=0.92x
  ... 140 more (use --show-evidence to dump all)
─────────────────────────────────────────────────────
```

---

## Architecture

```
hiwosy_bio/
  core.py          ConfidenceEngine — main orchestrator
  evidence.py      Loads V3 candidates_learned.json, filters by target class
  factors.py       9-factor confidence (wraps molecular-discovery V3 validator)
  divergence.py    Off-target divergence detector (CV of log activity ratios)
  liabilities.py   Per-group liability lookup
  synth_score.py   RDKit SA-Score on the proposed analog
  target_classes.py ChEMBL target → class taxonomy
  molecule.py      SMILES parsing, group localization, analog construction
  report.py        Renders the formatted output
  cli.py           Command-line entry point
data/
  liabilities.json    ~30 known group liability annotations
  target_classes.json ChEMBL target → class mapping (curated subset)
```

The engine reuses the 9-factor `ConfidenceValidator` from `molecular-discovery`
and reads candidate evidence from any `candidates_learned.json` produced by
the V3 cascade. Hiwosy BIO is **the consumer surface**; molecular-discovery
remains **the data factory**.

---

## What Hiwosy BIO does NOT do

This is the discipline. Each is a real temptation:

- ❌ Generate novel molecules — leave to ML
- ❌ Predict ADMET — leave to ADMETlab
- ❌ Retrosynthesis — leave to AiZynth
- ❌ Active learning loops — workflow product, locks out API distribution
- ❌ 3D shape matching — niche; opt-in factor only
- ❌ Multi-target selectivity bioisosteres — niche; filter inside engine

Every feature is a way to make **the confidence number** more defensible,
faster, or more actionable. If a feature does not directly improve
"score one swap in 5 seconds with full evidence," it does not ship.

---

## License

TBD. Open-source candidate (MIT or Apache-2.0).
