flockbio-bioscoring 0.4.0__tar.gz

flockbio_bioscoring-0.4.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Flock Bio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.
+
+NOTE: The MIT license applies to the LIBRARY CODE in this repository. License
+terms for downloaded / bundled DATASETS are tracked separately in
+`LICENSES.md` per the L20 4-layer audit pattern (article + supplementary +
+deposit + cross-walk). Datasets that fail the audit are HARD BLOCKED via the
+SENTINEL_LICENSE_BLOCKED marker in their DatasetSpec entries.

flockbio_bioscoring-0.4.0/LICENSES.md

@@ -0,0 +1,107 @@
+# LICENSES
+
+This file tracks licenses for **datasets** that the
+`flockbio_bioscoring` library will eventually download or
+bundle. The library code itself is MIT-licensed (see
+`LICENSE`).
+
+## License audit framework (per L20 + Part IX.7)
+
+Every dataset registered as a :class:`DatasetSpec` carries a
+`license` field + a `license_audit_note` that documents the
+**4-layer license audit**:
+
+1. **Article layer**: the journal article's license (CC BY,
+   CC BY-NC, CC BY-NC-ND, etc.). HARD BLOCKED if NC or ND
+   per L5.
+2. **Supplementary layer**: the supplementary file's license.
+   May differ from the article (some publishers grant CC BY
+   to the article but retain commercial rights for
+   supplementary data).
+3. **Deposit layer**: the data deposit's license (figshare,
+   Zenodo, GEO, ArrayExpress, etc.). May further restrict.
+4. **Cross-walk layer**: the per-row license check for
+   datasets that include multi-source data (e.g., an MPRA
+   library that lists sequences from licensed source X and
+   sequences from licensed source Y — each row inherits its
+   source's license).
+
+Only datasets that pass ALL FOUR layers are added to a
+DatasetSpec with a real (non-`SENTINEL_LICENSE_BLOCKED`)
+`expected_sha256`.
+
+## Sentinel marker for blocked datasets
+
+Datasets that fail any layer of the audit are recorded as
+`DatasetSpec` entries with
+`expected_sha256=SENTINEL_LICENSE_BLOCKED` + `parser=None`.
+This documents the audit decision in the same registry as the
+allowed datasets (forensic traceability) without any risk of
+accidentally downloading the blocked data.
+
+Example (from the codon repo's known-blocked list):
+
+```python
+DatasetSpec(
+    name="mauger2019_human_5utr_mpra",
+    url="https://www.pnas.org/doi/10.1073/pnas.1909563116",
+    expected_sha256=SENTINEL_LICENSE_BLOCKED,
+    license="CC BY-NC 4.0",
+    license_audit_note=(
+        "PNAS 116:24075. Article published with CC BY-NC. "
+        "HARD BLOCKED per L5; not downloaded, not parsed. "
+        "Useful as a how-we-would-love-to-use-this footnote."
+    ),
+    parser=None,
+)
+```
+
+## Per-dataset audit log
+
+When the Tier 1 extraction lands real datasets at Sprint 4
+Day 3, this section will be populated with one entry per
+DatasetSpec.
+
+The Sprint 4 Day 1 scaffold (this commit) does NOT include
+any real dataset entries — those migrate over from
+codon / 5utr / 3utr's existing audit ledgers in subsequent
+commits.
+
+## Known HARD BLOCKED datasets (inherited from consumers)
+
+These are blocked for ALL consumers + the orchestrator. Per
+L5 + L20, NC or ND-licensed datasets are HARD BLOCKED:
+
+- **Mauger 2019 (PNAS 116:24075)**: CC BY-NC. 5'UTR MPRA.
+- **Tani 2012 (Genome Res 22:947)**: CC BY-NC. mRNA half-life.
+- **Schwanhäusser 2011 (Nature 473:337)**: CC BY-NC. mRNA
+  half-life + protein abundance.
+- **Ginkgo 180k 3'UTR MPRA**: corresponding author no
+  longer at Ginkgo (2026-05-02 inquiry); license unknown.
+  Treated as blocked until license confirmed.
+- **TargetScan pre-computed scores**: license uncertain
+  (CC BY-NC suspected but not confirmed); treated as blocked
+  until L20 audit completes. We CAN recompute seed-match
+  counts from miRBase (CC BY 4.0).
+
+## Reference for new dataset additions
+
+When adding a DatasetSpec, follow this checklist:
+
+- [ ] Found article + checked CC license tier (Article layer).
+- [ ] Found supplementary file + checked its license
+      (Supplementary layer).
+- [ ] Located the data deposit (figshare / Zenodo / GEO /
+      ArrayExpress) + checked its license (Deposit layer).
+- [ ] Checked any cross-walk references for per-row
+      license inheritance (Cross-walk layer).
+- [ ] Recorded the audit decision in this file with a
+      direct link to the article + the deposit.
+- [ ] If approved, computed the SHA-256 (or marked with the
+      appropriate sentinel).
+- [ ] If blocked, added DatasetSpec with
+      `SENTINEL_LICENSE_BLOCKED` + `parser=None`.
+
+The `phase_d_calibration_matrix.yml` GHA workflow runs the
+download + the SHA verification fresh on every dispatch, so
+audit decisions are revisited rather than cached.

flockbio_bioscoring-0.4.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: flockbio_bioscoring
+Version: 0.4.0
+Summary: Flock Bio shared scoring + calibration infrastructure for transcript-design sub-pipelines.
+Author: Flock Bio
+License: MIT License
+        
+        Copyright (c) 2026 Flock Bio
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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.
+        
+        NOTE: The MIT license applies to the LIBRARY CODE in this repository. License
+        terms for downloaded / bundled DATASETS are tracked separately in
+        `LICENSES.md` per the L20 4-layer audit pattern (article + supplementary +
+        deposit + cross-walk). Datasets that fail the audit are HARD BLOCKED via the
+        SENTINEL_LICENSE_BLOCKED marker in their DatasetSpec entries.
+        
+Project-URL: Repository, https://github.com/flock-bio/bioscoring-shared-FB
+Project-URL: Documentation, https://github.com/flock-bio/bioscoring-shared-FB/blob/main/docs/INTEGRATION_GUIDE.md
+Project-URL: Changelog, https://github.com/flock-bio/bioscoring-shared-FB/blob/main/CHANGELOG.md
+Keywords: bioinformatics,mRNA,calibration,MPRA,Flock Bio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSES.md
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: scipy<2,>=1.10
+Provides-Extra: calibration
+Requires-Dist: pandas<3,>=2.0; extra == "calibration"
+Requires-Dist: openpyxl>=3.1; extra == "calibration"
+Provides-Extra: reporting
+Requires-Dist: Jinja2<4,>=3.1; extra == "reporting"
+Requires-Dist: matplotlib<4,>=3.7; extra == "reporting"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: all
+Requires-Dist: flockbio_bioscoring[calibration,dev,reporting]; extra == "all"
+Dynamic: license-file
+
+# bioscoring-shared-FB
+
+**Flock Bio shared scoring + calibration infrastructure
+library** (`flockbio_bioscoring`). The 5th repo in the Flock
+Bio transcript-design suite.
+
+This library packages the common machinery used by the four
+sub-pipelines + the orchestrator:
+
+- DatasetSpec dataclass + sentinel framework for offline
+  calibration runs
+- License-aware download helpers with retries + EBI tier-0
+  probe
+- Generic FASTA / CSV / GTF parsers
+- Bootstrap LODO + null-model + ship gate framework
+- NNLS calibration helpers
+- HTML / PDF report scaffolding (Jinja2 + matplotlib +
+  Chromium)
+
+Per the **Rule of Three** (L21 in `docs/CROSS_PIPELINE_LESSONS.md`;
+canonical here since 2026-05-12, moved from codon's `docs/`),
+this library is extracted from the **already-shipping** codon
++ 5'UTR + 3'UTR pipelines after they paid for the
+infrastructure once each.
+
+## Status
+
+✅ **v0.4.0 shipped** (Sprint 4 Day 8). All three extraction
+tiers are complete; the library is feature-complete for the
+Sprint 4 scope. Next milestone is **v1.0.0** after the four
+consumer pipelines migrate from their inline copies to the
+shared lib (see `docs/CONSUMER_MIGRATION_PLAN.md` +
+`docs/CONSUMER_MIGRATION_STATUS.md`).
+
+| Tier | Sprint 4 days | Modules | Status |
+|---|---|---|---|
+| 1 | Days 1-3 | DatasetSpec + sentinels + download + parsers + cache + EuropePMC tier-0 | ✅ shipped (v0.1.0) |
+| 2 | Days 4-5 | NNLS + ship gate + upload-success-gate + merge_artifacts + artifact_schema | ✅ shipped (v0.2.0) |
+| 3 | Days 6-7 | HTML / PDF report scaffolding (style + figures + chromium_pdf + templates_loader) | ✅ shipped (v0.3.0) |
+
+## Strategic position
+
+| Repo | Role | Status |
+|---|---|---|
+| `flock-bio/codon_optimization-FB` | Codon optimization | ✅ shipping (v2.8.0) |
+| `flock-bio/5utr_optimization-FB` | 5'UTR design | ✅ shipping (v2.8.24) |
+| `flock-bio/3utr_optimization-FB` | 3'UTR design | ✅ shipping (v0.2.0) |
+| `flock-bio/promoter_design-FB` | Tissue-specific promoter design | 📋 Sprint 8-12 |
+| `flock-bio/bioscoring-shared-FB` (THIS REPO) | Shared library | ✅ v0.4.0 shipped (consumer-harmonized); 4-consumer migration in flight → v1.0.0 |
+| `flock-bio/transcript_design-FB` | Orchestrator | 🟡 Sprint 13-16 (currently v0.4.1) |
+
+## Installation
+
+```bash
+pip install flockbio_bioscoring  # once published
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+PYTHONPATH=src python3 -m pytest tests/ -q
+```
+
+## Documentation
+
+- `CLAUDE.md` — Claude Code guidance for this repo.
+- `CHANGELOG.md` — chronological history of behavior changes.
+- `docs/INTEGRATION_GUIDE.md` — API surface reference + recipes
+  for consuming pipelines to migrate from inline copies to the
+  shared library.
+- `docs/CONSUMER_MIGRATION_PLAN.md` — master migration plan
+  for the 4-consumer migration (binding order, per-consumer
+  effort, Step 0-9 recipe).
+- `docs/CONSUMER_MIGRATION_STATUS.md` — live status tracker
+  for the 4-consumer migration.
+- `docs/CALIBRATION_RUNBOOK_TEMPLATE.md` — template for
+  consumer-side `CALIBRATION_RUNBOOK.md` (Phase D / OFFLINE
+  calibration operator doc; consumers extend with pipeline
+  specifics).
+- `docs/CROSS_PIPELINE_LESSONS.md` — canonical strategic doc
+  for the 6-repo suite (Strategic North Star + Part I L1-L21
+  lessons + Part X per-pipeline kickoff guides + Part XI
+  binding I/O contracts). Moved here from codon's `docs/`
+  on 2026-05-12 per L21.
+- `docs/CYPHERBIO_PIPELINE_PLAYBOOK.md` +
+  `docs/CYPHERBIO_PLAYBOOK_v2.md` — canonical CypherBio
+  packaging conventions (moved here from per-consumer copies
+  on 2026-05-12 per L21).
+
+## License
+
+The library code is licensed under the MIT license (see
+`LICENSE`). License terms for bundled / downloaded datasets
+are tracked separately in `LICENSES.md` per the L20 4-layer
+audit pattern (article + supplementary + deposit + cross-walk).

flockbio_bioscoring-0.4.0/README.md

@@ -0,0 +1,96 @@
+# bioscoring-shared-FB
+
+**Flock Bio shared scoring + calibration infrastructure
+library** (`flockbio_bioscoring`). The 5th repo in the Flock
+Bio transcript-design suite.
+
+This library packages the common machinery used by the four
+sub-pipelines + the orchestrator:
+
+- DatasetSpec dataclass + sentinel framework for offline
+  calibration runs
+- License-aware download helpers with retries + EBI tier-0
+  probe
+- Generic FASTA / CSV / GTF parsers
+- Bootstrap LODO + null-model + ship gate framework
+- NNLS calibration helpers
+- HTML / PDF report scaffolding (Jinja2 + matplotlib +
+  Chromium)
+
+Per the **Rule of Three** (L21 in `docs/CROSS_PIPELINE_LESSONS.md`;
+canonical here since 2026-05-12, moved from codon's `docs/`),
+this library is extracted from the **already-shipping** codon
++ 5'UTR + 3'UTR pipelines after they paid for the
+infrastructure once each.
+
+## Status
+
+✅ **v0.4.0 shipped** (Sprint 4 Day 8). All three extraction
+tiers are complete; the library is feature-complete for the
+Sprint 4 scope. Next milestone is **v1.0.0** after the four
+consumer pipelines migrate from their inline copies to the
+shared lib (see `docs/CONSUMER_MIGRATION_PLAN.md` +
+`docs/CONSUMER_MIGRATION_STATUS.md`).
+
+| Tier | Sprint 4 days | Modules | Status |
+|---|---|---|---|
+| 1 | Days 1-3 | DatasetSpec + sentinels + download + parsers + cache + EuropePMC tier-0 | ✅ shipped (v0.1.0) |
+| 2 | Days 4-5 | NNLS + ship gate + upload-success-gate + merge_artifacts + artifact_schema | ✅ shipped (v0.2.0) |
+| 3 | Days 6-7 | HTML / PDF report scaffolding (style + figures + chromium_pdf + templates_loader) | ✅ shipped (v0.3.0) |
+
+## Strategic position
+
+| Repo | Role | Status |
+|---|---|---|
+| `flock-bio/codon_optimization-FB` | Codon optimization | ✅ shipping (v2.8.0) |
+| `flock-bio/5utr_optimization-FB` | 5'UTR design | ✅ shipping (v2.8.24) |
+| `flock-bio/3utr_optimization-FB` | 3'UTR design | ✅ shipping (v0.2.0) |
+| `flock-bio/promoter_design-FB` | Tissue-specific promoter design | 📋 Sprint 8-12 |
+| `flock-bio/bioscoring-shared-FB` (THIS REPO) | Shared library | ✅ v0.4.0 shipped (consumer-harmonized); 4-consumer migration in flight → v1.0.0 |
+| `flock-bio/transcript_design-FB` | Orchestrator | 🟡 Sprint 13-16 (currently v0.4.1) |
+
+## Installation
+
+```bash
+pip install flockbio_bioscoring  # once published
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+PYTHONPATH=src python3 -m pytest tests/ -q
+```
+
+## Documentation
+
+- `CLAUDE.md` — Claude Code guidance for this repo.
+- `CHANGELOG.md` — chronological history of behavior changes.
+- `docs/INTEGRATION_GUIDE.md` — API surface reference + recipes
+  for consuming pipelines to migrate from inline copies to the
+  shared library.
+- `docs/CONSUMER_MIGRATION_PLAN.md` — master migration plan
+  for the 4-consumer migration (binding order, per-consumer
+  effort, Step 0-9 recipe).
+- `docs/CONSUMER_MIGRATION_STATUS.md` — live status tracker
+  for the 4-consumer migration.
+- `docs/CALIBRATION_RUNBOOK_TEMPLATE.md` — template for
+  consumer-side `CALIBRATION_RUNBOOK.md` (Phase D / OFFLINE
+  calibration operator doc; consumers extend with pipeline
+  specifics).
+- `docs/CROSS_PIPELINE_LESSONS.md` — canonical strategic doc
+  for the 6-repo suite (Strategic North Star + Part I L1-L21
+  lessons + Part X per-pipeline kickoff guides + Part XI
+  binding I/O contracts). Moved here from codon's `docs/`
+  on 2026-05-12 per L21.
+- `docs/CYPHERBIO_PIPELINE_PLAYBOOK.md` +
+  `docs/CYPHERBIO_PLAYBOOK_v2.md` — canonical CypherBio
+  packaging conventions (moved here from per-consumer copies
+  on 2026-05-12 per L21).
+
+## License
+
+The library code is licensed under the MIT license (see
+`LICENSE`). License terms for bundled / downloaded datasets
+are tracked separately in `LICENSES.md` per the L20 4-layer
+audit pattern (article + supplementary + deposit + cross-walk).

flockbio_bioscoring-0.4.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flockbio_bioscoring"
+version = "0.4.0"
+description = "Flock Bio shared scoring + calibration infrastructure for transcript-design sub-pipelines."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Flock Bio" },
+]
+keywords = [
+    "bioinformatics",
+    "mRNA",
+    "calibration",
+    "MPRA",
+    "Flock Bio",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    # Core scientific stack. Pinned conservatively — the shared
+    # lib must remain compatible with each consumer's existing
+    # version. Loosen only after coordinating across all 3
+    # consumers.
+    # numpy + scipy are required by Tier 2 calibration
+    # (`fit_nnls_with_prior`, `bootstrap_lodo`,
+    # `null_model_baseline`) per Sprint 4 Day 5 implementation.
+    "numpy>=1.24,<3",
+    "scipy>=1.10,<2",
+]
+
+[project.optional-dependencies]
+calibration = [
+    # Optional calibration extras. Required for the consumer-
+    # side Phase D scripts (DataFrame manipulation, xlsx
+    # parsing) but NOT for the shared lib's calibration core
+    # (NNLS / bootstrap / null model are numpy-only via the
+    # core scipy dep).
+    "pandas>=2.0,<3",
+    "openpyxl>=3.1",
+]
+reporting = [
+    # Tier 3 reporting framework deps (extracted at Sprint 4
+    # Day 6-7).
+    "Jinja2>=3.1,<4",
+    "matplotlib>=3.7,<4",
+]
+dev = [
+    "pytest>=8.0,<9",
+    "pytest-cov>=4.1",
+    "ruff>=0.4",
+    "mypy>=1.8",
+]
+all = [
+    "flockbio_bioscoring[calibration,reporting,dev]",
+]
+
+[project.urls]
+Repository = "https://github.com/flock-bio/bioscoring-shared-FB"
+Documentation = "https://github.com/flock-bio/bioscoring-shared-FB/blob/main/docs/INTEGRATION_GUIDE.md"
+Changelog = "https://github.com/flock-bio/bioscoring-shared-FB/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["flockbio_bioscoring*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+flockbio_bioscoring = [
+    "py.typed",
+    # Tier 3 reporting framework: ship the Jinja2 base template
+    # so consumers can extend it via FileSystemLoader on the
+    # shared lib's installed templates dir.
+    "reporting/templates/*.html.j2",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+addopts = "-q --tb=short"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+files = ["src"]

flockbio_bioscoring-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flockbio_bioscoring-0.4.0/src/flockbio_bioscoring/__init__.py

@@ -0,0 +1,103 @@
+"""Flock Bio shared scoring + calibration infrastructure library
+(`flockbio_bioscoring`).
+
+The 5th repo in the Flock Bio transcript-design suite. This
+library packages the common machinery used by the four
+sub-pipelines (codon + 5'UTR + 3'UTR + promoter) + the
+orchestrator (`transcript_design-FB`):
+
+- DatasetSpec dataclass + sentinel framework for offline
+  calibration runs (Tier 1).
+- License-aware download helpers with retries + EBI tier-0
+  probe (Tier 1).
+- Generic FASTA / CSV / GTF parsers (Tier 1).
+- Bootstrap LODO + null-model + ship gate framework (Tier 2,
+  Sprint 4 Day 4-5).
+- NNLS calibration helpers (Tier 2).
+- HTML / PDF report scaffolding (Tier 3, Sprint 4 Day 6-7).
+
+Per the **Rule of Three** (L21), the library is extracted from
+the already-shipping codon + 5'UTR + 3'UTR pipelines after
+they each paid for the infrastructure once. The codon
+pipeline's v1.0.1 byte-identical baseline is the hardest
+invariant to preserve during migration.
+
+Versioning per Part X.5.6:
+
+- **Patch (0.x.Y)**: bug fixes, no API changes.
+- **Minor (0.X.0)**: new APIs added, no removals.
+- **Major (X.0.0)**: breaking changes; coordinated release
+  across all consumers; orchestrator bumps in lockstep.
+
+Authoritative integration sources:
+
+- `docs/INTEGRATION_GUIDE.md` — consumer-side migration recipes.
+- `docs/CROSS_PIPELINE_LESSONS.md` — strategic doc for the
+  6-repo suite (canonical here since 2026-05-12, moved from
+  codon's `docs/` per L21).
+- Each consumer's `CLAUDE.md` for repo-specific conventions.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+
+# The shared lib's public schema version. Independent of
+# __version__: bumped only when the public API contracts
+# (DatasetSpec field names, sentinel string values, parser
+# return shapes) change in breaking ways. Per Part XI.8
+# patch bumps for backwards-compatible additions; MAJOR bumps
+# for breaking changes.
+__schema_version__ = "1.0"
+
+# Public re-exports — keep in sync with the per-module
+# __all__ declarations + the INTEGRATION_GUIDE.md API surface.
+from flockbio_bioscoring.cache import (
+    cache_size,
+    clear_cache_for_testing,
+    get_or_parse,
+)
+from flockbio_bioscoring.dataset_spec import (
+    DatasetSpec,
+    DatasetSpecValidationError,
+    DownloadStatus,
+    SentinelStatus,
+)
+from flockbio_bioscoring.europepmc import (
+    EuropePmcMirror,
+    get_mirror,
+    n_registered_mirrors,
+    probe_head,
+    register_mirror,
+)
+from flockbio_bioscoring.sentinels import (
+    SENTINEL_DEFERRED_BOT_DETECTION,
+    SENTINEL_GHA_DISPATCH_ONLY,
+    SENTINEL_LICENSE_BLOCKED,
+    SENTINEL_VERIFIED_IN_PARSER,
+    SHA256_SENTINELS,
+    is_sentinel_sha256,
+)
+
+__all__ = [
+    "__version__",
+    "__schema_version__",
+    "DatasetSpec",
+    "DatasetSpecValidationError",
+    "DownloadStatus",
+    "SentinelStatus",
+    "SENTINEL_DEFERRED_BOT_DETECTION",
+    "SENTINEL_GHA_DISPATCH_ONLY",
+    "SENTINEL_LICENSE_BLOCKED",
+    "SENTINEL_VERIFIED_IN_PARSER",
+    "SHA256_SENTINELS",
+    "is_sentinel_sha256",
+    "EuropePmcMirror",
+    "register_mirror",
+    "get_mirror",
+    "n_registered_mirrors",
+    "probe_head",
+    "get_or_parse",
+    "cache_size",
+    "clear_cache_for_testing",
+]