bijux-proteomics-intelligence 0.3.8

Policy-driven candidate ranking and scenario decision intelligence for protein progression and portfolio prioritization

bijux-proteomics-intelligence

bijux-proteomics-intelligence is the analytical judgment layer for bijux-proteomics. It can rank candidates, gate recommendation readiness, assemble decision briefs, summarize cautious interpretation posture, and carry learning pressure forward without claiming scientific truth, runtime orchestration, or lab execution authority.

Within the suite, intelligence owns recommendation posture, ranking sensitivity, and refusal behavior.

The package root is curated on purpose. Import exact owner modules such as candidates.ranking, judgment.paths, posture.evidence, interpretation.runs, and reviews.benchmarks instead of treating the package root like a broad symbol menu. The machine-readable charter in governance/charter.py and the governed capability map define six durable analytical families:

• candidates
• judgment
• posture
• interpretation
• reviews
• learning

Those families are the durable answer to what intelligence can decide and what it must refuse or downgrade.

Release-facing maintainers should keep README.md, CHANGELOG.md, and the package docs/*.md set aligned before claiming new intelligence behavior or scientific scope.

It also provides benchmark-backed review outputs for dda, dia, ptm, lfq, and multiplex workflows when reviewers need package-owned claims instead of presentation-only summaries.

At a glance

• Use intelligence when reviewers need ranking, readiness, refusal, or recommendation posture without pretending those outputs are scientific truth.
• Start with candidates.ranking, judgment.paths, and posture.evidence, then open the intelligence handbook for the full owner map.
• Route curated evidence memory to knowledge, scientific meaning to core, executable control to runtime, and assay follow-up execution to lab.

Why teams pick this package

• transparent ranking and recommendation outputs with traceable decision rationale
• explicit downgrade and refusal behavior when evidence is stale, thin, or contradictory
• review-ready packets and skeptical challenge surfaces that keep unresolved questions visible
• typed interpretation summaries that stay cautious about biological meaning

Typical use cases

• rank candidate proteins against defined decision policies
• decide whether current evidence is ready for progression-oriented review
• produce explainable shortlists and review-board packets for expert scrutiny
• summarize proteomics interpretation posture without re-owning raw analysis
• carry benchmark-backed review claims into release conversations

0.3.8 Release Highlights

• Intelligence now ships typed interpretation surfaces for run summaries, differential abundance, PTM review, missingness, outliers, contaminants, and enrichment-driven recommendation posture.
• The package is now organized around durable owner families for candidates, judgment, posture, interpretation, reviews, and learning, so recommendation boundaries are easier to audit.
• README and handbook examples now route readers through the currently shipped analytical entrypoints instead of older decision-brief naming.

Installation

pip install bijux-proteomics-intelligence

Quick start

from bijux_proteomics_intelligence.candidates.ranking import prioritize_candidates
from bijux_proteomics_intelligence.interpretation.runs import (
    build_run_interpretation_summary,
)
from bijux_proteomics_intelligence.interpretation.quantitative import (
    interpret_differential_abundance,
)
from bijux_proteomics_intelligence.judgment.paths import (
    build_review_board_decision_path,
)
from bijux_proteomics_intelligence.posture.evidence import (
    assess_recommendation_readiness,
)
from bijux_proteomics_intelligence.reviews.benchmarks import (
    build_dia_benchmark_review,
)

For grounded recommendation judgment:

ranking = prioritize_candidates(...)
readiness = assess_recommendation_readiness(...)
path = build_review_board_decision_path(...)

For benchmark-backed workflow review:

review = build_dia_benchmark_review(source_path=...)

For proteomics interpretation:

summary = build_run_interpretation_summary(...)
report = interpret_differential_abundance(...)

Public APIs

The public package root deliberately exports owner modules instead of a broad symbol bucket:

• falsifiers for challenge surfaces over typed claims
• refusal for refusal thresholds and unsupported-claim gating
• belief_audit for top-claim confidence and audit summaries
• reviews for typed report-contract assembly over supported workflows

Minimal executable example:

from bijux_proteomics_intelligence import falsifiers
from bijux_proteomics_knowledge import EvidenceClaim

claim = EvidenceClaim(
    claim_id="protein-claim:p11111",
    target_id="protein:p11111",
    statement="Protein PTM1 increased in treated vs control.",
    subject="P11111",
    relation="protein_abundance_change",
    object="up",
    direction="up",
    claim_type="biomarker",
    evidence_ids=["evidence:1"],
    status="supported",
    polarity="supporting",
    resolution_state="open",
    evidence_state="supported",
)
report = falsifiers.generate_falsifiers(claim)

assert report.summary.claim_count == 1
assert report.entries[0].claim_id == claim.claim_id

Package identity

• Distribution name: bijux-proteomics-intelligence
• Import root: bijux_proteomics_intelligence
• Canonical owner families: candidates/, judgment/, posture/, reviews/, interpretation/, learning/, and governance/
• Curated root owner families: candidates, judgment, posture, reviews, interpretation, learning, and governance

Package boundaries

This package owns analytical judgment over already-typed workflow and evidence surfaces.

It can decide:

• candidate ranking and lifecycle framing through candidates/
• scenario recommendations, uncertainty, and review-decision paths through judgment/
• evidence-readiness downgrade, refusal, and skeptical pressure through posture/
• benchmark-backed reviewer outputs and downstream analytical presentation through reviews/
• cautious interpretation summaries through interpretation/runs.py, interpretation/quantitative.py, interpretation/pathways.py, interpretation/ptm.py, interpretation/contaminants.py, and interpretation/contrasts.py
• learning pressure on future prioritization through learning/

It does not own scientific truth, evidence curation, workflow stage law, runtime transport, or lab scheduling.

What this package must not do

• it must not redefine scientific truth or evidence provenance that belongs in core or knowledge
• it must not absorb runtime execution transport or lab scheduling into analytical judgment
• it must not widen the package root into a convenience bucket that hides the real owner modules

Consequence chain route

Intelligence owns the recommendation sentence inside the shared consequence chain, but it does not own the whole story.

• use Workflow Consequence Maps when the question is whether the current recommendation already outruns the weakest downstream boundary
• use What Changed The Recommendation when the question is which counterfactual, contradiction, or lab burden actually changed the recommendation
• use Workflow Refusal Handbook when the honest next action may still be stop, rerun, narrow, or refuse even though a recommendation surface exists

Contract checkpoints

• ranking and scenario outputs must carry typed rationale instead of opaque scores
• recommendation outputs must expose downgrade or refusal when evidence posture is weak
• review outputs must keep unresolved questions visible instead of polishing them away
• interpretation outputs must preserve caveats instead of implying mechanistic certainty
• benchmark review outputs must stay tied to checked-in fixtures and explicit scientific limits

Choose this package when

• you need candidate ranking, scenario evaluation, or explainable recommendation logic
• the change affects analytical judgment rather than the way results are delivered
• policy and rationale should stay explicit and reproducible
• you need skeptical analytical review over whether a recommendation is truly defensible
• you need benchmark-backed release review outputs for dda, dia, ptm, lfq, or multiplex

Route elsewhere when

• the change defines scientific parsing, evidence storage, lab scheduling, or runtime transport wiring
• the helper only reformats recommendation outputs for CLI or API consumers
• the behavior needs operational burden or feasibility ownership that belongs in lab

Verification route

• check tests for ranking, evaluator, review, and interpretation proof before treating an intelligence change as safe
• review governance/charter.py and the capability map when ownership or analytical-band claims are part of the change
• review docs/BOUNDARIES.md, docs/CONTRACTS.md, and docs/INTERPRETATION.md when refusal, downgrade, or interpretation claims are part of the change

Review questions

• does the change preserve analytical judgment semantics rather than output transport
• would another package start carrying shadow ranking or refusal logic if this stayed outside intelligence
• can the change be justified without claiming scientific truth, runtime execution, or lab scheduling ownership

Escalation route

• route the change outward when the behavior mostly shapes scientific truth, evidence curation, lab operations, or delivery transport
• stop and review docs/BOUNDARIES.md and docs/ARCHITECTURE.md when a proposal starts looking broader than the six analytical families
• escalate before release when downstream consumers would need local exceptions to interpret recommendation readiness or refusal

Consumer impact signals

• expect downstream review when ranking rules, refusal posture, or review packet semantics change because consumers rely on stable recommendation meaning
• treat changes that alter downgrade thresholds or contradiction handling as high-impact even when function names and imports stay stable
• expect a lower release burden when the change only improves internal implementation without changing analytical meaning

Explicit non-goals

• this package does not own evidence storage, claim lineage, or trust semantics
• this package does not own runtime transport, provider selection, or operator entrypoints
• this package does not schedule lab workflows or carry workflow-local rerun policy

Source guide

• src/bijux_proteomics_intelligence/governance/charter.py for the machine-readable charter and capability map
• src/bijux_proteomics_intelligence/candidates/ranking.py for ranking and candidate framing
• src/bijux_proteomics_intelligence/candidates/lifecycle.py for lifecycle movement and risk context
• src/bijux_proteomics_intelligence/judgment/scenarios.py for scenario evaluation
• src/bijux_proteomics_intelligence/judgment/recommendations.py for escalation, refusal, and unresolved-question posture
• src/bijux_proteomics_intelligence/judgment/paths.py for end-to-end analytical decision paths
• src/bijux_proteomics_intelligence/posture/evidence.py for contradiction, freshness, downgrade, and refusal posture
• src/bijux_proteomics_intelligence/posture/skeptical.py for scientific and software challenge pressure
• src/bijux_proteomics_intelligence/reviews/decision_briefs.py for decision brief assembly and ranked evidence presentation
• src/bijux_proteomics_intelligence/reviews/boards.py for board-facing analytical review projections
• src/bijux_proteomics_intelligence/reviews/candidates.py for candidate-facing review projections
• src/bijux_proteomics_intelligence/reviews/pathways.py for pathway-facing review projections
• src/bijux_proteomics_intelligence/reviews/benchmarks.py for benchmark-backed release review
• src/bijux_proteomics_intelligence/interpretation/runs.py for run-level interpretation posture
• src/bijux_proteomics_intelligence/interpretation/quantitative.py for quantitative interpretation and missingness caveats
• src/bijux_proteomics_intelligence/learning/adaptation.py for follow-up learning pressure
• tests for executable behavior expectations

Documentation

• Decision support
• Workflow consequence maps
• What changed the recommendation
• Product architecture
• Cross-package ownership
• Package guide
• Ownership boundary
• Architecture overview
• Interface contracts
• Release and versioning
• Interpretation workflows