{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "vision-01",
   "metadata": {},
   "source": "# Vision model extraction\n\n`VisionModel` provides one interface across the `transformers`, `timm`, and `thingsvision` backends. Construction can require optional dependencies, network access, and model assets; run these cells in a suitable local environment."
  },
  {
   "cell_type": "markdown",
   "id": "vision-02",
   "metadata": {},
   "source": [
    "## Choose a backend\n",
    "\n",
    "Model IDs pass to the selected backend unchanged; VneuroTK does not substitute another backend or model.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision-03",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import torch\n",
    "\n",
    "import vneurotk as vtk\n",
    "\n",
    "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
    "model = vtk.VisionModel(\"facebook/dinov2-base\", backend=\"transformers\", device=device)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision-04",
   "metadata": {},
   "source": [
    "## Select modules\n",
    "\n",
    "Replace the default block-level selector by exact module type, exact name, their union, a selector object, or a custom list from `model.module_list`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision-05",
   "metadata": {},
   "outputs": [],
   "source": [
    "model.set_selector(\n",
    "    module_type=\"Dinov2Layer\",\n",
    "    module_name=\"layernorm\",\n",
    ")\n",
    "selected_names = model.module_names"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision-06",
   "metadata": {},
   "source": [
    "## Extract a stimulus mapping\n",
    "\n",
    "Batch input is a `{stimulus_id: image}` mapping so activation rows retain identity. `extract()` returns `VisualRepresentations`, with one `VisualRepresentation` per selected module.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision-07",
   "metadata": {},
   "outputs": [],
   "source": [
    "rng = np.random.default_rng(0)\n",
    "images = {f\"image-{i}\": rng.integers(0, 256, (64, 64, 3), dtype=np.uint8) for i in range(4)}\n",
    "representations = model.extract(images, batch_size=4, show_progress=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision-08",
   "metadata": {},
   "source": [
    "## Index arrays and provenance\n",
    "\n",
    "A string or integer selects one `VisualRepresentation`. A boolean mask always returns a `VisualRepresentations` collection, even for one match. Use `.array` or `.numpy(module_name)` for activations and `.select(ids)` to align every module to a stimulus subset.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vision-09",
   "metadata": {},
   "outputs": [],
   "source": [
    "first = representations[0]\n",
    "activation = representations.numpy(first.module_name)\n",
    "matching = representations[representations.meta[\"module_name\"] == first.module_name]\n",
    "first_two = representations.select(list(representations.stim_ids[:2]))\n",
    "provenance_record = first.provenance.to_dict()\n",
    "assert provenance_record[\"backend\"] == \"transformers\"\n",
    "assert provenance_record[\"model_id\"] == model.model_id"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vision-10",
   "metadata": {},
   "source": "`ExtractionProvenance` records locally discoverable revision, preprocessing, selector, dependency versions, dtype, device, and writer version. Unavailable values remain `\"unknown\"`; callers may supply a stimulus-content digest to `extract()`.\n\n## Related documentation\n\n- [Vision-model usage](../usage/vision_models)\n- [Standalone extraction usage](../usage/vision_alone)\n- [Vision API](../api/vision.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}