mirror of
https://github.com/saymrwulf/QuantumLearning.git
synced 2026-05-14 20:58:00 +00:00
236 lines
6.8 KiB
Markdown
236 lines
6.8 KiB
Markdown
# Operations
|
|
|
|
This file is the self-service operations manual for `QuantumLearning`. It is written to match the repo as it actually exists now, not a hypothetical future state.
|
|
|
|
## Operating Model
|
|
|
|
The project is intentionally local-first and repo-local:
|
|
|
|
- Python environment lives in `.venv/`
|
|
- Jupyter config and runtime live in `.jupyter_config/`, `.jupyter_data/`, `.jupyter_runtime/`, `.ipython/`, and `.cache/matplotlib/`
|
|
- Playwright browser runtime lives in `.playwright-browsers/`
|
|
- validation artifacts live in `.tmp_test_artifacts/`
|
|
|
|
That means the day-to-day operational commands are all inside this repo.
|
|
|
|
## Bootstrap On A New Mac
|
|
|
|
Prerequisites:
|
|
|
|
1. macOS
|
|
2. Python `3.12`
|
|
3. internet access for the initial dependency and browser download
|
|
|
|
If `python3.12` is missing, install it first.
|
|
Typical options:
|
|
|
|
```bash
|
|
brew install python@3.12
|
|
```
|
|
|
|
or install Python `3.12` from `python.org`.
|
|
|
|
Then bootstrap the repo:
|
|
|
|
```bash
|
|
cd /path/to/QuantumLearning
|
|
bash ./scripts/app.sh bootstrap
|
|
```
|
|
|
|
That command will:
|
|
|
|
- create `.venv/` if needed
|
|
- install the Python dependencies from `pyproject.toml`
|
|
- install the project-local Playwright Chromium runtime into `.playwright-browsers/`
|
|
|
|
If you want the bootstrap to finish with a full validation run:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh bootstrap --run-validation
|
|
```
|
|
|
|
If you want to delay the browser download:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh bootstrap --skip-browser
|
|
```
|
|
|
|
## Start And Use The Course
|
|
|
|
Start the app:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh start --open
|
|
```
|
|
|
|
That starts the repo-local Jupyter server as a detached background service, prints the exact URL, cleans up stale runtime files when needed, and opens `notebooks/START_HERE.ipynb` in the default browser.
|
|
|
|
If you run the launcher from an automation shell that reaps background child processes when the shell exits, use foreground mode instead:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh start --foreground
|
|
```
|
|
|
|
Other normal consumer commands:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh status
|
|
bash ./scripts/app.sh restart
|
|
bash ./scripts/app.sh stop
|
|
bash ./scripts/app.sh reset-state
|
|
bash ./scripts/app.sh logs -f
|
|
```
|
|
|
|
If you want foreground mode for debugging:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh start --foreground
|
|
```
|
|
|
|
Use the course in this order:
|
|
|
|
1. `notebooks/START_HERE.ipynb`
|
|
2. `notebooks/COURSE_BLUEPRINT.ipynb`
|
|
3. each module as `lecture -> lab -> problems -> studio`
|
|
4. `notebooks/COURSE_COMPLETE.ipynb`
|
|
|
|
Operational rule inside the notebooks:
|
|
|
|
- complete `MANDATORY` cells in order
|
|
- use `FACULTATIVE` cells only as optional extensions
|
|
- read `META` cells as route/objective guidance, not as part of the technical payload
|
|
- expect no facultative extensions inside the route notebooks `START_HERE`, `COURSE_BLUEPRINT`, or `COURSE_COMPLETE`
|
|
|
|
## Monitoring The Project
|
|
|
|
Use the repo-native status script:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh status
|
|
```
|
|
|
|
It reports:
|
|
|
|
- current git branch and commit
|
|
- whether the worktree is clean or dirty
|
|
- whether `.venv/` exists and which Python version it uses
|
|
- whether the project-local Playwright browser runtime is installed
|
|
- whether a repo-local Jupyter server is running and, if so, its full URL
|
|
- whether saved Jupyter UI state is still present and how to reset it
|
|
|
|
If you lose the Jupyter URL, `bash ./scripts/app.sh status` is the fastest recovery path.
|
|
|
|
In restricted automation sandboxes, the script may report that the live process probe is unavailable. In a normal terminal on your Mac, it will report the running server directly when the runtime file and process are both visible.
|
|
|
|
If JupyterLab reopens old tabs or appears to remember stale notebook activity, that is usually saved workspace state rather than a still-running repo-local server. Clear it with:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh reset-state
|
|
```
|
|
|
|
The consumer rule is simple: after `START_HERE`, follow the explicit next-notebook navigation inside the notebooks themselves instead of browsing for your own path.
|
|
|
|
## Validation Modes
|
|
|
|
Quick local validation:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh validate --quick
|
|
```
|
|
|
|
This runs:
|
|
|
|
- `ruff check src tests scripts`
|
|
- `pytest -m "not browser and not notebook"`
|
|
|
|
Standard validation:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh validate --standard
|
|
```
|
|
|
|
This runs the full pytest suite without coverage reporting.
|
|
|
|
Release-style validation:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh validate --full
|
|
```
|
|
|
|
This runs:
|
|
|
|
- `ruff check src tests scripts`
|
|
- full pytest suite
|
|
- coverage reporting
|
|
|
|
In restricted automation sandboxes, the browser and notebook execution suites may skip because localhost kernel and browser ports are blocked. In a normal terminal on your Mac, the same command should run those suites instead of skipping them.
|
|
|
|
At the current state of the repo, the full validation suite includes:
|
|
|
|
- curriculum/config/runtime tests
|
|
- notebook pedagogy tests
|
|
- notebook execution tests
|
|
- real JupyterLab browser workflow validation
|
|
- assessment and capstone validation tests
|
|
|
|
## What The Browser Workflow Validation Now Covers
|
|
|
|
The browser suite no longer stops at “page opened.”
|
|
|
|
It now validates learner-style flows such as:
|
|
|
|
- opening notebooks through JupyterLab
|
|
- running all notebook cells
|
|
- answering a multiple-choice quiz
|
|
- editing an `editable_circuit_lab` code cell and re-rendering it
|
|
- completing an evidence checklist
|
|
- filling a feedback iteration panel
|
|
- moving rubric sliders and observing the grading summary update
|
|
|
|
## Recovery Checklist
|
|
|
|
If something feels wrong, use this order:
|
|
|
|
1. `bash ./scripts/app.sh status`
|
|
2. `bash ./scripts/app.sh validate --quick`
|
|
3. if needed, `bash ./scripts/app.sh validate --full`
|
|
4. restart Jupyter with `bash ./scripts/app.sh restart`
|
|
5. if the UI still looks stale, run `bash ./scripts/app.sh reset-state`
|
|
|
|
If `.venv/` is missing or broken, re-run:
|
|
|
|
```bash
|
|
bash ./scripts/app.sh bootstrap
|
|
```
|
|
|
|
## Another-Mac Transfer Pattern
|
|
|
|
The clean transfer model is:
|
|
|
|
1. clone or copy the repo to the new Mac
|
|
2. make sure Python `3.12` exists
|
|
3. run `bash ./scripts/app.sh bootstrap`
|
|
4. run `bash ./scripts/app.sh validate --quick`
|
|
5. run `bash ./scripts/app.sh start --open`
|
|
|
|
That is the intended self-service installation path. You do not need agent support for normal setup, validation, status checks, or Jupyter startup.
|
|
|
|
## Agent Restart Handoff
|
|
|
|
If you restart a coding agent in this repo and want it to get up to speed quickly, use:
|
|
|
|
- [AGENT_CONTEXT.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_CONTEXT.md)
|
|
- [AGENT_RESTART_PROTOCOL.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_RESTART_PROTOCOL.md)
|
|
|
|
Those files are the repo-local handoff layer. They exist because session memory does not persist across restarts.
|
|
|
|
## Underlying Plumbing
|
|
|
|
The lower-level scripts still exist for direct use or debugging:
|
|
|
|
- `bash ./scripts/bootstrap_mac.sh`
|
|
- `bash ./scripts/project_status.sh`
|
|
- `bash ./scripts/run_validation.sh --quick`
|
|
- `./scripts/start_jupyter.sh --foreground`
|
|
|
|
Those are implementation details now. The normal consumer interface is `bash ./scripts/app.sh ...`.
|