openpkflow 2.3.0__tar.gz → 2.6.0__tar.gz

{openpkflow-2.3.0 → openpkflow-2.6.0}/.gitignore

@@ -22,6 +22,8 @@ ENV/
 .coverage
 htmlcov/
 .tox/
+.hypothesis/
+.ruff_cache/
 
 # Type checking
 .mypy_cache/
@@ -65,10 +67,32 @@ handout/
 !src/**/*.html
 !examples/**/*.html
 !docs/**
+!webapp/index.html
 
 # MkDocs generated site
 site/
+!site/
+site/*
+!site/app/
+!site/app/index.html
 
 # Uploaded images
 *.png
 !docs/**/*.png
+
+# Frontend tooling (never ship in sdist)
+webapp/node_modules/
+webapp/test-results/
+webapp/playwright-report/
+webapp/vite-dev.log
+**/node_modules/
+
+# Cloudflare / Wrangler local state (account metadata)
+.wrangler/
+wrangler.toml.bak
+
+# Local handoff archives / extraction (not package source)
+Untitled-handoff.zip
+untitled-handoff-extracted/
+*-handoff.zip
+*-handoff-extracted/

openpkflow-2.3.0/CLAUDE.md → openpkflow-2.6.0/AGENTS.md

@@ -1,19 +1,32 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
 
 ## Scope and boundary (read this first)
 
 **In scope — build, extend, polish:**
-- `dissolution/` — f1, f2, MSD, model fitting, multi-media (greenfield moat vs competitors)
+- `dissolution/` — f1, f2, MSD, model fitting, multi-media, SUPAC screening, alcohol f2
 - `nca/` — sparse, steady-state, urinary, CDISC PP (greenfield moat)
-- `ivivc/` — Level A (greenfield moat)
-- `sim/` — analytical compartment models
+- `ivivc/` — Level A + Level B/C helpers (MDT/MRT correlation)
+- `sim/` — analytical compartment models, transit oral, SS metrics
+- `pipeline/` — multi-stage study orchestration + unified reports (v2.6.0)
 - `bayes/` — MAP individual PK (scipy, screening tool, not regulatory primary)
-- `be/` — paired TOST convenience layer + BioEqPy export
+- `be/` — paired TOST convenience layer + power/n + BioEqPy export
 - `report/` — HTML, PDF, DOCX, Markdown
 - `validation/` — cross-checks against published references
 
+**Web app layer (same as CLAUDE.md):**
+- `api/` — FastAPI REST adapter. Current routers: nca, dissolution (incl. multi-media),
+  sim, ivivc, be (incl. power / sample-size). Adding a new endpoint requires a schema
+  (schemas/), service (services/), router (routers/), and registration in main.py.
+  Follow the existing nca router pattern exactly.
+- `webapp/` — React + Vite + Tailwind frontend. Current pages: Home, NCA, Dissolution
+  (single + multi-media tab), Sim, IVIVC, BE (analysis + power tab).
+  See `progress_web_app.md` for the full file map and next candidates.
+- Do NOT add pharmacometric logic to api/ or webapp/. Add to src/openpkflow/ first.
+
+**Takeover:** read `HANDOFF.md` first for branch/PR/release state.
+
 **Out of scope — do not extend (existing code is frozen at v2.3.0):**
 - `pop/estimation/` — FOCE-I and SAEM exist but must not be extended. Pharmpy and
   nlmixr2 are validated NLME engines. Bug fixes only. No IOV, no 3-cmt, no covariate
@@ -28,7 +41,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 3. The former covariate API in `pop/estimation/` (`CovariateModel`, `apply_covariates`)
    was a non-functional v2.2.0 skeleton and was removed in v2.3.0. Do not reintroduce
    covariate estimation without a full external validation plan.
-4. When ROADMAP.md and CLAUDE.md disagree, CLAUDE.md wins. Flag the conflict to the user.
+4. When ROADMAP.md and AGENTS.md disagree, AGENTS.md wins. Flag the conflict to the user.
 5. Never use `--no-verify` to bypass pre-commit hooks. Fix the underlying issue instead.
 
 ---
@@ -95,17 +108,19 @@ openpkflow dissolution compare data.csv --reference reference --test test --repo
 ### Module map
 
 ```
-dissolution/   -- f1, f2, bootstrap_f2, model fitting, loader, reporting   <- DONE v0.1-v0.2
-nca/           -- AUC, lambda_z, PK parameters, steady-state, urine, tlast  <- DONE v0.4.0, v1.3.0
-ivivc/         -- Wagner-Nelson, Loo-Riegelman, convolution, Levy, %PE     <- DONE v1.2.0
-sim/           -- analytical compartment models, dosing, superposition      <- DONE v0.5.0
-pop/           — GOF plots (4-panel), VPC (simulation-based), dataset      ← DONE v0.6.0
-bayes/         — ImportError guards; [bayes] extras wired; PyMC deferred   ← v0.8.0 deferred
-ml/            — PKSurrogate (torch MLP, EXPERIMENTAL)                     ← DONE v0.9.0
-report/        — Markdown, HTML, PDF (ReportLab), Word (python-docx)       ← DONE v0.3.0
-datasets/      — example CSVs (dissolution + theoph NCA reference)
-validation/    — reference comparison utilities
-cli.py         — Typer CLI entry point
+dissolution/   -- f1, f2, bootstrap, MSD, models, multi_media, supac       DONE (+ v2.6)
+nca/           -- AUC, lambda_z, SS, urine, sparse, CDISC PP               DONE
+ivivc/         -- Level A WN/LR/convolution/Levy + Level B/C helpers       DONE (+ v2.6)
+sim/           -- 1/2-cmt, dosing, transit oral, SS metrics                DONE (+ v2.6)
+pipeline/      -- StudyPipeline multi-stage orchestration + reports        DONE v2.6.0
+pop/           -- GOF/VPC + estimation/ FROZEN (bug fixes only)            DONE
+bayes/         -- MAP + optional PyMC                                      DONE
+ml/            -- PKSurrogate (torch MLP, EXPERIMENTAL)                    DONE
+report/        -- Markdown, HTML, PDF (ReportLab), Word (python-docx)      DONE
+datasets/      -- example CSVs (dissolution + theoph NCA reference)
+validation/    -- reference comparison utilities
+student/       -- simplified teaching APIs                                 DONE v2.5
+cli.py         -- Typer: dissolution, be, ivivc, pop, study run
 ```
 
 ### NCA module layout
@@ -233,9 +248,15 @@ Each test cites a source: paper DOI, FDA guidance ID, or reference implementatio
 
 ## Current focus
 
-v2.3.0 is current — Pop PK FOCE-I validated against nlme reference, covariate skeleton removed.
-Next focus: conda-forge distribution + PowerTOST cross-validation (nice-to-have).
-See `ROADMAP.md` for the full ladder.
+**v2.6.0** is the current tree version (pipeline, SUPAC/alcohol, IVIVC B/C, transit sim,
+webapp polish, convolution validation). Code lives on PR #27 until merge.
+
+**Immediate next work (in order):**
+1. Merge PR #27 when CI is green; tag/release v2.6.0 (`RELEASE.md`, `HANDOFF.md`).
+2. Webapp: study pipeline page; sparse NCA / MAP adapters; SUPAC UI; deploy.
+3. Keep validation discipline; do not extend frozen `pop/estimation/`.
+
+See `HANDOFF.md` for branch/PR state and `ROADMAP.md` for the full ladder.
 
 **Before any new feature:** run `python -m build && python -m twine check dist/*` to confirm the wheel is clean.
 
@@ -244,29 +265,14 @@ See `ROADMAP.md` for the full ladder.
 ## Release Ladder
 
 ```
-0.1.0  f1, f2, input validation, CSV loader, CLI, Markdown+HTML report stub, tests          DONE
-0.1.1  bootstrap_f2, profile plots in HTML reports, CI, example datasets, py.typed          DONE
-0.1.2  PyPI publish, Trusted Publishing workflow                                         DONE
-0.1.3  README polish, f2_method="regulatory" option, CV% warning in compare()
-0.2.0  dissolution model fitting (Weibull, Korsmeyer-Peppas, Higuchi, first-order,
-       zero-order) — scipy curve_fit, AIC/BIC/R2, fit overlay in HTML report
-0.3.0  full Markdown + HTML + ReportLab PDF report generator
-0.4.0  NCA engine (AUC, Cmax, Tmax, lambda_z, t1/2, CL/F, Vz/F)
-0.5.0  PK simulation (1-comp, 2-comp, oral, IV, infusion, repeated dosing)       DONE
-0.6.0  population PK diagnostics, GOF plots, VPC helpers                         DONE
-0.7.0  Pharmpy bridge                                                             SKIPPED (reserved)
-0.8.0  Bayesian PK (PyMC, CmdStanPy)                                             DEFERRED (extras wired)
-0.9.0  ML surrogate (torch MLP, EXPERIMENTAL)                                    DONE
-1.0.0  stable public release                                                      DONE
-1.1.0  dissolution regulatory toolkit: MSD, model-dependent comparison, RSD check  DONE
-1.2.0  IVIVC Level A: Wagner-Nelson, Loo-Riegelman, convolution predict, %PE      DONE
-1.3.0  NCA expansion: steady-state, urinary excretion, CDISC PP output             DONE
-1.4.0  multi-media dissolution: pH 1.2/4.5/6.8 panel, alcohol dose-dumping         DONE
-1.5.0  Sparse-sampling NCA: model-informed 1-cmt oral from 3-5 data points         DONE
-2.0.0  Bayesian PK: MAP individual estimation + full posterior + Bayesian BE (PyMC) DONE
-2.1.0  FOCE-I & SAEM population PK (1-cmt, diagonal Omega)                         DONE
-2.2.0  2-cmt models, full Omega matrix, covariate skeleton                          DONE
-2.3.0  Remove covariate skeleton, FOCE-I nlme cross-validation, conda-forge prep    DONE
+0.1.0 - 1.0.0  core dissolution, NCA, sim, reports, stable release              DONE
+1.1.0 - 1.5.0  MSD, IVIVC Level A, SS/urine NCA, multi-media, sparse NCA        DONE
+2.0.0          Bayesian MAP + PyMC BE                                           DONE
+2.1.0 - 2.3.0  FOCE-I/SAEM, 2-cmt Omega, freeze pop estimation + nlme val       DONE
+2.4.0          replicate BE screening + release credibility sprint              DONE
+2.5.0          web app (api/ + webapp/) + student helpers                       DONE
+2.6.0          study pipeline, SUPAC/alcohol, IVIVC B/C, transit, web polish    CODE DONE (tag pending)
+0.7.0          Pharmpy bridge                                                   SKIPPED (reserved)
 ```
 
 See `ROADMAP.md` for full milestone detail, scope rationale, and definition of done.

{openpkflow-2.3.0 → openpkflow-2.6.0}/CHANGELOG.md

@@ -9,6 +9,134 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+The v2.6.0 release candidate passes the full standard suite (1275 passed),
+API tests, frontend lint/build/browser tests, strict docs build, mypy, and
+wheel/sdist validation. Tag/PyPI publish remains pending until the hardening
+change is green on `main`.
+
+### Release hardening
+
+- **CI**: added API, frontend lint/build/Playwright, Python 3.13 Linux/Windows
+  smoke, and enforced type-check jobs; recent Codecov uploads were verified.
+- **API**: upload reads are bounded by the configured size limit; standard
+  anti-sniffing, framing, referrer, and browser-permission headers are added.
+- **Population PK**: fixed full-Omega label generation, which reused a string
+  loop variable as an integer and crashed for `omega_type="full"`.
+- **Student APIs**: typed dissolution comparison results and fail-closed PK
+  route validation; unsupported routes no longer fall through as IV bolus.
+- **Typing**: non-frozen modules pass strict mypy. The frozen legacy
+  `pop.estimation` implementation has an explicit module override until it is
+  reactivated with external validation.
+
+### Fixed (correction sprint)
+
+- **BE**: paired-design intra-subject CV now uses variance-halving
+  (`sigma_w^2 = s_d^2 / 2`) before log-normal CV back-transform.
+- **NCA / pipeline**: fail-closed config (unknown keys rejected; explicit
+  AUC/BLQ methods required for NCA stages); `auc_tau` enforces times in
+  `[0, tau]` and rejects unknown methods; string BLQ markers such as
+  `<0.5` no longer become observed concentrations under `blq_method="none"`.
+- **Sim transit**: Savic transit chain + absorption depot; `CL_F`/`Vz_F`
+  naming; MTT is applied for all `n_transit` including 1.
+- **IVIVC**: dissolution minutes converted to hours when requested;
+  incomplete dissolution no longer renormalised to 100%; default `kel=0.1`
+  removed; single-formulation FDA overall-pass disabled (use multi-
+  formulation aggregate for Cmax and AUC separately).
+- **Dissolution**: `compare(f2_method=...)` defaults to `regulatory`;
+  prerequisite warnings persisted on `ComparisonResult`; ICH M13B Step 2
+  absolute SD > 8% at any time point (not RSD only when mean <= 60%).
+- **SUPAC-IR**: function-specific threshold tables (filler, binder,
+  disintegrants, stearates, glidants, film coat).
+- **Packaging**: Hatch sdist allowlist excludes `node_modules`, Wrangler
+  state, Hypothesis caches, Playwright artifacts; `.gitignore` extended.
+- **Webapp**: NCA/IVIVC snapshot request with result; stale forms disable
+  report download until re-run. Extended the same guard to the BE and
+  Dissolution analysis tabs (parameter/limit/alpha/sequence/column-mapping
+  changes now invalidate the on-screen result); Sim page disables report
+  download while a live re-fetch is in flight.
+- **CI/CD**: `publish.yml` now refuses to publish to PyPI unless the pushed
+  tag's commit is reachable from `main`.
+
+---
+
+## [2.6.0] - 2026-07-09
+
+### Notes
+
+- **Not a corrected release.** Feature merge (#27). Correction sprint must
+  land before any scientific claim or tag re-cut for this version line.
+
+
+### Added
+
+- **Study pipeline** (`openpkflow.pipeline`): compose dissolution, NCA, and BE
+  stages into one run with audit metadata, HTML/Markdown multi-section reports,
+  and CLI `openpkflow study run config.json --report out.html`.
+- **SUPAC-IR screening** helpers: `classify_supac_ir_level()` and
+  `alcohol_dose_dumping_assessment()` in `dissolution/supac.py` (screening only;
+  not a substitute for full guidance interpretation).
+- **IVIVC Level B/C**: MDT, MRT, and linear correlation helpers
+  (`mean_dissolution_time`, `mean_residence_time`, `level_b_correlation`,
+  `level_c_correlation`).
+- **Transit-compartment oral absorption**: `c_1cmt_oral_transit()` (Savic-style
+  n/MTT convention) and closed-form `steady_state_metrics_1cmt_oral()`.
+- **Web API / app**: BE power and sample-size endpoints + calculator tab;
+  multi-media dissolution analyze/report + Dissolution page tab; IVIVC load
+  example and dose_diss/dose_iv UI; expanded Playwright smoke tests.
+- **Validation**: analytical IVIVC convolution cross-check
+  (`tests/validation/test_ivivc_convolution_reference.py`); BE power edge
+  cases (boundary GMR ~ alpha, monotonicity in n).
+- **Docs**: positioning page, pipeline tutorial, validation matrix updates,
+  Docker/compose polish, `examples/pipeline_walkthrough.py`.
+
+### Notes
+
+- Pop PK estimation remains frozen (bug fixes only). Formal RSABE remains out
+  of scope (companion BioEqPy). SUPAC and replicate BE are screening tools.
+
+---
+
+## [2.5.0] - 2026-06-12
+
+### Added
+
+- Student-friendly interface (`openpkflow.student`) with three one-call
+  functions: `analyze_pk()` for NCA, `fit_dissolution()` for dissolution
+  model fitting + f1/f2 comparison, and `fit_pk_model()` for 1/2-compartment
+  PK curve fitting.
+- `student/sim.py` compartmental equations delegate to validated
+  `sim/methods.py` functions (c_1cmt_oral, c_1cmt_iv_bolus, c_2cmt_oral) --
+  no duplicate math.
+- Hixson-Crowell model added to dissolution `_REGISTRY` (now 6 default
+  models: zero_order, first_order, higuchi, korsmeyer_peppas, weibull,
+  hixson_crowell).
+- External validation of NCA engine against WinNonlin(r) (Kim et al. 2018,
+  PMC6989226, Table 3): all 8 parameters within 0.02% for Theoph Subject 8
+  (Cmax, Tmax, lambda_z, t1/2, AUClast, AUCinf, CL/F, Vz/F).
+
+### Fixed
+
+- Mandated disclaimer text (CLAUDE.md rule 7) applied to all student module
+  report summaries.
+- `test_all_default_models_fit` updated to expect 6 default models.
+
+---
+
+## [2.4.0] — 2026-05-30
+
+### Added
+
+- Research-grade replicate bioequivalence screening via `replicate_be()`:
+  long-format full/partial replicate data parsing, GMR + conventional 90% CI,
+  CVwR estimation, EMA-style scaled-limit summaries, and FDA-style RSABE point
+  criterion screening. These outputs are explicitly documented as exploratory
+  and not a replacement for jurisdiction-specific validated SAS/R workflows.
+- Replicate BE CLI/report workflow: `openpkflow be replicate`, HTML/Markdown
+  reports, JSON export, example partial-replicate CSV, and scalar reference
+  validation fixtures for the screening calculations.
+- Release-readiness documentation and slow-validation workflow for heavyweight
+  reference checks, plus a read-only `scripts/release_readiness.py` checker.
+
 ---
 
 ## [2.3.0] — 2026-05-24

{openpkflow-2.3.0 → openpkflow-2.6.0}/CITATION.cff

@@ -5,7 +5,7 @@ authors:
     given-names: Priyam
     email: priyamthakar1@gmail.com
 title: "OpenPKFlow: Python-first pharmacometrics and dissolution toolkit"
-version: 0.1.0
-date-released: 2026-05-17
+version: 2.6.0
+date-released: 2026-07-09
 url: "https://github.com/priyamthakar/openpkflow"
 license: MIT