---
name: biosimulant-sbml
description: Author or revise an SBML-backed Biosimulant model from an exact source artifact while preserving equations, identifiers, units, events, provenance, tests, and intended-use limits.
metadata:
  version: "2026.09.15"
---

# SBML model work

For an account-backed workspace, fetch an exact BioModels artifact with authenticated MCP and place it in the workspace by opaque resource ID. Preserve the original SBML bytes and checksum. For local/offline work, pin the downloaded file and checksum in the local project instead. Build a thin `TelluriumSBMLBioModule` integration around the source; do not manually rewrite equations or parameters to make execution easier.

Inspect the installed `TelluriumSBMLBioModule` contract before authoring its
subclass. Its public constructor accepts `model_path` and optional
`integration_step`; declare adapter behavior with the supported class metadata
such as `_OBSERVABLES`, `_PARAMETER_INPUTS`, `_INITIAL_CONDITION_INPUTS`,
`_MULTIPLIER_INPUTS`, output aliases, and visualization hooks. Do not invent
constructor keywords, assume a manifest declaration configures the Python
adapter, or hide an unsupported source perturbation behind an approximate
parameter change.

Distinguish global SBML parameters from reaction-local kinetic-law parameters.
Before exposing any parameter, prove the native runtime can address that exact
identifier. A local XML ID such as `V1` does not become a global RoadRunner
selection merely because it appears in the source. When the requested value is
already immutable in the source and cannot be addressed, keep it unexposed; an
upstream component may validate a locked reference value but must not claim it
mutated the SBML.

Document species/parameter mappings, public ports, units, event semantics, solver assumptions, initialization, and supported perturbations in the MTS. Add tests for source parsing, declared inputs/outputs, units, representative trajectories, conservation or invariant checks where scientifically applicable, and failure behavior. Pin literature or database evidence separately. Report solver or model limitations in caveats.

When opting into model compatibility, bind exact profiles to the existing `io`
ports and declare SBML entity identifiers, compartments, quantity semantics,
units, time basis, and event/state lifecycle in `contract`. Do not infer missing
source annotations merely to make a profile validate.

Treat missing source units as missing metadata. Preserve the source convention
or require an explicit, cited conversion; do not relabel an unannotated SBML
quantity as nM, nM/minute, or another physical unit. Native-runtime parity must
execute an independent reference path against the immutable source and compare
the resulting trajectory. A value asserted by the adapter under test is not an
independent parity result.

Verify the physical/evaluation time basis with an executed source trajectory.
Do not equate requested minutes with raw SBML time units when the source omits a
complete time-unit declaration. If the intended-use protocol defines a
conversion, record it explicitly, apply it consistently to run duration,
sampling, peak times, and plots, and retain both raw source time and reported
time semantics.

Keep the source-faithful time-course adapter on its supported temporal hook. Any
new finite preprocessor uses `execute(inputs, *, context)` with the imported enum
member `ExecutionPolicy.ONCE_BEFORE_RUN`; never use the invalid quoted uppercase
string `"ONCE_BEFORE_RUN"`.


## Visualization deliverables

Before authoring, call `get_biosimulant_authoring_contract` with topic `visualization`.
The complete catalog contains timeseries, bar, scatter, heatmap, graph, table, image,
structure3d and text, including payload examples, limits and retained artifact rules.
Almost every scientific Lab needs a useful visual of actual computed outputs; choose
the type by the user's question rather than always emitting a table. Record expected
views, source outputs, units and caveats in the MRS; record render/schema, owning module,
typed wiring, lifecycle, artifact retention and executable checks in the MTS.
Implement reusable `BioModule.visualize()` and declare `lab.yaml` visualization requirements
(or a justified opt-out for infrastructure-only work). Inspect actual composed results,
check plotted values against typed outputs, and verify artifacts and reopening. Missing
or invalid required views block qualification/publication. Ad-hoc Studio chat charts
do not satisfy this contract. Historical Labs without a declaration remain compatible.