<!-- Source: https://docs.biosimulant.com/references/library/artifact-outputs -->

# 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`.

```python
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:

```python
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.

## See Also

- [BioSignal & Metadata](/references/library/signals)
- [Visualization Contract](/references/library/visualization)
- [How to Create a BioModule](/how-to/library/create-biomodule)