Installation — Gradiance

Requirements

Python 3.12 or newer recommended (tested on 3.12.13; 3.10 is the floor) · macOS (tested on Apple M-series) · No admin rights required

Step 1 — Download & extract

Unzip the interview_manager/ folder to your preferred location:

/Users/yourname/src/gradiance/interview_manager/

Step 2 — Create a virtual environment

cd /Users/yourname/src/gradiance/interview_manager
python3 -m venv venv
source venv/bin/activate

Step 3 — Install dependencies

pip install -r requirements.txt

That pins the versions the app is tested against:

Package	Version	Needed for
`matplotlib`	3.9.4	Charts in the Stats window
`numpy`	2.0.0	Chart data handling
`pillow`	10.2.0	Question images, competency PDF export
`certifi`	2024.12.14	TLS bundle for SMTP and model downloads
`wordfreq`	3.1.1	Comprehension Load vocabulary scoring

tkinter and sqlite3 are standard library. If you use pyenv on macOS, its Python may be built without Tk — either use the system Python or rebuild with --with-tcltk.

Don't drop wordfreq casually

The scorer runs without it, at reduced accuracy — but a score computed with wordfreq is not on the same scale as one computed without it. comprehension.VERSION records which tier produced each score, and rows scored under a different tier render as stale rather than being compared. If you remove the package, rescore the bank.

Optional extras, commented out in requirements.txt:

# Better spelling suggestions (detection is unaffected)
pip install pyspellchecker==0.8.2

# Audio transcription
pip install faster-whisper==1.2.0 sounddevice==0.4.7 soundfile==0.12.1

# Local LLM summarisation
pip install ollama==0.3.3

Step 4 — Launch

python3 main.py

main.py is the current entry point. It prepares the database and installs every subsystem it needs before the app opens.

Launch with main.py

Other scripts in the folder are older or build-related entry points and are not equivalent — launching through one of them on a fresh database can leave parts of the database uninitialised. Always start the app with python3 main.py.

First launch

A fresh interview_data.db is created automatically. You will be prompted to create a semester and class before adding students.

File structure

File / Folder	Purpose
`main.py`	Entry point — run this to start the app
`interview_manager.py`	Legacy entry point — do not launch with this
`gradiance_launch.py`	`.app` wrapper — redirects data to Application Support
`gradiance.spec`	PyInstaller build spec
`requirements.txt`	Pinned dependencies
`interview_data.db`	SQLite database — all your data lives here
`settings.json`	SMTP, theme, DB path, research salt, backup policy, window layout
`themes/`	Custom theme JSON files
`images/`	Question images
`dist/Gradiance.app`	Built macOS application bundle
`tests/`	84 unit tests + 46 stress tests

settings.json holds a plaintext SMTP password

Treat it as a secret: keep it out of version control and out of any bank file or archive you share. The research.research_salt value in the same file is what makes research exports re-identifiable if leaked, and warrants the same care.

Where data lives when packaged

Run from source, the database and settings sit beside the code. Launched as the bundled .app, gradiance_launch.py redirects both to:

~/Library/Application Support/Gradiance/

The bundle is read-only once signed, so this is not optional. Point ⚙️ Database in the top bar at an existing file if you are migrating from a source install.

Backups

Configured under the "backup" key in settings.json: a destination path (typically a OneDrive folder), how many copies to keep, and whether to back up on launch. Auto-backup runs silently at most once per 24 hours; Settings ▾ → Backup DB forces one immediately.

Running the tests

# Unit tests
python3 tests/test_core.py

# Stress tests (runs against a COPY of your DB)
cp interview_data.db /tmp/test.db
python3 tests/stress_test.py --db /tmp/test.db --yes-destroy-data