Metadata-Version: 2.4
Name: bijux-proteomics-knowledge
Version: 0.3.8
Summary: Evidence, trust, and contradiction-resolution models for auditable proteomics decision knowledge graphs
Project-URL: Homepage, https://bijux.io/bijux-proteomics/
Project-URL: Documentation, https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/
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-knowledge/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: conflict-resolution,evidence-graph,knowledge-governance,proteomics,trust-scoring
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: pydantic>=2.0.2
Provides-Extra: test
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'test'
Requires-Dist: pytest-benchmark<6.0,>=4.0.0; extra == 'test'
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'test'
Requires-Dist: pytest<10.0,>=8.4.1; extra == 'test'
Description-Content-Type: text/markdown

# bijux-proteomics-knowledge

<!-- 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-knowledge/)
[![Typing: typed](https://img.shields.io/badge/typing-typed%20(PEP%20561)-0A7BBB)](https://pypi.org/project/bijux-proteomics-knowledge/)
[![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-knowledge](https://img.shields.io/pypi/v/bijux-proteomics-knowledge?label=knowledge&logo=pypi)](https://pypi.org/project/bijux-proteomics-knowledge/)
[![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-intelligence](https://img.shields.io/pypi/v/bijux-proteomics-intelligence?label=intelligence&logo=pypi)](https://pypi.org/project/bijux-proteomics-intelligence/)
[![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-knowledge](https://img.shields.io/badge/knowledge-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-knowledge)
[![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-intelligence](https://img.shields.io/badge/intelligence-ghcr-181717?logo=github)](https://github.com/bijux/bijux-proteomics/pkgs/container/bijux-proteomics%2Fbijux-proteomics-intelligence)
[![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-knowledge docs](https://img.shields.io/badge/docs-knowledge-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/)
[![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-intelligence docs](https://img.shields.io/badge/docs-intelligence-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-proteomics/05-bijux-proteomics-intelligence/)
[![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-knowledge` is the repository's scientific memory with
provenance. It preserves evidence, claims, resolution history, and grounded
workflow references as selective, reviewable memory instead of as generic
context.

Within the suite, knowledge owns scientific memory, provenance, contradiction
handling, and review state.

Use this package when you need auditable scientific memory, explicit
provenance, contradiction-aware evidence reasoning, and grounded workflow
briefings that downstream packages can consume without re-curating locally.

## At a glance

- Use knowledge when evidence, claims, citations, and contradictions must stay
  reviewable over time instead of being flattened into generic context.
- Start with `references`, `memory.models`, and `reviews.decision_briefs`,
  then open the
  [knowledge handbook](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/)
  for the full owner surface.
- Route execution to runtime, recommendation posture to intelligence, assay
  follow-up to lab, and changes to scientific meaning back to core.

## Why teams pick this package

- explicit evidence and claim memory with provenance, trust, and freshness semantics
- contradiction-aware resolution flows that preserve audit history
- grounded workflow briefings, caveats, and scientific rules tied to citations
- compatibility with shared schema and serialization contracts

## Typical use cases

- preserve evidence bundles, claims, and resolution history for later scientific review
- retrieve grounded workflow caveats, benchmark claims, and ontology mappings
- explain why a scientific conclusion changed over time without losing provenance
- surface unresolved knowledge gaps before downstream packages rank, schedule, or execute work

## 0.3.8 Release Highlights

- Knowledge now exposes cited references, benchmark manifests, curated corpora,
  scientific rules, workflow briefing packets, comparator dossiers, and
  machine-readable release-gate registries as first-class public surfaces.
- Public resolution and lookup APIs now cover protein identity, feature
  overlap, pathway membership, complex membership, kinase substrates, drug
  targets, disease terms, knowledge coverage, and cross-species orthologs.
- The package is now grouped by durable `memory`, `references`, `reviews`, and
  `contracts` owners so provenance and trust semantics are easier to defend.

## Installation

```bash
pip install bijux-proteomics-knowledge
```

## Quick start

```python
from bijux_proteomics_knowledge.memory.models.evidence import EvidenceBundle, evidence_gaps
from bijux_proteomics_knowledge.memory.models.claims import build_claim
from bijux_proteomics_knowledge.reviews.decision_briefs import build_knowledge_decision_brief
from bijux_proteomics_knowledge.references.workflows.briefings import (
    build_workflow_reference_briefing,
)
```

## Public APIs

The stable root API focuses on query and compatibility surfaces over curated
scientific memory:

- `evaluate_schema_compatibility(...)` for document-version checks
- `resolve_protein_ids(...)`, `resolve_pathway_members(...)`, and related
  resolvers for grounded lookup work
- `compute_knowledge_coverage(...)` for annotation-sparsity review
- `EvidenceRecord`, `EvidenceBundle`, and `EvidenceClaim` for typed memory payloads

Minimal executable example:

```python
from bijux_proteomics_foundation import DocumentSchema
from bijux_proteomics_knowledge import evaluate_schema_compatibility

schema = DocumentSchema(
    created_by="bijux-proteomics-knowledge",
    document_kind="annotation_pack",
    package_name="bijux-proteomics-knowledge",
)
report = evaluate_schema_compatibility(schema)

assert report.compatible is True
assert report.profile_id == "knowledge-default-profile"
```

## Package identity

- Distribution name: `bijux-proteomics-knowledge`
- Import root: `bijux_proteomics_knowledge`
- Stable entrypoints: `memory.models.evidence`, `memory.models.claims`, `memory.reconciliation.resolution`, `reviews.decision_briefs`, `contracts.schema`, and `references`

## Package boundaries

This package owns scientific memory with provenance: evidence records, claim
state, contradiction resolution, resolution history, and curated workflow
references that ground shared interpretation boundaries.

It does not own execution orchestration, route-shaped payloads, candidate
ranking or recommendation policy, or experiment scheduling.

## What this package must not do

- it must not own runtime orchestration, route transport, or operator entrypoints
- it must not define ranking policy, recommendation posture, or lab scheduling behavior
- it must not accept uncited context blobs that are not selective, reviewable scientific memory

It is also not a generic context store. New content belongs here only when it
becomes selective, cited, and reviewable scientific memory.

## Consequence chain route

Knowledge is the first owner in the cross-package consequence chain, not a
complete trust story by itself.

- use [Workflow Consequence Maps](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/workflow-consequence-maps/)
  when the question is how contradiction pressure becomes a weaker or stronger
  recommendation and then a real assay burden
- use [What Changed The Recommendation](https://bijux.io/bijux-proteomics/01-bijux-proteomics/foundation/what-changed-the-recommendation/)
  when the question is whether literature pressure, comparator pressure, or
  downstream lab burden actually moved the call
- use [Outcome Learning Loops](https://bijux.io/bijux-proteomics/07-bijux-proteomics-lab/foundation/outcome-learning-loops/)
  when the question is how requested-versus-observed follow-up should tighten
  the next knowledge-facing claim

## Scientific memory charter

The package boundary is justified by five grounded capabilities:

- curated references
- ontology mappings
- benchmark manifests
- curated corpora
- scientific context

Everything else in the package exists to turn those capabilities into auditable
scientific memory with provenance:
- `memory/models/` owns evidence and claim records
- `memory/integrity/` owns graph integrity and decision tracing
- `memory/normalization/` owns evidence ingestion into knowledge-owned memory
- `memory/reconciliation/` owns contradiction resolution and resolution history
- `contracts/` owns knowledge document and schema compatibility contracts
- `reviews/` owns decision-facing briefs built from existing memory
- `references/grounding/` owns citations, contexts, corpora, ontologies, problems, and rules
- `references/workflows/` owns benchmark manifests, workflow narratives, workflow briefings, and narrow workflow lookups

## Contract checkpoints

- evidence and claim records must stay typed, auditable, and schema-versioned
- provenance, trust, freshness, and contradiction outputs must remain explicit instead of inferred
- resolution flows must preserve explainable lineage from evidence to decision
- downstream packages should depend on this layer for shared evidence meaning instead of recreating local memory models
- external evidence normalization belongs here only when it ends as scientific memory, not when it defines runtime adapters or orchestration seams
- every workflow-facing claim, caveat, and rule must stay grounded in citations, benchmark manifests, corpora, or scientific context entries

## Curated scientific reference surfaces

- `references` exposes a curated public slice for benchmark manifests, workflow briefings, ontology resolution, scientific rule references, and context entries
- `references` also exposes scientific context entries, known-problem registries, literature groups, workflow claim and limitation narratives, and workflow briefing packets for downstream consumers
- bundled fixture corpora stay distinct from external scientific references so reproducibility claims remain auditable
- scientific rules carry explicit citation and benchmark context instead of relying on package-local assumptions
- workflow briefing packets keep claim surfaces, limitation surfaces, and provenance attached so intelligence and lab can consume grounded context without re-curating it locally

## Choose this package when

- you need selective scientific memory with provenance
- auditability and review traceability are part of the contract
- multiple higher layers should share the same evidence, claim, and resolution semantics

## Route elsewhere when

- the change defines execution orchestration, route-shaped payloads, ranking or recommendation policy, or lab scheduling
- the helper only reformats evidence results for operator interfaces
- the behavior exists for one analytical workflow instead of shared scientific memory meaning

## Verification route

- check `tests/contracts`, `tests/governance`, `tests/memory`, `tests/references`, `tests/reviews`, and `tests/package`
  before treating a knowledge change as safe
- review `docs/BOUNDARIES.md`, `docs/CONTRACTS.md`, and `docs/ARCHITECTURE.md`
  when ownership or trust-semantics claims are part of the change
- use `README.md`, `CHANGELOG.md`, and package `docs/*.md` when the change
  affects package publication, metadata, or release-readiness expectations

## Review questions

- does the change preserve scientific memory, provenance, contradiction, or trust semantics rather than transport-bound presentation or workflow-local shaping
- would another package start carrying shadow scientific memory if this behavior stayed outside knowledge
- can the change be justified without claiming execution orchestration, ranking, recommendation, lab execution, or runtime interface ownership

## Escalation route

- route the change outward when the behavior mainly defines execution orchestration, ranking or recommendation policy, lab execution, or interface transport
- stop and review `docs/BOUNDARIES.md` and `docs/ARCHITECTURE.md` when the
  proposal starts looking like presentation reshaping instead of shared evidence
  meaning
- escalate before release when downstream consumers would need package-specific
  trust or lineage exceptions to adopt the change

## Consumer impact signals

- expect downstream review when evidence rules, provenance, lineage semantics, or trust resolution behavior change because other layers consume those meanings
- treat changes that alter contradiction handling, claim interpretation, or lineage expectations as high-impact even when APIs stay stable
- expect a narrower release burden when the change only improves internal implementation without changing scientific memory semantics

## Explicit non-goals

- this package does not own execution orchestration, provider wiring, replay behavior, or route-shaped payloads
- this package does not define candidate ranking or recommendation policy
- this package does not define lab-specific scheduling logic
- this package does not carry shared primitive contracts that belong in the foundation package
- this package does not serve as a generic context sink for uncited scientific notes

## Source guide

- [`src/bijux_proteomics_knowledge/memory/models/evidence.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/memory/models/evidence.py) for evidence models, provenance scoring, contradiction detection, and memory quality audits
- [`src/bijux_proteomics_knowledge/memory/models/claims.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/memory/models/claims.py) for claim modeling, lineage, and knowledge-gap audits
- [`src/bijux_proteomics_knowledge/memory/reconciliation/resolution.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/memory/reconciliation/resolution.py) for conflict-resolution policies over shared scientific memory
- [`src/bijux_proteomics_knowledge/memory/integrity/graph.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/memory/integrity/graph.py) for evidence-graph validation rules and decision tracing
- [`src/bijux_proteomics_knowledge/memory/normalization/ingestion.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/memory/normalization/ingestion.py) for normalization of external evidence into knowledge-owned memory records
- [`src/bijux_proteomics_knowledge/reviews/decision_briefs.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/reviews/decision_briefs.py) for decision-facing briefs and multi-decision readiness summaries derived from existing memory
- [`src/bijux_proteomics_knowledge/reviews/explanations.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/reviews/explanations.py) for candidate-level graph explanations built from existing decision briefs
- [`src/bijux_proteomics_knowledge/reviews/trends.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/reviews/trends.py) for decision-brief comparisons and trend summaries that keep decision-facing change explicit
- [`src/bijux_proteomics_knowledge/governance/charter.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/governance/charter.py) for the machine-readable package charter and module audit
- [`src/bijux_proteomics_knowledge/references/`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/references) for curated references split into grounding and workflow families
- [`src/bijux_proteomics_knowledge/references/workflows/briefings.py`](https://github.com/bijux/bijux-proteomics/blob/main/packages/bijux-proteomics-knowledge/src/bijux_proteomics_knowledge/references/workflows/briefings.py) for workflow-level claim, limitation, context, literature, problem, and rule packets that preserve provenance for downstream consumers
- [`tests`](https://github.com/bijux/bijux-proteomics/tree/main/packages/bijux-proteomics-knowledge/tests) for executable behavior expectations organized by memory, references, reviews, and package contracts

## 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/)
- [Workflow claim grounding](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/foundation/workflow-claim-grounding/)
- [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/06-bijux-proteomics-knowledge/)
- [Ownership boundary](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/foundation/ownership-boundary/)
- [Architecture overview](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/architecture/)
- [Interface contracts](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/interfaces/)
- [Release and versioning](https://bijux.io/bijux-proteomics/06-bijux-proteomics-knowledge/operations/release-and-versioning/)
