stuff

src/wf_artifacts/__init__.py

@@ -1,3 +1,8 @@
+from .catalog import (
+    WorkflowArtifactCatalogEntry,
+    artifact_catalog_entry,
+    artifact_node_name,
+)
 from .models import (
     AvailableCapability,
     AvailableSource,
@@ -20,7 +25,10 @@ __all__ = [
     "FileWorkflowArtifactStore",
     "RequiredCapability",
     "WorkflowArtifact",
+    "WorkflowArtifactCatalogEntry",
     "WorkflowArtifactStore",
     "WorkflowDeployment",
+    "artifact_catalog_entry",
+    "artifact_node_name",
     "validate_deployment_dependencies",
 ]

src/wf_artifacts/catalog.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from .models import DependencyDiagnostic, JsonObject, WorkflowArtifact
+
+
+class WorkflowArtifactCatalogEntry(BaseModel):
+    """NodeSpec-shaped projection of a saved workflow artifact."""
+
+    name: str
+    display_name: str
+    description: str | None = None
+    outcomes: tuple[str, ...]
+    input_schema: JsonObject
+    output_schema: JsonObject
+    required_sources: tuple[str, ...] = Field(default_factory=tuple)
+    diagnostics: tuple[DependencyDiagnostic, ...] = Field(default_factory=tuple)
+
+
+def artifact_node_name(artifact: WorkflowArtifact) -> str:
+    """Return the stable planner name for an artifact version."""
+    return f"workflow.{artifact.id}.v{artifact.version}"
+
+
+def artifact_catalog_entry(
+    artifact: WorkflowArtifact,
+    *,
+    diagnostics: list[DependencyDiagnostic] | tuple[DependencyDiagnostic, ...] = (),
+) -> WorkflowArtifactCatalogEntry:
+    """Project an artifact as a catalog entry without exposing its internal plan."""
+    required_sources = sorted(
+        {
+            capability.logical_source
+            for capability in artifact.required_capabilities.values()
+        }
+    )
+    return WorkflowArtifactCatalogEntry(
+        name=artifact_node_name(artifact),
+        display_name=artifact.title,
+        description=artifact.description,
+        outcomes=artifact.outcomes,
+        input_schema=artifact.input_schema,
+        output_schema=artifact.output_schema,
+        required_sources=tuple(required_sources),
+        diagnostics=tuple(diagnostics),
+    )