Metadata-Version: 2.4
Name: bijux-proteomics-intelligence
Version: 0.3.8
Summary: Policy-driven candidate ranking and scenario decision intelligence for protein progression and portfolio prioritization
Project-URL: Homepage, https://bijux.io/bijux-proteomics/
Project-URL: Documentation, https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/
Project-URL: Repository, https://github.com/bijux/bijux-proteomics
Project-URL: Issues, https://github.com/bijux/bijux-proteomics/issues
Project-URL: Changelog, https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/CHANGELOG.md
Project-URL: Security, https://github.com/bijux/bijux-proteomics/blob/main/SECURITY.md
Author-email: Bijan Mousavi <bijan@bijux.io>
Maintainer-email: Bijan Mousavi <bijan@bijux.io>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: bioinformatics,candidate-ranking,decision-intelligence,policy-engine,proteomics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4,>=3.11
Requires-Dist: bijux-proteomics-core>=0.3.8
Requires-Dist: bijux-proteomics-foundation>=0.3.8
Requires-Dist: bijux-proteomics-knowledge>=0.3.8
Requires-Dist: loguru>=0.7
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: pydantic>=2.0.2
Description-Content-Type: text/markdown

# bijux-proteomics-intelligence

<!-- bijux-proteomics-badges:generated:start -->
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://pypi.org/project/bijux-proteomics-intelligence/)
[![Typing: typed](https://img.shields.io/badge/typing-typed%20(PEP%20561)-0A7BBB)](https://pypi.org/project/bijux-proteomics-intelligence/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0F766E)](https://github.com/bijux/bijux-proteomics/blob/main/LICENSE)
[![CI Status](https://github.com/bijux/bijux-proteomics/actions/workflows/verify.yml/badge.svg?branch=main)](https://github.com/bijux/bijux-proteomics/actions/workflows/verify.yml?query=branch%3Amain)
[![GitHub Repository](https://img.shields.io/badge/github-bijux%2Fbijux--proteomics-181717?logo=github)](https://github.com/bijux/bijux-proteomics)

[![bijux-proteomics-intelligence](https://img.shields.io/pypi/v/bijux-proteomics-intelligence?label=intelligence&logo=pypi)](https://pypi.org/project/bijux-proteomics-intelligence/)
[![agentic-proteins](https://img.shields.io/pypi/v/agentic-proteins?label=agentic--proteins&logo=pypi)](https://pypi.org/project/agentic-proteins/)
[![bijux-proteomics-foundation](https://img.shields.io/pypi/v/bijux-proteomics-foundation?label=foundation&logo=pypi)](https://pypi.org/project/bijux-proteomics-foundation/)
[![bijux-proteomics-core](https://img.shields.io/pypi/v/bijux-proteomics-core?label=core&logo=pypi)](https://pypi.org/project/bijux-proteomics-core/)
[![bijux-proteomics-runtime](https://img.shields.io/pypi/v/bijux-proteomics-runtime?label=runtime&logo=pypi)](https://pypi.org/project/bijux-proteomics-runtime/)
[![bijux-proteomics-knowledge](https://img.shields.io/pypi/v/bijux-proteomics-knowledge?label=knowledge&logo=pypi)](https://pypi.org/project/bijux-proteomics-knowledge/)
[![bijux-proteomics-lab](https://img.shields.io/pypi/v/bijux-proteomics-lab?label=lab&logo=pypi)](https://pypi.org/project/bijux-proteomics-lab/)

[![bijux-proteomics-intelligence](https://img.shields.io/badge/intelligence-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-intelligence)
[![agentic-proteins](https://img.shields.io/badge/agentic--proteins-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fagentic-proteins)
[![bijux-proteomics-foundation](https://img.shields.io/badge/foundation-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-foundation)
[![bijux-proteomics-core](https://img.shields.io/badge/core-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-core)
[![bijux-proteomics-knowledge](https://img.shields.io/badge/knowledge-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-knowledge)
[![bijux-proteomics-lab](https://img.shields.io/badge/lab-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-lab)

[![bijux-proteomics-intelligence docs](https://img.shields.io/badge/docs-intelligence-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
[![agentic-proteins docs](https://img.shields.io/badge/docs-agentic--proteins-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/02-agentic-proteins/)
[![bijux-proteomics-foundation docs](https://img.shields.io/badge/docs-foundation-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/03-bijux-proteomics-foundation/)
[![bijux-proteomics-core docs](https://img.shields.io/badge/docs-core-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/04-bijux-proteomics-core/)
[![bijux-proteomics-runtime docs](https://img.shields.io/badge/docs-runtime-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/09-bijux-proteomics-runtime/)
[![bijux-proteomics-knowledge docs](https://img.shields.io/badge/docs-knowledge-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/)
[![bijux-proteomics-lab docs](https://img.shields.io/badge/docs-lab-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/07-bijux-proteomics-lab/)
<!-- bijux-proteomics-badges:generated:end -->

`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](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
  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

```bash
pip install bijux-proteomics-intelligence
```

## Quick start

```python
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:

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

For benchmark-backed workflow review:

```python
review = build_dia_benchmark_review(source_path=...)
```

For proteomics interpretation:

```python
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:

```python
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](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/workflow-consequence-maps/)
  when the question is whether the current recommendation already outruns the
  weakest downstream boundary
- use [What Changed The Recommendation](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/what-changed-the-recommendation/)
  when the question is which counterfactual, contradiction, or lab burden
  actually changed the recommendation
- use [Workflow Refusal Handbook](https://bijux.io/bijux-proteomics/07-bijux-proteomics-lab/foundation/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`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/governance/charter.py) for the machine-readable charter and capability map
- [`src/bijux_proteomics_intelligence/candidates/ranking.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/candidates/ranking.py) for ranking and candidate framing
- [`src/bijux_proteomics_intelligence/candidates/lifecycle.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/candidates/lifecycle.py) for lifecycle movement and risk context
- [`src/bijux_proteomics_intelligence/judgment/scenarios.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/judgment/scenarios.py) for scenario evaluation
- [`src/bijux_proteomics_intelligence/judgment/recommendations.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/judgment/recommendations.py) for escalation, refusal, and unresolved-question posture
- [`src/bijux_proteomics_intelligence/judgment/paths.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/judgment/paths.py) for end-to-end analytical decision paths
- [`src/bijux_proteomics_intelligence/posture/evidence.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/posture/evidence.py) for contradiction, freshness, downgrade, and refusal posture
- [`src/bijux_proteomics_intelligence/posture/skeptical.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/posture/skeptical.py) for scientific and software challenge pressure
- [`src/bijux_proteomics_intelligence/reviews/decision_briefs.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/reviews/decision_briefs.py) for decision brief assembly and ranked evidence presentation
- [`src/bijux_proteomics_intelligence/reviews/boards.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/reviews/boards.py) for board-facing analytical review projections
- [`src/bijux_proteomics_intelligence/reviews/candidates.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/reviews/candidates.py) for candidate-facing review projections
- [`src/bijux_proteomics_intelligence/reviews/pathways.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/reviews/pathways.py) for pathway-facing review projections
- [`src/bijux_proteomics_intelligence/reviews/benchmarks.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/reviews/benchmarks.py) for benchmark-backed release review
- [`src/bijux_proteomics_intelligence/interpretation/runs.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/interpretation/runs.py) for run-level interpretation posture
- [`src/bijux_proteomics_intelligence/interpretation/quantitative.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/interpretation/quantitative.py) for quantitative interpretation and missingness caveats
- [`src/bijux_proteomics_intelligence/learning/adaptation.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/src/bijux_proteomics_intelligence/learning/adaptation.py) for follow-up learning pressure
- [`tests`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-intelligence/tests) for executable behavior expectations

## Documentation

- [Decision support](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/decision-support/)
- [Workflow consequence maps](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/workflow-consequence-maps/)
- [What changed the recommendation](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/what-changed-the-recommendation/)
- [Product architecture](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/product-architecture/)
- [Cross-package ownership](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/cross-package-ownership/)
- [Package guide](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
- [Ownership boundary](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/foundation/ownership-boundary/)
- [Architecture overview](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/architecture/)
- [Interface contracts](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/interfaces/)
- [Release and versioning](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/operations/release-and-versioning/)
- [Interpretation workflows](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-intelligence/docs/INTERPRETATION.md)
