{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:07.201314Z",
     "iopub.status.busy": "2026-05-20T13:58:07.201116Z",
     "iopub.status.idle": "2026-05-20T13:58:07.328017Z",
     "shell.execute_reply": "2026-05-20T13:58:07.327096Z"
    }
   },
   "outputs": [],
   "source": [
    "!rm .fleche -rf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started with Fleche"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook demonstrates the main features of the `fleche` library, a caching library for Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Long-running calculation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:07.330249Z",
     "iopub.status.busy": "2026-05-20T13:58:07.330073Z",
     "iopub.status.idle": "2026-05-20T13:58:07.827336Z",
     "shell.execute_reply": "2026-05-20T13:58:07.826483Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Using default memory cache: no config file found\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "from fleche import fleche, cache, tags\n",
    "from fleche.digest import Digest"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:07.860549Z",
     "iopub.status.busy": "2026-05-20T13:58:07.860339Z",
     "iopub.status.idle": "2026-05-20T13:58:07.863912Z",
     "shell.execute_reply": "2026-05-20T13:58:07.863261Z"
    }
   },
   "outputs": [],
   "source": [
    "@fleche\n",
    "def long_running_calculation(x):\n",
    "    print(f'Running calculation for {x}...')\n",
    "    time.sleep(2)\n",
    "    return x * x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:07.865443Z",
     "iopub.status.busy": "2026-05-20T13:58:07.865285Z",
     "iopub.status.idle": "2026-05-20T13:58:09.869405Z",
     "shell.execute_reply": "2026-05-20T13:58:09.868698Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running calculation for 2...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First call took 2.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "start = time.time()\n",
    "long_running_calculation(2)\n",
    "end = time.time()\n",
    "print(f'First call took {end - start:.2f} seconds.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:09.871116Z",
     "iopub.status.busy": "2026-05-20T13:58:09.870933Z",
     "iopub.status.idle": "2026-05-20T13:58:09.874285Z",
     "shell.execute_reply": "2026-05-20T13:58:09.873651Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second call took 0.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "start = time.time()\n",
    "long_running_calculation(2)\n",
    "end = time.time()\n",
    "print(f'Second call took {end - start:.2f} seconds.')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:09.875846Z",
     "iopub.status.busy": "2026-05-20T13:58:09.875701Z",
     "iopub.status.idle": "2026-05-20T13:58:11.879508Z",
     "shell.execute_reply": "2026-05-20T13:58:11.878897Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running calculation for 100...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second call took 2.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "start = time.time()\n",
    "long_running_calculation(100)\n",
    "end = time.time()\n",
    "print(f'Second call took {end - start:.2f} seconds.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the second call returns almost instantly, because the result was cached.\n",
    "As soon as the argument changes, fleche runs the original function again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Recursive function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:11.881446Z",
     "iopub.status.busy": "2026-05-20T13:58:11.881285Z",
     "iopub.status.idle": "2026-05-20T13:58:11.884148Z",
     "shell.execute_reply": "2026-05-20T13:58:11.883546Z"
    }
   },
   "outputs": [],
   "source": [
    "@fleche\n",
    "def fib(n):\n",
    "    if n < 2:\n",
    "        return n\n",
    "    return fib(n-1) + fib(n-2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:11.885758Z",
     "iopub.status.busy": "2026-05-20T13:58:11.885608Z",
     "iopub.status.idle": "2026-05-20T13:58:11.895163Z",
     "shell.execute_reply": "2026-05-20T13:58:11.894533Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "fib(20) took 0.0066 seconds with caching.\n"
     ]
    }
   ],
   "source": [
    "start = time.time()\n",
    "fib(20)\n",
    "end = time.time()\n",
    "print(f'fib(20) took {end - start:.4f} seconds with caching.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Without caching, this would be much slower as each call to `fib` would be recomputed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Passing Digests as Arguments\n",
    "\n",
    "`fleche` supports passing `Digest` objects directly to cached functions. When a function receives a `Digest`, `fleche` automatically expands it to its actual value from the cache before executing the function. You can use the convenience wrapper `D` to mark a string as a digest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:11.896880Z",
     "iopub.status.busy": "2026-05-20T13:58:11.896729Z",
     "iopub.status.idle": "2026-05-20T13:58:13.901989Z",
     "shell.execute_reply": "2026-05-20T13:58:13.901245Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running calculation for 10...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value Digest: 60079f7901a9295349d1796c037afc132e81286f785ddeeb763104ef02363102\n",
      "Short digest: 60079f79\n",
      "Doubling 100...\n",
      "Result: 200\n"
     ]
    }
   ],
   "source": [
    "from fleche import D\n",
    "from fleche.digest import digest as value_digest\n",
    "\n",
    "@fleche\n",
    "def double(x):\n",
    "    print(f\"Doubling {x}...\")\n",
    "    return x * 2\n",
    "\n",
    "# 1. Run the calculation to ensure it is cached\n",
    "long_running_calculation(10)\n",
    "\n",
    "# 2. Compute the value digest for 100 (the cached result)\n",
    "v = long_running_calculation(10)\n",
    "val_dig = value_digest(v)\n",
    "print(f\"Value Digest: {val_dig}\")\n",
    "\n",
    "# 3. Pass a short digest prefix of the value to double(); it will expand to 100.\n",
    "short = str(val_dig)[:8]\n",
    "print(f\"Short digest: {short}\")\n",
    "print(f\"Result: {double(D(short))}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying Cached Calls "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### via Function Wrapper\n",
    "\n",
    "You can retrieve previously cached calls that match some of your function's arguments and metadata using the function wrapper's `query` method. Any field left as `None` is treated as a wildcard. Arguments and result are compared by digest internally, but the wrapper decodes them back to Python objects when returning matches.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Query returns an iterator object, that also defines additional utilities, e.g. to create a table of queried calls, do"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.903818Z",
     "iopub.status.busy": "2026-05-20T13:58:13.903659Z",
     "iopub.status.idle": "2026-05-20T13:58:13.917178Z",
     "shell.execute_reply": "2026-05-20T13:58:13.916567Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1b9e6318e4a97368e8</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.898600340+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.898777008+00:00</td>\n",
       "      <td>2.000177</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  long_running_calculation   \n",
       "\n",
       "                                                      module  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:11.898600340+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:13.898777008+00:00   \n",
       "\n",
       "                                                    walltime  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187  \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  2.000177  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "long_running_calculation.fleche.query().table()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The table includes the call digest as an index and the metadata associated with the call.\n",
    "\n",
    "Arguments can be selectively included in the table via the `arguments`.  You only pay the loading cost for the specified arguments, not for arguments that are not included in the table."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.918894Z",
     "iopub.status.busy": "2026-05-20T13:58:13.918739Z",
     "iopub.status.idle": "2026-05-20T13:58:13.928099Z",
     "shell.execute_reply": "2026-05-20T13:58:13.927451Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "      <th>x</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "      <td>100</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1b9e6318e4a97368e8</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.898600340+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.898777008+00:00</td>\n",
       "      <td>2.000177</td>\n",
       "      <td>10</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  long_running_calculation   \n",
       "\n",
       "                                                      module  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:11.898600340+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:13.898777008+00:00   \n",
       "\n",
       "                                                    walltime    x  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202    2  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187  100  \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  2.000177   10  "
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "long_running_calculation.fleche.query().table(arguments=['x'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.929884Z",
     "iopub.status.busy": "2026-05-20T13:58:13.929726Z",
     "iopub.status.idle": "2026-05-20T13:58:13.938874Z",
     "shell.execute_reply": "2026-05-20T13:58:13.938197Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>result</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "      <th>x</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>4</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>10000</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "      <td>100</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1b9e6318e4a97368e8</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>100</td>\n",
       "      <td>2026-05-20 13:58:11.898600340+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.898777008+00:00</td>\n",
       "      <td>2.000177</td>\n",
       "      <td>10</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  long_running_calculation   \n",
       "\n",
       "                                                      module  result  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__       4   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   10000   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  __main__     100   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:11.898600340+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:13.898777008+00:00   \n",
       "\n",
       "                                                    walltime    x  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202    2  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187  100  \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  2.000177   10  "
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "long_running_calculation.fleche.query().table(arguments=['x'], results=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### via Cache"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.940504Z",
     "iopub.status.busy": "2026-05-20T13:58:13.940358Z",
     "iopub.status.idle": "2026-05-20T13:58:13.942861Z",
     "shell.execute_reply": "2026-05-20T13:58:13.942089Z"
    }
   },
   "outputs": [],
   "source": [
    "from fleche.call import QueryCall"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.944241Z",
     "iopub.status.busy": "2026-05-20T13:58:13.944094Z",
     "iopub.status.idle": "2026-05-20T13:58:13.954197Z",
     "shell.execute_reply": "2026-05-20T13:58:13.953508Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>698e29f05ba00ee23503848cd166215f62cd976d54431594036979d8d56f254f</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887941122+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.887945414+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4edeafb1c6f236fc80</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.888637781+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.888642073+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>24231d9bc47f7abc0ea485d178fc8457dce8082790f8c948b936ebe906352225</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887756109+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889148235+00:00</td>\n",
       "      <td>0.001392</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...                       fib   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...                       fib   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...                       fib   \n",
       "\n",
       "                                                      module  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  __main__   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  __main__   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887941122+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888637781+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.887756109+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887945414+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888642073+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.889148235+00:00   \n",
       "\n",
       "                                                    walltime  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187  \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  0.000004  \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  0.000004  \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  0.001392  "
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cache().query(QueryCall(module=\"__main__\")).table().head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.955584Z",
     "iopub.status.busy": "2026-05-20T13:58:13.955435Z",
     "iopub.status.idle": "2026-05-20T13:58:13.965522Z",
     "shell.execute_reply": "2026-05-20T13:58:13.964872Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>698e29f05ba00ee23503848cd166215f62cd976d54431594036979d8d56f254f</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887941122+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.887945414+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4edeafb1c6f236fc80</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.888637781+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.888642073+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>24231d9bc47f7abc0ea485d178fc8457dce8082790f8c948b936ebe906352225</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887756109+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889148235+00:00</td>\n",
       "      <td>0.001392</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2b9a284dc1bb743d79</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887614489+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889541388+00:00</td>\n",
       "      <td>0.001927</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6faeefc15b4231178912</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887559414+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889832497+00:00</td>\n",
       "      <td>0.002273</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                   name    module  \\\n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  fib  __main__   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  fib  __main__   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  fib  __main__   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...  fib  __main__   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...  fib  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887941122+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888637781+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.887756109+00:00   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2... 2026-05-20 13:58:11.887614489+00:00   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa... 2026-05-20 13:58:11.887559414+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887945414+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888642073+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.889148235+00:00   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2... 2026-05-20 13:58:11.889541388+00:00   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa... 2026-05-20 13:58:11.889832497+00:00   \n",
       "\n",
       "                                                    walltime  \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  0.000004  \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  0.000004  \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  0.001392  \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...  0.001927  \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...  0.002273  "
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cache().query(QueryCall(name=\"fib\")).table().head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.967025Z",
     "iopub.status.busy": "2026-05-20T13:58:13.966852Z",
     "iopub.status.idle": "2026-05-20T13:58:13.975284Z",
     "shell.execute_reply": "2026-05-20T13:58:13.974666Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748de84aad8f244a2d8f</th>\n",
       "      <td>double</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.899759531+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.899780273+00:00</td>\n",
       "      <td>0.000021</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...                    double   \n",
       "\n",
       "                                                      module  \\\n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899759531+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899780273+00:00   \n",
       "\n",
       "                                                    walltime  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187  \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  0.000021  "
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cache().query(QueryCall(arguments={\"x\": 100})).table()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fleche` allows you to add metadata to your cached functions using the `tags` context manager. This can be useful for organizing and querying your results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.977044Z",
     "iopub.status.busy": "2026-05-20T13:58:13.976880Z",
     "iopub.status.idle": "2026-05-20T13:58:13.979637Z",
     "shell.execute_reply": "2026-05-20T13:58:13.978955Z"
    }
   },
   "outputs": [],
   "source": [
    "@fleche\n",
    "def another_calculation(a, b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.981076Z",
     "iopub.status.busy": "2026-05-20T13:58:13.980906Z",
     "iopub.status.idle": "2026-05-20T13:58:13.984271Z",
     "shell.execute_reply": "2026-05-20T13:58:13.983610Z"
    }
   },
   "outputs": [],
   "source": [
    "with tags(project='my_project', category='testing'):\n",
    "    another_calculation(1, 2)\n",
    "    another_calculation(3, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This metadata is stored alongside the cached result. This metadata can be used to query the cache as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.985809Z",
     "iopub.status.busy": "2026-05-20T13:58:13.985640Z",
     "iopub.status.idle": "2026-05-20T13:58:13.991292Z",
     "shell.execute_reply": "2026-05-20T13:58:13.990653Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "another_calculation LazyArguments({'a': 'da217d50752f3371d9f8b62a3e72409592bd34b74e14fdac43e2b137bd59f21f', 'b': '92a9b214d814a4a7b5f9ba52e2248c6d16ec0196d8cd7798b345471118bf0c67'}) {'project': 'my_project', 'category': 'testing'}\n",
      "LazyArguments({'a': '65d52a82c5a72f12ca0499522dc9274a0e6822e1038630ba68f94400b3e4c98f', 'b': '83ada2198553b88cb3d0882f7fca8c4e9531049b978df3e9e3b5d6301c6c0bfa'}) 7\n"
     ]
    }
   ],
   "source": [
    "# Query by metadata presence (tags) and a specific key-value filter\n",
    "for call in another_calculation.fleche.query(1, 2, metadata={\"tags\": {}}):\n",
    "    # presence-only: any call with 'tags'\n",
    "    print(call.name, call.arguments, call.metadata.get(\"tags\"))\n",
    "\n",
    "for call in another_calculation.fleche.query(3, 4, metadata={\"tags\": {\"project\": \"my_project\"}}):\n",
    "    # equality filter on metadata\n",
    "    assert call.metadata[\"tags\"][\"project\"] == \"my_project\"\n",
    "    # arguments and result are decoded if they were stored as digests\n",
    "    print(call.arguments, call.result)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Caching Methods of User-defined Types\n",
    "\n",
    "`fleche` can also cache methods of classes. For this to work, the class must be \"digest-compatible\". There are three ways to achieve this:\n",
    "\n",
    "- Implement a `__digest__` method that returns a `Digest` representing the instance.\n",
    "- Use a `dataclass` — `fleche` hashes all fields automatically.\n",
    "- Use an `attrs`-decorated class — the same automatic field hashing applies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.992792Z",
     "iopub.status.busy": "2026-05-20T13:58:13.992638Z",
     "iopub.status.idle": "2026-05-20T13:58:13.996094Z",
     "shell.execute_reply": "2026-05-20T13:58:13.995392Z"
    }
   },
   "outputs": [],
   "source": [
    "class MyClass:\n",
    "    def __init__(self, val):\n",
    "        self.val = val\n",
    "    \n",
    "    def __digest__(self):\n",
    "        # The digest defines how the instance is identified in the cache\n",
    "        return Digest(str(self.val))\n",
    "\n",
    "    @fleche\n",
    "    def compute(self, x):\n",
    "        print(f\"Computing {self.val} + {x}...\")\n",
    "        time.sleep(1)\n",
    "        return self.val + x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:13.997512Z",
     "iopub.status.busy": "2026-05-20T13:58:13.997365Z",
     "iopub.status.idle": "2026-05-20T13:58:15.001914Z",
     "shell.execute_reply": "2026-05-20T13:58:15.001244Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Computing 10 + 5...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result: 15\n",
      "First call took 1.00 seconds.\n",
      "Result: 15\n",
      "Second call (same instance) took 0.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "obj = MyClass(10)\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {obj.compute(5)}\")\n",
    "print(f\"First call took {time.time() - start:.2f} seconds.\")\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {obj.compute(5)}\")\n",
    "print(f\"Second call (same instance) took {time.time() - start:.2f} seconds.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you mutate the instance such that its digest changes, the cache will be missed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:15.003719Z",
     "iopub.status.busy": "2026-05-20T13:58:15.003539Z",
     "iopub.status.idle": "2026-05-20T13:58:16.007710Z",
     "shell.execute_reply": "2026-05-20T13:58:16.007047Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Computing 20 + 5...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result: 25\n",
      "Call after mutation took 1.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "obj.val = 20\n",
    "start = time.time()\n",
    "print(f\"Result: {obj.compute(5)}\")\n",
    "print(f\"Call after mutation took {time.time() - start:.2f} seconds.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### With `dataclass`\n",
    "\n",
    "`dataclass`-decorated classes are digest-compatible out of the box — no `__digest__` needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:16.009547Z",
     "iopub.status.busy": "2026-05-20T13:58:16.009386Z",
     "iopub.status.idle": "2026-05-20T13:58:17.015622Z",
     "shell.execute_reply": "2026-05-20T13:58:17.014916Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Computing 10 + 5...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result: 15\n",
      "First call took 1.00 seconds.\n",
      "Result: 15\n",
      "Second call (same instance) took 0.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "from dataclasses import dataclass\n",
    "\n",
    "@dataclass\n",
    "class MyDataClass:\n",
    "    val: int\n",
    "\n",
    "    @fleche\n",
    "    def compute(self, x):\n",
    "        print(f\"Computing {self.val} + {x}...\")\n",
    "        time.sleep(1)\n",
    "        return self.val + x\n",
    "\n",
    "dc = MyDataClass(10)\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {dc.compute(5)}\")\n",
    "print(f\"First call took {time.time() - start:.2f} seconds.\")\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {dc.compute(5)}\")\n",
    "print(f\"Second call (same instance) took {time.time() - start:.2f} seconds.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### With `attrs`\n",
    "\n",
    "`attrs`-decorated classes work the same way. Install the optional `attrs` package and `fleche` will hash all `attrs` fields automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:17.017317Z",
     "iopub.status.busy": "2026-05-20T13:58:17.017160Z",
     "iopub.status.idle": "2026-05-20T13:58:18.023215Z",
     "shell.execute_reply": "2026-05-20T13:58:18.022608Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Computing 10 + 5...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result: 15\n",
      "First call took 1.00 seconds.\n",
      "Result: 15\n",
      "Second call (same instance) took 0.00 seconds.\n"
     ]
    }
   ],
   "source": [
    "import attr\n",
    "\n",
    "@attr.s\n",
    "class MyAttrsClass:\n",
    "    val: int = attr.ib()\n",
    "\n",
    "    @fleche\n",
    "    def compute(self, x):\n",
    "        print(f\"Computing {self.val} + {x}...\")\n",
    "        time.sleep(1)\n",
    "        return self.val + x\n",
    "\n",
    "ac = MyAttrsClass(10)\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {ac.compute(5)}\")\n",
    "print(f\"First call took {time.time() - start:.2f} seconds.\")\n",
    "\n",
    "start = time.time()\n",
    "print(f\"Result: {ac.compute(5)}\")\n",
    "print(f\"Second call (same instance) took {time.time() - start:.2f} seconds.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Passing Digests as Arguments\n",
    "\n",
    "`fleche` supports passing `Digest` objects directly to cached functions. When a function receives a `Digest`, `fleche` automatically expands it to its actual value from the cache before executing the function. You can use the convenience wrapper `D` to mark a string as a digest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.025190Z",
     "iopub.status.busy": "2026-05-20T13:58:18.025031Z",
     "iopub.status.idle": "2026-05-20T13:58:18.029564Z",
     "shell.execute_reply": "2026-05-20T13:58:18.029011Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value Digest: 60079f7901a9295349d1796c037afc132e81286f785ddeeb763104ef02363102\n",
      "Short digest: 60079f79\n",
      "Result: 200\n"
     ]
    }
   ],
   "source": [
    "from fleche import D\n",
    "from fleche.digest import digest as value_digest\n",
    "\n",
    "@fleche\n",
    "def double(x):\n",
    "    print(f\"Doubling {x}...\")\n",
    "    return x * 2\n",
    "\n",
    "# 1. Run the calculation to ensure it is cached\n",
    "long_running_calculation(10)\n",
    "\n",
    "# 2. Compute the value digest for 100 (the cached result)\n",
    "v = long_running_calculation(10)\n",
    "val_dig = value_digest(v)\n",
    "print(f\"Value Digest: {val_dig}\")\n",
    "\n",
    "# 3. Pass a short digest prefix of the value to double(); it will expand to 100.\n",
    "short = str(val_dig)[:8]\n",
    "print(f\"Short digest: {short}\")\n",
    "print(f\"Result: {double(D(short))}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fleche` allows you to add metadata to your cached functions using the `tags` context manager. This can be useful for organizing and querying your results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.031298Z",
     "iopub.status.busy": "2026-05-20T13:58:18.031135Z",
     "iopub.status.idle": "2026-05-20T13:58:18.033771Z",
     "shell.execute_reply": "2026-05-20T13:58:18.033192Z"
    }
   },
   "outputs": [],
   "source": [
    "@fleche\n",
    "def another_calculation(a, b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.035359Z",
     "iopub.status.busy": "2026-05-20T13:58:18.035202Z",
     "iopub.status.idle": "2026-05-20T13:58:18.038188Z",
     "shell.execute_reply": "2026-05-20T13:58:18.037556Z"
    }
   },
   "outputs": [],
   "source": [
    "with tags(project='my_project', category='testing'):\n",
    "    another_calculation(1, 2)\n",
    "    another_calculation(3, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This metadata is stored alongside the cached result. You can then use the `metadata.table` method to view the metadata for all cached results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.039805Z",
     "iopub.status.busy": "2026-05-20T13:58:18.039664Z",
     "iopub.status.idle": "2026-05-20T13:58:18.053669Z",
     "shell.execute_reply": "2026-05-20T13:58:18.053069Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "      <th>project</th>\n",
       "      <th>category</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>698e29f05ba00ee23503848cd166215f62cd976d54431594036979d8d56f254f</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887941122+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.887945414+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4edeafb1c6f236fc80</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.888637781+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.888642073+00:00</td>\n",
       "      <td>0.000004</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>24231d9bc47f7abc0ea485d178fc8457dce8082790f8c948b936ebe906352225</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887756109+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889148235+00:00</td>\n",
       "      <td>0.001392</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2b9a284dc1bb743d79</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887614489+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889541388+00:00</td>\n",
       "      <td>0.001927</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6faeefc15b4231178912</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887559414+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.889832497+00:00</td>\n",
       "      <td>0.002273</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f4fcd3190b6187b0ac</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887506008+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.890038490+00:00</td>\n",
       "      <td>0.002532</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d199b8606eed60579d91</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887447834+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.890216112+00:00</td>\n",
       "      <td>0.002768</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>db6b5632c77a01a692e13c486c54536a0c46907972d93900a60a1eab59110b93</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887393475+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.890395880+00:00</td>\n",
       "      <td>0.003002</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f18b57abc5e07b6457</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887343407+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.890571594+00:00</td>\n",
       "      <td>0.003228</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78dad4feb055b56fd47de</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887291431+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.890746593+00:00</td>\n",
       "      <td>0.003455</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>bc7f8b67d293d9fbdec343f49c44d46e655516537cc492ba3a990edb7f86f176</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887238741+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.891099215+00:00</td>\n",
       "      <td>0.003860</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f01322946f5e53e7cf</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887186289+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.891317129+00:00</td>\n",
       "      <td>0.004131</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1bd078db3377cca4c3</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887124300+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.891495228+00:00</td>\n",
       "      <td>0.004371</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c35567b81514b90c053f2</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.887062788+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.891667604+00:00</td>\n",
       "      <td>0.004605</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7a18a0001fd0b65cf9</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886986971+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.891838551+00:00</td>\n",
       "      <td>0.004852</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9b23a905e639149d35169118ffefadec03a181cbd290006620e671655b1499c3</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886909723+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892037153+00:00</td>\n",
       "      <td>0.005127</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18e77dab7a4a0385a66512547336e7a02ee62803634fd801e6dd49c6e5444e2f</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886851072+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892219305+00:00</td>\n",
       "      <td>0.005368</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>e1a78503325bcbb94116e03febed590b14bdd7f955c4f15b8649e613fbd6bf5c</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886792183+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892392159+00:00</td>\n",
       "      <td>0.005600</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c4342b29231a8213ea</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886729956+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892567873+00:00</td>\n",
       "      <td>0.005838</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d1fd7ef30aa2c75873</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886659861+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892740965+00:00</td>\n",
       "      <td>0.006081</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf19505cc660b50e6d9</th>\n",
       "      <td>fib</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.886577129+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.892913580+00:00</td>\n",
       "      <td>0.006336</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1b9e6318e4a97368e8</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.898600340+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.898777008+00:00</td>\n",
       "      <td>2.000177</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748de84aad8f244a2d8f</th>\n",
       "      <td>double</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.899759531+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.899780273+00:00</td>\n",
       "      <td>0.000021</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae7a2e91aa1fbac8c80</th>\n",
       "      <td>another_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.981916666+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.981927633+00:00</td>\n",
       "      <td>0.000011</td>\n",
       "      <td>my_project</td>\n",
       "      <td>testing</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0feca453b301b40156a</th>\n",
       "      <td>another_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.982227802+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.982236147+00:00</td>\n",
       "      <td>0.000008</td>\n",
       "      <td>my_project</td>\n",
       "      <td>testing</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d94ba6be4b64e1be86</th>\n",
       "      <td>MyClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.998702288+00:00</td>\n",
       "      <td>2026-05-20 13:58:14.998900652+00:00</td>\n",
       "      <td>1.000198</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>34818cf0647e22b9f7e0d46adac2fd394b76e572f132976946f2c76498a6140f</th>\n",
       "      <td>MyClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:15.004741192+00:00</td>\n",
       "      <td>2026-05-20 13:58:16.004941463+00:00</td>\n",
       "      <td>1.000200</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5fef928ab57118f9390f0627ba47fe2030d9287e5b05826292042b5a41a4ec06</th>\n",
       "      <td>MyDataClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:16.012222767+00:00</td>\n",
       "      <td>2026-05-20 13:58:17.012420893+00:00</td>\n",
       "      <td>1.000198</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0359b0c3903ae8c466</th>\n",
       "      <td>MyAttrsClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:17.020026207+00:00</td>\n",
       "      <td>2026-05-20 13:58:18.020214558+00:00</td>\n",
       "      <td>1.000188</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...                       fib   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...                       fib   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...                       fib   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...                       fib   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...                       fib   \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f...                       fib   \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19...                       fib   \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390...                       fib   \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f...                       fib   \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da...                       fib   \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b...                       fib   \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f...                       fib   \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1...                       fib   \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355...                       fib   \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7...                       fib   \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006...                       fib   \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80...                       fib   \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15...                       fib   \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c...                       fib   \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d...                       fib   \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf...                       fib   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  long_running_calculation   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...                    double   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...       another_calculation   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...       another_calculation   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...           MyClass.compute   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...           MyClass.compute   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...       MyDataClass.compute   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...      MyAttrsClass.compute   \n",
       "\n",
       "                                                      module  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  __main__   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  __main__   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  __main__   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...  __main__   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...  __main__   \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f...  __main__   \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19...  __main__   \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390...  __main__   \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f...  __main__   \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da...  __main__   \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b...  __main__   \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f...  __main__   \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1...  __main__   \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355...  __main__   \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7...  __main__   \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006...  __main__   \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80...  __main__   \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15...  __main__   \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c...  __main__   \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d...  __main__   \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf...  __main__   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  __main__   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  __main__   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  __main__   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  __main__   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...  __main__   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...  __main__   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...  __main__   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887941122+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888637781+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.887756109+00:00   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2... 2026-05-20 13:58:11.887614489+00:00   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa... 2026-05-20 13:58:11.887559414+00:00   \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f... 2026-05-20 13:58:11.887506008+00:00   \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19... 2026-05-20 13:58:11.887447834+00:00   \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390... 2026-05-20 13:58:11.887393475+00:00   \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f... 2026-05-20 13:58:11.887343407+00:00   \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da... 2026-05-20 13:58:11.887291431+00:00   \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b... 2026-05-20 13:58:11.887238741+00:00   \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f... 2026-05-20 13:58:11.887186289+00:00   \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1... 2026-05-20 13:58:11.887124300+00:00   \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355... 2026-05-20 13:58:11.887062788+00:00   \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7... 2026-05-20 13:58:11.886986971+00:00   \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006... 2026-05-20 13:58:11.886909723+00:00   \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80... 2026-05-20 13:58:11.886851072+00:00   \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15... 2026-05-20 13:58:11.886792183+00:00   \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c... 2026-05-20 13:58:11.886729956+00:00   \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d... 2026-05-20 13:58:11.886659861+00:00   \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf... 2026-05-20 13:58:11.886577129+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:11.898600340+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899759531+00:00   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae... 2026-05-20 13:58:13.981916666+00:00   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f... 2026-05-20 13:58:13.982227802+00:00   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d... 2026-05-20 13:58:13.998702288+00:00   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976... 2026-05-20 13:58:15.004741192+00:00   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826... 2026-05-20 13:58:16.012222767+00:00   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0... 2026-05-20 13:58:17.020026207+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159... 2026-05-20 13:58:11.887945414+00:00   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4... 2026-05-20 13:58:11.888642073+00:00   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94... 2026-05-20 13:58:11.889148235+00:00   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2... 2026-05-20 13:58:11.889541388+00:00   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa... 2026-05-20 13:58:11.889832497+00:00   \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f... 2026-05-20 13:58:11.890038490+00:00   \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19... 2026-05-20 13:58:11.890216112+00:00   \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390... 2026-05-20 13:58:11.890395880+00:00   \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f... 2026-05-20 13:58:11.890571594+00:00   \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da... 2026-05-20 13:58:11.890746593+00:00   \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b... 2026-05-20 13:58:11.891099215+00:00   \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f... 2026-05-20 13:58:11.891317129+00:00   \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1... 2026-05-20 13:58:11.891495228+00:00   \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355... 2026-05-20 13:58:11.891667604+00:00   \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7... 2026-05-20 13:58:11.891838551+00:00   \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006... 2026-05-20 13:58:11.892037153+00:00   \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80... 2026-05-20 13:58:11.892219305+00:00   \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15... 2026-05-20 13:58:11.892392159+00:00   \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c... 2026-05-20 13:58:11.892567873+00:00   \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d... 2026-05-20 13:58:11.892740965+00:00   \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf... 2026-05-20 13:58:11.892913580+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:13.898777008+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899780273+00:00   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae... 2026-05-20 13:58:13.981927633+00:00   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f... 2026-05-20 13:58:13.982236147+00:00   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d... 2026-05-20 13:58:14.998900652+00:00   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976... 2026-05-20 13:58:16.004941463+00:00   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826... 2026-05-20 13:58:17.012420893+00:00   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0... 2026-05-20 13:58:18.020214558+00:00   \n",
       "\n",
       "                                                    walltime     project  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202         NaN   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187         NaN   \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...  0.000004         NaN   \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...  0.000004         NaN   \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...  0.001392         NaN   \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...  0.001927         NaN   \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...  0.002273         NaN   \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f...  0.002532         NaN   \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19...  0.002768         NaN   \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390...  0.003002         NaN   \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f...  0.003228         NaN   \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da...  0.003455         NaN   \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b...  0.003860         NaN   \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f...  0.004131         NaN   \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1...  0.004371         NaN   \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355...  0.004605         NaN   \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7...  0.004852         NaN   \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006...  0.005127         NaN   \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80...  0.005368         NaN   \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15...  0.005600         NaN   \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c...  0.005838         NaN   \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d...  0.006081         NaN   \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf...  0.006336         NaN   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  2.000177         NaN   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  0.000021         NaN   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  0.000011  my_project   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  0.000008  my_project   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...  1.000198         NaN   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...  1.000200         NaN   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...  1.000198         NaN   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...  1.000188         NaN   \n",
       "\n",
       "                                                   category  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...      NaN  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...      NaN  \n",
       "698e29f05ba00ee23503848cd166215f62cd976d5443159...      NaN  \n",
       "405dfbadf453a9d5bbe3482fbb05251a6fc18b90045f8b4...      NaN  \n",
       "24231d9bc47f7abc0ea485d178fc8457dce8082790f8c94...      NaN  \n",
       "dabebddba19859bdb1a075e422b1842dde433c7d6ca51c2...      NaN  \n",
       "e2b3a4eaf9036f83560677b9bad64cbb8263cf3496ba6fa...      NaN  \n",
       "981a54293b3027931a47d21c275955d6dab2fe6d8fa4c2f...      NaN  \n",
       "fdb0a9b8b1df91293924ad8fc03bcf041f3e50f924e9d19...      NaN  \n",
       "db6b5632c77a01a692e13c486c54536a0c46907972d9390...      NaN  \n",
       "cd94bda61e484ca82c470b6ab50c0f1b98055e6a905d82f...      NaN  \n",
       "f4efb0e68400d195d8d57051088964d98b9ae4f7dbb78da...      NaN  \n",
       "bc7f8b67d293d9fbdec343f49c44d46e655516537cc492b...      NaN  \n",
       "6fbe26ceafe80276c7714b2aae14c25bd38e24683d6624f...      NaN  \n",
       "f3cefd42fd07119792c38084ecbb33f1955ccd83d8021e1...      NaN  \n",
       "2b7c9e8c5e0a73afddb28a49d47415462b3c84adc05c355...      NaN  \n",
       "60bf26e7cdec62d1a8f9ebfbebb336850cf588d547badc7...      NaN  \n",
       "9b23a905e639149d35169118ffefadec03a181cbd290006...      NaN  \n",
       "18e77dab7a4a0385a66512547336e7a02ee62803634fd80...      NaN  \n",
       "e1a78503325bcbb94116e03febed590b14bdd7f955c4f15...      NaN  \n",
       "34814b3262b7920c7cef43eaf8a1e86e849611ed0d0317c...      NaN  \n",
       "9214caae9e9819230882f7e9f0f1970fd5f2fc354c3404d...      NaN  \n",
       "c5a5bb6cf5b69c7eb5e244ed540af44391dff12a77fcecf...      NaN  \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...      NaN  \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...      NaN  \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  testing  \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  testing  \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...      NaN  \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...      NaN  \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...      NaN  \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...      NaN  "
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cache().table()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Filtering\n",
    "\n",
    "The metadata table is just pandas so you can query and filter as you like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.055311Z",
     "iopub.status.busy": "2026-05-20T13:58:18.055147Z",
     "iopub.status.idle": "2026-05-20T13:58:18.068524Z",
     "shell.execute_reply": "2026-05-20T13:58:18.067953Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>module</th>\n",
       "      <th>timestart</th>\n",
       "      <th>timestop</th>\n",
       "      <th>walltime</th>\n",
       "      <th>project</th>\n",
       "      <th>category</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>4435e2927c194eff1bb90270ab3f353f0db1a8b50ec04932de88f7a4e5745953</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:07.866472244+00:00</td>\n",
       "      <td>2026-05-20 13:58:09.866674185+00:00</td>\n",
       "      <td>2.000202</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4cfb21baa5874c2b9e</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:09.876649618+00:00</td>\n",
       "      <td>2026-05-20 13:58:11.876836300+00:00</td>\n",
       "      <td>2.000187</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1b9e6318e4a97368e8</th>\n",
       "      <td>long_running_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:11.898600340+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.898777008+00:00</td>\n",
       "      <td>2.000177</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748de84aad8f244a2d8f</th>\n",
       "      <td>double</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.899759531+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.899780273+00:00</td>\n",
       "      <td>0.000021</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae7a2e91aa1fbac8c80</th>\n",
       "      <td>another_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.981916666+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.981927633+00:00</td>\n",
       "      <td>0.000011</td>\n",
       "      <td>my_project</td>\n",
       "      <td>testing</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0feca453b301b40156a</th>\n",
       "      <td>another_calculation</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.982227802+00:00</td>\n",
       "      <td>2026-05-20 13:58:13.982236147+00:00</td>\n",
       "      <td>0.000008</td>\n",
       "      <td>my_project</td>\n",
       "      <td>testing</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d94ba6be4b64e1be86</th>\n",
       "      <td>MyClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:13.998702288+00:00</td>\n",
       "      <td>2026-05-20 13:58:14.998900652+00:00</td>\n",
       "      <td>1.000198</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>34818cf0647e22b9f7e0d46adac2fd394b76e572f132976946f2c76498a6140f</th>\n",
       "      <td>MyClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:15.004741192+00:00</td>\n",
       "      <td>2026-05-20 13:58:16.004941463+00:00</td>\n",
       "      <td>1.000200</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5fef928ab57118f9390f0627ba47fe2030d9287e5b05826292042b5a41a4ec06</th>\n",
       "      <td>MyDataClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:16.012222767+00:00</td>\n",
       "      <td>2026-05-20 13:58:17.012420893+00:00</td>\n",
       "      <td>1.000198</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0359b0c3903ae8c466</th>\n",
       "      <td>MyAttrsClass.compute</td>\n",
       "      <td>__main__</td>\n",
       "      <td>2026-05-20 13:58:17.020026207+00:00</td>\n",
       "      <td>2026-05-20 13:58:18.020214558+00:00</td>\n",
       "      <td>1.000188</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                        name  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  long_running_calculation   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  long_running_calculation   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  long_running_calculation   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...                    double   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...       another_calculation   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...       another_calculation   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...           MyClass.compute   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...           MyClass.compute   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...       MyDataClass.compute   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...      MyAttrsClass.compute   \n",
       "\n",
       "                                                      module  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  __main__   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  __main__   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  __main__   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  __main__   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  __main__   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  __main__   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...  __main__   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...  __main__   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...  __main__   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...  __main__   \n",
       "\n",
       "                                                                             timestart  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:07.866472244+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:09.876649618+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:11.898600340+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899759531+00:00   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae... 2026-05-20 13:58:13.981916666+00:00   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f... 2026-05-20 13:58:13.982227802+00:00   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d... 2026-05-20 13:58:13.998702288+00:00   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976... 2026-05-20 13:58:15.004741192+00:00   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826... 2026-05-20 13:58:16.012222767+00:00   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0... 2026-05-20 13:58:17.020026207+00:00   \n",
       "\n",
       "                                                                              timestop  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493... 2026-05-20 13:58:09.866674185+00:00   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4... 2026-05-20 13:58:11.876836300+00:00   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1... 2026-05-20 13:58:13.898777008+00:00   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748... 2026-05-20 13:58:13.899780273+00:00   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae... 2026-05-20 13:58:13.981927633+00:00   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f... 2026-05-20 13:58:13.982236147+00:00   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d... 2026-05-20 13:58:14.998900652+00:00   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976... 2026-05-20 13:58:16.004941463+00:00   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826... 2026-05-20 13:58:17.012420893+00:00   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0... 2026-05-20 13:58:18.020214558+00:00   \n",
       "\n",
       "                                                    walltime     project  \\\n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...  2.000202         NaN   \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...  2.000187         NaN   \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...  2.000177         NaN   \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...  0.000021         NaN   \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  0.000011  my_project   \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  0.000008  my_project   \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...  1.000198         NaN   \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...  1.000200         NaN   \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...  1.000198         NaN   \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...  1.000188         NaN   \n",
       "\n",
       "                                                   category  \n",
       "4435e2927c194eff1bb90270ab3f353f0db1a8b50ec0493...      NaN  \n",
       "cb9db168b7a8eb99bda637a54241ad5d4e2726b5cd67ad4...      NaN  \n",
       "a7ce6824785adc406ca3561dcf98b3c64ddf1539d2467e1...      NaN  \n",
       "3fb9bd0ba9c388530e4a0f5fbb789aaf7b5c598c1fae748...      NaN  \n",
       "a8a3061653183cff08e5c414f9a4087550ab5e33cc186ae...  testing  \n",
       "1e352b538b9219d4e5fcaf429882a4b3587f3bc6358ef0f...  testing  \n",
       "ae154f37c2176451bd04c82e702bd934f1ecfdb5d49698d...      NaN  \n",
       "34818cf0647e22b9f7e0d46adac2fd394b76e572f132976...      NaN  \n",
       "5fef928ab57118f9390f0627ba47fe2030d9287e5b05826...      NaN  \n",
       "f240e0fe816bfa4476a5ef4e5de2c98d4b5276da3fb10e0...      NaN  "
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cache().table().query('name!=\"fib\"')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying Cached Calls via Function Wrapper\n",
    "\n",
    "You can retrieve previously cached calls that match some of your function's arguments and metadata using the function wrapper's `query` method. Any field left as `None` is treated as a wildcard. Arguments and result are compared by digest internally, but the wrapper decodes them back to Python objects when returning matches.\n",
    "\n",
    "Example using the `another_calculation` wrapper we created above:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.070266Z",
     "iopub.status.busy": "2026-05-20T13:58:18.070116Z",
     "iopub.status.idle": "2026-05-20T13:58:18.076002Z",
     "shell.execute_reply": "2026-05-20T13:58:18.075287Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "another_calculation LazyArguments({'a': 'da217d50752f3371d9f8b62a3e72409592bd34b74e14fdac43e2b137bd59f21f', 'b': '92a9b214d814a4a7b5f9ba52e2248c6d16ec0196d8cd7798b345471118bf0c67'}) {'project': 'my_project', 'category': 'testing'}\n",
      "LazyArguments({'a': '65d52a82c5a72f12ca0499522dc9274a0e6822e1038630ba68f94400b3e4c98f', 'b': '83ada2198553b88cb3d0882f7fca8c4e9531049b978df3e9e3b5d6301c6c0bfa'}) 7\n"
     ]
    }
   ],
   "source": [
    "# Query by metadata presence (tags) and a specific key-value filter\n",
    "for call in another_calculation.fleche.query(1, 2, metadata={\"tags\": {}}):\n",
    "    # presence-only: any call with 'tags'\n",
    "    print(call.name, call.arguments, call.metadata.get(\"tags\"))\n",
    "\n",
    "for call in another_calculation.fleche.query(3, 4, metadata={\"tags\": {\"project\": \"my_project\"}}):\n",
    "    # equality filter on metadata\n",
    "    assert call.metadata[\"tags\"][\"project\"] == \"my_project\"\n",
    "    # arguments and result are decoded if they were stored as digests\n",
    "    print(call.arguments, call.result)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lazy Loading\n",
    "\n",
    "When you load a call from the cache, fleche returns it as a `LazyCall` by default. Arguments and results are only fetched from storage when you actually access them — so iterating over a large cache or inspecting metadata stays fast even when individual results are huge.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.077515Z",
     "iopub.status.busy": "2026-05-20T13:58:18.077364Z",
     "iopub.status.idle": "2026-05-20T13:58:18.080869Z",
     "shell.execute_reply": "2026-05-20T13:58:18.080146Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Got a LazyCall for fib(20)\n",
      "Result: 6765\n"
     ]
    }
   ],
   "source": [
    "# Default load: returns a LazyCall — no deserialization yet\n",
    "key = fib.fleche.digest(20)\n",
    "lazy_call = cache().load(key)\n",
    "print(f\"Got a {type(lazy_call).__name__} for {lazy_call.name}(20)\")\n",
    "\n",
    "# Accessing .result triggers the actual load from storage\n",
    "print(f\"Result: {lazy_call.result}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To load everything upfront, call `.fetch()` on a lazy call you already have.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T13:58:18.082406Z",
     "iopub.status.busy": "2026-05-20T13:58:18.082257Z",
     "iopub.status.idle": "2026-05-20T13:58:18.085421Z",
     "shell.execute_reply": "2026-05-20T13:58:18.084841Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Call(name='fib', arguments={'n': 20}, metadata=defaultdict(<class 'dict'>, {'runtime': {'timestart': 1779285491.8865771, 'timestop': 1779285491.8929136, 'walltime': 0.0063364505767822266}}), module='__main__', version=None, code_digest=None, result=6765)"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Fetch everything upfront from a lazy call:\n",
    "lazy_call.fetch()\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}