Assets

Assets are how runs produce durable outputs (checkpoints, reports, datasets, environment snapshots) and how researchers attach research documents to experiments. methodic supports two upload paths depending on size and shape, plus convenience helpers on Run and chronicle.assets.

Inline (small structured payloads)

For research reports, environment snapshots, and other small payloads, post the content inline and Chronicle auto-finalizes:

# Worker side — auto-populates output_of from the bound run
run.upload_asset(
    asset_type="takeaways_report",
    content={
        "summary": "Loss converged at step 12000",
        "key_findings": [...],
    },
)

# Researcher side — explicit (no run context)
chronicle.assets.create_inline(
    asset_type="research_report",
    content={"notes": "..."},
)

Reserved asset types Chronicle knows about:

• hypothesis_report — full hypothesis document, submitted at experiment creation
• takeaways_report — post-experiment analysis
• research_report — general research documents (literature review, synthesis)

You can use any other string for custom asset types.

Markdown / plain text

For human-readable docs (research reports, notes), pass the text as content and override the content type:

hypothesis = open("hypothesis.md").read()
chronicle.assets.create_inline(
    asset_type="hypothesis_report",
    content=hypothesis,
    content_type="text/markdown",
)

Binary (presigned URL flow)

For checkpoints, large datasets, or anything you'd rather not pipe through Chronicle, the upload goes directly to cloud storage. Three steps:

# 1. Register the asset and get presigned URLs (one per component)
upload_info = run.create_asset_presigned(
    asset_type="checkpoint",
    components=["model.safetensors", "optimizer.pt", "metadata.json"],
)

# 2. PUT each component to its presigned URL
for filename, url in upload_info.upload_urls.items():
    run.upload_component(url, local_path=Path(f"./out/{filename}"), content_type="application/octet-stream")

# 3. Finalize — asset transitions to `ready` and becomes immutable
run.finalize_asset(upload_info.asset_id)

For convenience, run.upload_directory_async() does all three steps for a directory of files in the background.

Asset states

State	Meaning
pending	Created, components not all uploaded yet
ready	Finalized, immutable, available as an input to other variations
abandoned	Run failed before finalize; storage may be GC'd

Validity flags (read-only)

Chronicle may mark an asset:

• deprecated — soft warning, asset still usable
• invalidated — hard block; Chronicle won't accept it as a new input without allow_invalid_assets: true. Outputs of a retracted experiment are invalidated automatically.

These flags don't change the lifecycle state; they're orthogonal annotations.

Downloading

chronicle.assets.download(asset_id, local_dir=Path("./checkpoint"))

Single GET request: chronicle.assets.get(asset_id, include_presigned=True) returns metadata + presigned read URLs in one call, which download consumes. Files stream straight to disk.