Data Learning Apps

Data Learning Apps is a collection of interactive demos that explain technical concepts through visuals and exploration. Each app lives under apps/<app_slug>/ and may use different frameworks such as Streamlit, Dash, or custom frontends. The shared goal is to make certain systems or methods more intuitive, by letting people poke at them directly. App-specific setup notes live in each app’s README.md, while testing instructions are documented in apps/<app_slug>/tests/TESTS.md.

Design documents

Every app includes a DESIGN.md that outlines the functional goals of the experience: what the demo teaches, how the content is structured, and how interactive elements guide the learning journey. Draft or update the design document before changing an app so the educational story is settled first. A reusable template is available at DESIGN_TEMPLATE.md in the project root.

Available apps

• Gradient Descent Explorer (apps/gradient_descent/): Tune learning-rate controls and visualize how gradient descent optimizes a linear regression model. See apps/gradient_descent/README.md for run commands and tests.
• Fuzzy Inverted Index Explorer (apps/fuzzy_inverted_index/): Learn how n-gram fragmentation turns an inverted index into a fuzzy search engine with scoring explanations. See apps/fuzzy_inverted_index/README.md for details.
• SIMD vs SIMT Explorer (apps/simt_vs_simd/): Follow eight pixels through six guided steps to learn what SIMD and SIMT each mean, why an if costs both of them, and which one you actually end up using. Assumes no GPU background. See apps/simt_vs_simd/README.md for details.

Getting started

1. Install uv.

2. Install Python dependencies (this also creates a .venv with the right Python version):

   uv sync

3. Run any command in that environment by prefixing it with uv run, e.g. uv run streamlit run apps/gradient_descent/main.py.

Development workflow

• Review the relevant app’s DESIGN.md before making changes to keep the learning story aligned with the implementation.
• Keep each app self-contained with its own README.md, DESIGN.md, tests/TESTS.md, and any framework-specific notes.
• Run the commands listed in tests/TESTS.md and the app’s own tests/TESTS.md before wrapping up changes.
• Automation- or AI-specific guidelines for working in this repository live in AGENTS.md (root and per-app).

Creating new apps

1. Create a new directory under apps/ (for example, apps/new_concept/).
2. Copy DESIGN_TEMPLATE.md to apps/new_concept/DESIGN.md and complete it to describe the learning experience.
3. Stop here and get the design approved. Share DESIGN.md, iterate on it, and wait for explicit approval before any code is written. Steps 4 onward do not start until that approval exists — a finished implementation submitted alongside an unreviewed design does not satisfy this step.
4. Add any framework-specific instructions to apps/new_concept/AGENTS.md.
5. Build the app according to the approved design document.
6. Provide automated checks and document them in apps/new_concept/tests/TESTS.md.
7. Add an apps/new_concept/README.md describing the experience and run instructions.
8. Update the root README.md and tests/TESTS.md to reference the new app.