SugarPy (Student MVP)

Current documentation entry points:

• Product guide and feature inventory: docs/PRODUCT_GUIDE.md
• Run and test commands: docs/RUNBOOK.md
• Architecture and runtime invariants: docs/ARCHITECTURE.md
• Math cell semantics: docs/MATH_CELL_SPEC.md

A minimal, student-friendly Jupyter toolkit with:

• A Function Builder widget for quick math functions.
• A Chemistry Balancer widget to balance reaction equations.

# Requires uv (https://astral.sh/uv)
UV_PROJECT_ENVIRONMENT=.venv uv sync --extra lab --frozen
source .venv/bin/activate

Run Jupyter server (kernel backend):

./scripts/launch.sh

Open the custom UI (frontend):

cd web
npm install
npm run dev

Then open http://localhost:5173 and click Connect Kernel.

Or run everything at once:

./scripts/run-all.sh

Run full checks (includes UI console checks):

./scripts/test-all.sh

./scripts/test-all.sh uses uv for Python deps and npm ci for the web app. UI checks use Playwright (smoke/e2e) in headless mode by default.

• Code cells use CodeMirror 6 (Python). Shift+Enter runs the cell; Tab indents; Enter accepts autocomplete.
• Execution counter is global (Jupyter-like). Indicator appears in the left gutter as [n] and [*] while running.
• Output renders below the code cell.
• Markdown cells render on blur; click to edit. Shift+Enter (or Render button) toggles to rendered view.
• Insert controls appear on hover above/below each cell (“+ Code / + Text”).
• Cell menu (top-right) supports move up/down and delete.
• Function autocomplete combines library functions + any def executed in the session.
• Library functions are auto-loaded into the kernel on connect (no import needed).
• Math cells are CAS-style: = means equation, := means assignment, ^ is supported, and implicit multiplication works.
• Math cells share namespace with Code cells (functions/variables defined in Code cells are available in Math cells).

• Use Code cells for Python logic (def, loops, imports, custom utilities).
• Use Math cells for CAS input (x^2 + 2x + 1, x^2 = 2, a := 5).
• If you need to define a function, do it in Code and then call it from Math.

• Built-in function list: web/public/functions.json
• Add your own functions to ~/.sugarpy/user_functions.py (auto-loaded on startup).

from sugarpy.chem import balance_equation
balance_equation("H2 + O2 -> H2O")

• The chemistry parser supports common formulas with parentheses.
• The frontend reads web/public/functions.json for the function list.