{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Research data: inspect, pin and download\n",
    "\n",
    "SDK 0.7. Default mode uses clearly labelled synthetic bytes, not a real Parquet file or FM. Download support.py beside this notebook. Explicit live mode inspects one available Iris catalogue entry and downloads its eligible pinned content without private workspace upload or fit. Downloaded bytes live in a disposable local directory; hosted state is never deleted.\n"
   ],
   "id": "research-datasets-0"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "source": [
    "from support import notebook_research_client\n",
    "from pathlib import Path\n",
    "from tempfile import TemporaryDirectory\n",
    "from hashlib import sha256\n",
    "\n",
    "with notebook_research_client() as client:\n",
    "    page = client.research_datasets(q=\"iris\", availability=\"available\", limit=10)\n",
    "    if not page[\"items\"]:\n",
    "        raise RuntimeError(\"No eligible catalogue entry; no download or fallback.\")\n",
    "    selected = page[\"items\"][0][\"id\"]\n",
    "    info = client.research_dataset(selected)\n",
    "    content = info[\"content\"]\n",
    "    if content is None:\n",
    "        raise RuntimeError(\"Catalogue metadata is not download permission.\")\n",
    "    print(info[\"license\"])\n",
    "    suffix = {\"application/vnd.apache.parquet\": \".parquet\", \"application/zip\": \".zip\"}[content[\"media_type\"]]\n",
    "    with TemporaryDirectory(prefix=\"welt-research-example-\") as folder:\n",
    "        path = client.download_research_dataset(selected, Path(folder) / (\"research\" + suffix),\n",
    "                                                version=content[\"version\"])\n",
    "        assert path.stat().st_size == content[\"size_bytes\"]\n",
    "        assert sha256(path.read_bytes()).hexdigest() == content[\"sha256\"]\n",
    "        print(\"Verified bytes; no private dataset created or model fitted.\")\n"
   ],
   "execution_count": null,
   "outputs": [],
   "id": "research-datasets-1"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preserve the experiment contract\n",
    "\n",
    "Inspect `schema`, `targets`, `splits`, `license` and `provenance` before using real bytes. Missing source information stays missing. Research download is separate from uploading a private execution table. A ZIP distribution includes `dataset.parquet`, `LICENSE.txt` and `ATTRIBUTION.txt`; retain all three, refuse unexpected members and never discard notices. Archive `content.sha256` differs from the inner table `provenance.canonical_sha256`. See the research guide for explicit safe extraction. The fixture never calls its labelled bytes valid Parquet. Full files can exceed model limits; choose and record an explicit split/seed/recipe rather than silently sampling.\n"
   ],
   "id": "research-datasets-2"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}