Raw outputs are hard to compare at scale
Structural deviations, mutation properties, and model confidence do not naturally combine into a stable ranking without shared logic.
Open-source platform
MHC Atlas OS
Runtime-agnostic, explainable, structure-guided mutation prioritization
MHC Atlas OS is a peptide MHC decision platform that turns AlphaFold-derived structure signals into inspectable experimental prioritization outputs through explainable mutation scoring, policy-governed evaluation, and runtime-agnostic execution.
The problem
Structure outputs are useful, but they do not tell a team what to prioritize next.
In practice, protein structure mutation analysis often fragments across notebooks, scripts, manual inspection, and disconnected model artifacts. Raw structure files, confidence values, and isolated comparisons can be informative, but they do not by themselves create a consistent, explainable structure-guided mutation prioritization workflow.
Review logic becomes opaque quickly
Once prioritization spreads across scripts and manual inspection, the reasoning behind a decision becomes difficult to inspect or rerun.
This is a workflow problem, not only an analysis problem
Teams need interpretable, repeatable, policy-aware ways to turn structure-derived signals into prioritization decisions.
Why this is a big problem
When review is manual, opaque, or runtime-specific, both scientific time and engineering trust erode.
Candidate review is rarely a one-shot task. Prioritization needs to be repeated, audited, compared over time, and adapted across local runs, governed execution paths, and more automated orchestration modes.
Manual or weakly structured review wastes time. Opaque ranking weakens trust. One-off scripts do not scale well. And once decisions cannot be clearly explained or replayed, experimental planning becomes harder to compare across cycles.
Operational cost
Repeated manual review and fragile handoffs create avoidable overhead.
Reproducibility risk
Opaque ranking makes it difficult to justify why one candidate outranked another.
Execution brittleness
Runtime-specific tooling does not adapt well as review evolves from local inspection to governed or agent-capable execution.
Decision memory loss
Without stored outputs and rationale, teams relearn the same context instead of building on it.
What the platform does
Provides the missing layer between structure-derived evidence and experimental prioritization.
MHC Atlas OS addresses the workflow problem directly: it parses structures, compares candidates, applies explainable structural scoring, evaluates policy constraints, and produces readable outputs that can be reviewed, remembered, and reused across execution modes.
Structure parsing
Ingests PDB and mmCIF inputs, normalizes structure context, and prepares analysis-ready representations.
WT vs mutant comparison
Measures structural change between wild-type and variant states to expose deltas that matter for review.
Explainable scoring
Combines multiple explicit signal groups into an interpretable prioritization score rather than opaque inference.
Policy checks
Applies domain and execution rules before recommendation output, making decision logic inspectable and governable.
Readable reports
Produces decision summaries and report artifacts that can be reviewed by engineers, researchers, and collaborators.
Decision memory
Tracks history, rationale, and prior outputs so prioritization can be revisited with context rather than guesswork.
Why governed and runtime-agnostic execution matters
The platform is solving an execution problem as much as an analysis problem.
Different execution modes fit different review and automation needs. Local runs support direct inspection, governed execution supports traceability and reproducibility, and agent-capable orchestration expands workflow automation. Those changes should not require rewriting the core decision logic.
Stable core logic
Scoring and comparison logic should remain stable even when orchestration changes.
Policy and trust
Governance matters when prioritization outputs need to be reviewed, rerun, and defended.
Execution fit
Different runtime modes fit different stages of inspection, control, and automation.
Agent usefulness with discipline
Agent-capable execution is valuable only if the underlying decision logic remains understandable.
Architecture overview
Runtime-agnostic architecture enabling deterministic, governed, and multi-agent execution modes.
MHC Atlas OS separates runtime concerns from domain logic so the same scoring, policy, and reporting core can operate across local execution, governed runtime contexts, and collaborative agent orchestration.
Architecture figure unavailable
The architecture figure is expected at docs/architecture.svg.
Runtime layer
Abstracts execution from implementation details so local, governed, or multi-agent modes can share the same core pipeline.
Agent orchestration
Coordinates task routing and collaboration while preserving explicit boundaries around who evaluates what.
Domain logic
Holds structure parsing, comparison, and prioritization logic in deterministic modules rather than runtime-specific glue.
Policy engine
Encodes decision rules, gates, warnings, and governance so output can be defended and re-evaluated consistently.
Decision output
Generates reports, API responses, UI views, and decision memory artifacts that make the system operationally usable.
Runtime modes
Same domain core, different execution envelopes.
Runtime abstraction is a product strength here, not a side detail. It keeps the platform portable while preserving deterministic domain logic and explainable output semantics.
Local Runtime
Deterministic local execution
Direct pipeline execution for development, testing, reproducible evaluation, and low-friction local use.
- Best for debugging, batch runs, and direct inspection.
- Minimal execution overhead and predictable behavior.
- Useful when decision logic needs to be audited step by step.
Nemo Runtime
Governed execution with policy context
Introduces execution context, policy enforcement, warnings, traceability, and a more controlled decision path.
- Best for organizational review, guarded workflows, and provenance-sensitive evaluation.
- Emphasizes policy gating and observable runtime behavior.
- Turns prioritization into a governed system rather than an ad hoc script run.
AutoGen Runtime
Collaborative multi-agent execution
Supports agent-driven evaluation patterns where multiple task roles contribute to the final structured output.
- Best for role-based review, delegation, and richer orchestration flows.
- Extends execution without rewriting domain scoring logic.
- Shows why runtime abstraction matters beyond a single agent stack.
Scoring model
Interpretable prioritization, not black-box prediction.
The scoring system is designed to expose structured signals that help decide what to validate next. It does not claim to predict binding affinity or biological outcome directly.
Input evidence
WT vs mutant structure context
Signal group 01
Structural deviation
Signal group 02
Biochemical severity
Signal group 03
Confidence signals
Signal group 04
Consistency signals
Output
Explainable prioritization score
Structural deviation
Geometric change signals capture the degree and character of structural difference between wild-type and mutant states.
Biochemical mutation severity
Residue-class transitions provide explicit mutation severity cues rather than hiding the rationale inside a learned model.
Confidence signals
Model reliability indicators shape how strongly a result should influence prioritization and review attention.
Consistency signals
Agreement across multiple indicators helps distinguish stable prioritization signals from noisy or ambiguous cases.
Design philosophy
Engineering principles for explainable scientific tooling.
No black-box ML
Priority comes from explicit, reviewable signals rather than opaque prediction layers.
Explainable scoring
Every score should be legible enough to support discussion, skepticism, and revision.
Policy-driven decisions
Recommendations should pass through declared rules, not just internal heuristics.
Runtime abstraction
The execution framework can change without forcing a rewrite of domain reasoning.
Deterministic domain logic
Core biology and scoring modules remain stable, testable, and portable across orchestration modes.
What this is not
Clear boundaries are part of the product.
MHC Atlas OS is intentionally positioned as a decision-support system for structured prioritization. That distinction matters for technical evaluation and for scientific credibility.
Not a black-box binding predictor
It does not claim direct affinity prediction or biological truth. It emits structured prioritization signals for validation planning.
Not an opaque ranking pipeline
Ranking logic is explicit, multi-factor, and policy-aware rather than buried inside a fixed heuristic stack.
Not a single-runtime agent prototype
Runtime abstraction is built into the architecture so the platform is not trapped inside one orchestration choice.
Not just a structure viewer
The system includes decision logic, reporting, and memory instead of stopping at inspection or visualization.
Not a one-off analysis script
The platform is organized around reusable workflows, policy gates, and artifacts that support repeatable review.
Workflow / execution flow
From mutation context to stored decision output.
-
01
Input structure and mutation context
Provide wild-type and mutant structure data with the candidate context that frames the evaluation task.
-
02
Select runtime mode
Choose local, governed, or multi-agent execution based on the level of control, traceability, and orchestration required.
-
03
Route orchestration path
Dispatch through the appropriate orchestration layer while keeping the domain core stable.
-
04
Run structure analysis
Parse files, compare state changes, and assemble the raw signals required for scoring.
-
05
Compute explainable scoring
Integrate structural, biochemical, confidence, and consistency signals into a readable prioritization output.
-
06
Apply policy evaluation
Gate, warn, or annotate results according to declared rules before anything is presented as a decision artifact.
-
07
Write reports and decision memory
Produce reports, API/UI outputs, and saved decision history for review, comparison, and follow-on work.
Artifacts / resources
Evaluation paths and operating documents.
GitHub repository
Source tree, issues, releases, and implementation details.
README
Site deployment notes and homepage maintenance instructions.
Quickstart
Fastest path to a demo workflow and first execution.
Installation guide
Environment and package installation options.
CLI usage
Command-line entry points and usage patterns.
Demos
Walkthroughs and evaluation scenarios.
Pilot workflow
Structured evaluation path for collaborative review.
Release notes
Versioned changes, maturity signals, and evolution history.
Project status / roadmap
Active, architecture-forward, and still expanding.
Architecture
Core runtime, orchestration, scoring, reporting, and storage layers are already visible as distinct system boundaries.
Explainability
Scoring and decision outputs are positioned around readable rationale instead of opaque predictive claims.
Extensibility
Future work can expand runtime integrations, plugin surfaces, and scoring policy modules without collapsing the core architecture.
Contact / contribution
Built as an open technical system.
Contributions, evaluation feedback, and architecture discussion are best routed through the repository. Replace the placeholder contact below if you want a direct collaborator or diligence contact.
Licensed under MIT where applicable in the repository.