bijux-proteomics-knowledge

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

pip install bijux-proteomics-knowledge

Quick start

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:

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 when the question is how contradiction pressure becomes a weaker or stronger recommendation and then a real assay burden
• use 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 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 for evidence models, provenance scoring, contradiction detection, and memory quality audits
• src/bijux_proteomics_knowledge/memory/models/claims.py for claim modeling, lineage, and knowledge-gap audits
• src/bijux_proteomics_knowledge/memory/reconciliation/resolution.py for conflict-resolution policies over shared scientific memory
• src/bijux_proteomics_knowledge/memory/integrity/graph.py for evidence-graph validation rules and decision tracing
• 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 for decision-facing briefs and multi-decision readiness summaries derived from existing memory
• src/bijux_proteomics_knowledge/reviews/explanations.py for candidate-level graph explanations built from existing decision briefs
• 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 for the machine-readable package charter and module audit
• src/bijux_proteomics_knowledge/references/ for curated references split into grounding and workflow families
• 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 for executable behavior expectations organized by memory, references, reviews, and package contracts

Documentation

• Decision support
• Workflow consequence maps
• Workflow claim grounding
• Product architecture
• Cross-package ownership
• Package guide
• Ownership boundary
• Architecture overview
• Interface contracts
• Release and versioning