Artifact Tools

The artifact tools family contains a single tool — get_artifact — that fetches artifact metadata and a download URI by artifact_id. Artifacts are the durable outputs of runs: every backtest produces an 8-file bundle, and every skill run produces its own artifacts. Each file is content-hashed with SHA-256 so reproducibility can be verified independently.

`get_artifact`

Fetch artifact metadata and a download URI by artifact_id. The URI is a short-lived, signed URL — it expires after a few minutes. Fetch the content promptly after calling get_artifact.

Arguments

Argument	Type	Required	Description
`artifact_id`	string	Yes	The artifact identifier.

Return value

Field	Type	Description
`artifact_id`	string	The artifact identifier.
`run_id`	string	The run that produced this artifact.
`filename`	string	The file name within the bundle (e.g. `metrics.json`).
`content_type`	string	MIME type (e.g. `application/json`, `text/html`).
`content_hash`	string	SHA-256 hash of the file content.
`size_bytes`	integer	File size in bytes.
`uri`	string	Short-lived signed download URL.
`expires_at`	string (ISO 8601)	When the signed URL expires.

Example call

{ "artifact_id": "art_01HQKX2J3K4M5N6P7R8S9T0V2B" }

Example response

{
  "artifact_id": "art_01HQKX2J3K4M5N6P7R8S9T0V2B",
  "run_id": "run_01HQKX2J3K4M5N6P7R8S9T0V2A",
  "filename": "metrics.json",
  "content_type": "application/json",
  "content_hash": "sha256:d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5",
  "size_bytes": 1843,
  "uri": "https://artifacts.doomberg.me/run_01.../metrics.json?sig=...",
  "expires_at": "2025-01-15T14:45:00.000Z"
}

The 8-file backtest artifact bundle

Every backtest_run produces a bundle of exactly 8 files. Together they form a complete, reproducible record of the backtest. The bundle is stored as a group; the artifact_bundle returned by backtest_run points to all 8.

File	Content type	Description
`summary.json`	application/json	Top-level summary: run ID, strategy ID, range, engine version, final stats, and pointers to the other 7 files.
`metrics.json`	application/json	Full statistics block: Sharpe, Sortino, CAGR, max drawdown, win rate, turnover, VaR, CVaR, and per-period returns.
`equity_curve.json`	application/json	The complete equity curve as an array of `{ date, equity }` points.
`positions.json`	application/json	The position history: per-date weights for every symbol in the universe, including cash.
`data_manifest.json`	application/json	Manifest of every data input: symbol, date range, interval, provider, and content hash for each OHLCV series used.
`environment_lock.json`	application/json	The execution environment: numpy version, engine version, Python version, and OS platform.
`run_trace.json`	application/json	The chronological event log from the run: state transitions, job starts/ends, and timing.
`report.html`	text/html	A human-readable HTML report with charts (equity curve, drawdown), the stats table, and the risk attestation.

Why 8 files

The bundle is designed so that a third party with no access to Ithaca can reproduce the backtest. Give them the bundle and they have everything: the strategy (in summary.json), the data (in data_manifest.json), the environment (in environment_lock.json), and the expected output (in metrics.json and equity_curve.json).

The split serves three purposes:

Machine readability. The 7 JSON files are structured and parseable. Tools can diff two bundles field-by-field.
Human readability. report.html renders the same information as a styled report with charts — no JSON parsing required.
Selective access. A reviewer can grab just metrics.json and report.html without downloading the full equity curve or position history.

SHA-256 content hashing

Every file in the bundle has a SHA-256 content hash. The hash is computed over the exact bytes stored in the bundle, not a normalized form. This means:

Reproducibility check. If you re-run a backtest with the same spec, range, engine version, and data hashes, the output file hashes will match. If they don’t, something changed — and the data_manifest.json and environment_lock.json tell you what.
Tamper detection. The hashes are stored on the artifact record in the database, separate from the file storage. If a file is modified in storage, the hash won’t match the record.
Bundle integrity. The artifact_bundle.content_hash returned by backtest_run is a hash over the concatenation of all 8 file hashes. This single hash verifies the entire bundle.

When comparing two backtests, start by comparing their artifact_bundle.content_hash values. If they match, the runs are identical — no need to diff the individual files.

Fetching the full bundle

To fetch all 8 files, call get_run first to get the artifacts array, then call get_artifact for each:

run = get_run(run_id="run_01HQKX2J3K4M5N6P7R8S9T0V2A")
for artifact in run["artifacts"]:
    meta = get_artifact(artifact_id=artifact["artifact_id"])
    # fetch meta["uri"] within the expiry window

The signed URIs returned by get_artifact expire after a few minutes. If you need long-term access, download the content and store it yourself. The content_hash lets you verify that your stored copy hasn’t drifted.

Backtest tools — the tool that produces the bundle
Run management tools — get_run returns the artifacts array
Strategy artifacts — the strategy-level view of the bundle

​get_artifact

​Arguments

​Return value

​Example call

​Example response

​The 8-file backtest artifact bundle

​Why 8 files

​SHA-256 content hashing

​Fetching the full bundle

​Related

`get_artifact`

Arguments

Return value

Example call

Example response

The 8-file backtest artifact bundle

Why 8 files

SHA-256 content hashing

Fetching the full bundle

Related