Qualify a model
A compatibility profile says two ports describe the same information in the same form. Qualification asks the bigger question: does this model do what it claims, and what is the evidence?
They are separate. A model can be profile-compatible and completely unqualified.
The qualification states
The Hub reports one of four states for every release. The state is derived by the validator, not declared by the model. A manifest can’t claim its own qualification.
| State | What it means |
|---|---|
unqualified | The package has not validated |
schema_valid | The package validated: manifests parse, ports and declarations are consistent |
runtime_valid | Schema-valid, and the validator confirmed it executes under the pinned runtime |
domain_validated | Runtime-valid, and domain evidence was reviewed and accepted |
Each state requires the one before it. Hub search can filter on it, so asking an agent for domain_validated results only is a reasonable way to narrow a shortlist. Read the caveat below before you lean on it.
domain_validated is a statement about reviewed evidence, not a guarantee of
scientific correctness for your question. A model validated for one
intended use is not thereby validated for another.
The specification track
Four documents get you from “it runs” to reviewed evidence. Write them in this order, because each one constrains the next.
| Document | Answers |
|---|---|
| MRS — Model Requirements Specification | What must this model do, and what would count as meeting it? |
| MTS — Modeling Technical Specification | How is each requirement realized, and by which component? |
| Port contracts | What exactly does each input and output carry — units, validation, failure behaviour? |
| Validation plan | What evidence closes each gate, and what is its current status? |
The MRS comes first and gets approved before anyone writes an MTS against it. An MTS traced to an unapproved MRS is a draft, however complete it looks.
Two of the agent skills write these: create-mrs and create-mts.
Writing requirements that can fail
An MRS is only worth writing if it can fail. Requirements get identifiers (MRS-001, MRS-IN-001, MRS-OUT-002, MRS-PERF-001) so the MTS can trace each one to a component and the validation plan can trace each one to evidence.
A validation gate records what evidence would close it and where it stands: pass, warning, fail, or not run. “Not run” is a common status and an honest one. A gate that never ran must not be reported as passing.
Port contracts
Port contracts are where compatibility and qualification overlap. For each input and output, state:
- the signal type and schema;
- whether it is required, and its default if not;
- the scientific meaning, the units, and the validation applied;
- what happens on failure — and specifically, what is not emitted.
Then make three things agree: the canonical io block in model.yaml, the typed SignalSpec declarations in Python, and the lab output map. Biosimulant checks that they agree. It can’t check that they’re right.
A port with no reviewed cross-family meaning should map to a model-specific profile rather than borrow a general one. See Profile catalogue.
What qualification never does
- It does not convert units or infer missing scientific context.
- It does not make a successful run into experimental evidence.
- It does not transfer: a model qualified for one intended use is unqualified for another until that case is reviewed.
- It does not override the caveats in a run’s Evidence Passport.
Next steps
- Check scientific outputs: declaring acceptance checks that run with the model
- Profile catalogue: the six profiles and their limits
- Propose a profile: when your port has no honest match
- Passports and evidence: what a run records