neorx 0.2.0__tar.gz

neorx-0.2.0/.gitignore

@@ -0,0 +1,76 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment files (not .env.example)
+.env
+.env.local
+.env.production
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Generated outputs
+reports/
+results/
+
+# Molecular data caches
+modules/dockbot/cache/
+*.pdb
+*.pdbqt
+*.sdf
+*.mol2
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Model weights (too large for git)
+*.pt
+*.pth
+*.h5
+*.pkl
+*.ckpt
+
+# Shipped model asset — must be committed and packaged (see pyproject artifacts)
+!src/neorx/genmol/assets/*.pt
+
+# ChEMBL SQLite database (28 GB — too large for git)
+chembl_*.db
+
+# Local backups and trained-model checkpoints -- large and machine-specific,
+# never meant to be committed (a `git add -A` would otherwise pull in tens
+# of MB of these).
+.backup-scripts/
+checkpoints/
+
+# Experiment run records are deliverables, not scratch -- they are the
+# evidence behind every reported number, IF they are cited. See
+# docs/run-manifest.toml. Default to NOT tracking a run directory (so a
+# routine `git add -A` cannot sweep in an ad-hoc or smoke run); a record
+# that actually backs a claim is added deliberately with
+# `git add -f runs/<run-id>`.
+!runs/
+runs/*
+!runs/.gitkeep

neorx-0.2.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to NeoRx will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-02
+
+### Changed
+- **Breaking:** `modules.*` imports become `neorx.*`; `modules.neorx` becomes
+  `neorx.core`. The `modules/` compatibility shim was removed outright rather
+  than deprecated -- there is no shim in 0.2.x, and old `modules.*` imports
+  simply no longer exist. (The plan that shipped with this release assumed a
+  shim deprecated through 0.2.x and removed in 0.3.0; that step was dropped
+  during implementation.)
+- Package moves to a `src/` layout, so tests exercise the installed artifact.
+- Python floor lowered from 3.13 to 3.12; dependency floors correspondingly
+  reassessed (see Fixed).
+- `pandas` is replaced with `polars` throughout (was not part of the original
+  plan for this release; `benchmark.py`'s reporting is the only affected
+  call site).
+- Five console scripts unified under `neorx <module> <command>`. The old
+  script names remain as deprecated aliases through 0.2.x.
+
+### Added
+- All six modules exposed through the public API. `molscreen` previously
+  exported nothing.
+- Trained GenMol weights ship as package data; `load_pretrained()` raises
+  `GenMolAssetError` rather than returning an untrained model.
+- **CausalBioRL integration** — RL agent now drives the full drug
+  discovery pipeline through `DrugDiscoveryEnv` (Gymnasium).
+- **`run_rl_pipeline()`** — RL-driven alternative to the linear
+  `run_pipeline()`. Agent iteratively selects targets and generates
+  molecules via latent-space navigation.
+- **R-GCN graph encoder** — `DiseaseGraphEncoder` maps disease knowledge
+  graphs to fixed 128-D embeddings using relational graph convolution.
+- **Surrogate docking model** — `SurrogateDockingModel` (MLP) provides
+  ~1ms binding affinity predictions, trained on DockBot observations.
+- **Adaptive reward learner** — `AdaptiveRewardLearner` with 6 per-objective
+  critics and difficulty-adaptive weighting (hindsight shaping).
+- **Hierarchical planner** — `HierarchicalPlanner` with UCB1 target
+  selection (Level 1) and CEM molecule generation (Level 2).
+- **Typed edges in SCM** — Edges tagged with provenance (`api` vs
+  `learned`), `augment_graph()` for merging discovered edges,
+  `from_disease_graph()` classmethod.
+- **CounterfactualValidator bridge** — `validate_with_biorl_scm()` method
+  delegates to the shared SCM when CausalBioRL is available.
+- **DrugDiscovery-v0** environment registered in Gymnasium.
+- **GitHub Actions CI** — lint (Ruff), test (pytest on Ubuntu + macOS),
+  type check (mypy), coverage upload (Codecov).
+- **CONTRIBUTING.md** — contributor guide with style, testing, and PR
+  conventions.
+- **CODE_OF_CONDUCT.md** — Contributor Covenant v2.1.
+- **SECURITY.md** — vulnerability reporting policy.
+- **Ruff configuration** — formatter + linter in `pyproject.toml`.
+- **pytest-cov integration** — coverage config with source filtering.
+- **Expanded .gitignore** — reports/, results/, *.pdb, *.pdbqt, model
+  weights, IDE files, OS files.
+
+### Fixed
+- `DrugDiscovery-v0` now generates through the trained VAE. It previously
+  built an unvocabularised tokenizer and a randomly initialised model, called
+  a `decode_from_latent` method that does not exist, swallowed the resulting
+  `AttributeError`, and returned one of twelve hardcoded scaffolds.
+- `DrugDiscoveryEnv` now rejects a `latent_dim` that does not match the
+  shipped VAE's, instead of silently constructing a mismatched network (not
+  part of the original plan; found while wiring the previous fix).
+- Four dependency floors (`numpy`, `rdkit`, `pyyaml`, `psycopg2-binary`) had
+  been raised past their true minimum on the reasoning that no cp313 wheel
+  existed for the lower version on macOS arm64 -- but a floor is a lower
+  bound, not a pin, so a wheel gap on a newer interpreter never justifies
+  raising it. Re-derived from declared dependency constraints and actual
+  binary/API compatibility, verified on Python 3.12.
+- **SCM self-loop bug** — autoregressive dependencies (`s0→s0`) were
+  being stripped, preventing linear mechanisms from seeing state input.
+- **Matplotlib `tostring_rgb` deprecation** — all 3 toy env renderers
+  now use `buffer_rgba()` (works on macOS and headless Linux).
+- **Pydantic v2 deprecation** — `class Config` replaced with
+  `model_config = ConfigDict(...)` in `EpisodeResult` and
+  `BenchmarkResult`.
+- **Docstring escape sequence** — invalid `\s` in planner docstring.
+- **SCM test flakiness** — increased learning rate for reliable
+  convergence in unit tests.
+
+## [0.1.0] — 2026-03-29
+
+### Added
+
+- **Causal inference engine** — multi-source evidence triangulation via
+  path strength × d-separation quality × centrality × source corroboration.
+- **Backdoor criterion** — proper d-separation analysis using
+  `networkx.d_separated()` for identifiability testing.
+- **Bootstrap confidence intervals** — 95% CIs on causal confidence
+  (200 resamples).
+- **Leave-one-source-out sensitivity analysis** — robustness validation
+  by systematically removing each data source.
+- **7 biomedical data source clients** — DisGeNET, Open Targets (GraphQL),
+  KEGG, Reactome, STRING, UniProt, RCSB PDB — all with curated mock
+  fallbacks for offline use.
+- **Parallel API queries** — `ThreadPoolExecutor` for concurrent database
+  queries (~2× speedup on graph building).
+- **File/Redis caching layer** — 24h TTL for API responses, 7d for graphs.
+  Configurable via `NEORX_CACHE_BACKEND` env var.
+- **Multi-rule ADMET predictor** — 8 rule systems: Lipinski RO5, Veber,
+  Ghose, Egan egg, PAINS (RDKit FilterCatalog), BBB permeability, hERG
+  liability, reactive group alerts.  Weighted composite score.
+- **Graph persistence & export** — JSON, GraphML, GEXF, Cytoscape formats.
+  PostgreSQL persistence for Docker deployments.
+- **Disease ontology resolution** — `resolve_disease_id()` maps free-text
+  disease names to EFO/MONDO identifiers via Open Targets search.
+- **Configurable scorer weights** — override via Python parameter, env var
+  (`NEORX_WEIGHTS`), or defaults.  Auto-normalised to sum=1.0.
+- **SMILES canonicalization** — duplicate elimination via RDKit canonical
+  SMILES before screening.
+- **Interactive HTML reports** — vis.js causal knowledge graph, 95% CI
+  column, UTC timestamps, updated methodology section.
+- **Non-blocking FastAPI endpoints** — `asyncio.to_thread()` on all
+  CPU/IO-bound handlers.
+- **Rich CLI** — progress bar, `--seed` for reproducibility, `--export`
+  for graph formats, `--log-file`, `--no-cache`.
+- **Docker Compose infrastructure** — Redis 7 (AOF + LRU), PostgreSQL 16
+  (5-table schema with indexes), API container with healthchecks.
+- **PEP 561 `py.typed` marker** — full static typing support.
+- **Clean public API** — `from neorx import run_pipeline` works
+  after `pip install neorx`.
+- **108 tests** covering data sources, graph builder, identifier, pipeline,
+  scorer, cache, persistence, ADMET, configurable weights, SMILES
+  canonicalization, confidence intervals, and disease ID resolution.
+
+[Unreleased]: https://github.com/NeoForge/NeoRx/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/NeoForge/NeoRx/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/NeoForge/NeoRx/releases/tag/v0.1.0

neorx-0.2.0/LICENSE

@@ -0,0 +1,31 @@
+NeoRx Source Available License
+
+Copyright (c) 2026 Kelyn Paul Njeri, NeoForge Labs
+
+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, modify, and distribute the Software for NON-COMMERCIAL PURPOSES ONLY,
+subject to the following conditions:
+
+1. NON-COMMERCIAL USE PERMITTED. You may use, copy, modify, merge, and
+   distribute the Software and derivative works thereof for personal,
+   academic, educational, and research purposes at no charge.
+
+2. COMMERCIAL USE PROHIBITED WITHOUT LICENCE. You may NOT use the Software,
+   or any derivative works thereof, for commercial purposes — including but
+   not limited to: selling the Software or services built on it, incorporating
+   it into commercial products, or using it to generate revenue — without
+   obtaining a separate commercial licence from the copyright holder.
+
+   To obtain a commercial licence, contact: kelyn@neoforgelabs.tech
+
+3. ATTRIBUTION. The above copyright notice and this permission notice shall
+   be included in all copies or substantial portions of the Software.
+
+4. NO WARRANTY. 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.