Using Your Notebook
Notebook best practices
How to get the most from your pysolvr notebook -- versioning, customisation, Drive hygiene, and habits that save you from losing work.
These habits take thirty seconds each and will save you from losing work, breaking your notebook, or wondering why something stopped working.
Save to Drive immediately -- and name it with the version number
When you open a notebook from GitHub, you're viewing a read-only copy. Nothing you do persists until you save it to your Drive.
File > Save a copy in Drive -- do this before running anything.
When you save, rename the file to include the version number. You'll find the version in the notebook header (the first cell). For example:
PlanForge v0.3.ipynb
Why this matters:
- You always know which version you're running
- When a new version ships, you can keep both copies open side by side
- If an update introduces a problem, you can revert to the previous copy instantly
- Your customisations are safe -- they live in your named copy, not the shared GitHub version
Run Setup every session
Colab sessions are temporary. When you close the tab or the session times out, the runtime resets. That means installed packages, loaded variables, and API connections are gone.
The Setup cell reinstalls everything and reconnects in about 30 seconds. Run it every time you open the notebook -- even if you were just using it an hour ago.
If you skip Setup and run a later cell, you'll get errors that look confusing but have a simple fix: go back and run Setup first.
Never edit the Setup or Account cells
These are universal cells -- they're maintained by pysolvr and updated with every new version. If you edit them, two things happen:
- Your edits will be lost when you upgrade to a new version
- You may break functionality that depends on the cell running exactly as written
If you want to add something to the setup process (extra imports, custom variables), add a new cell immediately after Setup. Don't touch the original.
The same applies to the Account cell. It handles your subscription, usage tracking, and version checks. Leave it as-is.
Add new cells -- don't modify existing ones
If you want to extend the notebook -- add a calculation, reformat output, chain results into another tool -- add a new cell rather than editing an existing one.
This keeps your customisations portable. When a new version ships, you copy your added cells across to the new copy. If you've edited existing cells instead, you'll need to diff them manually to figure out what changed.
A clean rule: cells you added are yours to edit freely. Cells that came with the notebook, leave alone.
Don't rename your Drive output folder
The notebook saves generated files to a specific folder in your Drive -- something like My Drive/pysolvr/planforge/. This path is set in the notebook's config.
If you rename or move that folder, the notebook won't find it and will either error or create a new folder alongside your renamed one. Your old files won't be lost, but the notebook won't know where they are.
If you want to organise your Drive, create subfolders inside the pysolvr folder rather than renaming the root folder.
Keep your API key in Colab Secrets -- not in the notebook
Your API key should live in Colab Secrets (the key icon in the left sidebar), not pasted into a cell. The notebook reads it from there automatically.
If your key is in a cell, it's visible to anyone you share the notebook with and will be committed to Drive in plain text.
If you think your key has been exposed, rotate it from the Account cell (Account > Rotate key). Your old key stops working immediately and a new one is emailed to you.
Notebooks require an internet connection -- always
Your notebook file lives in Google Drive and may be available to view offline if you have Drive sync enabled. But viewing the file and running it are different things.
Three things need to be online for a session to work:
- Google Colab -- it's a cloud runtime running in your browser. There is no offline mode.
- PyPI -- the Setup cell installs packages from the internet every session. No connection, no packages, nothing else runs.
- The pysolvr API -- every cell that does useful work calls our backend. No connection, no results.
If you're on a slow or unreliable connection, run Setup first and wait for it to complete before running anything else. A partial Setup is the most common cause of confusing errors.
If you're travelling or know you'll be offline, there's no workaround -- plan to use the notebook when you have a reliable connection.
Check your Account cell regularly
The Account cell is your dashboard. Run it to see:
- Your current plan and spend this month
- How much of your monthly limit you've used
- Whether a new notebook version is available
- A support form if something isn't working
It takes two seconds to run and tells you everything you need to know about your account without leaving the notebook.
Before upgrading -- keep your old copy until you've verified the new one
When a new version is available, don't overwrite your current copy immediately. Open the new version in a separate tab, save it to Drive with the new version number, and verify it works before retiring the old one.
Once you're happy with the new version and have moved across any custom cells, you can delete the old copy -- or keep it as a backup. Drive storage is cheap.
See Updating your notebook for the full upgrade process.
The short version: save to Drive with a version number, run Setup every session, add cells rather than editing them, and check your Account cell when something seems off. Everything else follows from those four habits.