<!-- Source: https://docs.biosimulant.com/references/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.

## Local runs: `structure3d` sources

In `biosimulant labs serve`, point a `structure3d` visual at a file with `source.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),
            },
        },
    }
```

When Labs Serve collects run results, it resolves `path`. If the file exists, it
records the file as a run artifact and sets `source.url` to
`/api/runs/{run_id}/artifacts/{artifact_id}`. If `artifact_id` is missing, one is
derived from the path. A `source.url` you set yourself is left unchanged.

## Remote runs: the `structure_artifacts` output

Remote runs on the hosted platform also read a module output named
`structure_artifacts`. This is a platform convention. The open-source package
does not act on it.

Emit a record whose value holds fields ending in `_file`, either directly or
under a `payload` key:

```python
def outputs(self):
    return {
        "structure_artifacts": biosim.SignalSpec.record(
            schema={"payload": "json"},
            description="Files produced by the docking run.",
        )
    }

def execute(self, inputs, *, context):
    ...
    return {
        "structure_artifacts": {
            "payload": {
                "docking_output_file": str(self.output_pdbqt),
                "top_complex_file": str(self.top_complex_pdb),
                "pose_summary_file": str(self.pose_summary_json),
            }
        }
    }
```

For each `*_file` value that points at an existing file, the remote executor
uploads the file with its size and SHA-256 hash and replaces the path in the run
results with an artifact reference. Paths that do not exist are skipped. If a
`structure3d` visual uses the same `source.path`, its `artifact_id` is reused.

Return each file separately. Do not return directories as `*_file` values. A
non-file field such as `prediction_dir` can name the folder that groups them.

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

## See Also

- [BioSignal & Metadata](/references/signals)
- [Visualization Contract](/references/visualization)
- [Labs Serve UI](/references/labs-serve)