EDKG-DL 1.0.0__tar.gz

edkg_dl-1.0.0/EDKG_DL.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: EDKG-DL
+Version: 1.0.0
+Summary: Deep Learning framework with causality-integrated Endocrine Disruption Knowledge Graph
+Author-email: haoyuejudy <njutanhaoyue@nju.edu.cn>
+License-Expression: LicenseRef-Custom-Academic-Research
+Project-URL: Homepage, https://edkgdl.com/
+Project-URL: Repository, https://github.com/haoyuejudy/EDKG-DL
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface-hub>=0.32
+Requires-Dist: joblib>=1.5.1
+Requires-Dist: networkx>=3.1
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: padelpy>=0.1.16
+Requires-Dist: pandas>=2.0
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: requests>=2.31
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torch-geometric>=2.4
+Requires-Dist: xgboost>=3.0.2
+Requires-Dist: xlsxwriter>=3.1
+Provides-Extra: api
+Requires-Dist: fastapi[standard]>=0.115; extra == "api"
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.8; extra == "plots"
+Dynamic: license-file
+
+# EDKG-DL
+
+English | [简体中文](README_zh.md)
+
+**D**eep **L**earning framework with causality-integrated **E**ndocrine **D**isruption **K**nowledge **G**raph. Predicts endocrine-disrupting effects (EDC), applicability domain (AD), and sensitive event pathways from compound SMILES using machine learning and an AOP network.
+
+Pipeline: PaDEL 2D descriptors/fingerprints → qualitative/quantitative event-endpoint models → dual-track EDC classification (tabular model + graph neural network, GCN) → sensitive event and AOP pathway inference, producing JSON / Excel reports. Results are for research support only and must not replace experimental or regulatory conclusions.
+
+## Installation
+
+Install from PyPI (Python ≥ 3.10):
+
+```bash
+pip install edkg-dl
+# or
+uv add edkg-dl
+```
+
+Optional extras: `pip install "edkg-dl[api]"` (HTTP service) and `pip install "edkg-dl[plots]"` (applicability-domain plots). See [installation docs](docs/en/installation.md) for details, including the automatic Temurin JRE download for PaDEL.
+
+Model assets (~930 MB) are fetched automatically from [Hugging Face](https://huggingface.co/HaoyueTan/edkg-dl-models) on first use — no manual setup required.
+
+## Quick start
+
+CLI:
+
+```bash
+edkg-dl-predict "CCO"                                   # JSON to stdout
+edkg-dl-predict "CCO" -o runs/example --ad-plots        # reports + PCA plots
+edkg-dl-predict batch molecules.txt -o runs/batch       # batch from a text file
+```
+
+Python:
+
+```python
+from edkg_dl import Predictor
+
+predictor = Predictor.from_assets("./models")
+result = predictor.predict("CCO")
+```
+
+## Documentation
+
+| Topic | Link |
+| --- | --- |
+| Installation | [docs/en/installation.md](docs/en/installation.md) |
+| Model assets | [docs/en/assets.md](docs/en/assets.md) |
+| CLI usage | [docs/en/cli.md](docs/en/cli.md) |
+| Python API | [docs/en/python-api.md](docs/en/python-api.md) |
+| HTTP API | [docs/en/http-api.md](docs/en/http-api.md) |
+| Output formats | [docs/en/output.md](docs/en/output.md) |
+| Development | [docs/en/development.md](docs/en/development.md) |

edkg_dl-1.0.0/EDKG_DL.egg-info/SOURCES.txt

@@ -0,0 +1,36 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+EDKG_DL.egg-info/PKG-INFO
+EDKG_DL.egg-info/SOURCES.txt
+EDKG_DL.egg-info/dependency_links.txt
+EDKG_DL.egg-info/entry_points.txt
+EDKG_DL.egg-info/requires.txt
+EDKG_DL.egg-info/top_level.txt
+edkg_dl/__init__.py
+edkg_dl/__main__.py
+edkg_dl/api.py
+edkg_dl/cli.py
+edkg_dl/config.py
+edkg_dl/exceptions.py
+edkg_dl/http_api.py
+edkg_dl/hub.py
+edkg_dl/java.py
+edkg_dl/pipeline.py
+edkg_dl/schemas.py
+edkg_dl/domain/__init__.py
+edkg_dl/domain/applicability.py
+edkg_dl/domain/causal_chains.py
+edkg_dl/domain/pathways.py
+edkg_dl/domain/sensitivity.py
+edkg_dl/features/__init__.py
+edkg_dl/features/padel.py
+edkg_dl/predictors/__init__.py
+edkg_dl/predictors/gcn.py
+edkg_dl/predictors/registry.py
+edkg_dl/reporting/__init__.py
+edkg_dl/reporting/_files.py
+edkg_dl/reporting/ad_plot.py
+edkg_dl/reporting/excel_report.py
+edkg_dl/reporting/json_report.py

edkg_dl-1.0.0/EDKG_DL.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

edkg_dl-1.0.0/EDKG_DL.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+edkg-dl-api = edkg_dl.http_api:run
+edkg-dl-predict = edkg_dl.cli:main

edkg_dl-1.0.0/EDKG_DL.egg-info/requires.txt

@@ -0,0 +1,19 @@
+huggingface-hub>=0.32
+joblib>=1.5.1
+networkx>=3.1
+numpy<3,>=1.26
+padelpy>=0.1.16
+pandas>=2.0
+platformdirs>=4.3
+requests>=2.31
+scikit-learn>=1.6.1
+torch>=2.0.0
+torch-geometric>=2.4
+xgboost>=3.0.2
+xlsxwriter>=3.1
+
+[api]
+fastapi[standard]>=0.115
+
+[plots]
+matplotlib>=3.8

edkg_dl-1.0.0/EDKG_DL.egg-info/top_level.txt

@@ -0,0 +1 @@
+edkg_dl

edkg_dl-1.0.0/LICENSE

@@ -0,0 +1,36 @@
+Custom Academic and Research Use License
+
+Copyright (c) 2026 Nanjing University
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, and distribute the Software in unmodified form solely for non-commercial
+educational and research purposes, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software must be distributed in its original, unmodified form. No
+   modification, adaptation, translation, reverse engineering, decompilation,
+   or disassembly of the Software is permitted.
+
+3. The Software may not be used for any commercial purpose, including but not
+   limited to use in a production environment, integration into a product for
+   sale or service, or use as part of a business operation.
+
+4. No derivative works based upon the Software are permitted.
+
+5. Any use of the Software outside the scope of non-commercial educational and
+   research purposes requires a separate commercial license, which may be
+   obtained by contacting the copyright holder (Nanjing University) or the
+   author.
+
+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.

edkg_dl-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+prune test

edkg_dl-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: EDKG-DL
+Version: 1.0.0
+Summary: Deep Learning framework with causality-integrated Endocrine Disruption Knowledge Graph
+Author-email: haoyuejudy <njutanhaoyue@nju.edu.cn>
+License-Expression: LicenseRef-Custom-Academic-Research
+Project-URL: Homepage, https://edkgdl.com/
+Project-URL: Repository, https://github.com/haoyuejudy/EDKG-DL
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface-hub>=0.32
+Requires-Dist: joblib>=1.5.1
+Requires-Dist: networkx>=3.1
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: padelpy>=0.1.16
+Requires-Dist: pandas>=2.0
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: requests>=2.31
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torch-geometric>=2.4
+Requires-Dist: xgboost>=3.0.2
+Requires-Dist: xlsxwriter>=3.1
+Provides-Extra: api
+Requires-Dist: fastapi[standard]>=0.115; extra == "api"
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.8; extra == "plots"
+Dynamic: license-file
+
+# EDKG-DL
+
+English | [简体中文](README_zh.md)
+
+**D**eep **L**earning framework with causality-integrated **E**ndocrine **D**isruption **K**nowledge **G**raph. Predicts endocrine-disrupting effects (EDC), applicability domain (AD), and sensitive event pathways from compound SMILES using machine learning and an AOP network.
+
+Pipeline: PaDEL 2D descriptors/fingerprints → qualitative/quantitative event-endpoint models → dual-track EDC classification (tabular model + graph neural network, GCN) → sensitive event and AOP pathway inference, producing JSON / Excel reports. Results are for research support only and must not replace experimental or regulatory conclusions.
+
+## Installation
+
+Install from PyPI (Python ≥ 3.10):
+
+```bash
+pip install edkg-dl
+# or
+uv add edkg-dl
+```
+
+Optional extras: `pip install "edkg-dl[api]"` (HTTP service) and `pip install "edkg-dl[plots]"` (applicability-domain plots). See [installation docs](docs/en/installation.md) for details, including the automatic Temurin JRE download for PaDEL.
+
+Model assets (~930 MB) are fetched automatically from [Hugging Face](https://huggingface.co/HaoyueTan/edkg-dl-models) on first use — no manual setup required.
+
+## Quick start
+
+CLI:
+
+```bash
+edkg-dl-predict "CCO"                                   # JSON to stdout
+edkg-dl-predict "CCO" -o runs/example --ad-plots        # reports + PCA plots
+edkg-dl-predict batch molecules.txt -o runs/batch       # batch from a text file
+```
+
+Python:
+
+```python
+from edkg_dl import Predictor
+
+predictor = Predictor.from_assets("./models")
+result = predictor.predict("CCO")
+```
+
+## Documentation
+
+| Topic | Link |
+| --- | --- |
+| Installation | [docs/en/installation.md](docs/en/installation.md) |
+| Model assets | [docs/en/assets.md](docs/en/assets.md) |
+| CLI usage | [docs/en/cli.md](docs/en/cli.md) |
+| Python API | [docs/en/python-api.md](docs/en/python-api.md) |
+| HTTP API | [docs/en/http-api.md](docs/en/http-api.md) |
+| Output formats | [docs/en/output.md](docs/en/output.md) |
+| Development | [docs/en/development.md](docs/en/development.md) |

edkg_dl-1.0.0/README.md

@@ -0,0 +1,52 @@
+# EDKG-DL
+
+English | [简体中文](README_zh.md)
+
+**D**eep **L**earning framework with causality-integrated **E**ndocrine **D**isruption **K**nowledge **G**raph. Predicts endocrine-disrupting effects (EDC), applicability domain (AD), and sensitive event pathways from compound SMILES using machine learning and an AOP network.
+
+Pipeline: PaDEL 2D descriptors/fingerprints → qualitative/quantitative event-endpoint models → dual-track EDC classification (tabular model + graph neural network, GCN) → sensitive event and AOP pathway inference, producing JSON / Excel reports. Results are for research support only and must not replace experimental or regulatory conclusions.
+
+## Installation
+
+Install from PyPI (Python ≥ 3.10):
+
+```bash
+pip install edkg-dl
+# or
+uv add edkg-dl
+```
+
+Optional extras: `pip install "edkg-dl[api]"` (HTTP service) and `pip install "edkg-dl[plots]"` (applicability-domain plots). See [installation docs](docs/en/installation.md) for details, including the automatic Temurin JRE download for PaDEL.
+
+Model assets (~930 MB) are fetched automatically from [Hugging Face](https://huggingface.co/HaoyueTan/edkg-dl-models) on first use — no manual setup required.
+
+## Quick start
+
+CLI:
+
+```bash
+edkg-dl-predict "CCO"                                   # JSON to stdout
+edkg-dl-predict "CCO" -o runs/example --ad-plots        # reports + PCA plots
+edkg-dl-predict batch molecules.txt -o runs/batch       # batch from a text file
+```
+
+Python:
+
+```python
+from edkg_dl import Predictor
+
+predictor = Predictor.from_assets("./models")
+result = predictor.predict("CCO")
+```
+
+## Documentation
+
+| Topic | Link |
+| --- | --- |
+| Installation | [docs/en/installation.md](docs/en/installation.md) |
+| Model assets | [docs/en/assets.md](docs/en/assets.md) |
+| CLI usage | [docs/en/cli.md](docs/en/cli.md) |
+| Python API | [docs/en/python-api.md](docs/en/python-api.md) |
+| HTTP API | [docs/en/http-api.md](docs/en/http-api.md) |
+| Output formats | [docs/en/output.md](docs/en/output.md) |
+| Development | [docs/en/development.md](docs/en/development.md) |

edkg_dl-1.0.0/edkg_dl/__init__.py

@@ -0,0 +1,46 @@
+"""EDC toxicity prediction and AOP pathway inference."""
+
+from .api import BatchPredictionItem, BatchPredictionResult, Predictor
+from .domain import CausalChainPolicy
+from .exceptions import (
+    ArtifactIntegrityError,
+    ArtifactMissingError,
+    ConfigurationError,
+    EdkgDlError,
+    FeatureExtractionError,
+    InvalidSmilesError,
+    OutputExistsError,
+    PredictionError,
+)
+from .schemas import (
+    AOCandidate,
+    AOPRelation,
+    CausalChainResult,
+    EventPrediction,
+    PredictionResult,
+    SensitiveEvent,
+)
+
+
+__all__ = [
+    "AOCandidate",
+    "AOPRelation",
+    "ArtifactIntegrityError",
+    "ArtifactMissingError",
+    "BatchPredictionItem",
+    "BatchPredictionResult",
+    "ConfigurationError",
+    "CausalChainResult",
+    "CausalChainPolicy",
+    "EdkgDlError",
+    "EventPrediction",
+    "FeatureExtractionError",
+    "InvalidSmilesError",
+    "OutputExistsError",
+    "PredictionError",
+    "PredictionResult",
+    "Predictor",
+    "SensitiveEvent",
+]
+
+__version__ = "1.0.0"

edkg_dl-1.0.0/edkg_dl/__main__.py

@@ -0,0 +1,6 @@
+"""Package CLI entry point via ``python -m edkg_dl``."""
+
+from .cli import main
+
+
+raise SystemExit(main())

edkg_dl-1.0.0/edkg_dl/api.py

@@ -0,0 +1,211 @@
+"""Stable public Python API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import ProjectPaths
+from .domain import CausalChainPolicy
+from .exceptions import EdkgDlError
+from .hub import download_assets
+from .pipeline import PredictionPipeline
+from .schemas import PredictionResult
+
+
+@dataclass(frozen=True)
+class BatchPredictionItem:
+    """Success or error outcome for one input in a batch request."""
+
+    index: int
+    smiles: str
+    result: PredictionResult | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize a single batch outcome.
+
+        Returns:
+            JSON-compatible batch outcome mapping.
+        """
+        return {
+            "index": self.index,
+            "smiles": self.smiles,
+            "ok": self.result is not None,
+            "result": None if self.result is None else self.result.to_dict(),
+            "error": None
+            if self.error_code is None
+            else {"code": self.error_code, "message": self.error_message},
+        }
+
+
+@dataclass(frozen=True)
+class BatchPredictionResult:
+    """Batch prediction result that preserves input order and tolerates partial failures."""
+
+    items: tuple[BatchPredictionItem, ...]
+
+    @property
+    def succeeded(self) -> int:
+        """Return the number of successfully predicted inputs."""
+        return sum(item.result is not None for item in self.items)
+
+    @property
+    def failed(self) -> int:
+        """Return the number of failed inputs."""
+        return len(self.items) - self.succeeded
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the complete batch result.
+
+        Returns:
+            JSON-compatible mapping with counts and per-item outcomes.
+        """
+        return {
+            "total": len(self.items),
+            "succeeded": self.succeeded,
+            "failed": self.failed,
+            "items": [item.to_dict() for item in self.items],
+        }
+
+
+@dataclass
+class Predictor:
+    """Reusable prediction facade that caches loaded endpoint models."""
+
+    pipeline: PredictionPipeline
+
+    @classmethod
+    def from_assets(
+        cls,
+        asset_dir: str | Path | None = None,
+        *,
+        max_paths: int = 1_000,
+        max_path_length: int | None = None,
+        causal_chain_policy: CausalChainPolicy | None = None,
+    ) -> Predictor:
+        """Create a reusable predictor from an external asset directory.
+
+        When the resolved asset directory does not contain ``settings.json``,
+        the assets are downloaded automatically from the Hugging Face Hub
+        into that directory (the per-user cache directory by default).
+
+        Args:
+            asset_dir: Directory containing settings and model artifacts.
+            max_paths: Maximum number of sensitive paths to return.
+            max_path_length: Maximum number of edges allowed per path;
+                unlimited when ``None``.
+            causal_chain_policy: Causal-chain validity evaluation policy.
+
+        Returns:
+            Predictor with a reusable pipeline and cached models.
+
+        Raises:
+            EdkgDlError: Raised when configuration or required assets are invalid,
+                or when a required automatic download fails.
+        """
+        paths = ProjectPaths.resolve(asset_dir)
+        if not paths.settings.is_file():
+            paths = ProjectPaths.resolve(download_assets(paths.asset_root))
+        pipeline = PredictionPipeline.from_paths(
+            paths,
+            max_paths=max_paths,
+            max_path_length=max_path_length,
+            causal_chain_policy=causal_chain_policy,
+        )
+        return cls(pipeline)
+
+    def predict(self, smiles: str) -> PredictionResult:
+        """Predict a single molecule.
+
+        Args:
+            smiles: SMILES string describing a single molecule.
+
+        Returns:
+            Complete structured prediction result.
+        """
+        return self.pipeline.predict(smiles)
+
+    def predict_many(self, smiles_values: Iterable[str]) -> list[PredictionResult]:
+        """Predict multiple molecules while reusing loaded artifacts.
+
+        Args:
+            smiles_values: Iterable of SMILES strings.
+
+        Returns:
+            Prediction results in input order.
+        """
+        return [self.predict(smiles) for smiles in smiles_values]
+
+    def predict_batch(
+        self,
+        smiles_values: Iterable[str],
+        *,
+        max_items: int = 100,
+        max_workers: int = 1,
+    ) -> BatchPredictionResult:
+        """Run a bounded batch prediction with per-item failure isolation.
+
+        Args:
+            smiles_values: Iterable of SMILES strings.
+            max_items: Maximum number of inputs allowed in one batch.
+            max_workers: Number of in-process concurrent worker threads.
+
+        Returns:
+            Per-item success or failure outcomes in input order.
+
+        Raises:
+            ValueError: Raised when batch or concurrency bounds are invalid.
+        """
+        values = list(smiles_values)
+        if max_items < 1:
+            raise ValueError("max_items must be at least 1")
+        if len(values) > max_items:
+            raise ValueError(f"batch size exceeds limit of {max_items}")
+        if max_workers < 1:
+            raise ValueError("max_workers must be at least 1")
+
+        if max_workers == 1:
+            items = tuple(
+                self._predict_batch_item(index, smiles) for index, smiles in enumerate(values)
+            )
+        else:
+            with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                items = tuple(
+                    executor.map(
+                        lambda indexed: self._predict_batch_item(*indexed),
+                        enumerate(values),
+                    )
+                )
+        return BatchPredictionResult(items)
+
+    def _predict_batch_item(self, index: int, smiles: str) -> BatchPredictionItem:
+        """Catch prediction exceptions for one input and convert to a batch outcome.
+
+        Args:
+            index: Zero-based index of the input within the batch.
+            smiles: SMILES to predict.
+
+        Returns:
+            Single success outcome or structured error.
+        """
+        try:
+            return BatchPredictionItem(index=index, smiles=smiles, result=self.predict(smiles))
+        except EdkgDlError as exc:
+            return BatchPredictionItem(
+                index=index,
+                smiles=smiles,
+                error_code=exc.__class__.__name__,
+                error_message=str(exc),
+            )
+        except Exception:  # noqa: BLE001 - batch isolation is an API guarantee.
+            return BatchPredictionItem(
+                index=index,
+                smiles=smiles,
+                error_code="InternalPredictionError",
+                error_message="unexpected prediction failure",
+            )