refactor(PR0–PR1): API contract freeze + CI, shared helpers + _keys adoption - #30
Merged
Conversation
Full NumPy-style docstrings (summary, parameters, returns with shapes/units, math definitions, examples) for the core analysis API in tcri.metrics: clonotypic_entropy, phenotypic_entropy, clonality, mutual_information, flux. These flow into the D11 autodoc reference and mirror the D2 concepts page. Docstring-only (no behavior change); docs build clean (0 warnings); math and cross-references render. Part of Notion D1 (public API docstrings). Remaining chunks: preprocessing (register_model, joint_distribution*), model (TCRIModel), then plotting/utils. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Living refactor spec, PR agenda/diary with removal ledger, and hard rules. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…pers PR0: tcri/_contract.pyi (frozen target surface) + test_contract_conformance. PR1 foundation: _keys/_console/_stats/_distance + unit tests (true HDI/ETI, kl/js/l1 dispatch). No behavior change; all additive. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove 12 copied _ok/_info/_warn/_fin defs across metrics/preprocessing/ plotting; relocate stars/auc_and_label_permutation/bootstrap_auc utils->_stats. No behavior change; full suite 34 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Migrate 85 canonical uns/obsm/obs key literals -> K.* in preprocessing/metrics/ plotting/utils; add test_no_canonical_key_literals guard. Legacy keys left for their removal phases. No behavior change; full suite 35 passed / 1 skipped. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…based guard Multi-agent audit caught the K.* migration over-reaching into 10 display/ warning/docstring strings (printed code tokens instead of key names). Restore readable key text in all 10; make the key-literal guard AST-based (checks real subscripts/.get, ignores prose); drop 3 dead utils imports. Suite 35 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First two PRs of the tcri → scverse-package refactor. No behavior change — additive scaffolding + internal dedup. Full suite: 35 passed / 1 skipped.
PR0 — Contract freeze + CI scaffolding
tcri/_contract.pyi— frozen target public surface (27 functions, namespacedtl/pp/pl/diag/ut+TCRIModel; locked decisions baked in:n_samples=250,weighted=False,use_logits,normalize_mode, American spelling, keyword-only).tests/test_contract_conformance.py— live-signature-vs-contract guard (for anything inIMPLEMENTED, empty today), an unimplemented worklist, import-smoke, and an AST-based canonical-key-literal guard.PR1 — Shared helpers +
_keysadoption_keys.py(all uns/obsm/obs key constants),_console.py(single console helpers),_stats.py(true HDI/ETI,prob_direction, + relocatedstars/auc/bootstrap),_distance.py(kl/js/l1+ dispatch).tests/test_helpers.py(8 tests)._console; moved stats out ofutils; migrated 85 canonical key literals →K.*; dropped deadutilsimports.hdioff-by-one before it shipped.Audit
A 3-lens multi-agent audit (doc-vs-code · correctness · plan/contract) ran on this branch and caught a real regression — the key migration over-reached into 10 display/warning/docstring strings (
register_model/load_tcri_sessionprinted"K.X_LOGITS"etc.). Fixed in this branch: readable key text restored in all 10, and the key-literal guard made AST-based (checks real code, ignores prose).Two non-blocking follow-ups deferred (tracked in
docs/contract/REFACTOR_NOTES.md, pre-Phase-6):_contract.pyi↔ api-doc §7–§9 — the contract already carries the consistency/sufficiency decisions; the api-doc lags. Not CI-enforced yet (IMPLEMENTED={}).jensen_shannon/js_divergence,prob_direction/prob_gt_zero,hdi(prob=)/hdi_prob=,phenotype_distanceshape).Planning/spec docs live under
docs/contract/(excluded from the Sphinx build). The living agenda + removal ledger isdocs/contract/REFACTOR_AGENDA.md.🤖 Generated with Claude Code