Artifact Outputs

Use artifact outputs when a module produces files that need to survive beyond the Python process, such as structures, ranked poses, reports, images, or summary JSON.

The `structure_artifacts` signal

For structure-like outputs, emit a record signal named structure_artifacts. Its payload should contain file fields whose names end in _file.

def outputs(self):
    return {
        "structure_artifacts": biosim.SignalSpec.record(
            schema={"payload": "json"},
            description="Files produced by the docking run.",
        )
    }
 
def get_outputs(self):
    return {
        "structure_artifacts": biosim.RecordSignal(
            source="vina",
            name="structure_artifacts",
            emitted_at=self.t,
            spec=self.outputs()["structure_artifacts"],
            value={
                "payload": {
                    "docking_output_file": str(self.output_pdbqt),
                    "top_complex_file": str(self.top_complex_pdb),
                    "pose_summary_file": str(self.pose_summary_json),
                }
            },
        )
    }

Common roles include:

Field	Meaning
`structure_file`	Primary structure file for a module.
`top_complex_file`	Merged receptor-ligand or predicted complex.
`docking_output_file`	Docking engine output such as PDBQT or SDF.
`pose_summary_file`	JSON summary of ranked poses.
`rank_1_file`, `rank_2_file`	Individual ranked pose files.

File requirements

Every *_file value must be a path to a local file that exists when get_outputs() returns. The path may point into a temporary runtime directory; Biosimulant copies or uploads the file before the run is finalized.

Do not return directories as *_file values. If a directory groups several artifacts, return each file separately and optionally add a non-file metadata field such as prediction_dir.

Remote execution

For remote runs, the sandbox automatically detects structure_artifacts, uploads each declared *_file to the backend, verifies its size and SHA-256 hash, and rewrites final results to durable artifact references. Model code does not need to call backend APIs directly.

The backend stores completed uploads as run artifacts. Desktop, Hub, downloads, and visualizers read those artifacts through normal run permissions.

Original sandbox paths are debug metadata only. They are not used as the download source once the artifact is uploaded.

Privacy and access

Artifact visibility is controlled by the backend. If a run or lab is private, its artifacts are private. Public access only follows the same run, lab, and Hub permission rules used by the rest of Biosimulant.

The internal remote upload channel is write-only for one run, short-lived, and authenticated by a scoped token issued during remote submission.

Visualizers

Structure visualizers should reference the artifact ID rather than a runtime path:

def visualize(self):
    return {
        "render": "structure3d",
        "data": {
            "title": "Top ranked complex",
            "format": "pdb",
            "source": {
                "kind": "artifact",
                "artifact_id": "top-complex",
                "path": str(self.top_complex_pdb),
            },
        },
    }

For local runs, path can be a local file path. For remote runs, Biosimulant resolves artifact_id through the backend artifact API.