Skip to content

Commit f12dc07

Browse files
T-DevHT-DevH
committed
fix: add initialization cell and fix kernel switch issues in setup notebook
- Add reusable initialization cell after Step 1 with PROJECT_ROOT_MARKERS and get_project_root() - Update Step 2 to always run (remove skip option) and use initialization utilities - Update Step 3 to check builtins for utilities after kernel switches - Update Step 4 to check builtins for utilities with proper error handling - Fixes NameError issues when skipping Step 2 or after kernel switches - All steps now resilient to kernel restarts by checking builtins module
1 parent 4df9a41 commit f12dc07

1 file changed

Lines changed: 140 additions & 90 deletions

File tree

‎notebooks/setup/complete_setup_guide.ipynb‎

Lines changed: 140 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -169,120 +169,156 @@
169169
"print(\"\\n📝 If any checks failed, please install the missing tools before proceeding.\")\n"
170170
]
171171
},
172-
{
173-
"cell_type": "markdown",
174-
"metadata": {},
175-
"source": [
176-
"## Step 2: Repository Setup\n",
177-
"\n",
178-
"If you haven't cloned the repository yet, follow the instructions below. If you're already in the repository, you can skip this step.\n"
179-
]
180-
},
181172
{
182173
"cell_type": "code",
183174
"execution_count": null,
184175
"metadata": {},
185176
"outputs": [],
186177
"source": [
178+
"# ============================================================================\n",
179+
"# INITIALIZATION: Project Root Detection Utilities\n",
180+
"# ============================================================================\n",
181+
"# ⚠️ IMPORTANT: Run this cell after any kernel restart or kernel switch!\n",
182+
"# This cell defines essential utilities used throughout the notebook.\n",
183+
"# ============================================================================\n",
184+
"\n",
187185
"import os\n",
186+
"import builtins\n",
188187
"from pathlib import Path\n",
189-
"# Constant for notebook filename to avoid duplication\n",
190-
"NOTEBOOK_FILENAME = \"complete_setup_guide.ipynb\"\n",
191188
"\n",
192-
"# Constants for project root detection (to avoid duplication)\n",
193-
"PROJECT_ROOT_MARKERS = (\"src\", \"api\"), (\"scripts\", \"setup\")\n",
189+
"# Constants for project root detection\n",
190+
"NOTEBOOK_FILENAME = \"complete_setup_guide.ipynb\"\n",
191+
"PROJECT_ROOT_MARKERS = ((\"src\", \"api\"), (\"scripts\", \"setup\"))\n",
194192
"NOTEBOOK_SETUP_DIR = \"setup\"\n",
195193
"NOTEBOOKS_DIR = \"notebooks\"\n",
196194
"\n",
197195
"\n",
198-
"\n",
199-
"\n",
200-
"# Detect project root: navigate from current directory to find project root\n",
201-
"# This handles cases where notebook is opened from notebooks/setup/ or project root\n",
202-
"def find_project_root():\n",
203-
" \"\"\"Find the project root directory.\"\"\"\n",
204-
" current = Path.cwd()\n",
205-
" \n",
206-
" # Check if we're already in project root\n",
207-
" if (current / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (current / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
208-
" return current\n",
209-
"\n",
210-
"\n",
211196
"def get_project_root():\n",
212197
" \"\"\"Get project root directory, detecting it if needed.\n",
213198
" \n",
214199
" This function works regardless of where the notebook is opened from.\n",
215200
" It stores the result in builtins so it persists across cells.\n",
216-
" \"\"\"\n",
217-
" import builtins\n",
218-
" import os\n",
219-
" from pathlib import Path\n",
220201
" \n",
221-
" # Check if already stored\n",
202+
" ⚠️ IMPORTANT: This function must be defined before Step 2, 3, and 4.\n",
203+
" If you get a NameError, re-run this initialization cell.\n",
204+
" \"\"\"\n",
205+
" # Check if already stored (persists across cells in same kernel)\n",
222206
" if hasattr(builtins, '__project_root__'):\n",
223207
" return builtins.__project_root__\n",
224208
" \n",
225209
" # Try to find project root\n",
226210
" current = Path.cwd()\n",
227211
" \n",
228212
" # Check if we're already in project root\n",
229-
" if (current / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (current / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
213+
" if (current / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \\\n",
214+
" (current / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
230215
" project_root = current\n",
231216
" # Check if we're in notebooks/setup/ (go up 2 levels)\n",
232217
" elif (current / NOTEBOOK_FILENAME).exists() or current.name == NOTEBOOK_SETUP_DIR:\n",
233218
" project_root = current.parent.parent\n",
219+
" # Verify it's actually the project root\n",
220+
" if not ((project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \n",
221+
" (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()):\n",
222+
" project_root = current\n",
234223
" # Check if we're in notebooks/ (go up 1 level)\n",
235224
" elif current.name == NOTEBOOKS_DIR:\n",
236225
" project_root = current.parent\n",
226+
" # Verify it's actually the project root\n",
227+
" if not ((project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \n",
228+
" (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()):\n",
229+
" project_root = current\n",
237230
" else:\n",
238231
" # Try going up from current directory\n",
239232
" project_root = current\n",
240233
" for parent in current.parents:\n",
241-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
234+
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \\\n",
235+
" (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
242236
" project_root = parent\n",
243237
" break\n",
244238
" \n",
245239
" # Change to project root and store it\n",
246240
" os.chdir(project_root)\n",
247241
" builtins.__project_root__ = project_root\n",
242+
" builtins.__PROJECT_ROOT_MARKERS__ = PROJECT_ROOT_MARKERS\n",
243+
" builtins.__NOTEBOOK_FILENAME__ = NOTEBOOK_FILENAME\n",
244+
" builtins.__NOTEBOOK_SETUP_DIR__ = NOTEBOOK_SETUP_DIR\n",
245+
" builtins.__NOTEBOOKS_DIR__ = NOTEBOOKS_DIR\n",
246+
" builtins.__get_project_root__ = get_project_root\n",
247+
" \n",
248248
" return project_root\n",
249249
"\n",
250-
" \n",
251-
" # Check if we're in notebooks/setup/ (go up 2 levels)\n",
252-
" if (current / NOTEBOOK_FILENAME).exists() or current.name == NOTEBOOK_SETUP_DIR:\n",
253-
" parent = current.parent.parent\n",
254-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
255-
" return parent\n",
256-
" \n",
257-
" # Check if we're in notebooks/ (go up 1 level)\n",
258-
" if current.name == NOTEBOOKS_DIR:\n",
259-
" parent = current.parent\n",
260-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
261-
" return parent\n",
262-
" \n",
263-
" # Try going up from current directory\n",
264-
" for parent in current.parents:\n",
265-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
266-
" return parent\n",
267-
" \n",
268-
" # Fallback: return current directory\n",
269-
" return current\n",
270250
"\n",
271-
"# Find and change to project root\n",
272-
"project_root = find_project_root()\n",
273-
"is_in_repo = (project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()\n",
251+
"# Initialize project root detection\n",
252+
"try:\n",
253+
" project_root = get_project_root()\n",
254+
" print(\"✅ Initialization complete!\")\n",
255+
" print(f\" Project root: {project_root}\")\n",
256+
" print(f\" Working directory: {Path.cwd()}\")\n",
257+
" print(\"\\n📝 These utilities are now available for all subsequent steps:\")\n",
258+
" print(\" - PROJECT_ROOT_MARKERS\")\n",
259+
" print(\" - get_project_root()\")\n",
260+
" print(\"\\n⚠️ If you switch kernels, re-run this cell first!\")\n",
261+
"except Exception as e:\n",
262+
" print(f\"⚠️ Initialization warning: {e}\")\n",
263+
" print(\" This is okay if you haven't cloned the repository yet.\")\n",
264+
" print(\" Continue to Step 2 to set up the repository.\")\n"
265+
]
266+
},
267+
{
268+
"cell_type": "markdown",
269+
"metadata": {},
270+
"source": [
271+
"## Step 2: Repository Setup\n",
272+
"\n",
273+
"**⚠️ IMPORTANT:** Always run this step, even if you're already in the repository. This step verifies your repository setup and ensures the working directory is correct.\n",
274+
"\n",
275+
"**Note:** If you just switched kernels (e.g., to `warehouse-assistant`), make sure you've run the **Initialization** cell above first!\n"
276+
]
277+
},
278+
{
279+
"cell_type": "code",
280+
"execution_count": null,
281+
"metadata": {},
282+
"outputs": [],
283+
"source": [
284+
"# ============================================================================\n",
285+
"# Step 2: Repository Setup\n",
286+
"# ============================================================================\n",
287+
"# This step verifies repository setup and ensures correct working directory.\n",
288+
"# It uses the utilities defined in the Initialization cell above.\n",
289+
"# ============================================================================\n",
290+
"\n",
291+
"import os\n",
292+
"import builtins\n",
293+
"from pathlib import Path\n",
294+
"\n",
295+
"# Ensure initialization utilities are available\n",
296+
"# If they're not defined, try to get them from builtins (from initialization cell)\n",
297+
"if 'PROJECT_ROOT_MARKERS' not in globals():\n",
298+
" if hasattr(builtins, '__PROJECT_ROOT_MARKERS__'):\n",
299+
" PROJECT_ROOT_MARKERS = builtins.__PROJECT_ROOT_MARKERS__\n",
300+
" NOTEBOOK_FILENAME = builtins.__NOTEBOOK_FILENAME__\n",
301+
" NOTEBOOK_SETUP_DIR = builtins.__NOTEBOOK_SETUP_DIR__\n",
302+
" NOTEBOOKS_DIR = builtins.__NOTEBOOKS_DIR__\n",
303+
" get_project_root = builtins.__get_project_root__\n",
304+
" else:\n",
305+
" print(\"⚠️ ERROR: Initialization cell not run!\")\n",
306+
" print(\" Please run the 'Initialization: Project Root Detection Utilities' cell above first.\")\n",
307+
" print(\" This cell must be run before Step 2, 3, and 4.\")\n",
308+
" raise NameError(\"Initialization utilities not found. Please run the Initialization cell first.\")\n",
309+
"\n",
310+
"# Get project root using the initialization function\n",
311+
"project_root = get_project_root()\n",
312+
"\n",
313+
"# Verify we're in the repository\n",
314+
"is_in_repo = (project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \\\n",
315+
" (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()\n",
274316
"\n",
275317
"if is_in_repo:\n",
276-
" # Change to project root so all subsequent operations work correctly\n",
277-
" os.chdir(project_root)\n",
278-
" # Store project_root globally so other cells can use it\n",
279-
" import builtins\n",
280-
" builtins.__project_root__ = project_root\n",
281-
" builtins.__find_project_root__ = find_project_root\n",
282-
" print(\"✅ You're already in the Warehouse Operational Assistant repository!\")\n",
318+
" print(\"✅ Repository verified!\")\n",
283319
" print(f\" Project root: {project_root}\")\n",
284-
" print(f\" Changed working directory to: {Path.cwd()}\")\n",
285-
" print(\"\\n📝 You can skip the cloning step and proceed to environment setup.\")\n",
320+
" print(f\" Working directory: {Path.cwd()}\")\n",
321+
" print(\"\\n📝 Repository is set up correctly. Proceed to Step 3 (Environment Setup).\")\n",
286322
"else:\n",
287323
" print(\"📦 Repository Setup Instructions\")\n",
288324
" print(\"=\" * 60)\n",
@@ -385,34 +421,31 @@
385421
" )\n",
386422
" return result.returncode == 0, result.stdout, result.stderr\n",
387423
"\n",
388-
"# Get project root (from Step 2 if available, otherwise find it)\n",
389-
"try:\n",
390-
" import builtins\n",
391-
" if hasattr(builtins, '__project_root__'):\n",
392-
" project_root = builtins.__project_root__\n",
393-
" elif hasattr(builtins, '__find_project_root__'):\n",
394-
" project_root = builtins.__find_project_root__()\n",
424+
"# Ensure initialization utilities are available\n",
425+
"# If they're not defined, try to get them from builtins (from initialization cell)\n",
426+
"import builtins\n",
427+
"if 'PROJECT_ROOT_MARKERS' not in globals():\n",
428+
" if hasattr(builtins, '__PROJECT_ROOT_MARKERS__'):\n",
429+
" PROJECT_ROOT_MARKERS = builtins.__PROJECT_ROOT_MARKERS__\n",
430+
" get_project_root = builtins.__get_project_root__\n",
395431
" else:\n",
396-
" # Fallback: try to find project root\n",
397-
" current = Path.cwd()\n",
398-
" for parent in current.parents:\n",
399-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
400-
" project_root = parent\n",
401-
" break\n",
402-
" else:\n",
403-
" project_root = current\n",
404-
"except:\n",
405-
" # Fallback: try to find project root\n",
406-
" current = Path.cwd()\n",
407-
" project_root = current\n",
408-
" for parent in current.parents:\n",
409-
" if (parent / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (parent / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists():\n",
410-
" project_root = parent\n",
411-
" break\n",
432+
" print(\"⚠️ ERROR: Initialization cell not run!\")\n",
433+
" print(\" Please run the 'Initialization: Project Root Detection Utilities' cell above first.\")\n",
434+
" print(\" This is especially important after switching kernels.\")\n",
435+
" raise NameError(\"Initialization utilities not found. Please run the Initialization cell first.\")\n",
436+
"\n",
437+
"# Get project root using the initialization function\n",
438+
"try:\n",
439+
" project_root = get_project_root()\n",
440+
"except NameError:\n",
441+
" print(\"⚠️ ERROR: get_project_root() not available!\")\n",
442+
" print(\" Please run the 'Initialization: Project Root Detection Utilities' cell above first.\")\n",
443+
" raise\n",
412444
"\n",
413445
"# Check if requirements.txt exists\n",
414446
"requirements_file = project_root / \"requirements.txt\"\n",
415-
"is_in_repo = (project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()\n",
447+
"is_in_repo = (project_root / PROJECT_ROOT_MARKERS[0][0] / PROJECT_ROOT_MARKERS[0][1]).exists() and \\\n",
448+
" (project_root / PROJECT_ROOT_MARKERS[1][0] / PROJECT_ROOT_MARKERS[1][1]).exists()\n",
416449
"\n",
417450
"if not requirements_file.exists() or not is_in_repo:\n",
418451
" print(f\"\\n⚠️ WARNING: Repository not found!\")\n",
@@ -943,11 +976,28 @@
943976
"import getpass\n",
944977
"from pathlib import Path\n",
945978
"import re\n",
979+
"import builtins\n",
980+
"\n",
981+
"# Ensure initialization utilities are available\n",
982+
"if 'get_project_root' not in globals():\n",
983+
" if hasattr(builtins, '__get_project_root__'):\n",
984+
" get_project_root = builtins.__get_project_root__\n",
985+
" else:\n",
986+
" print(\"⚠️ ERROR: Initialization cell not run!\")\n",
987+
" print(\" Please run the 'Initialization: Project Root Detection Utilities' cell above first.\")\n",
988+
" def get_project_root():\n",
989+
" raise NameError(\"Initialization utilities not found. Please run the Initialization cell first.\")\n",
946990
"\n",
947991
"def setup_api_keys():\n",
948992
" \"\"\"Interactive setup for API keys (NVIDIA and/or Brev).\"\"\"\n",
949993
" # Get project root (works from any directory)\n",
950-
" project_root = get_project_root()\n",
994+
" try:\n",
995+
" project_root = get_project_root()\n",
996+
" except NameError as e:\n",
997+
" print(f\"⚠️ ERROR: {e}\")\n",
998+
" print(\" Please run the 'Initialization: Project Root Detection Utilities' cell above first.\")\n",
999+
" return False\n",
1000+
" \n",
9511001
" print(\"🔑 API Key Configuration\")\n",
9521002
" print(\"=\" * 60)\n",
9531003
" \n",

0 commit comments

Comments
 (0)