flockbio-bioscoring 0.4.0

Flock Bio shared scoring + calibration infrastructure for transcript-design sub-pipelines.

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

pip install flockbio_bioscoring  # once published

For development:

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).