pybiotech 0.3.2
A collection of reusable python biotech library from AI Lingues.
License: MIT
Requires Python: >=3.11
Keywords: AILingues, components, biotech, library

# AI Lingues Biotech Python Library

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-active-brightgreen.svg)](https://github.com/ailingues/pybiotech)

pybiotech is a biology-focused toolkit from AI Lingues that builds on RDKit, PubChem, and UniProt to deliver molecule optimization, fingerprinting, structured loaders, and request modeling for data-driven biomedical workflows.

---

## Key Capabilities

- Molecular engineering with ETKDG embedding, MMFF/UFF optimization, surface and hydrophobic metrics, ring counts, fingerprints, and pharmacophore distances.
- Binary serialization that wraps rdkit.Chem.Mol objects in a CRC32-protected container suitable for IPC, sockets, or shared memory.
- Loader stack covering file, directory, and text SDF parsing plus UniProt XML streaming with error tolerance and namespace handling.
- PubChem request builder that unifies Input, Operation, Output, and Query segments, enforces validation rules, and can reverse-parse existing URLs.
- Schema modeling using Pydantic and xsdata so UniProt query fields and PubChem domain pieces stay type-safe.

---

## 📦 Installation

### Install from PyPI

```bash
pip install pybiotech
```

### Requirements

- Python 3.10 or newer (3.11 recommended)
- RDKit for molecule processing
- Additional dependencies declared in pyproject.toml / requirements.txt (xsdata, lxml, pydantic, scipy, numpy, etc.)

---

## 📚 Quick Start

### 1. Embed, optimize, and serialize a molecule

```python
from rdkit import Chem
from pybiotech.core.molecule.optimizer import Optimizer

mol = Chem.MolFromSmiles("c1ccccc1O")
mol3d, ok, meta = Optimizer.embed_and_optimize(mol, random_seed=42)
blob = Optimizer.to_serialize([mol3d, None], include_props=True, with_checksum=True)
print("converged:", ok, "method:", meta["method"])
```

### 2. Read SDF records from a directory

```python
from pybiotech.loaders.sdf_loader import SDFLoader

mols, expected, actual = SDFLoader.readDataFromDir("data/sdf", recursive=True)
print(f"expected {expected}, loaded {actual} valid molecules")
```

### 3. Build a PubChem REST URL

```python
from pybiotech.classes.nih.https.pubchem.input_spec import InputSpec
from pybiotech.classes.nih.https.pubchem.opera_spec import OperationSpec
from pybiotech.classes.nih.https.pubchem.output_spec import OutputSpec
from pybiotech.classes.nih.https.pubchem.query_options import QueryOptions
from pybiotech.classes.nih.https.pubchem.request import PubChemRequest

input_spec = InputSpec(domain="compound", namespace="cid", identifiers="2244")
operation_spec = OperationSpec(operation="property", tags=["MolecularFormula", "InChIKey"], domain="compound")
output_spec = OutputSpec(output_format="JSON")
query_options = QueryOptions(record_type="3d", image_size="large")

req = PubChemRequest(
    input_spec=input_spec,
    operation_spec=operation_spec,
    output_spec=output_spec,
    query_options=query_options,
)
print(req.build_url())
```

---

## Module overview

### Core (molecule)

| Module | Purpose | Docs |
| --- | --- | --- |
| `core.molecule.calculator` | Geometry, surface, fingerprint, and pharmacophore helpers for Chem.Mol. | [docs/core/molecule/calculator.md](docs/core/molecule/calculator.md) |
| `core.molecule.optimizer` | ETKDG embedding plus MMFF/UFF optimization, serialization container, and checksum-aware deserialization. | [docs/core/molecule/optimizer.md](docs/core/molecule/optimizer.md) |

### Loaders

| Module | Purpose | Docs |
| --- | --- | --- |
| `loaders.sdf_loader` | Stream file/dir/text SDF content with index filtering, error tolerance, and warning control. | [docs/pybiotech/loaders/sdf_loader.md](docs/pybiotech/loaders/sdf_loader.md) |
| `loaders.uniprot_loader` | Auto namespace detection and entry-by-entry UniProt XML parsing. | [docs/pybiotech/loaders/uniprot_loader.md](docs/pybiotech/loaders/uniprot_loader.md) |
| `loaders.uniprot_query_field_loader` | Load QueryField definitions from JSON/text and build validated term:value fragments. | [docs/pybiotech/loaders/uniprot_query_field_loader.md](docs/pybiotech/loaders/uniprot_query_field_loader.md) |

### Classes (models and request helpers)

| Module | Purpose | Docs |
| --- | --- | --- |
| `classes.uniprot.https.uniprot.org.uniprot_query_field` | Pydantic QueryField model with recursive siblings/items. | [docs/classes/uniprot/https/uniprot/org/uniprot_query_field.md](docs/classes/uniprot/https/uniprot/org/uniprot_query_field.md) |
| `classes.uniprot.https.uniprot.org.uniprot` | xsdata-generated dataclasses and enums for UniProt Entry, Protein, Sequence, etc. | [docs/classes/uniprot/https/uniprot/org/uniprot.md](docs/classes/uniprot/https/uniprot/org/uniprot.md) |
| `classes.nih.https.pubchem.*` | Input, Operation, Output, Query, Request, and Identifier/domain modeling for PubChem PUG REST. | [docs/classes/nih/https/pubchem](docs/classes/nih/https/pubchem) |

---

## 📖 Documentation

Detailed API references are under docs/:

- docs/core/molecule/ - optimizer and calculator references
- docs/pybiotech/loaders/ - SDF/UniProt loader documentation
- docs/classes/nih/https/pubchem/ - PubChem URL and query modeling
- docs/classes/uniprot/https/uniprot/org/ - UniProt schema reference

---

## 🏗️ Project layout

- pybiotech/
  - pybiotech/
    - core/
      - molecule/
    - loaders/
    - classes/
  - docs/
  - scripts/
  - README.md
  - README_Example.md
  - pyproject.toml
  - requirements.txt

---

## 📝 License & Usage Terms

### Package Usage License

The PyBiotech package (the binary package installed via pip) is released under the MIT License:

- ✅ Free Use – May be used freely in personal and enterprise projects
- ✅ Commercial Use – Allowed in commercial products and services
- ✅ Free Distribution – You may freely distribute and redistribute the package
- ✅ No Usage Restrictions – No fees or additional authorization required

### Source Code Protection Terms

Important Notice: The source code of this project is private property and protected by intellectual property law:

- ❌ Source Code Not Public – The source code is not publicly available
- ❌ No Reverse Engineering – Decompilation, reverse engineering, or disassembly of the package is strictly prohibited
- ❌ No Source Distribution – You may not obtain, copy, or distribute the source code in any form
- ❌ No Modified Redistribution – You may not modify the package and redistribute it
In short: You are free to use our package (including for commercial purposes), but please respect our source code intellectual property rights.

## 📧 Contact Us

Website: https://www.ailingues.com

Email: support@ailingues.com

Technical Support: For any questions or suggestions, please contact us via email.

---

**Made with ❤️ by AI Lingues Team**