Planning Algorithms Explorer

An interactive web application for learning and visualizing algorithms from Steven M. LaValle's Planning Algorithms. The first milestone focuses on Chapter 2, discrete planning, with grid search algorithms and weighted graph algorithms.

The project is intentionally small and direct:

• backend/: Python FastAPI service and tested search algorithms
• frontend/: Vite, React, and TypeScript learning interface
• docs/: architecture notes, development workflow, and Chapter 2 learning notes
• chapter2/: early Python learning notes and prototypes

Run Locally

Install backend dependencies:

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Install frontend dependencies:

cd frontend
npm install
npm run dev

Open the frontend at http://127.0.0.1:5173.

Test

Backend:

cd backend
pytest

Frontend unit tests:

cd frontend
npm test

Frontend smoke test:

cd frontend
npx playwright test

Deploy

The default deployment target is Vercel. The repository includes vercel.json, a Python Function entrypoint in api/index.py, and a root requirements.txt that points to the FastAPI backend dependencies.

Deploy from the repository root:

vercel
vercel --prod

Vercel builds frontend/dist and routes /api/* to the FastAPI app. See docs/deployment.md for setup notes, limitations, and the live-code execution safety warning.

Current MVP

The current application implements a Chapter 2 workbench:

• choose forward, backward, or bidirectional search
• choose Dijkstra, A*, forward value iteration, or backward value iteration on a weighted graph
• edit a grid with S, G, ., and #
• edit a directed weighted graph as JSON, including edge costs and optional A* heuristic values
• run the exact Python3 code currently in the live editor
• inspect the returned trace frame by frame
• compare the explored visited nodes against the final plan
• inspect weighted graph relaxations, priority queue state, node values, parent edges, and policy edges
• read short explanations, complexity notes, LaTeX-rendered pseudocode, and source citations
• edit the selected Python3 algorithm implementation and run it through the local judge

The Python backend is the source of truth for execution and judging. The frontend edits examples, submits the current Python3 code for grid algorithms, and renders the trace produced from that submitted code. Weighted graph algorithms currently use the direct trace endpoint so the graph-specific visualization contract can stay focused on costs, relaxations, and value labels.

Live Code Evaluation

The live editor sends the exact Python3 code in the editor to the backend. The visualization run uses that code and validates the returned action sequence. Default implementations also return trace frames with visited sets, frontiers, and search-tree edges, so the visualization can show the full explored BFS tree. User edits can still return a plain action list, but then the app can only visualize the returned path.

If an edit breaks the algorithm, the visualization run reports the failure and keeps the previous trace. Use Reset code to restore the default implementation, then run the visualization again.

This is designed for local learning, not for running untrusted public submissions. Do not expose the judge endpoint on the public internet without a stronger sandbox such as a container, seccomp profile, network isolation, and per-run filesystem limits.

References

• Steven M. LaValle, Planning Algorithms
• Steven M. LaValle, Chapter 2: Discrete Planning
• Cambridge University Press, 2 - Discrete Planning