llm-batch-annotate 0.1.0__tar.gz

llm_batch_annotate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Paula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_batch_annotate-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: llm-batch-annotate
+Version: 0.1.0
+Summary: Batch-oriented LLM annotation workflows for tabular datasets with OpenAI Batch support.
+Author: Felipe Paula
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/felipepaula/batch_api_annotate
+Project-URL: Documentation, https://llm-batch-annotate.readthedocs.io/
+Project-URL: Repository, https://github.com/felipepaula/batch_api_annotate
+Project-URL: Issues, https://github.com/felipepaula/batch_api_annotate/issues
+Keywords: annotation,batch,llm,openai,pydantic,tabular-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Requires-Dist: myst-parser<5,>=4; extra == "docs"
+Requires-Dist: sphinx<9,>=8; extra == "docs"
+Dynamic: license-file
+
+# `llm-batch-annotate`
+
+`llm-batch-annotate` is a Python package for running reproducible LLM annotation workflows over tabular datasets. It materializes units from source rows, groups them into provider requests, submits them through an execution adapter, parses structured outputs, validates coverage, and writes run artifacts for auditability.
+
+## Highlights
+
+- single-unit and grouped annotation workflows
+- provider-agnostic task, builder, parser, and artifact abstractions
+- concrete OpenAI Batch adapter
+- resumable CLI-driven runs with persisted manifests
+- example configs, prompts, schemas, and sample data under `examples/`
+
+## Installation
+
+When the package is published:
+
+```bash
+pip install llm-batch-annotate
+```
+
+From a local checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .[test,docs]
+```
+
+## Quickstart
+
+Single-unit example:
+
+```bash
+export OPEN_AI_KEY="your-key"
+llm-batch-annotate run examples/config/run_config.json --run-id example-single --no-poll-until-terminal
+llm-batch-annotate resume examples/config/run_config.json example-single --poll-interval 2m
+```
+
+Grouped example:
+
+```bash
+export OPEN_AI_KEY="your-key"
+llm-batch-annotate run examples/config/run_config_2.json --run-id example-grouped --no-poll-until-terminal
+llm-batch-annotate resume examples/config/run_config_2.json example-grouped --poll-interval 2m
+```
+
+## Documentation
+
+Project documentation is intended to be hosted on Read the Docs. The Sphinx source lives under `docs/`.
+
+Planned public docs include:
+
+- installation
+- quickstart
+- CLI reference
+- config reference
+- OpenAI Batch provider guide
+- worked examples
+- API reference
+- development and release notes
+
+## Repository layout
+
+- `src/llm_batch_annotate/`: package source
+- `examples/`: tracked example inputs and configs
+- `tests/`: pytest suite
+- `docs/`: Sphinx documentation source
+
+Generated example runs are written to `examples/runs/` and are intentionally excluded from version control.

llm_batch_annotate-0.1.0/README.md

@@ -0,0 +1,68 @@
+# `llm-batch-annotate`
+
+`llm-batch-annotate` is a Python package for running reproducible LLM annotation workflows over tabular datasets. It materializes units from source rows, groups them into provider requests, submits them through an execution adapter, parses structured outputs, validates coverage, and writes run artifacts for auditability.
+
+## Highlights
+
+- single-unit and grouped annotation workflows
+- provider-agnostic task, builder, parser, and artifact abstractions
+- concrete OpenAI Batch adapter
+- resumable CLI-driven runs with persisted manifests
+- example configs, prompts, schemas, and sample data under `examples/`
+
+## Installation
+
+When the package is published:
+
+```bash
+pip install llm-batch-annotate
+```
+
+From a local checkout:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .[test,docs]
+```
+
+## Quickstart
+
+Single-unit example:
+
+```bash
+export OPEN_AI_KEY="your-key"
+llm-batch-annotate run examples/config/run_config.json --run-id example-single --no-poll-until-terminal
+llm-batch-annotate resume examples/config/run_config.json example-single --poll-interval 2m
+```
+
+Grouped example:
+
+```bash
+export OPEN_AI_KEY="your-key"
+llm-batch-annotate run examples/config/run_config_2.json --run-id example-grouped --no-poll-until-terminal
+llm-batch-annotate resume examples/config/run_config_2.json example-grouped --poll-interval 2m
+```
+
+## Documentation
+
+Project documentation is intended to be hosted on Read the Docs. The Sphinx source lives under `docs/`.
+
+Planned public docs include:
+
+- installation
+- quickstart
+- CLI reference
+- config reference
+- OpenAI Batch provider guide
+- worked examples
+- API reference
+- development and release notes
+
+## Repository layout
+
+- `src/llm_batch_annotate/`: package source
+- `examples/`: tracked example inputs and configs
+- `tests/`: pytest suite
+- `docs/`: Sphinx documentation source
+
+Generated example runs are written to `examples/runs/` and are intentionally excluded from version control.

llm_batch_annotate-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "llm-batch-annotate"
+dynamic = ["version"]
+description = "Batch-oriented LLM annotation workflows for tabular datasets with OpenAI Batch support."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Felipe Paula"},
+]
+keywords = [
+  "annotation",
+  "batch",
+  "llm",
+  "openai",
+  "pydantic",
+  "tabular-data",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/felipepaula/batch_api_annotate"
+Documentation = "https://llm-batch-annotate.readthedocs.io/"
+Repository = "https://github.com/felipepaula/batch_api_annotate"
+Issues = "https://github.com/felipepaula/batch_api_annotate/issues"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8,<9",
+]
+docs = [
+  "furo>=2024.8.6",
+  "myst-parser>=4,<5",
+  "sphinx>=8,<9",
+]
+
+[project.scripts]
+llm-batch-annotate = "llm_batch_annotate.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.dynamic]
+version = {attr = "llm_batch_annotate._version.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

llm_batch_annotate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

llm_batch_annotate-0.1.0/src/llm_batch_annotate/__init__.py

@@ -0,0 +1,193 @@
+"""Public package exports for llm_batch_annotate."""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .artifacts.naming import (
+    ARTIFACT_REGISTRY,
+    ArtifactDefinition,
+    artifact_path,
+    artifact_ref,
+    artifact_refs_for_run,
+    artifact_relative_path,
+    get_artifact_definition,
+    run_directory,
+)
+from .artifacts.local import LocalArtifactStore
+from .builders import (
+    BaseBuilder,
+    ProgrammaticBuilderBase,
+    PromptAssetBundle,
+    SimpleTemplateBuilder,
+    load_prompt_asset_text,
+    load_prompt_assets,
+    resolve_prompt_asset_path,
+)
+from .configs.models import (
+    ArtifactStoreConfig,
+    ArtifactStoreSelectionConfig,
+    BaseProviderConfig,
+    GenericProviderConfig,
+    GroupingConfig,
+    OpenAIBatchConfig,
+    OutputConfig,
+    PromptAssetsConfig,
+    ProviderConfig,
+    ProviderSelectionConfig,
+    RetryPolicyConfig,
+    RunConfig,
+    RunMetadataConfig,
+    SourceInputConfig,
+)
+from .contracts.base import ArtifactStore, BaseMessageBuilder, BaseParser, BaseTask, ExecutionProvider
+from .contracts.records import (
+    AnnotationRecord,
+    ArtifactRef,
+    ComponentRef,
+    ExecutionHandle,
+    FailureRecord,
+    GroupRecord,
+    GroupMembershipRecord,
+    ParsedRequestRecord,
+    ProviderCapabilities,
+    RawErrorRecord,
+    RawOutputRecord,
+    RawResultRecord,
+    RequestRecord,
+    UnitRecord,
+)
+from .execution import (
+    ExecutionProviderBase,
+    OpenAIBatchProvider,
+    OpenAIBatchProviderError,
+    SUCCESSFUL_EXECUTION_STATUSES,
+    TERMINAL_EXECUTION_STATUSES,
+    is_successful_execution_status,
+    is_terminal_execution_status,
+    normalize_execution_status,
+)
+from .enums import (
+    ArtifactFormat,
+    ArtifactKind,
+    ArtifactStoreKind,
+    ExecutionStatus,
+    FailureKind,
+    GroupingStrategy,
+    ProviderKind,
+    RunStatus,
+    SourceFormat,
+    TaskKind,
+)
+from .manifests.models import (
+    ComponentIdentitySummary,
+    GroupingSummary,
+    InputSummary,
+    LineageSummary,
+    ParseSummary,
+    RunManifest,
+    ValidationSummary,
+)
+from .orchestration import OfflineTaskPipeline, OfflineTaskPipelineResult, TaskOrchestrator, TaskRunState, default_run_id
+from .parsers import BaseOutputParser, StructuredOutputParser
+from .tasks import ComposedTaskBase, GroupedTaskBase, SingleTaskBase
+from .grouping.fixed_size import build_group_memberships, membership_map, plan_fixed_size_groups
+from .units.materialization import derive_unit_id, materialize_units, validate_unique_unit_ids
+from .validation.coverage import CoverageValidationResult, coverage_failures, validate_coverage, validate_group_coverage
+
+__all__ = [
+    "ARTIFACT_REGISTRY",
+    "AnnotationRecord",
+    "ArtifactDefinition",
+    "ArtifactFormat",
+    "ArtifactKind",
+    "ArtifactRef",
+    "ArtifactStore",
+    "LocalArtifactStore",
+    "ArtifactStoreConfig",
+    "ArtifactStoreKind",
+    "ArtifactStoreSelectionConfig",
+    "BaseBuilder",
+    "BaseMessageBuilder",
+    "BaseOutputParser",
+    "BaseParser",
+    "BaseProviderConfig",
+    "BaseTask",
+    "ComposedTaskBase",
+    "ComponentIdentitySummary",
+    "ComponentRef",
+    "ExecutionHandle",
+    "ExecutionProvider",
+    "ExecutionProviderBase",
+    "ExecutionStatus",
+    "FailureKind",
+    "FailureRecord",
+    "GenericProviderConfig",
+    "GroupRecord",
+    "GroupMembershipRecord",
+    "GroupingConfig",
+    "GroupingStrategy",
+    "GroupingSummary",
+    "GroupedTaskBase",
+    "InputSummary",
+    "LineageSummary",
+    "OfflineTaskPipeline",
+    "OfflineTaskPipelineResult",
+    "OpenAIBatchConfig",
+    "OpenAIBatchProvider",
+    "OpenAIBatchProviderError",
+    "OutputConfig",
+    "ParseSummary",
+    "ParsedRequestRecord",
+    "ProgrammaticBuilderBase",
+    "PromptAssetBundle",
+    "PromptAssetsConfig",
+    "ProviderCapabilities",
+    "ProviderConfig",
+    "ProviderKind",
+    "ProviderSelectionConfig",
+    "RawErrorRecord",
+    "RawOutputRecord",
+    "RawResultRecord",
+    "RequestRecord",
+    "RetryPolicyConfig",
+    "RunConfig",
+    "RunManifest",
+    "RunMetadataConfig",
+    "RunStatus",
+    "SingleTaskBase",
+    "SimpleTemplateBuilder",
+    "SourceFormat",
+    "SourceInputConfig",
+    "StructuredOutputParser",
+    "SUCCESSFUL_EXECUTION_STATUSES",
+    "TaskKind",
+    "TaskOrchestrator",
+    "TaskRunState",
+    "TERMINAL_EXECUTION_STATUSES",
+    "UnitRecord",
+    "ValidationSummary",
+    "CoverageValidationResult",
+    "artifact_path",
+    "artifact_ref",
+    "artifact_refs_for_run",
+    "artifact_relative_path",
+    "build_group_memberships",
+    "coverage_failures",
+    "default_run_id",
+    "derive_unit_id",
+    "get_artifact_definition",
+    "load_prompt_asset_text",
+    "load_prompt_assets",
+    "materialize_units",
+    "membership_map",
+    "normalize_execution_status",
+    "plan_fixed_size_groups",
+    "resolve_prompt_asset_path",
+    "run_directory",
+    "is_successful_execution_status",
+    "is_terminal_execution_status",
+    "validate_coverage",
+    "validate_group_coverage",
+    "validate_unique_unit_ids",
+    "__version__",
+]

llm_batch_annotate-0.1.0/src/llm_batch_annotate/_model.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FrameworkModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        validate_assignment=True,
+    )

llm_batch_annotate-0.1.0/src/llm_batch_annotate/_version.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.1.0"

llm_batch_annotate-0.1.0/src/llm_batch_annotate/artifacts/__init__.py

@@ -0,0 +1,23 @@
+from .naming import (
+    ARTIFACT_REGISTRY,
+    ArtifactDefinition,
+    artifact_path,
+    artifact_ref,
+    artifact_refs_for_run,
+    artifact_relative_path,
+    get_artifact_definition,
+    run_directory,
+)
+from .local import LocalArtifactStore
+
+__all__ = [
+    "ARTIFACT_REGISTRY",
+    "ArtifactDefinition",
+    "LocalArtifactStore",
+    "artifact_path",
+    "artifact_ref",
+    "artifact_refs_for_run",
+    "artifact_relative_path",
+    "get_artifact_definition",
+    "run_directory",
+]

llm_batch_annotate-0.1.0/src/llm_batch_annotate/artifacts/local.py

@@ -0,0 +1,86 @@
+"""Filesystem-backed artifact store implementation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..configs.models import ArtifactStoreConfig
+from ..contracts.base import ArtifactStore
+from ..contracts.records import ArtifactRef
+from ..enums import ArtifactFormat, ArtifactKind, ArtifactStoreKind
+from ..manifests.models import RunManifest
+from .naming import ARTIFACT_REGISTRY, artifact_path, artifact_ref, run_directory
+
+
+class LocalArtifactStore(ArtifactStore):
+    """Persist run artifacts under a canonical local directory tree."""
+
+    def validate_config(self, config: ArtifactStoreConfig) -> None:
+        if config.kind is not ArtifactStoreKind.LOCAL:
+            msg = "LocalArtifactStore requires ArtifactStoreConfig.kind='local'"
+            raise ValueError(msg)
+
+    def run_path(self, run_id: str, config: ArtifactStoreConfig) -> Path:
+        self.validate_config(config)
+        return run_directory(run_id=run_id, runs_root=config.root_dir)
+
+    def artifact_path(self, run_id: str, artifact_kind: ArtifactKind, config: ArtifactStoreConfig) -> Path:
+        self.validate_config(config)
+        return artifact_path(run_id=run_id, artifact_kind=artifact_kind, runs_root=config.root_dir)
+
+    def initialize_run(self, run_id: str, config: ArtifactStoreConfig) -> Path:
+        run_path = self.run_path(run_id, config)
+        run_path.mkdir(parents=True, exist_ok=True)
+
+        for definition in ARTIFACT_REGISTRY.values():
+            (run_path / definition.relative_path.parent).mkdir(parents=True, exist_ok=True)
+
+        return run_path
+
+    def write_artifact(
+        self,
+        run_id: str,
+        artifact_kind: ArtifactKind,
+        content: str | bytes,
+        config: ArtifactStoreConfig,
+    ) -> ArtifactRef:
+        artifact_file = self.artifact_path(run_id, artifact_kind, config)
+        artifact_file.parent.mkdir(parents=True, exist_ok=True)
+
+        if isinstance(content, bytes):
+            artifact_file.write_bytes(content)
+        else:
+            artifact_file.write_text(content, encoding="utf-8")
+
+        return artifact_ref(artifact_kind)
+
+    def read_artifact(
+        self,
+        run_id: str,
+        artifact_kind: ArtifactKind,
+        config: ArtifactStoreConfig,
+    ) -> str | bytes:
+        artifact_file = self.artifact_path(run_id, artifact_kind, config)
+        artifact = artifact_ref(artifact_kind)
+
+        if artifact.format in {ArtifactFormat.JSON, ArtifactFormat.JSONL}:
+            return artifact_file.read_text(encoding="utf-8")
+        return artifact_file.read_bytes()
+
+    def resolve_artifact(
+        self,
+        run_id: str,
+        artifact_kind: ArtifactKind,
+        config: ArtifactStoreConfig,
+    ) -> ArtifactRef:
+        _ = self.artifact_path(run_id, artifact_kind, config)
+        return artifact_ref(artifact_kind)
+
+    def write_manifest(self, manifest: RunManifest, config: ArtifactStoreConfig) -> ArtifactRef:
+        self.initialize_run(manifest.run_id, config)
+        return self.write_artifact(
+            manifest.run_id,
+            ArtifactKind.MANIFEST,
+            manifest.model_dump_json(indent=2),
+            config,
+        )

llm_batch_annotate-0.1.0/src/llm_batch_annotate/artifacts/naming.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from ..contracts.records import ArtifactRef
+from ..enums import ArtifactFormat, ArtifactKind
+
+
+@dataclass(frozen=True)
+class ArtifactDefinition:
+    artifact_kind: ArtifactKind
+    format: ArtifactFormat
+    relative_path: PurePosixPath
+
+
+ARTIFACT_REGISTRY: dict[ArtifactKind, ArtifactDefinition] = {
+    ArtifactKind.RUN_CONFIG: ArtifactDefinition(
+        artifact_kind=ArtifactKind.RUN_CONFIG,
+        format=ArtifactFormat.JSON,
+        relative_path=PurePosixPath("config/run_config.json"),
+    ),
+    ArtifactKind.MANIFEST: ArtifactDefinition(
+        artifact_kind=ArtifactKind.MANIFEST,
+        format=ArtifactFormat.JSON,
+        relative_path=PurePosixPath("metadata/manifest.json"),
+    ),
+    ArtifactKind.SUMMARY: ArtifactDefinition(
+        artifact_kind=ArtifactKind.SUMMARY,
+        format=ArtifactFormat.JSON,
+        relative_path=PurePosixPath("metadata/summary.json"),
+    ),
+    ArtifactKind.UNITS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.UNITS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("tables/units.jsonl"),
+    ),
+    ArtifactKind.GROUPS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.GROUPS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("tables/groups.jsonl"),
+    ),
+    ArtifactKind.REQUESTS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.REQUESTS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("tables/requests.jsonl"),
+    ),
+    ArtifactKind.RAW_OUTPUTS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.RAW_OUTPUTS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("raw/raw_outputs.jsonl"),
+    ),
+    ArtifactKind.RAW_ERRORS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.RAW_ERRORS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("raw/raw_errors.jsonl"),
+    ),
+    ArtifactKind.PARSED_REQUESTS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.PARSED_REQUESTS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("parsed/parsed_requests.jsonl"),
+    ),
+    ArtifactKind.FLATTENED_ANNOTATIONS: ArtifactDefinition(
+        artifact_kind=ArtifactKind.FLATTENED_ANNOTATIONS,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("parsed/flattened_annotations.jsonl"),
+    ),
+    ArtifactKind.FAILURES: ArtifactDefinition(
+        artifact_kind=ArtifactKind.FAILURES,
+        format=ArtifactFormat.JSONL,
+        relative_path=PurePosixPath("parsed/failures.jsonl"),
+    ),
+}
+
+
+def get_artifact_definition(artifact_kind: ArtifactKind) -> ArtifactDefinition:
+    return ARTIFACT_REGISTRY[artifact_kind]
+
+
+def run_directory(run_id: str, runs_root: str | Path = "runs") -> Path:
+    return Path(runs_root) / run_id
+
+
+def artifact_relative_path(artifact_kind: ArtifactKind) -> PurePosixPath:
+    return get_artifact_definition(artifact_kind).relative_path
+
+
+def artifact_path(run_id: str, artifact_kind: ArtifactKind, runs_root: str | Path = "runs") -> Path:
+    return run_directory(run_id=run_id, runs_root=runs_root) / artifact_relative_path(artifact_kind)
+
+
+def artifact_ref(artifact_kind: ArtifactKind) -> ArtifactRef:
+    definition = get_artifact_definition(artifact_kind)
+    return ArtifactRef(
+        artifact_kind=definition.artifact_kind,
+        format=definition.format,
+        relative_path=str(definition.relative_path),
+    )
+
+
+def artifact_refs_for_run(run_id: str, runs_root: str | Path = "runs") -> dict[ArtifactKind, ArtifactRef]:
+    _ = run_directory(run_id=run_id, runs_root=runs_root)
+    return {artifact_kind: artifact_ref(artifact_kind) for artifact_kind in ARTIFACT_REGISTRY}