From 3929a7929b3278187b165593fd2063f0f718f0d2 Mon Sep 17 00:00:00 2001 From: Christian Dominguez Dalmases Date: Wed, 2 Sep 2026 10:40:35 +0200 Subject: [PATCH] docs(artifact): document labels on BaseArtifact Companion to temple-compute/horus-runtime#183, which adds BaseArtifact.labels: free-form string metadata the runtime never interprets or uses for caching, for whatever reads the workflow afterwards (a UI, a lineage query). --- content/docs/guides/writing-workflows-yaml.mdx | 13 +++++++++++++ content/docs/sdk/core/artifact.mdx | 5 +++++ 2 files changed, 18 insertions(+) diff --git a/content/docs/guides/writing-workflows-yaml.mdx b/content/docs/guides/writing-workflows-yaml.mdx index cd2f6a4..2c156b3 100644 --- a/content/docs/guides/writing-workflows-yaml.mdx +++ b/content/docs/guides/writing-workflows-yaml.mdx @@ -94,6 +94,19 @@ outputs: Each artifact has an `id` (unique within the task's inputs or outputs) and a `path`. A task counts as complete when all of its `outputs` exist on disk. +An artifact may also carry `labels`, a free-form `string: string` mapping the +runtime never reads: + +```yaml +outputs: + - { kind: file, id: scored, path: batch_017.parquet, labels: { subject: batch_017, role: measurement } } +``` + +They exist for whatever reads the workflow afterwards, not for the run +itself: a UI grouping nodes, or a lineage query answering "everything derived +from subject X." A domain expresses its own structure through labels instead +of the runtime growing a field per domain. + The **directory containing** each output is created before the task runs, so `path: "./out/model.pkl"` works even when `out/` does not exist yet. No task needs a `mkdir` step of its own. diff --git a/content/docs/sdk/core/artifact.mdx b/content/docs/sdk/core/artifact.mdx index d0cb1b7..803b127 100644 --- a/content/docs/sdk/core/artifact.mdx +++ b/content/docs/sdk/core/artifact.mdx @@ -39,6 +39,11 @@ Each artifact: unique (see [DAG planning](/sdk/core/workflow#dag-planning) and [edges](/sdk/core/workflow#edges)). - Has a **path** identifying its location on disk +- Carries optional **`labels`**: a `dict[str, str]` of free-form metadata + (`labels: {subject: batch_017, role: measurement}`). The runtime never + interprets them and they play no part in caching; they exist for whatever + reads the workflow afterwards, such as a UI grouping nodes or a lineage + query. - Defines: - How to **read** its contents back into a Python object - How to **write** a Python object to its file representation